IPC and Endpoints

Endpoints let one process serve capability calls to another process without adding a separate IPC syscall surface. The same ring transport carries ordinary kernel capability calls and cross-process endpoint calls.

Status: Partially implemented. Ring-native endpoint CALL/RECV/RETURN, client endpoint attenuation, badges, copy and move capability transfer, direct IPC handoff, transfer delivery rollback helpers, and cleanup for many exit paths are implemented. Notification objects, promise pipelining, shared buffers, and revocation remain open.

Current Behavior

An Endpoint is a kernel capability object with queues for pending client calls, pending server receives, and in-flight calls awaiting RETURN. A service that owns the raw endpoint can receive and return. Importers receive a ClientEndpoint facet that can CALL but cannot RECV or RETURN.

sequenceDiagram
    participant Client
    participant ClientRing as Client ring
    participant Endpoint
    participant ServerRing as Server ring
    participant Server
    Server->>ServerRing: submit RECV on raw endpoint
    Client->>ClientRing: submit CALL on client facet
    ClientRing->>Endpoint: deliver params and caller result target
    Endpoint->>ServerRing: complete RECV with EndpointMessageHeader and params
    ServerRing-->>Server: cap_enter returns completion
    Server->>ServerRing: submit RETURN with call_id and result
    ServerRing->>Endpoint: take in-flight target
    Endpoint->>ClientRing: post caller CQE with result and badge
    ClientRing-->>Client: wait returns matching completion

If a CALL arrives before a RECV, the endpoint queues bounded params. If a RECV arrives before a CALL, the endpoint queues the receive request. Delivered calls move into the in-flight queue until the server returns or cleanup cancels them.

Design

Endpoint IPC is capability-oriented. The manifest can export a raw endpoint from one service; importers get a narrowed client facet. This keeps server-only authority out of clients without introducing rights bitmasks.

CALL and RETURN may carry sideband transfer descriptors. Copy transfers insert a new cap into the receiver while preserving the sender. Move transfers reserve the sender slot, insert the destination, then remove the source on commit. RETURN-side transfers append result-cap records after the normal result payload.

Badges are stored on cap-table hold edges and delivered to servers with endpoint invocation metadata, so one endpoint can distinguish callers without one object per caller.

Future IPC should add notification objects for lightweight signaling and promise pipelining for Cap’n Proto-style dependent calls.

Invariants

Only raw endpoint holders may RECV or RETURN.
Imported endpoint caps are ClientEndpoint facets and must reject RECV and RETURN from userspace.
Endpoint queues are bounded by call count, receive count, in-flight count, per-call params, and total queued params.
Each in-flight call has a kernel-assigned non-zero call_id.
CALL delivery copies params into kernel-owned queued storage before the caller can resume.
Move transfer commit must not leave both source and destination live.
Transfer rollback must preserve source authority if destination insertion or result delivery fails.
Process exit must cancel queued state involving that pid and wake affected peers when possible.

Code Map

kernel/src/cap/endpoint.rs - endpoint queues, client facet, call IDs, cancellation by pid.
kernel/src/cap/ring.rs - endpoint CALL/RECV/RETURN dispatch, result copying, deferred cancellation CQEs.
kernel/src/cap/transfer.rs - transfer descriptor loading and transaction preparation.
capos-lib/src/cap_table.rs - cap-table transfer primitives and rollback.
kernel/src/cap/mod.rs - manifest export resolution and client-facet construction.
capos-config/src/ring.rs - EndpointMessageHeader, transfer descriptors, transfer result records, endpoint opcodes.
demos/capos-demo-support/src/lib.rs - endpoint, IPC, transfer, and hostile IPC smoke routines.
demos/endpoint-roundtrip, demos/ipc-server, demos/ipc-client - QEMU smoke binaries.

Validation

make run validates same-process endpoint RECV/RETURN, cross-process IPC, endpoint exit cleanup, badged calls, transfer success/failure paths, and clean halt.
make run-spawn validates init-spawned endpoint-roundtrip, server, and client processes.
cargo test-lib covers cap-table transfer preflight, provisional insertion, commit, rollback, stale generation, and slot exhaustion cases.
cargo test-ring-loom covers ring queue behavior that endpoint IPC depends on for completion delivery.

Open Work

Add notification objects for signal-style events.
Add Cap’n Proto promise pipelining after endpoint routing can resolve dependent answers.
Add shared-buffer or memory-object capabilities for bulk data transfer.
Add epoch-based revocation if broad authority invalidation becomes necessary.

Keyboard shortcuts