seriald

seriald is the serial console mediation service in EriX userspace.

EriX is a clean-room, capability-based microkernel operating system written entirely in Rust.

Technical requirements are tracked in the EriX requirements, conventions, and project documentation.

See:

• docs for design documents, specifications, and development plans.
• Related architecture repositories for kernel, services, libraries, drivers, and integration tooling.

Purpose of This Repository

This repository implements the EriX serial service daemon. Its purpose in EriX is to provide the serial service role through explicit IPC and startup authority.

Functionally, it implements the daemon runtime, state model, IPC handling, and validation tests. The repository keeps the implementation, interface contracts, tests, and documentation for that behavior in one reviewable ownership boundary.

The maintained responsibilities are:

• implement the serial service runtime and state model
• validate startup authority before accepting IPC requests
• retain required provider calls and all replies through authoritative completion on the assigned endpoint set
• keep service behavior, tests, and authority invariants documented

Clean-Room Policy

EriX follows a strict clean-room philosophy:

• No external source code may be copied.
• No external Rust crates are allowed.
• No code generation tools that embed third-party code.
• All code must be authored within the project.

Violations will result in rejection of the contribution.

License

All EriX repositories are licensed under the ISC License.

Development Model

EriX development is modular, deterministic, reproducible, authority-explicit, security-first, and self-hosting oriented.

This repository follows the project roadmap and the validation rules documented in its own roadmap.

Runtime model

• Single-threaded service loop.
• Canonical 8-KiB IPC transport storage shared with the wire contract.
• Deployment-authenticated stream retention backed by a dedicated, page-rounded arena; packaging selects the retained byte count.
• A terminal 64 KiB stack reserve follows the arena, so startup and provider discovery cannot overwrite retained stream storage.
• The root-published canonical endpoint is read-only. Rootd, logd, and ttyd write through distinct send-only clients whose matching receivers are delegated to seriald at startup.
• Serial-console disablement omits only ttyd's authenticated receiver; seriald proves the omitted slot absent once, then never queries or receives on that route at runtime. Public history and mandatory root/log output remain available, with unchanged exact-rights validation.
• Ttyd's private serial route admits ordinary-session output, UART-input dequeue, and modal TRUSTED_WRITE review output. Rootd and logd retain ordinary-write-only routes; the public route remains output history only.
• Trusted review bytes bypass public history. While a trusted record is active, ordinary writes return RETRY with zero accepted bytes before any provider or retention effect. Input dequeue remains available. Only ttyd's canonical empty, zero-padded trusted request releases modal exclusion; partial writes and provider errors cannot silently reopen ordinary output.
• Endpoint identity authorizes writes; request bodies and forwarded drv-serial requests carry no caller-selected role.
• Startup validates the exact five-capability delegated bundle: two narrow deviced clients and three authenticated writer receivers.
• Peer-only runtime authority: the split deviced HAL-registration and provider-resolution endpoints plus a transient materialized provider.
• seriald neither self-registers nor receives service-directory authority; rootd publishes its endpoint after observing successful startup.
• Background deviced registration is primed once after the startup reply and then retried from the single-threaded service loop's idle/provider path.
• Idle and foreground provider discovery make one nonblocking acceptance attempt per service-loop opportunity. Unavailable discovery cannot stall the receive loop; once accepted, the call retains its buffer through the authoritative reply. Required calls to an active provider have no service-local timeout or retry ceiling.
• Provider refresh first claims a live drv-serial cap already materialized in the canonical local slot before issuing another deviced resolve request.
• A successful resolution must carry exactly one send-only endpoint receipt from and to the canonical provider slot, and its typed response must name the serial policy identity, driver role, interface class, terminal cursor, and a nonzero generation. Any mismatch retires the destination capability.
• Ordinary service calls and authority-free peer replies retire every unwanted receipt before rejection. Malformed receipt state or an unprovable drop terminates seriald so process teardown retires the complete CSpace.
• UART RX remains private to drv-serial; seriald advances its own driver cursor and returns bounded bytes only to the authenticated ttyd receiver.
• Startup intake blocks without a service-local deadline. Runtime polling is nonblocking only where it multiplexes the four authority-partitioned receivers or tests optional peer availability before call acceptance.
• No dynamic allocation and no external crates.
• Request dispatch parses each exact typed body before reusing reply storage, without a shared mutable payload scratch buffer.

Feature flags

• seriald-runtime
• seriald-runtime-serial
• seriald-integration-smoke
• seriald-integration-force-fail
• seriald-integration-serial

Default build has no integration feature enabled.

Build and test

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features

Repository CI additionally runs default-feature cargo build, cargo test, and cargo doc with exact commit-pinned dependencies and identity-preserving caches.

Dependencies

• lib-bootstrap
• lib-capabi
• lib-device
• lib-ipc
• ipc-syscall-x86_64

No third-party crates are used.

Dynamic Boot Artifact Evidence

The image build packages seriald as an ELF64 x86_64 ET_DYN executable with .erix_dynlink metadata in the signed dynlink-store and mirrors it under /lib/erix/dynlink with its required shared objects.

Startup remains rootd through procd staged dynamic creation before dynlinkd; authority remains explicit deviced/provider and writer endpoints. Dynamic packaging and filesystem mirror records are evidence and launch inputs only; they do not grant filesystem, loader, object-store, service-discovery, provider-bypass, block-device, or dynlinkd authority. seriald receives only the documented startup endpoints, peers, and capabilities for its role.

Governance Principles

seriald governance is scoped to serial console service behavior above serial drivers.

The scoped governance rules are:

• It consumes only explicit serial-provider authority.
• It keeps console input/output bounded by the service IPC contract.
• It separates serial service policy from hardware driver ownership.
• It does not manage serial hardware directly or start drivers.

Authority Boundaries

• seriald operates only through startup-assigned service capabilities.
• New authority must be represented in bootstrap/capability validation and integration tests before use.

Contact

Development occurs in EriX organization and discussions happen in issues and design documents.

No decisions are considered valid without documented rationale.

Maintainers can be reached via email: admin@erikinkinen.fi.