Module service_context 

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

Provides safe, named access to the capabilities the service declared in its contract. Capability names match the contract field names exactly. Requesting a cap not in the contract returns Err(CapNotHeld).

Modules

death

How a task ended, as the kernel says it in the death notice (name, NUL, then one of these). The kernel’s task::death holds the same values; ask asserts its copy against these.

hwclass

Device classes a spawner can name in SpawnRequest::hw_flags. The kernel resolves the class to what its own bus scan found - a CLASS rather than an address, because the kernel keeps a permanent physical DMA reservation per device that a respawned driver must get back.

privbits

Bits for SpawnRequest::privileges. A spawner may only request what it HOLDS ITSELF - the kernel checks, and refuses otherwise - so this passes authority on, it never mints it (3.1, 7.3).

supcmd

The supervisor’s command channel wire format.

usbdev

A USB host’s report to the supervisor about a device it does not drive itself, so the supervisor can start that device’s driver when it arrives and stop it when it leaves (docs/usb-device-drivers.md).

Structs

BootManifest

CapInfo

One held capability, as reported by ServiceContext::task_caps.

Datetime

Wall-clock date/time read from the hardware RTC, fully decoded (binary, 24-hour). See ServiceContext::datetime.

PowerPending

The machine’s one pending power action, as the kernel holds it (InspectKernel query 28, docs/shutdown.md). See ServiceContext::power_pending.

ServiceContext

Passed by the kernel to service_main. Non-Copy; one per service instance.

ServiceDescriptor

SpawnRequest

What a spawner tells the kernel about a task it wants started from an image IT supplies (SpawnImage, syscall 52). Layout must match the kernel’s SpawnRequest exactly.

TaskStat

Snapshot of kernel task state for a single scheduler slot.

Enums

AcquireFailure

Why a reacquire_cap_detail failed. The two real cases want OPPOSITE responses, which is the entire reason this type exists rather than a bool.

AllocError

Error from the AllocMem syscall (6).

ClockSource

Where a wall-clock reading came from. Reported alongside the time so a displayed timestamp says what it is standing on: a local hardware clock, a network correction, or nothing (§26.4 - a fallback chain is mechanism while its choice is visible, and magic when it is not).

DeadlineOutcome

Outcome of ServiceContext::request_with_reply_deadline_outcome, which distinguishes the two ways a deadline request fails - so a caller can self-heal a restarted peer without penalising a silent one. SendFailed: the send never left (the peer’s cap is stale or its name is currently unresolvable - it was killed and respawned, generation bumped), so reacquiring it by name and retrying will reach the fresh instance. Timeout: the peer received the request but did not reply within the deadline (a genuinely silent/absent host) - retrying only doubles the wait. request_with_reply_deadline collapses both to None; use this when the difference matters.

DeadlineOutcomeInto

Outcome of ServiceContext::request_with_reply_deadline_outcome_into - the buffer-writing twin of DeadlineOutcome.

ReqOutcome

Outcome of an abortable request/reply (ServiceContext::request_with_reply_abortable): the reply arrived, the user pressed q/Q/ESC to abort the wait, or the deadline expired with no reply. Timeout also covers a request that never left (no such peer, no reply cap, a failed send).

Constants

AUTHORITIES

THE KERNEL’S FIXED AUTHORITIES, by resource id: (id, the name a contract uses, what it lets a task do).

BOOT_READ_CHUNK

The most one boot-record read copies (InspectKernel query 27). Equal to the kernel’s log::BOOT_READ_CHUNK; a reader’s buffer is exactly this size, so the kernel never writes past it.

LAYOUT_RELEASE

The first GodspeedOS release whose program layout this one runs: the context page and TaskStat, which changed when names grew to 128 bytes. A package built for an earlier release would read them wrongly, so the supervisor refuses to start it and says its publisher must rebuild it.

NAME_MAX

The longest name the kernel holds - a task’s, a send-peer’s, a directory entry’s - and so the longest a program can run under and be reached by. 128 since 2026-10-18: an installed package runs under its publisher/name, which may be that long. It was 24 for a peer and for acquiring by name, and 32 for a task, and a 26-byte package name was then unreachable by its own clients. Growing it changed the context page’s layout, so its magic changed with it, and a package built before that is refused at start (LAYOUT_RELEASE).

SPAWN_FLAG_CORE_STRICT

core is a STRICT placement, not a preference.

SPAWN_FLAG_HANDOVER

A live handover: start this beside the one task already running under its name, which keeps running until it ends itself; the new one takes the name. The supervisor’s alone, since only SpawnImage honours it (CLAUDE.md 2.5).

SPAWN_FLAG_PEERS_GRANT

Mint the child’s name-wired peer caps WITH GRANT, so it can re-delegate them.

SPAWN_FLAG_REQ_CONSOLE

SPAWN_FLAG_REQ_RECV

SPAWN_FLAG_WATCHED

Report this task’s death to the supervisor’s death-notification endpoint and count it as a restart. The supervisor sets it for every service it manages; the kernel keeps no list of which services those are (docs/audio.md, “No service names in the kernel”).

SPAWN_PAYLOAD_MAX

Upper bound on a spawn name payload (name + NUL-separated peers). Matches the kernel’s limit.

SPAWN_REQUEST_VERSION

2 since installs was added, 3 since probe_mode was. A spawner built against a different kernel is refused loudly.

USB_DISK_ABSENT

No USB disk is attached - the opposite instruction to USB_DISK_BUSY, and it must stay in step with the kernel’s USB_DISK_ABSENT. BUSY means “come back, I am working”; ABSENT means “there is nothing here, and asking again cannot change that - only a hot-plug can”. A caller that retries on this waits out its entire budget against an empty socket and then reports the device as busy, which is a false statement about hardware sitting on the operator’s desk.

USB_DISK_BUSY

The USB-disk syscalls’ “device NAKed, re-ask” status.