EriX Kernel

kernel is the policy-minimal microkernel core in the EriX boot chain.

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 kernel component. Its purpose in EriX is to provide the minimal capability kernel substrate for user-space services.

Functionally, it owns kernel memory, scheduling, interrupt, and capability primitives while keeping policy in user space. The repository keeps the implementation, interface contracts, tests, and documentation for that behavior in one reviewable ownership boundary.

The maintained responsibilities are:

• provide process, memory, interrupt, IPC, and capability primitives
• keep policy in user-space services wherever possible
• maintain the system-call and authority boundaries used by the rest of EriX

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.

Build Status

Current implementation status:

• strict bl -> kernel ingress wrapper and deterministic kernel markers
• multi-page bootloader handoff ingress for the current Filesystem provider work provider service set
• memory reservation extraction and untyped seed derivation (RAM + device)
• bootstrap object/capability setup for root CSpace/VSpace/TCB/endpoint/untyped pool
• kernel -> root handoff builder with lib-handoff validation roundtrip
• default kernel bootstrap path selects required root module and attempts CPL3 root launch
• runtime endpoint path no longer synthesizes non-root service replies in normal builds; service interactions use endpoint queue/call-recv-reply mechanics
• transfer-bearing runtime replies now also require GRANT on the replying endpoint slot itself, so capability materialization stays explicit in the sender's local policy instead of being inferred from endpoint receipt
• CAP_TYPE_DEVICE_FRAME is now a first-class capability type distinct from ordinary RAM frames, and the kernel-control path can derive one validated BAR-backed MMIO frame for deviced without exposing a generic device-memory escape hatch
• feature-gated rootd integration smoke syscall path (kernel-rootd-smoke-test) for deterministic VM completion:
  • accepts ROOTD_STAGE:* progress reports and emits deterministic stage markers without exiting
  • rootd ready -> 0x10
  • rootd internal failure/unknown status -> 0x13
  • downstream service bootstrap failure -> 0x14
• additive runtime-mode kernel rootd report path (kernel-rootd-runtime) is now the canonical feature; kernel-rootd-smoke-test remains as a compatibility alias used by smoke/negative integration scenarios
• runtime/appliance kernel builds enable kernel-runtime-image without kernel-rootd-smoke-test; deterministic debug-exit remains an integration harness opt-in, not part of packaged runtime images
• normal runtime builds seed only the narrow preinstalled runtime endpoints; the legacy SLOT_ROOT_ENDPOINT constant remains reserved for ABI stability but is no longer handed to rootd
• dev-profile early console feature (kernel-dev-console) mirrors kernel markers to framebuffer via lib-console until ROOTD_REPORT_STAGE_FBCOND_READY
• release-profile runtime can disable early kernel serial/framebuffer sink output while keeping userspace console services active
• centralized-process-authority deep runtime trace families stay smoke-only, so ordinary appliance dev/release images do not emit ad-hoc staged lifecycle or capability-trace chatter
• rootd stage-marker mapping includes phase3 input stages (DRV_I8042_READY, DRV_PS2_KEYBOARD_READY, DRV_PS2_MOUSE_READY, INPUTD_READY, INPUT_ROUTING_READY, CONSOLE_INPUT_READY)
• rootd stage-marker mapping now also includes the current filesystem slice (MEMORY_PROVIDER_READY, VFSD_READY, VFS_MOUNT_READY, VFS_IO_READY)
• rootd runtime report decoding recognizes the expanded VFS backend operation debug family (rename, truncate, symlink, readlink, link, and metadata update) so diagnostics remain non-terminal during filesystem API verification
• rootd stage-marker mapping now also includes storage bring-up (BLOCKD_READY, STORAGE_READY)
• rootd stage-marker mapping now also includes Filesystem provider work filesystem providers, private key service, and program-loader service (KEYD_READY, E2FSD_READY, FATD_READY, LOADERD_READY, FS_MOUNT_READY, PERSISTENT_FS_IO_READY)
• kernel-control op READ_PLATFORM_CAPS (30) exposes deterministic platform-presence bits for probe-gated driver activation
• kernel-origin failure class is 0x12 in kernel binary integration flow
• scheduler/SMP/exception selftests retained behind explicit feature flags
• runtime IPC dispatch now enforces endpoint send/recv rights:
  • CALL / NOTIFY require SEND
  • RECV / REPLY require RECV
• timed runtime CALLs now also prefer a running receiver that shares the callee endpoint's CSpace recv binding, even when that service TCB is bound to a different local endpoint slot inside the same process
• kernel-control slot arguments used by process/capability operations are now constrained to the caller-visible process window
• kernel-control op QUERY_CAP (34) now exposes local capability type/rights for startup-time authority inventory checks without opening foreign-slot visibility
• kernel-control op QUERY_CAP (34) now also supports opt-in endpoint-kind reporting via IPC_KERNEL_CONTROL_QUERY_CAP_FLAG_INCLUDE_ENDPOINT_KIND, with the upper 32 bits of value1 carrying endpoint kind while non-endpoint caps report GENERIC/0
• kernel-control op CREATE_ENDPOINT (35) now materializes a fresh send/recv endpoint in one caller-local slot, which rootd uses through the dedicated CHILD_POPULATE endpoint family to seed explicit startup-only control surfaces before service bootstrap
• kernel-control fast-path dispatch is now keyed by the endpoint object's stored family kind rather than by canonical slot numbers: the optional test-only root endpoint retains the full kernel-operation surface when enabled, while normal runtime boot seeds rootd with the dedicated log endpoint plus the narrow runtime endpoint inventory: the dedicated timed endpoint at slot 2128 accepts only READ_MONOTONIC_CLOCK and local QUERY_CAP
• the dedicated irqd endpoint at slot 2144 accepts only interrupt-control and timing operations needed by irqd
• the dedicated hotplugd endpoint at slot 2160 accepts only hotplug-event wait plus local QUERY_CAP
• the dedicated PCI-config endpoint at slot 2176 accepts only READ_PLATFORM_CAPS, READ_PCI_CONFIG_DWORD, and local QUERY_CAP
• the dedicated console endpoint at slot 2192 accepts only framebuffer/font query/map operations, LOG_STRING, and local QUERY_CAP
• the dedicated COM1 endpoint at slot 2208 accepts only IOPORT_READ8, IOPORT_WRITE8, and local QUERY_CAP, with hardware-port policy restricted to 0x3F8..=0x3FF
• the dedicated memory endpoint at slot 2224 accepts only RETYPE_UNTYPED_TO_FRAME and local QUERY_CAP
• the dedicated vspace endpoint at slot 2240 accepts only MAP_FRAME, UNMAP_FRAME, and local QUERY_CAP
• the dedicated pager endpoint at slot 2256 accepts only RESOLVE_FAULT and local QUERY_CAP
• the dedicated log/query endpoint at slot 2272 accepts only QUERY_CAP, LOG_STRING, and WRITE_LEGACY_SERIAL, which narrows deviced's runtime control surface to startup inventory checks and logging
• the dedicated process-control endpoint at slot 2288 accepts only the bounded process/capability lifecycle ops procd actually uses; CAP_COPY (8) is reserved/denied, so runtime duplication stays on CAP_COPY_ATTENUATED instead of leaving a full-rights local copy path on the process endpoint
• the dedicated ACPI endpoint at slot 2320 accepts only READ_PLATFORM_CAPS, GET_ACPI_RSDP, READ_ACPI_QWORDS, and local QUERY_CAP
• the dedicated i8042 endpoint at slot 2336 accepts only IOPORT_READ8, IOPORT_WRITE8, and local QUERY_CAP, with hardware-port policy restricted to 0x60 and 0x64
• canonical boot-root slot numbers no longer imply authority in non-root CSpaces; runtime policy follows the endpoint kind or cap actually installed in the caller's local slot, and services consume only their explicit local startup transfers instead of inferring access from slot numbers
• syscall QUERY_LOCAL_CAP (0x45) now exposes the same caller-local slot type/rights introspection path to peer-only services that do not carry a kernel-control endpoint, and on x86_64 it now returns additive endpoint-kind metadata in r8
• syscall DROP_LOCAL_CAP (0x47) now lets callers clear one caller-local slot directly so fixed-slot peer bindings can be dropped before retrying late rematerialization
• READ_ACPI_QWORDS now rejects arbitrary physical reads; the requested window must be fully contained in the RSDP, XSDT/RSDT, or a checksum-valid ACPI table reachable from that root walk
• bootstrap/root CSpace capacity is now 4096 slots so explicit local slots in the extended startup-transfer range remain representable without falling back to shared canonical windows
• runtime TCB records now carry private CSpace/VSpace identities, and kernel slot lookup resolves against the current process CSpace rather than a single shared runtime slot table
• endpoint capability copy/move/drop now preserves endpoint-object identity across multiple local slots:
  • copied endpoint caps alias the same endpoint runtime queue
  • dropping one alias removes only that slot binding
  • kernel-control family dispatch follows the endpoint object, so a copied local control slot keeps the same bounded policy surface as the canonical control endpoint it aliases
• kernel-control op CAP_COPY_ATTENUATED (36) now installs explicit rights-reduced local aliases, which rootd uses to materialize startup control and driver-lifecycle slots instead of treating transfer descriptors as metadata only
• runtime IPC now supports explicit capability transfer tables on CALL, REPLY, and NOTIFY messages when the sender's endpoint cap carries GRANT
• CAP_TYPE_INSTALL_GRANT is now implemented in-kernel for staged child population, and START_PROCESS is denied while live grants still target the child stage
• kernel-control ops CREATE_STAGED_PROCESS (37), DERIVE_INSTALL_GRANT (38), INSTALL_WITH_GRANT (39), and ABORT_STAGED_PROCESS (40) now provide private-child creation and scoped startup-cap installation
• staged child creation now emits the same ERIX_KERNEL:PHASE2:CSPACE_WINDOW_SET smoke marker as the explicit window-setting control path, so integration validation observes child-window establishment independent of which kernel entrypoint performed it
• legacy kernel-control op CREATE_PROCESS (1) is now reserved for ABI stability and denied at runtime; staged child creation is the supported process-creation path
• TCB endpoint and pager registration now validate the target process's private CSpace instead of assuming the caller's current CSpace
• kernel-control op KILL_PROCESS (33) provides explicit managed-stop support for procd
• kernel-control op WRITE_PROCESS_MEMORY (44) copies caller bytes only into already mapped anonymous child process pages, allowing procd to populate file-backed loader images without accepting caller-selected frame or VSPACE authority
• initial syscall-resume frames are written into the target VSpace's anonymous stack backing before first activation, so materialized file-backed children do not depend on the caller's currently active page mapping

Governance Principles

kernel governance is scoped to minimal mechanism: scheduling, memory, IPC, interrupts, and capability enforcement.

The scoped governance rules are:

• Policy belongs in user-space services unless enforcing it in the kernel is necessary for isolation.
• Capability checks must be explicit and auditable at every authority boundary.
• Unsafe Rust and architecture-specific code must stay narrow, documented, and covered by invariants.
• Kernel ABI changes require matching updates in libraries, services, and integration validation.

Authority Boundaries

• The kernel creates and enforces capabilities; it does not grant ambient service authority.
• New kernel mechanisms must preserve deterministic startup and fail-closed behavior.

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.