Appendix 2.A KMES ABI Reference

9 min read

Every name, value, offset and size in this appendix is generated from pkm/uapi/pkm/kmes.h by pkm/tools/gen-kmes-abi.py, with struct layouts measured by compiling a probe against the real header. Regenerate it whenever the ABI changes; do not edit it by hand. The names here are the ones a program actually compiles against.

What a compiler cannot measure -- the error vocabulary of each syscall, the privilege each requires by name, what the configuration keys do, and the implementation bounds that are not in the header -- is in the notes appendix, §2.B, which this generator does not touch.

2.A.1 Syscall numbers #

Signatures are read from the SYSCALL_DEFINE sites in pkm/kmes/.

2.A.2 Structure layouts #

Offsets and sizes are measured, not declared.

2.A.2.1 struct kmes_emit_entry #

Total size 32 bytes.

2.A.3 Constants #

Grouped as the header groups them.

Event origin class — kmes_event_header.origin_class.

Ring-slot discovery.

Ring slots are indexed by logical CPU id and the array is sized by the kernel's nr_cpu_ids, so a slot inside the array holds no ring when that CPU is not possible. Counting up from 0 until SYS_KMES_ATTACH returns -EINVAL therefore stops at the first hole and misses every ring above it, leaving those CPUs' events permanently unreachable.

Call SYS_KMES_ATTACH with cpu_id KMES_ATTACH_QUERY_SLOTS to learn the slot count instead. It writes the count through the capacity argument, returns 0, and opens no descriptor. Enumerate 0 .. count-1 and treat -EINVAL as "this slot holds no ring", not as the end of the array.

The sentinel is outside the index space for good: nr_cpu_ids is bounded by CONFIG_NR_CPUS, which cannot reach 2^32-1.

Largest entry count a single SYS_KMES_EMIT_BATCH call accepts.

Runtime configuration registry location and keys.

Type values match the LCS REG_* constants: REG_DWORD is 4 and REG_QWORD is 11. They are repeated here so <pkm/kmes.h> remains standalone.

Privilege requirements.

Values mirror the corresponding KACS privilege bits while keeping this header standalone.

On-wire event header.

Every event in a ring begins with a fixed 77-byte header, followed by event_type_len bytes of type string and then the msgpack payload. Events abut at event_size stride, so a header is not generally aligned; it crosses the ABI as raw bytes, not a C struct. Its fields, in order:

__u32  event_size            total event byte length (header + type + payload)
__u32  header_size           byte offset from the event start to the payload
__u64  timestamp_ns
__u64  sequence
__u16  cpu_id
__u8   origin_class          one of KMES_ORIGIN_* above
__u8   effective_token_guid[16]
__u8   true_token_guid[16]
__u8   process_guid[16]
__u16  event_type_len        length of the type string following the header

The three GUIDs are 16-byte Microsoft GUID binary values (Data1/Data2/Data3 little-endian, Data4 raw), captured from KACS at emission time; the null GUID (16 zero bytes) means identity was unavailable (KACS not initialised, or no process context). KMES copies them opaquely.

Read each field at its KMES_EVENT_*_OFFSET below. header_size locates the payload: it is KMES_EVENT_HEADER_BASE_SIZE + event_type_len. A future revision may grow the header, so consumers must use header_size, not the end of the type string, to find the payload.

Byte width of each identity GUID in the event header.

Byte size of the fixed event header — the offset at which the type string begins.

Ring-buffer metadata layout.

An attached ring is mmap'd as:

page 0          producer metadata (read-only to the consumer)
page 1          consumer metadata (read-write)
ring data       the event bytes, mapped twice back-to-back so an event
                that wraps the buffer end is still contiguous.

The producer metadata page begins with KMES_RING_MAGIC.

Field offsets within the producer metadata page.

Field offset within the consumer metadata page.

2.A.4 Tracepoint diagnostic codes #

From uapi/pkm/trace.h. These are a diagnostic contract for ftrace, perf and eBPF consumers, letting a tool decode a kmes: event's reason, op or state field without recompiling against a specific kernel. No KMES syscall accepts or returns them, and values are append-only.

kmes_drop reason — why the KMES ring machinery lost an event.

RING_FULL is a normal overwrite; TAIL_RESYNC is the silent corruption- recovery path that discards ALL pending events; VALIDATE is a kernel- emit size/type reject at the ring boundary; BATCH_STRUCT_INVALID is a per-entry structural reject in the kernel batch path. Emitted by kmes:kmes_drop. No event payload bytes.

kmes_swap reason — a bounded ring capacity swap lifecycle marker.

BEGIN and COMPLETE/FAILED are whole-topology (cpu field is U16_MAX); MIGRATE_SKIP is per-CPU and carries the skipped byte count in ret. Emitted by kmes:kmes_swap.

kmes_rate reason — the per-process token-bucket backpressure signal.

THROTTLE is an -EAGAIN emit rejection; RECONFIGURE marks an admin rate change clamping all buckets. Emitted by kmes:kmes_rate.

kmes_wake reason — consumer wakeup machinery.

NOTE arms a pending wake; FUTEX is the actual futex wake of blocked consumers. Emitted by kmes:kmes_wake.

kmes_ring_lifecycle reason — a generation-stable ring object transition.

ret is the outcome. Emitted by kmes:kmes_ring_lifecycle.

kmes_ingress_reject reason — why an emit request was rejected before the ring.

OVER_MAX/OVER_CAP_HALF/SIZE_OVERFLOW are declared-size rejects; EMIT_OVERSIZE is a staged event too large at ring-write time; BATCH_PARTIAL marks a batch that validated fewer entries than requested. Emitted by kmes:kmes_ingress_reject.

kmes_validate reason — the C-boundary result of the Rust staged-event validator.

The Rust side collapses its structural checks into one nonzero return; only visible type/payload lengths and ret are recorded here. Emitted by kmes:kmes_validate.

Edit this page