Appendix 5.A LCS ABI Reference

23 min read

Every name, value, offset and size in this appendix is generated from pkm/uapi/pkm/lcs.h by pkm/tools/gen-lcs-abi.py, with ioctl encodings and 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 -- which properties belong with their operations rather than here, and the kernel configuration -- is in the notes appendix, §5.B, which this generator does not touch.

5.A.1 Syscall numbers #

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

5.A.2 Ioctls #

The type byte is 'R'. Ioctl number namespaces are per fd type, so REG_SRC_REGISTER (number 0 on the source device) and REG_IOC_QUERY_VALUE (number 0 on a key fd) do not collide: the kernel dispatches on the fd's file_operations, not globally. The encoded value is what _IOC produces from the direction, type byte, number and argument size.

Source device fd.

Key fd.

Transaction fd.

5.A.3 Structure layouts #

Offsets and sizes are measured, not declared. The header also defines a _SIZE constant for each of these structures; the two agree by construction, and a mismatch fails the build in uapi/smoke_test.c.

5.A.3.1 struct reg_create_key_args #

Total size 48 bytes.

5.A.3.2 struct reg_query_value_args #

Total size 64 bytes.

5.A.3.3 struct reg_set_value_args #

Total size 64 bytes.

5.A.3.4 struct reg_delete_value_args #

Total size 40 bytes.

5.A.3.5 struct reg_blanket_tombstone_args #

Total size 24 bytes.

5.A.3.6 struct reg_query_values_batch_args #

Total size 24 bytes.

5.A.3.7 struct reg_enum_value_args #

Total size 40 bytes.

5.A.3.8 struct reg_enum_subkey_args #

Total size 40 bytes.

5.A.3.9 struct reg_query_key_info_args #

Total size 64 bytes.

5.A.3.10 struct reg_delete_key_args #

Total size 24 bytes.

5.A.3.11 struct reg_hide_key_args #

Total size 24 bytes.

5.A.3.12 struct reg_get_security_args #

Total size 16 bytes.

5.A.3.13 struct reg_set_security_args #

Total size 24 bytes.

5.A.3.14 struct reg_notify_args #

Total size 8 bytes.

5.A.3.15 struct reg_backup_args #

Total size 4 bytes.

5.A.3.16 struct reg_restore_args #

Total size 4 bytes.

5.A.3.17 struct reg_txn_status_args #

Total size 8 bytes.

5.A.3.18 struct reg_src_register_args #

Total size 24 bytes.

5.A.3.19 struct reg_src_hive_entry #

Total size 56 bytes.

5.A.4 Constants #

Grouped as the header groups them.

Syscall and ioctl argument sizes.

_IOWR, not _IOR: the kernel reads the caller's name_len and name_ptr out of the argument struct before it writes the result back, so the argument crosses in both directions. It was declared _IOR, which put the wrong direction bits in the encoded number -- and since the kernel dispatches on the whole encoded value, correcting it is a wire break, not a relabelling.

Transaction state codes.

Syscall flags and dispositions.

Registry key access rights.

Security information flags for REG_IOC_GET_SECURITY / SET_SECURITY.

Registry value types.

Watch event types and filters.

Watch event raw byte layout.

RSI common wire layout.

RSI op codes and response op codes.

RSI status codes.

RSI path target types.

RSI_WRITE_KEY field mask bits.

RSI transaction modes and source-registration flags.

Backup record types and magic.

5.A.5 Tracepoint diagnostic codes #

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

lcs_rsi_request op — which of the 18 RSI dispatch verbs a source-side request admission record describes. Emitted by lcs:lcs_rsi_request on successful queue admission and on the admission error rungs; the rung is read from ret (0 == enqueued, -EAGAIN == in-flight at limit / backpressure, -EIO == source gone / fd closing, -EOVERFLOW == request-id space exhausted, other == build reject). The same op enum tags the round-trip begin marker (lcs_rsi_roundtrip). Never records a pathname, key name, GUID, or frame bytes — only this op code, ids, counts and ret.

lcs_rsi_response reason — the outcome of accepting/validating a source's RSI response frame, and the late-response effects that silently mark a source DOWN. ACCEPTED is the clean path; DESYNC / OP_MISMATCH / UNKNOWN_STATUS are the accept-time rejects that all surface as -EINVAL/-EIO; MALFORMED_PAYLOAD is a per-op body validation reject; the LATE_* codes mark a response whose deferred effect (commit/mutation/begin bookkeeping) failed and took the source DOWN. Verdict/outcome is also in ret. Never records name/GUID/frame bytes.

lcs_source_fd reason — which source-fd lifecycle transition a record marks.

OPEN is a fresh /dev/pkm_registry fd; the remaining codes are the entry points that drive a source to the DOWN/closing state. source_down_id is the source id that transitioned DOWN (0 if the call was a no-op). The semantic cause of a late-effect-driven DOWN is carried by lcs_rsi_response (LCS_RESP_LATE_*); here EXPLICIT/MARK_BY_ID are the mechanical transitions. No pathname/SD bytes.

lcs_in_flight reason — an in-flight RSI request table transition (kept lean; insert on admission, delivered when handed to the source's read(), release on response completion or teardown). in_flight_count is the post-transition depth. Emitted by lcs:lcs_in_flight.

lcs_route op — which resolution the lcs:lcs_route event describes.

lcs_registration decision — the source registration path.

NEW/RESUME_DOWN are publish verdicts; COPY is the input-copy stage; REPLAY_FAIL/OVERFLOW_FAIL are resume post-publish -EIO paths that mark the resumed source down. Emitted by lcs:lcs_source_register / _registration_publish / _registration_copy.

lcs_bootstrap stage — the phase of a bootstrap / self-config refresh.

Emitted by lcs:lcs_bootstrap_refresh / _self_config_refresh / _self_config_publish.

lcs_runtime_limits field_id — which runtime-limit field a validate reject names, or LCS_LIM_ALL for a successful whole-struct publish. Emitted by lcs:lcs_limits_validate (-EINVAL, value offending) and lcs:lcs_limits_publish.

lcs_audit event_type_id — which LCS audit event a record describes.

Emitted by lcs:lcs_audit_emit and lcs:lcs_audit_emit_failed. result_errno carries the op-specific numeric. No SD or raw GUID bytes; key GUID is a u64 hash.

lcs_txn state — the transaction-fd state machine state carried in old_state new_state.

Emitted by lcs:lcs_txn_begin / _first_bind / _bind_mutation _commit / _abort / _timeout / _source_down.

lcs_key_fd cmd — the key-fd ioctl verb (also stamped on lcs_key_mutation).

LCS_KCMD_NONE is used by publish/release/read. Never records key/name/SD bytes. Emitted by lcs:lcs_key_ioctl / _mutation.

Edit this page