irqd

irqd is the interrupt routing 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 irq service daemon. Its purpose in EriX is to provide the irq service role through explicit IPC and startup authority.

Functionally, it implements the daemon runtime, state model, IPC handling, and validation tests. The repository keeps the implementation, interface contracts, tests, and documentation for that behavior in one reviewable ownership boundary.

The maintained responsibilities are:

• implement the irq service runtime and state model
• validate startup authority before accepting IPC requests
• handle authority-scoped service operations through the assigned endpoint set
• keep service behavior, tests, and authority invariants documented

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.

Status

• IRQ routing paths are implemented for IPC_INTERRUPT_LINE_LAPIC_TIMER and IPC_INTERRUPT_LINE_UART_COM1.
• Root orchestration integration is implemented (named -> timed -> logd -> crashd -> irqd -> ...).
• Runtime interrupt and ACK control now use only the startup-assigned primary control slot.
• Runtime request, response, and notification bodies contain no reserved alignment or tail words. Event notifications carry only sequence, line, and CPU delivery identity; they do not claim a timestamp IRQD cannot validate.
• irqd now receives a dedicated primary control slot at SLOT_KERNEL_IRQ_ENDPOINT (2144) instead of the broad root endpoint.
• The dedicated kernel endpoint permits only wait, acknowledge, and line configuration operations. Startup capability inspection uses the local capability-query syscall, not extra endpoint authority.
• Startup ready-state validates actual local slot type/rights with bare-metal QUERY_LOCAL_CAP and host/test QUERY_CAP fallback.
• The linker now keeps the dedicated .stack_reserve inside the loaded image so early startup validation does not fault on stripped reserve pages.
• Handler records now come from an exact deployment-patched arena. The service validates the embedded record layout and authenticated count, borrows only that typed prefix, and retains no allocator over page padding.
• Positive, SMP, and missing-service negative VM scenarios are implemented and passing.

Runtime model

irqd lifecycle:

1. Startup envelope validation and ready reply.
2. Root-seeded handler tuple intake (SEED_HANDLER) and SEAL.
3. Root unmasks the seeded lines through the administrative endpoint.
4. Handler activation by exact tuple match (REGISTER_HANDLER) on the line-bound LAPIC-timer or COM1 endpoint.
5. Interrupt wait/dispatch loop:
   • wait kernel interrupt event,
   • send typed notify payload to registered handler endpoint,
   • require explicit ACK on the same line-bound endpoint before the next delivery for the line. LAPIC-timer and COM1 pending state is independent, so one delayed handler does not stop the other line.

The root-only administrative endpoint accepts seed, seal, and mask-control operations. Handler endpoints accept only registration and acknowledgement; the endpoint object supplies the line, so callers cannot select or control another line.

Registration must deliver exactly one kernel-normalized send-endpoint receipt. IRQD uses the receipt's destination as its retained local handler slot; the caller's source slot may differ and is never treated as an IRQD-local coordinate. Missing, malformed, excess, or wrong-shaped receipts are denied. Every destination not retained by a successful registration is visited and dropped before reply, including destinations after an earlier failed drop attempt. If complete cleanup cannot be proven, IRQD asks the kernel to tear down its process rather than retain uncertain authority.

The cooperative event loop polls all three authority planes. A transfer-bearing caller reported as waiting is received without a private deadline; idle endpoints use zero-time polls and never park IRQ dispatch or another line's control traffic. Replies and notifications retry kernel backpressure without a service-imposed attempt ceiling. Queued notifications receive one fair attempt per loop pass, while terminal transport failures tear down the process. The kernel interrupt wait operation is a direct nonblocking poll: a syscall or typed response RETRY means that no event is currently available and does not tear down IRQD. Other failures remain terminal. Process exit codes encode the exact failure plane above the complete status word, distinguishing panic, kernel wait, notification delivery, unclaimed acknowledgement, pending-event collision, LAPIC handler, COM1 handler, and administrative failures without collapsing one endpoint or operation into another.

The registry's record count is deployment policy installed into the signed service image. Exhaustion reports BUSY for that concrete deployment; there is no crate-wide handler ceiling or caller-side duplicate cap.

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. The runtime path now uses only the kind-aware query helper so release image builds do not retain dead local-cap wrappers.

Dynamic Boot Artifact Evidence

The runtime image contract documents irqd as a dynamic boot artifact. The image build packages the interrupt service daemon 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 rootd through procd staged dynamic creation before dynlinkd; authority remains the dedicated IRQ-control endpoint and 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. irqd receives only the documented startup endpoints, peers, and capabilities for its role.

Governance Principles

irqd governance is scoped to interrupt registration and event distribution.

The scoped governance rules are:

• It registers interrupt consumers only through explicit authority.
• It permits one pending delivery per line and validates interrupt ownership before dispatch.
• It keeps hardware interrupt routing policy outside individual drivers.
• It does not grant device or process-management authority to consumers.

Authority Boundaries

• irqd operates only through startup-assigned service capabilities.
• New authority must be represented in bootstrap/capability validation and integration tests before use.

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.