drv-ps2-keyboard

drv-ps2-keyboard is the EriX PS/2 keyboard protocol translator daemon.

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, service, library, driver, and integration contracts.

Purpose of This Repository

This repository owns translation between the byte stream supplied by drv-i8042 and normalized key events accepted by inputd.

The maintained responsibilities are:

• validate the exact startup role and delegated capability inventory;
• consume the keyboard-only i8042 stream through its fixed send client;
• decode PS/2 scan-code set 1 make, break, extended, Print Screen, and Pause sequences;
• detect stream discontinuities before applying a retained prefix;
• append normalized events through the fixed keyboard-producer endpoint; and
• reject unwanted authority and terminate on state whose cleanup or delivery cannot be proven.

Low-level controller access belongs to drv-i8042. Event retention, routing, and console projection belong to inputd.

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.

Runtime model

• The daemon is single-threaded and performs at most one keyboard read plus one nonblocking service-endpoint receive per scheduling turn.
• A validated empty controller reply skips exactly seven subsequent backend read turns. Every turn still scans the private receiver; any consumed byte, including a partial decode, permits another read on the next turn. This is a turn bound, not a wall-clock deadline, and introduces no timing authority.
• Only a correlated NOT_FOUND with zero sequence and byte value arms this backoff. Errors retain the existing fail-stop path, without retry.
• Idle turns yield cooperatively; no service-local tick or attempt budget limits accepted work.
• The startup receive buffer is derived from the exact three-transfer role envelope. The reusable peer-call buffer is derived from the larger of the fixed i8042 and inputd message bodies.
• Required calls retain their request storage from kernel acceptance through the authoritative reply. Accepted replies remain retained through delivery.
• A correlated inputd NOT_FOUND means that no focused session or pending trusted prompt accepted the physical event. The decoded controller byte is consumed without terminating the private driver; every other non-success append result remains terminal.
• Complete unwanted capability receipts are dropped before a message is rejected. Uncertain cleanup and terminal peer failures tear down the process so no residual authority remains.
• Stream sequence gaps, restarts, and rollover discard any partial multi-byte decode state.
• No heap allocation or runtime service discovery is used.

Feature flags

• drv-ps2-keyboard-runtime
• drv-ps2-keyboard-runtime-input
• drv-ps2-keyboard-integration-smoke
• drv-ps2-keyboard-integration-input
• drv-ps2-keyboard-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-input
• ipc-syscall-x86_64

All Cargo Git dependencies use full 40-character commit rev pins. Integration source revisions and CI caches preserve those Git objects without branch-head or synthetic-commit substitution. No third-party crates are used.

Dynamic boot artifact evidence

The runtime image packages drv-ps2-keyboard as an ELF64 x86_64 ET_DYN executable with authenticated dynamic-link metadata. Catalog and filesystem mirror records establish artifact identity but grant no filesystem, loader, object-store, service-discovery, provider-bypass, block-device, or dynlinkd authority.

Governance Principles

drv-ps2-keyboard governance is scoped to its private translation role.

• deviced and procd own lifecycle; the daemon does not self-register or discover peers.
• The only steady-state authority is the startup-delegated keyboard-read client, keyboard-append client, and private receive endpoint.
• The primary control slot may be zero because this role performs no direct kernel-control operation.
• Peer replies and unexpected inbound calls must not delegate authority. Complete unwanted receipts are retired before rejection.
• Downstream rejection cannot grant authority: a correlated NOT_FOUND drops only that event and leaves no deferred event or session/prompt selector in the driver.
• New hardware or peer access requires an explicit startup contract and integration coverage.

Contact

Development occurs in the 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.