Crate godspeed_sdk 

GodspeedOS service SDK.

All userspace services link against this crate. It provides the typed wrappers around kernel syscalls so service code never issues raw syscalls.

A service, whole

Everything a service is fits in one picture, and it is worth having in your head before reading any module here.

  contracts/ping.toml         what the service ASKS for, in writing
    ipc_send    = ["pong"]
    ipc_receive = ["ping"]
    log_write   = true
           │
           │   the supervisor spawns it with a spawn REQUEST (its spawn
           │   row, held to this contract by contract_check), and the
           │   KERNEL mints exactly what that request grants. Not one more.
           │   The kernel never reads the contract (CLAUDE.md 13.6).
           ▼
  ┌──────────────────────────────────────────────────────────┐
  │  ServiceContext        the only door to the outside      │
  │                                                          │
  │  ctx.log(..)      ctx.try_send(..)     ctx.recv()        │
  │  ctx.alloc_mem(..)   ctx.spawn(..)     ctx.mmio()        │
  └──────────────────────────────────────────────────────────┘
           │
           ▼
  fn service_main(ctx) -> !      a loop that never returns

Three consequences, and they are the whole model:

• What the spawn request did not grant, the service cannot do. There is no ambient authority to fall back on: no root, no inherited handles, no global namespace. A call whose capability was never granted returns CapNotHeld - it does not fail late or half-succeed.
• ServiceContext is the only way out. Everything crossing the boundary goes through it, so the answer to “what can this service reach?” is its spawn request plus this type, and nothing else needs reading to be sure. (The contract is where a reviewer reads that request, and the checkers hold the two together.)
• Failure is a value, never a surprise. EndpointDead, CapRevoked, AllocDenied are ordinary Results a service is expected to handle: a peer that died is reacquired by name and the work retried. Services are killed and restarted routinely, including by the chaos suite, so this path is the common one rather than the exception.

examples/ping is the whole of the above in about forty lines, contract included.

Where the unsafe lives

Service code contains none. §18.1 designates syscall.rs, mmio.rs, dma.rs and adversarial.rs; in practice the largest holder is service_context.rs (77 lines) with ipc.rs (8), both recorded as GRANDFATHERED FLOORS by §18.5’s 2026-09-12 amendment and the three amendments after it (audits/unsafe-audit.md has the counts) - nearly all of them are unsafe { raw_syscall(..) } call sites, and they may rise only by a §18.5 amendment. Every block carries a SAFETY argument. (This said the unsafe “is confined to syscall.rs, mmio.rs and dma.rs”, which left the largest holder unnamed.) scripts/unsafe_check.py fails the build on an unsafe in any service, which is what keeps that true rather than merely intended.

Re-exports

pub use capability::CapHandle;

pub use capability::CapError;

pub use dma::Dma;

pub use ipc::Message;

pub use ipc::IpcError;

pub use mmio::Framebuffer;

pub use mmio::Mmio;

pub use record::Table;

pub use record::Value;

pub use record::RecordSink;

pub use record::parse_predicate;

pub use service_context::ServiceContext;

pub use service_context::TaskStat;

pub use service_context::CapInfo;

pub use service_context::Datetime;

pub use service_context::ClockSource;

pub use service_context::ReqOutcome;

pub use service_context::DeadlineOutcome;

pub use service_context::USB_DISK_BUSY;

pub use service_context::USB_DISK_ABSENT;

Modules

adversarial

Adversarial test primitives for the §22 red-team / fuzz / chaos harness (the probe service).

capability

Typed capability handles for service code - §7.

churn

The self-describing content pattern that makes a TORN FILE detectable.

dma

DMA arena access for userspace driver services (§12, §18).

hid

USB HID boot-protocol decoding, shared by the USB host drivers (xhci, ehci, dwc2).

ipc

IPC syscall wrappers - §8.2.

memory

A bounded block of this task’s own memory, as a byte slice.

mmio

Memory-mapped I/O access for userspace driver services (§12, §18).

record

Structured records - the typed Table that flows through GodspeedOS pipes.

service_context

ServiceContext - entry-point type handed to every service’s service_main.

trace

IPC trace emission - the client half of the trace ring events holds (utilities/47_events.md). IPC trace emission - the client half of the trace ring that events holds (utilities/47_events.md).

usbfn

The USB FUNCTION PROTOCOL’s numbers: what a USB host service (xhci, dwc2, ehci) answers for the one device it binds for a driver of its own, and what that driver asks. A driver package speaks it through gs::driver::bus; the WiFi dongle’s driver through godspeed_wifi::usbfn, which re-exports these and says what each one means in full (sdk/wifi/src/usbfn.rs). Every request starts with its op, and every reply with [op, status].

Enums

Error

Type Aliases

Result