drv-ps2-mouse

drv-ps2-mouse is the EriX PS/2 mouse 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 pointer events accepted by inputd.

The maintained responsibilities are:

• validate the exact startup role and delegated capability inventory;
• consume the mouse-only i8042 stream through its fixed send client;
• assemble synchronized standard three-byte PS/2 packets;
• decode their button state and complete nine-bit signed motion counters;
• detect stream discontinuities before completing a partial packet;
• append normalized events through the fixed mouse-producer endpoint; and
• reject unwanted authority and terminate on state whose cleanup or delivery cannot be proven.

Low-level controller access and mouse mode selection belong to drv-i8042. Event retention and routing 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 mouse 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.
• 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 packet.
• The decoder preserves the standard packet's full signed displacement range and converts upward-positive PS/2 Y motion to downward-positive screen motion.
• No heap allocation or runtime service discovery is used.

Feature flags

• drv-ps2-mouse-runtime
• drv-ps2-mouse-runtime-input
• drv-ps2-mouse-integration-smoke
• drv-ps2-mouse-integration-input
• drv-ps2-mouse-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-mouse 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-mouse 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 mouse-read client, mouse-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.
• New hardware modes or peer access require 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.