drv-serial

drv-serial is the userspace serial hardware driver daemon for EriX.

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 driver service. Its purpose in EriX is to mediate serial hardware or protocol behavior under explicit deviced / procd ownership.

Functionally, it implements the driver startup, runtime, and validation contracts for serial. 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 driver logic behind explicit driver authority
• bind only to startup-assigned device, interrupt, and transport capabilities
• accept write identity from the provider endpoint rather than caller-supplied role telemetry
• serve bounded driver operations without creating public service authority
• keep driver validation and failure behavior documented for integration tests

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, rotating event loop over separate public-provider and private interrupt receivers.
• IRQD authority is the COM1-specific handler endpoint. Registration and ACK derive the line from that object; the driver has no registry or mask-control authority.
• Root unmasks COM1 after sealing IRQD policy. On notification, the driver drains at most one 16-byte 16550 receive FIFO before acknowledging the exact sequence. Validated provider reads also drain one bounded FIFO, so serial input progresses on platforms without a hardware COM1 interrupt route.
• Registration transfers one send-only alias of the private interrupt endpoint into IRQD's canonical COM1-handler slot and waits for the accepted transfer call's reply without resubmitting it or imposing an arbitrary retry count. The registration-only local alias is dropped immediately after acceptance; the service loop retains only the receive alias.
• Public calls and every received call reply must be authority-free. Unexpected received capabilities are dropped before the message is rejected; uncertain cleanup terminates the process.
• The shared message buffer is exactly sized for the fixed-role startup bundle and the largest serial response.
• Retained stream capacity is an explicit positive deployment setting. Image packaging patches an authenticated capacity descriptor and expands a private, page-rounded linker arena; the driver exposes only the selected prefix.
• Retained stream bytes are UART RX only. Transmitted bytes affect statistics but cannot be replayed as terminal input.
• A terminal 64 KiB stack reserve follows that arena, keeping startup stack growth disjoint from live retained bytes.
• No dynamic allocation and no external crates.

Feature flags

• drv-serial-runtime
• drv-serial-runtime-serial
• drv-serial-integration-smoke
• drv-serial-integration-force-fail
• drv-serial-integration-serial
• drv-serial-integration-serial-probe

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-ipc
• lib-service
• lib-interrupt
• lib-log
• ipc-syscall-x86_64

No third-party crates are used.

Validation Note

The host/test QUERY_CAP fallback remains cfg-scoped so runtime/release builds stay warning-free. Required deviced and IRQD calls use the shared retained-call transport: pre-acceptance backpressure may be retried, while an accepted call keeps its exact caller buffer until the reply is delivered. Optional integration-time logd diagnostics make one availability attempt and never delay provider readiness when logd is busy or absent. Runtime images suppress direct drv-serial debug proof lines (ERIX_DRV_SERIAL:UART_OK, ERIX_DRV_SERIAL:PROVIDER_ATTEMPT, and ERIX_DRV_SERIAL:PROVIDER_REGISTERED) while keeping the public ERIX_DEVICED:READY:DRV_SERIAL readiness marker visible through the service logging path. Logd may mirror an accepted record to serial after the logical submit reply, so diagnostic line order is not a provider-readiness contract. The provider path no longer carries a fallback kernel LOG_STRING helper; optional diagnostics use the lib-log submit path when a logd endpoint is explicitly present.

Each serial write makes one readiness observation before accepting its first byte and returns typed BUSY backpressure when the UART is not yet ready. After accepting a byte, the driver preserves the write as one operation and waits cooperatively for readiness before each remaining byte, yielding to the scheduler between observations without a private attempt ceiling. The reply is sent after all bytes enter the transmit holding register; the driver does not add an unnecessary final shift-register drain.

Optional logd probe/runtime marker submission uses the shared lib-log Rust-string submit helper. The driver does not build submit frames directly, maintain NUL scratch storage, or parse chunk responses locally.

Dynamic Boot Artifact Evidence

The image build packages drv-serial 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 deviced through procd dynamic driver creation with a role- derived executable identity; authority remains the COM1 endpoint, delegated IRQ peer, and explicit startup peers. 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. drv-serial receives only the documented startup endpoints, peers, and capabilities for its role.

Governance Principles

drv-serial governance is scoped to the serial driver role and its assigned hardware/provider authority.

The scoped governance rules are:

• It must be started and supervised through deviced and procd, not as an independently discovered public service.
• It uses only the device, interrupt, transport, and provider capabilities explicitly transferred at startup.
• It validates startup-wired peer slots through an explicitly supplied caller-local query operation.
• It keeps hardware-specific behavior inside the driver while leaving device-matching policy to deviced.
• It rejects malformed device state and unexpected authority instead of broadening access.

Authority Boundaries

• The driver receives no named authority; optional integration paths use only their explicitly declared peer endpoints.
• It receives no filesystem-provider or unrelated peer-driver authority.
• New hardware access requires explicit manifest, startup, and integration-test coverage.

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.