lib-ipc

lib-ipc defines shared IPC ABI primitives 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 IPC library. Its purpose in EriX is to provide reusable IPC primitives and contracts to EriX components.

Functionally, it exposes the IPC 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-ipc crate API for IPC 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

Implemented baseline:

• transport syscall IDs (0x40/0x41/0x42) and result codes
• typed payload header/body helpers
• kernel-control operation IDs and fixed request/response body structs
• legacy kernel-control op CREATE_PROCESS (1) retained as a reserved ABI ID while staged child creation remains the supported runtime process-creation path
• core service operation IDs and status/spawn body structs
• typed core procd lifecycle bodies for:
  • reserved ADOPT_PROCESS (0x403) compatibility ABI
  • STOP_PROCESS (0x404)
  • WAIT_PROCESS_EVENT (0x408)
  • QUERY_PROCESS (0x409)
  • SET_RESTART_POLICY (0x40A)
  • GET_RESTART_POLICY (0x40B)
  • UPDATE_FOUNDATION_ENDPOINTS (0x40C)
  • LAUNCH_LOADED_IMAGE (0x40D) retained as a reserved/denied legacy loader summary handoff
  • BEGIN_LOADER_IMAGE_TRANSFER (0x40E), SEND_LOADER_IMAGE_CHUNK (0x40F), and COMMIT_LOADER_IMAGE_TRANSFER (0x410) for the bounded file-backed image materialization and static-bootstrap launch ABI
• kernel-control process-stop operation KILL_PROCESS (33) and managed-stop kill reason constant
• kernel-control local-slot introspection operation QUERY_CAP (34)
• kernel-control endpoint-creation operation CREATE_ENDPOINT (35) for explicit runtime endpoint materialization in caller-local slots
• kernel-control attenuated-capability-copy operation CAP_COPY_ATTENUATED (36) for rights-reduced startup materialization into caller-local slots
• staged process-control operation IDs:
  • CREATE_STAGED_PROCESS (37)
  • DERIVE_INSTALL_GRANT (38)
  • INSTALL_WITH_GRANT (39)
  • ABORT_STAGED_PROCESS (40)
• kernel-control process image population operation WRITE_PROCESS_MEMORY (44) for copying caller bytes only into already mapped anonymous child process pages
• typed procd staged lifecycle bodies for:
  • CREATE_STAGED_PROCESS (0x405)
  • START_STAGED_PROCESS (0x406)
  • ABORT_STAGED_PROCESS (0x407)
• phase2 driver start bodies now carry explicit device_cap_slot, device_mmio_base, and device_mmio_size fields for narrowed storage bring-up
• caller-local capability introspection syscall QUERY_LOCAL_CAP (0x45) for peer-only services that do not carry a control endpoint
• caller-local capability drop syscall DROP_LOCAL_CAP (0x47) so peer-only services can clear stale local slots before rematerializing dynamic peers
• additive endpoint-kind reporting for local capability introspection:
  • on x86_64, QUERY_LOCAL_CAP now returns status in rax, cap_type/rights in rdx, and endpoint_kind in r8
  • non-endpoint capabilities report endpoint kind GENERIC/0
• additive kernel-control query flag IPC_KERNEL_CONTROL_QUERY_CAP_FLAG_INCLUDE_ENDPOINT_KIND, which extends QUERY_CAP replies to report endpoint kind in the upper half of value1
• dedicated narrow endpoint-kind IDs for PciConfigRead, AcpiRead, Com1Io, and I8042Io
• rootd stage IDs now include BLOCKD_READY and STORAGE_READY, and the kernel-control registry includes DERIVE_PCI_BAR_DEVICE_FRAME (42) plus the block-provider interface class used by deviced
• capability-transfer table parse helpers for typed payloads, including the header flag IPC_MESSAGE_FLAG_CAP_TRANSFER_TABLE_V1 and the fixed v1 transfer-table prelude used by transfer-bearing replies
• Public/private filesystem bodies implemented: public vfsd ops for mount, file I/O, directory I/O, and metadata plus private generic filesystem-provider op bodies for volatile-memory, ext, and FAT backends
• Key authority bodies implemented for private keyd lookup and zeroize operations; these bodies are private provider plumbing and do not expose key material through named
• Filesystem provider work generic filesystem provider bodies implemented: provider kind constants, public mount_fs fields, and private provider mount, open/create/mkdir, read/write, readdir/stat, rename, truncate, symlink/readlink, link, metadata update, close, unlink, and rmdir request/response bodies shared by ramfsd, e2fsd, fatd, and vfsd
• VFS stat responses now carry mode, link count, uid/gid, allocation size, device number, timestamps, and filesystem flags; xattr IPC remains out of scope for this v1 expansion.
• VFS path and directory-entry name fields now carry bounded UTF-8 byte sequences. The wire sizes and op IDs are unchanged; invalid UTF-8, NUL bytes, empty components, ., .., non-canonical paths, and non-zero padding still fail closed.
• rootd stage-report constants now include MEMORY_PROVIDER_READY, VFSD_READY, VFS_MOUNT_READY, and VFS_IO_READY
• Phase 4.7 loader contract bodies now define path discovery plus path-only native launch request/response formats, bounded argument/environment blocks, loader-visible source metadata, deterministic failure codes, and explicit no-inherit authority policy for the first loaderd surface
• Phase 4.7.7 loader image transfer bodies now define the ordered loaderd -> procd materialization ABI: source identity, source size/hash, plan hash, segment descriptors, inline chunk ranges, zero-fill ranges, W^X permissions, entry/stack bounds, and pre-mutation sequence validation for executable and dynamic-object image kinds
• Phase 4.7.8 uses the transfer ABI as the active filesystem-byte launch path; the legacy summary body remains an ABI id but cannot represent successful disk-backed execution
• Phase 4.7 closure keeps the loader ABI as the final static-bootstrap bridge: focused VM groups prove VFS policy rejection, malformed transfer/ELF rejection, true disk-byte execution, stale-source rejection, cleanup, and unwanted-authority denial while Phase 5.4 remains responsible for dynamic object dependency resolution
• test-only rootd/service completion syscall/status constants

Governance Principles

lib-ipc governance is scoped to reusable IPC 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-ipc 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.