Appendix 6.A PNP ABI Reference

10 min read

Every name, value, offset and size in this appendix is generated from pkm/uapi/pkm/pnp.h by pkm/tools/gen-pnp-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 device's read and poll semantics, what each ioctl expects, the error vocabulary, and the bounds that are not in the header -- is in the notes appendix, §6.B, which this generator does not touch.

6.A.1 Ioctl requests #

Request numbers on /dev/peios-pnp, packed as <linux/ioctl.h> packs them (direction, argument size, type 'N', number).

6.A.2 Structure layouts #

Offsets and sizes are measured, not declared.

6.A.2.1 struct peios_pnp_event #

Total size 176 bytes.

6.A.2.2 struct peios_pnp_status #

Total size 352 bytes.

6.A.2.3 struct peios_pnp_counter_rec #

Total size 232 bytes.

6.A.2.4 struct peios_pnp_counters_query #

Total size 24 bytes.

6.A.2.5 struct peios_pnp_flow_rec #

Total size 288 bytes.

6.A.2.6 struct peios_pnp_flows_query #

Total size 24 bytes.

6.A.3 Constants #

Grouped as the header groups them.

PNP — Peios Network Policy: the verdict event stream and engine status.

The engine (net/pnp) judges every traversal at its standing seats and appends one event per evaluation to a bounded ring. /dev/peios-pnp (mode 0600; one reader at a time) drains it: read() returns whole events only — never a partial record — and blocks when the ring is empty unless O_NONBLOCK; poll() raises POLLIN when events are waiting. A slow reader loses the OLDEST events, and the loss is confessed in peios_pnp_status.events_dropped (the honesty rule: drops are counted, never silent).

Events are emitted for real evaluations (a published forest judged the traversal) and for fail-closed drops; permissive traversals (a layer with no forest — all of them at generation 0) emit nothing, because there is no decision to attribute. Status tells that story instead: generation 0 means "not enforcing", loudly.

This ABI is EXPERIMENTAL while PNP grows: no stability promise until the design ships (PEI-598). Check abi before trusting the rest.

Which standing seat judged the traversal.

Which rules layer.

The verdict, in strictness order.

The story a REJECT told (meaningful iff verdict == REJECT).

Traversal direction.

Flow state as the snapshot carried it (0 = the fact was absent).

Event flags.

One counter cell, as the counters dump reports it: the stream and key- spec of its table, the key it holds (only the facts the key-spec names are meaningful; the rest are zero), the cumulative total, and the value of every window the table answers.

Key-spec bits.

One live flow, as the flows dump reports it (ABI 3): conntrack's view of the flow (original-direction tuple, state, remaining lifetime, accounting), PNP's extension (start time, the interface and direction at first judgment, the sentences, the tags). Tags are reported by hash; the policy names them.

The flows dump: fills buf with as many records as fit; count is how many were written, total how many live flows the walk saw. A best- effort snapshot of a table that changes under the walk.

Edit this page