lib-interrupt

lib-interrupt provides typed client helpers for the EriX interrupt routing service.

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 interrupt library. Its purpose in EriX is to provide reusable interrupt primitives and contracts to EriX components.

Functionally, it exposes the interrupt APIs, validation tests, and documentation used by dependent repositories. The repository keeps the implementation, interface contracts, tests, and documentation for that behavior in one reviewable ownership boundary.

The maintained responsibilities are:

• expose the lib-interrupt crate API for interrupt behavior used by dependent components
• keep data formats, constants, and validation helpers documented and tested
• preserve clean-room, no-external-crate implementation boundaries
• maintain compatibility expectations for downstream repositories

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

• Request helpers implemented:
  • register_handler_with_attached_endpoint
  • ack
• Blocking wait helper implemented:
  • wait_next
• Notify parsing accepts both framed notify messages and raw notify payload deliveries used by current runtime.
• Interrupt request, response, and notify bodies contain only fields consumed by the routing contract; no reserved alignment or tail words remain. Events expose sequence, line, and CPU delivery identity only, without a timestamp the routing service cannot validate.

Validation guarantees

lib-interrupt validates:

• endpoint slot non-zero,
• response size/op-id/request-id consistency,
• exact 16-byte notify payload shape.

The endpoint capability selects the interrupt line. The public client API therefore accepts neither a caller-selected line nor mask-control requests; mask policy belongs to root orchestration. Registration always attaches exactly one send-only handler capability. Its caller-local source slot and IRQD-local destination slot are separate coordinates; neither is carried in the request body.

Errors are returned as typed Error values.

Build and test

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

Dependencies

• lib-ipc
• lib-capabi

No third-party crates are used.

Governance Principles

lib-interrupt governance is scoped to reusable interrupt contracts shared by dependent repositories.

The scoped governance rules are:

• It must expose narrow, documented APIs rather than component-specific policy.
• It keeps wire formats, constants, parsers, and validation helpers deterministic and testable.
• It preserves clean-room implementation boundaries and does not introduce external crate dependencies.
• Breaking API or format changes require coordinated updates in every dependent repository.

Library Boundaries

• lib-interrupt carries no runtime authority by itself; authority is held by callers that use the library.
• The crate must not hide ambient I/O, allocation policy, or service discovery behind helper APIs.

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.