drv-i8042

drv-i8042 is the userspace i8042 controller owner for EriX input bring-up.

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

Functionally, it implements the driver startup, runtime, and validation contracts for i8042. The repository keeps the implementation, interface contracts, tests, and documentation for that behavior in one reviewable ownership boundary.

The maintained responsibilities are:

• implement the i8042 driver logic behind explicit driver authority
• bind only to the startup-assigned controller and receive capabilities
• serve typed 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 loop.
• Message storage is the exact fixed-role startup envelope, which dominates all runtime requests and responses.
• Keyboard and mouse FIFO capacities are independent positive deployment selections installed as exact slices of one authenticated page-rounded arena.
• Startup enables both controller ports, restores standard PS/2 mouse defaults, and requires the exact auxiliary acknowledgements before enabling stream reporting or publishing readiness.
• No dynamic allocation and no access to arena padding.
• An empty controller observation skips seven subsequent hardware polls, but every service turn still scans the three disjoint receiver endpoints. Any consumed byte resumes polling on the next turn to drain bursts. The bounded counter adds no clock/IRQ authority and does not change startup handshakes.

Feature flags

• drv-i8042-runtime
• drv-i8042-runtime-input
• integration feature selections:
  • drv-i8042-integration-smoke
  • drv-i8042-integration-input
  • drv-i8042-integration-force-fail

Build and test

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

Dependencies

• lib-bootstrap
• lib-capabi
• lib-ipc
• lib-service
• 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. Startup waits on its explicitly delegated endpoint without a private deadline. Caller messages and kernel replies must be authority-free; complete unwanted receipts are retired, while malformed receipt state or uncertain cleanup terminates the process. Kernel calls and every accepted reply retain their encoded buffers through transient delivery backpressure. Each startup controller write waits cooperatively for the i8042 input buffer and mouse command acknowledgements are accepted only from the auxiliary output. Every service turn observes at most one controller byte and then scans all three runtime endpoint families nonblockingly, so controller traffic and independent keyboard, mouse, and diagnostic authority all make progress without a private polling batch limit.

Dynamic Boot Artifact Evidence

The runtime image contract documents drv-i8042 as a dynamic boot artifact. The image build packages the i8042 controller driver service 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 dedicated i8042 endpoint and explicit startup peers. Keyboard reads, mouse reads, and root diagnostics arrive on three distinct endpoint objects; a translator cannot read the other stream or invoke diagnostic/test operations. 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-i8042 receives only the documented startup endpoints, peers, and capabilities for its role.

Governance Principles

drv-i8042 governance is scoped to the i8042 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 controller-I/O and receive 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-i8042 does not receive named, filesystem-provider, or peer-driver authority.
• The assigned service endpoint accepts root-controlled diagnostics only. Keyboard and mouse byte reads require their respective receive bindings.
• Controller-I/O failure, terminal receive/reply failure, or uncertain capability cleanup causes process teardown rather than a spinning task that retains delegated 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.