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
• 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 event loop with mixed RPC and interrupt-notify handling.
• Fixed message buffers (IPC_MSG_BUFFER_BYTES = 1024).
• Fixed RX ring (RX_RING_CAPACITY = 4096).
• No dynamic allocation and no external crates.

Feature flags

• drv-serial-integration-smoke
• drv-serial-integration-force-fail
• drv-serial-integration-phase3-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 branch-aware dependency overrides.

Dependencies

• lib-bootstrap
• lib-capabi
• lib-ipc
• lib-service
• lib-interrupt
• 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. The transfer-reply probe used to exercise the optional transfer-bearing lookup path remains unit-test-only, so default builds keep the startup-wired peer path warning-free as well. The shorter logd control-call timeout used by optional Phase3 serial integration transport stays cfg-scoped with that transport, so runtime/release builds keep the default control path warning-free as well. 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.

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 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

• drv-serial does not receive named, filesystem-provider, or 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.