ktstr/vmm/
wire.rs

1//! Shared wire-format types for the host/guest virtio-console port-1
2//! TLV stream and the multiport control protocol.
3//!
4//! Both [`super::guest_comms`] (guest-only senders) and
5//! [`super::host_comms`] (host-only consumers) reference this module.
6//! Splitting the wire format out of the transport modules keeps the
7//! frame layout authoritative — a producer change here lands in both
8//! the guest writer and the host parser without a hand-sync step.
9//!
10//! # Postcard wire-format pin inventory (contributor guide)
11//!
12//! Every type that crosses the in-VM postcard TLV channel MUST be
13//! externally-tagged (postcard cannot decode `#[serde(untagged)]`
14//! or `#[serde(tag, content)]` enums — encode raises `WontImplement`
15//! at runtime and the host surfaces it as
16//! `ERR_NO_TEST_FUNCTION_OUTPUT`). The compile-time
17//! `#[derive(serde::Serialize, serde::Deserialize)]` itself does
18//! NOT catch the shape mismatch; the contract is verified by the
19//! per-type roundtrip pin tests listed below. A contributor adding
20//! a new postcard payload MUST add a roundtrip pin in the
21//! corresponding location and update this inventory.
22//!
23//! Inventory (type → test name → file):
24//!   - `AssertResult` → `assert_result_postcard_roundtrip`
25//!     → `src/assert/tests_serde.rs`
26//!   - `KernAddrs` → `kern_addrs_roundtrip_all_present` (+ 4 sibling
27//!     boundary pins) → `src/vmm/wire.rs` (this file)
28//!   - `KernelOpRequestPayload` / `KernelOpReplyPayload`
29//!     → 4 tests → `src/vmm/wire.rs` (this file)
30//!   - `PayloadMetrics`
31//!     → `payload_metrics_postcard_roundtrip`
32//!     → `src/test_support/payload.rs`
33//!   - `WorkloadConfig` → `payload_roundtrip`
34//!     → `src/test_support/payload.rs`
35//!   - `WorkerReport` → `worker_report_postcard_roundtrip` (+ 3 sibling
36//!     pins covering `Vec<WorkerReport>` + all `ExitInfo` variants)
37//!     → `src/workload/spawn/tests_integration.rs`
38//!   - `PersistedCastAnalysis` → see `src/vmm/cast_analysis_load`
39//!     module's tests
40//!
41//! # Frame layout
42//!
43//! Each guest→host bulk message is a 16-byte [`ShmMessage`] header
44//! followed by `length` payload bytes. The host's
45//! [`super::host_comms::parse_tlv_stream`] consumes this format. CRC32
46//! covers payload bytes only, not the header.
47//!
48//! ```text
49//! offset  size  field
50//! ------  ----  ----------------------------------------------
51//!   0      4    msg_type (u32 LE)  — see [`MsgType`]
52//!   4      4    length   (u32 LE)  — payload bytes following
53//!   8      4    crc32    (u32 LE)  — crc32fast over payload
54//!  12      4    _pad     (u32 LE)  — reserved, MUST be zero
55//!  16      N    payload  (N=length bytes)
56//! ```
57//!
58//! # Control protocol
59//!
60//! [`VirtioConsoleControl`] mirrors the kernel uapi `struct
61//! virtio_console_control` for multiport handshake messages on the
62//! c_ivq / c_ovq queues (8 bytes: id u32, event u16, value u16).
63//! [`ControlEvent`] enumerates the event discriminants the kernel and
64//! the host VMM exchange during port enumeration.
65//!
66//! Many of the typed wrappers and constants in this module are part
67//! of the public bulk API surface; the lib build does not yet read
68//! every variant from internal call sites (the typed `MsgType` enum,
69//! `ControlEvent`, `VirtioConsoleControl`, `NUM_PORTS`, `PORT1_NAME`,
70//! and the `from_wire` reverse mappings are reachable via the public
71//! crate path for downstream test code and wire-format tests). The
72//! module-level `#[allow(dead_code)]` matches the `VmResult` field
73//! pattern in `result.rs` — public surface that the in-tree readers
74//! do not exercise without the unused-X lint firing.
75
76#![allow(dead_code)]
77
78use zerocopy::{FromBytes, IntoBytes};
79
80// ---------------------------------------------------------------------------
81// MsgType — typed message-type discriminant
82// ---------------------------------------------------------------------------
83
84/// Message-type discriminant for the bulk TLV stream.
85///
86/// Each variant maps to a 32-bit on-wire value via [`Self::wire_value`].
87/// The values are 4-character ASCII tags chosen so the integer literal
88/// itself spells the tag in hex (e.g. `0x4558_4954` reads as `"EXIT"`
89/// — `45`='E', `58`='X', `49`='I', `54`='T'). Because the wire format
90/// is little-endian, a raw byte-level hex dump of a captured frame
91/// shows the bytes in reverse order (e.g. `54 49 58 45` for the
92/// `Exit` tag, which spells `"TIXE"` byte-by-byte). The integer
93/// hex value spells the tag; the on-wire bytes are reversed.
94///
95/// On-wire values are stable across host/guest builds — adding a new
96/// variant requires picking a fresh ASCII tag and updating
97/// [`Self::from_wire`] to recognise it. Existing tags must never be
98/// repurposed.
99#[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
100pub enum MsgType {
101    /// Stimulus event from the guest step executor — emitted at each
102    /// step's START (the StepStart frame).
103    Stimulus,
104    /// Per-step END frame from the guest step executor, emitted at the
105    /// end of each step's hold while its workers are still alive.
106    /// Reuses the [`StimulusPayload`] body (same 24 bytes) carrying the
107    /// step's coincident end-of-hold (elapsed_ms, total_iterations) and
108    /// the SAME 1-indexed `step_index` as its StepStart. The host pairs
109    /// `StepStart[k]` -> `StepEnd[k]` for each step's OWN throughput
110    /// (step-local iteration_rate), which — unlike the cross-step
111    /// `StepStart[k]` -> `StepStart[k+1]` delta — does not read ~0 for
112    /// workers respawned per step.
113    StepEnd,
114    /// Scenario start marker. Sets a fresh watchdog deadline.
115    ScenarioStart,
116    /// Scenario end marker (payload: two 8-byte LE u64s — elapsed_ms
117    /// then the final cumulative `total_iterations`; see
118    /// [`SCENARIO_END_PAYLOAD_SIZE`] / [`parse_scenario_end`]).
119    ScenarioEnd,
120    /// Pause the watchdog clock. Wall time while paused doesn't
121    /// count against the workload budget.
122    ScenarioPause,
123    /// Resume the watchdog clock after a pause. Extends the deadline
124    /// by the pause duration — gives back the paused time.
125    ScenarioResume,
126    /// Guest exit code (payload: 4-byte LE i32).
127    Exit,
128    /// Test result (payload: postcard-encoded `AssertResult`).
129    TestResult,
130    /// Scheduler process exit (payload: 4-byte LE i32 exit code).
131    SchedExit,
132    /// Guest crash diagnostic (payload: UTF-8 panic + backtrace).
133    /// Reserved tag — never travels on the bulk port. Panic
134    /// diagnostics are written directly to COM2 (`/dev/ttyS1`)
135    /// because `virtio_console` TX can block on host backpressure
136    /// and blocking inside a fault handler would deadlock the
137    /// guest before the diagnostic reached the host.
138    Crash,
139    /// Per-payload-invocation metrics (payload: postcard-encoded
140    /// `PayloadMetrics`).
141    PayloadMetrics,
142    /// Coverage profraw blob.
143    Profraw,
144    /// Guest→host stdout chunk. Payload: opaque UTF-8 bytes. Each
145    /// frame carries one chunk read from the guest's stdout pipe;
146    /// host concatenates chunks in arrival order to reconstruct the
147    /// stream. Replaces the prior COM2 stdout redirect.
148    Stdout,
149    /// Guest→host stderr chunk. Payload: opaque UTF-8 bytes. Same
150    /// chunked semantics as [`Self::Stdout`].
151    Stderr,
152    /// Guest→host scheduler-log chunk. Payload: opaque UTF-8 bytes
153    /// from the scheduler child process's captured log. Replaces
154    /// the prior COM2 SCHED_OUTPUT_START/END dump path. The host
155    /// concatenates chunks in arrival order; the existing
156    /// `SCHED_OUTPUT_START` / `SCHED_OUTPUT_END` delimiters and the
157    /// embedded BPF verifier section are preserved verbatim
158    /// inside the chunk bytes.
159    SchedLog,
160    /// Guest→host scheduler-STDOUT chunk. Payload: opaque UTF-8 bytes
161    /// read live from the scheduler child's stdout pipe. Distinct from
162    /// [`Self::SchedLog`] (which ships the merged `/tmp/sched.log` file
163    /// only at teardown / boot-failure): these frames stream each read
164    /// chunk as it arrives, so the scheduler's stdout survives a
165    /// watchdog timeout that never reaches the teardown dump. The host
166    /// concatenates chunks in arrival order. Unlike `SchedLog`, these
167    /// carry NO `SCHED_OUTPUT_START/END` framing — the stream is the
168    /// raw child output, delimited only by the frame boundaries.
169    SchedStdout,
170    /// Guest→host scheduler-STDERR chunk. Payload: opaque UTF-8 bytes
171    /// read live from the scheduler child's stderr pipe. Same live
172    /// streaming semantics as [`Self::SchedStdout`]; with the split
173    /// streams, libbpf / log-crate output (including the BPF verifier
174    /// log region between the `-- BEGIN/END PROG LOAD LOG --` markers)
175    /// typically lands here.
176    SchedStderr,
177    /// Guest→host authoritative terminal scheduler-STDOUT chunk.
178    ///
179    /// Live [`Self::SchedStdout`] frames are best-effort and may be
180    /// deliberately suppressed while scheduler lifecycle control boundaries
181    /// own the bulk channel. Once the child and both pipe forwarders have
182    /// exited, the guest replays the complete stdout sidecar through this
183    /// message type only if a live frame was suppressed or failed. Each
184    /// payload carries a total-length/offset header, so the host accepts only
185    /// complete terminal streams and can fall back to the live stream when a
186    /// terminal replay is interrupted.
187    SchedStdoutFinal,
188    /// Guest→host authoritative terminal scheduler-STDERR chunk.
189    ///
190    /// Same completion-aware terminal semantics as
191    /// [`Self::SchedStdoutFinal`], applied to the scheduler child's stderr.
192    SchedStderrFinal,
193    /// Guest→host lifecycle phase event. Payload: 1-byte
194    /// [`LifecyclePhase`] discriminant followed by an optional
195    /// UTF-8 reason buffer (used by `SchedulerNotAttached`'s
196    /// suffix detail). Replaces the prior `KTSTR_INIT_STARTED` /
197    /// `KTSTR_PAYLOAD_STARTING` / `SCHEDULER_DIED` /
198    /// `SCHEDULER_NOT_ATTACHED` sentinel strings on COM2.
199    Lifecycle,
200    /// Guest→host shell-exec exit. Payload: 4-byte LE i32 exit
201    /// code from `cargo ktstr shell --exec <cmd>`. Replaces the
202    /// prior COM2 `KTSTR_EXEC_EXIT=N` sentinel line.
203    ExecExit,
204    /// Guest→host kernel ring-buffer dump. Payload: opaque UTF-8
205    /// bytes from `rmesg::logs_raw`. Sent on the
206    /// initramfs-extraction failure path so the host sees the
207    /// kernel OOM messages without scraping COM2.
208    Dmesg,
209    /// Guest→host probe-pipeline JSON output. Payload: opaque UTF-8
210    /// bytes from the probe output stream. Replaces the prior
211    /// COM2 ProbeDrain path so probe JSON does not interleave
212    /// with sched-log dumps on the same serial port.
213    ProbeOutput,
214    /// Guest→host on-demand snapshot request (payload:
215    /// [`SnapshotRequestPayload`]). The freeze coordinator's bulk-drain
216    /// path intercepts this frame, runs the CAPTURE / WATCH dispatch,
217    /// and replies with [`MsgType::SnapshotReply`] on port 1 RX.
218    SnapshotRequest,
219    /// Host→guest snapshot reply (payload: [`SnapshotReplyPayload`]).
220    /// Sent on port 1 RX so the guest's blocking read on the port
221    /// advertised as [`PORT1_NAME`] wakes within microseconds. Reply payload
222    /// carries the matching request_id, the status, and a UTF-8
223    /// reason buffer for the failure path.
224    SnapshotReply,
225    /// Guest→host kernel-memory write/read op request (payload:
226    /// postcard-encoded [`KernelOpRequestPayload`]). Carries the
227    /// `Op::WriteKernel{Hot,Cold}` / `Op::ReadKernel{Hot,Cold}`
228    /// invocation from the guest's step executor; variable-length
229    /// payload rides this distinct MSG_TYPE rather than extending
230    /// the fixed-72-byte [`SnapshotRequestPayload`].
231    KernelOpRequest,
232    /// Host→guest reply to [`MsgType::KernelOpRequest`] (payload:
233    /// postcard-encoded [`KernelOpReplyPayload`]).
234    KernelOpReply,
235    /// Guest→host wprof Perfetto-format trace blob (payload: raw
236    /// `.pb` bytes from `wprof -T trace.pb`). The freeze
237    /// coordinator writes the payload as `wprof.pb` next to the
238    /// failure-dump JSON so the operator picks it up alongside the
239    /// rest of the per-test debugging artefacts.
240    WprofTrace,
241    /// Guest→host wprof trace CHUNK (payload: a ≤`MAX_BULK_FRAME_PAYLOAD`
242    /// slice of the `.pb`). A wprof trace larger than the single-frame
243    /// bulk-port ceiling is split into ordered `WprofTraceChunk` frames
244    /// terminated by a final [`Self::WprofTrace`] frame (the last slice);
245    /// the host concatenates the chunk payloads in arrival order and
246    /// appends the terminal `WprofTrace` payload to reconstruct the `.pb`.
247    /// A trace that fits in one frame ships as a lone `WprofTrace` (no
248    /// chunks) — the reassembly is a no-op for that fast path.
249    ///
250    /// Like the `Stdout`/`Stderr`/`SchedLog` transports, a large blob is
251    /// split across frames and concatenated on the host. It DIVERGES from
252    /// them in using a distinct terminal frame type rather than uniform
253    /// same-type frames: a Perfetto `.pb` is useless if truncated (a partial
254    /// protobuf still passes the leading-tag/size shape check but decodes to
255    /// garbage), whereas partial stdout is still useful. The terminal frame
256    /// lets the host distinguish a complete trace (terminal present → write
257    /// the `.pb`) from a transport that tore mid-ship (chunks but no terminal
258    /// → write nothing, so the post_vm `.pb`-landed assert fails loudly
259    /// instead of shipping a plausible-but-corrupt artifact). Stdout/SchedLog
260    /// need no such marker — their in-band `SCHED_OUTPUT_START/END` content
261    /// delimiters, not the framing, bound their payloads.
262    WprofTraceChunk,
263    /// Guest→host ordered teardown barrier (payload: empty).
264    ///
265    /// Emitted only by the progress-watchdog teardown-wedge fault
266    /// injector, after its `ScenarioEnd` and test-result frames. The
267    /// coordinator advances the lifecycle to Teardown, persists every
268    /// earlier frame in the same ordered bulk stream, then replies with
269    /// [`MsgType::TeardownBarrierAck`] on port 1 RX. The guest must not
270    /// enter its intentional infinite wedge until that reply arrives.
271    /// Coordinator-internal: carries no test verdict.
272    TeardownBarrier,
273    /// Host→guest acknowledgement for [`MsgType::TeardownBarrier`]
274    /// (payload: empty). A guest TX frame stamped with this host-only
275    /// tag is illegitimate and is filtered as coordinator-internal.
276    TeardownBarrierAck,
277    /// Guest→host system-ready signal (payload: empty).
278    ///
279    /// Emitted by the guest's `ktstr_guest_init` after
280    /// `mount_filesystems()` completes, so by the time the host
281    /// observes the frame the guest's `setup_per_cpu_areas` and
282    /// KASLR randomization (both kernel-boot prerequisites) are
283    /// already done. The freeze coordinator's bulk-drain dispatch
284    /// promotes a CRC-valid SYS_RDY frame into the monitor's
285    /// boot-complete eventfd, so the monitor's pre-sample
286    /// `epoll_wait` returns within microseconds rather than
287    /// waiting for the 5 s fallback timeout. Replaces an earlier
288    /// trigger that fired on the first port-0 TX byte (kernel
289    /// printk via `/dev/hvc0`), which depended on incidental
290    /// console traffic rather than an explicit readiness signal.
291    SysRdy,
292    /// Guest→host readiness edge for configured host BPF-map writes
293    /// (payload: empty).
294    ///
295    /// Emitted immediately before ScenarioStart, after the guest's probe
296    /// pipeline and optional wprof capture are armed. The host may discover
297    /// and resolve the target map earlier, but waits on this edge before
298    /// mutating it. This prevents a crash injection from killing the
299    /// scheduler before the instrumentation needed to observe that crash is
300    /// live. Coordinator-internal: carries no test verdict.
301    BpfMapWriteReady,
302    /// Guest→host boundary for a finite prerequisite/readiness wait.
303    ///
304    /// Payload is the fixed-size [`ReadinessWaitEvent`] encoding. A
305    /// generation-tagged `Started` event transfers ordinary watchdog
306    /// progress ownership to that finite wait immediately before the guest
307    /// blocks; the matching `Finished` event returns ownership after
308    /// readiness or failure. The watchdog policy is deliberately independent
309    /// of [`ReadinessWaitKind`].
310    ///
311    /// Coordinator-internal: carries accounting control only, never a test
312    /// verdict.
313    ReadinessWait,
314    /// Guest→host scheduler-swap notification (payload: empty).
315    ///
316    /// Emitted by the guest's `kill_current_scheduler`
317    /// (`Op::DetachScheduler` / `RestartScheduler` / `ReplaceScheduler`)
318    /// AFTER `wait_for_scx_disabled` returns, so by the time the host
319    /// observes the frame the kernel has already NULLed `*scx_root`
320    /// (`RCU_INIT_POINTER(scx_root, NULL)` precedes
321    /// `scx_set_enable_state(SCX_DISABLED)` in kernel/sched/ext.c) and
322    /// the prior scx_sched object is unlinked (`*scx_root` NULLed) and
323    /// its slab is subject to RCU-grace-period reuse. The freeze
324    /// coordinator decodes a CRC-valid frame and SYNCHRONOUSLY
325    /// invalidates the periodic-capture accessor (mirroring the
326    /// watchpoint poll's Detached teardown) rather than waiting up to
327    /// one SCAN_INTERVAL for the poll to notice the rebind — collapsing
328    /// the post-swap periodic-capture defer window. Coordinator-internal:
329    /// carries no test verdict.
330    SchedSwapNotify,
331    /// Guest→host scheduler-attach attempt boundary.
332    ///
333    /// Payload is the fixed-size [`AttachAttemptEvent`] encoding. A
334    /// `Started` event opens one host-side attach-budget generation and a
335    /// matching `Finished` event closes it. This is deliberately separate
336    /// from [`Self::Lifecycle`]: scheduler lifecycle Ops can attach while the
337    /// coarse guest lifecycle is already in `Body`, and that coarse stage is
338    /// forward-only.
339    ///
340    /// Coordinator-internal: the frame drives host watchdog accounting and
341    /// carries no test verdict.
342    AttachAttempt,
343}
344
345impl MsgType {
346    /// 32-bit on-wire discriminant for this message type. The value is
347    /// the big-endian ASCII representation of a 4-character tag.
348    pub const fn wire_value(self) -> u32 {
349        match self {
350            MsgType::Stimulus => MSG_TYPE_STIMULUS,
351            MsgType::StepEnd => MSG_TYPE_STEP_END,
352            MsgType::ScenarioStart => MSG_TYPE_SCENARIO_START,
353            MsgType::ScenarioEnd => MSG_TYPE_SCENARIO_END,
354            MsgType::ScenarioPause => MSG_TYPE_SCENARIO_PAUSE,
355            MsgType::ScenarioResume => MSG_TYPE_SCENARIO_RESUME,
356            MsgType::Exit => MSG_TYPE_EXIT,
357            MsgType::TestResult => MSG_TYPE_TEST_RESULT,
358            MsgType::SchedExit => MSG_TYPE_SCHED_EXIT,
359            MsgType::Crash => MSG_TYPE_CRASH,
360            MsgType::PayloadMetrics => MSG_TYPE_PAYLOAD_METRICS,
361            MsgType::Profraw => MSG_TYPE_PROFRAW,
362            MsgType::WprofTrace => MSG_TYPE_WPROF_TRACE,
363            MsgType::WprofTraceChunk => MSG_TYPE_WPROF_TRACE_CHUNK,
364            MsgType::TeardownBarrier => MSG_TYPE_TEARDOWN_BARRIER,
365            MsgType::TeardownBarrierAck => MSG_TYPE_TEARDOWN_BARRIER_ACK,
366            MsgType::SnapshotRequest => MSG_TYPE_SNAPSHOT_REQUEST,
367            MsgType::SnapshotReply => MSG_TYPE_SNAPSHOT_REPLY,
368            MsgType::KernelOpRequest => MSG_TYPE_KERNEL_OP_REQUEST,
369            MsgType::KernelOpReply => MSG_TYPE_KERNEL_OP_REPLY,
370            MsgType::SysRdy => MSG_TYPE_SYS_RDY,
371            MsgType::BpfMapWriteReady => MSG_TYPE_BPF_MAP_WRITE_READY,
372            MsgType::ReadinessWait => MSG_TYPE_READINESS_WAIT,
373            MsgType::SchedSwapNotify => MSG_TYPE_SCHED_SWAP_NOTIFY,
374            MsgType::AttachAttempt => MSG_TYPE_ATTACH_ATTEMPT,
375            MsgType::Stdout => MSG_TYPE_STDOUT,
376            MsgType::Stderr => MSG_TYPE_STDERR,
377            MsgType::SchedLog => MSG_TYPE_SCHED_LOG,
378            MsgType::SchedStdout => MSG_TYPE_SCHED_STDOUT,
379            MsgType::SchedStderr => MSG_TYPE_SCHED_STDERR,
380            MsgType::SchedStdoutFinal => MSG_TYPE_SCHED_STDOUT_FINAL,
381            MsgType::SchedStderrFinal => MSG_TYPE_SCHED_STDERR_FINAL,
382            MsgType::Lifecycle => MSG_TYPE_LIFECYCLE,
383            MsgType::ExecExit => MSG_TYPE_EXEC_EXIT,
384            MsgType::Dmesg => MSG_TYPE_DMESG,
385            MsgType::ProbeOutput => MSG_TYPE_PROBE_OUTPUT,
386        }
387    }
388
389    /// Reverse the wire mapping. Returns `None` when `value` is not a
390    /// recognised discriminant — callers can either skip the frame or
391    /// surface the unknown tag for diagnostics.
392    pub const fn from_wire(value: u32) -> Option<Self> {
393        match value {
394            MSG_TYPE_STIMULUS => Some(MsgType::Stimulus),
395            MSG_TYPE_STEP_END => Some(MsgType::StepEnd),
396            MSG_TYPE_SCENARIO_START => Some(MsgType::ScenarioStart),
397            MSG_TYPE_SCENARIO_END => Some(MsgType::ScenarioEnd),
398            MSG_TYPE_SCENARIO_PAUSE => Some(MsgType::ScenarioPause),
399            MSG_TYPE_SCENARIO_RESUME => Some(MsgType::ScenarioResume),
400            MSG_TYPE_EXIT => Some(MsgType::Exit),
401            MSG_TYPE_TEST_RESULT => Some(MsgType::TestResult),
402            MSG_TYPE_SCHED_EXIT => Some(MsgType::SchedExit),
403            MSG_TYPE_CRASH => Some(MsgType::Crash),
404            MSG_TYPE_PAYLOAD_METRICS => Some(MsgType::PayloadMetrics),
405            MSG_TYPE_PROFRAW => Some(MsgType::Profraw),
406            MSG_TYPE_WPROF_TRACE => Some(MsgType::WprofTrace),
407            MSG_TYPE_WPROF_TRACE_CHUNK => Some(MsgType::WprofTraceChunk),
408            MSG_TYPE_TEARDOWN_BARRIER => Some(MsgType::TeardownBarrier),
409            MSG_TYPE_TEARDOWN_BARRIER_ACK => Some(MsgType::TeardownBarrierAck),
410            MSG_TYPE_SNAPSHOT_REQUEST => Some(MsgType::SnapshotRequest),
411            MSG_TYPE_SNAPSHOT_REPLY => Some(MsgType::SnapshotReply),
412            MSG_TYPE_KERNEL_OP_REQUEST => Some(MsgType::KernelOpRequest),
413            MSG_TYPE_KERNEL_OP_REPLY => Some(MsgType::KernelOpReply),
414            MSG_TYPE_SYS_RDY => Some(MsgType::SysRdy),
415            MSG_TYPE_BPF_MAP_WRITE_READY => Some(MsgType::BpfMapWriteReady),
416            MSG_TYPE_READINESS_WAIT => Some(MsgType::ReadinessWait),
417            MSG_TYPE_SCHED_SWAP_NOTIFY => Some(MsgType::SchedSwapNotify),
418            MSG_TYPE_ATTACH_ATTEMPT => Some(MsgType::AttachAttempt),
419            MSG_TYPE_STDOUT => Some(MsgType::Stdout),
420            MSG_TYPE_STDERR => Some(MsgType::Stderr),
421            MSG_TYPE_SCHED_LOG => Some(MsgType::SchedLog),
422            MSG_TYPE_SCHED_STDOUT => Some(MsgType::SchedStdout),
423            MSG_TYPE_SCHED_STDERR => Some(MsgType::SchedStderr),
424            MSG_TYPE_SCHED_STDOUT_FINAL => Some(MsgType::SchedStdoutFinal),
425            MSG_TYPE_SCHED_STDERR_FINAL => Some(MsgType::SchedStderrFinal),
426            MSG_TYPE_LIFECYCLE => Some(MsgType::Lifecycle),
427            MSG_TYPE_EXEC_EXIT => Some(MsgType::ExecExit),
428            MSG_TYPE_DMESG => Some(MsgType::Dmesg),
429            MSG_TYPE_PROBE_OUTPUT => Some(MsgType::ProbeOutput),
430            _ => None,
431        }
432    }
433
434    /// `true` for control frames the freeze coordinator interprets
435    /// internally and that must NOT surface as test verdict entries
436    /// in [`super::host_comms::BulkDrainResult`]. Both the
437    /// coordinator's mid-run `bulk_messages_for_closure` filter and
438    /// `collect_results`'s post-run drain key on this single
439    /// classifier so the gate stays in lockstep — adding a new
440    /// internal control frame is a one-line update here.
441    ///
442    /// The current internal set:
443    ///   - [`MsgType::SnapshotRequest`] — has its matching
444    ///     [`MsgType::SnapshotReply`] delivered over port-1 RX; the
445    ///     request itself carries no test verdict.
446    ///   - [`MsgType::SnapshotReply`] — host→guest only on port-1 RX.
447    ///     A guest TX frame stamped with this tag is illegitimate
448    ///     (only the host coordinator emits replies); drop it instead
449    ///     of bucketing it as a phantom verdict entry. Including the
450    ///     tag in the internal set keeps the dispatch and the
451    ///     `collect_results` post-run drain in lockstep — both filter
452    ///     the same way.
453    ///   - [`MsgType::KernelOpRequest`] — paired with its
454    ///     [`MsgType::KernelOpReply`] over port-1 RX (the cold-path
455    ///     kernel-op roundtrip); the request carries no test verdict.
456    ///   - [`MsgType::KernelOpReply`] — host→guest only on port-1 RX,
457    ///     same illegitimate-guest-TX reasoning as `SnapshotReply`.
458    ///   - [`MsgType::TeardownBarrier`] — ordered guest→host fence used
459    ///     by the progress-watchdog fault injector; carries no verdict.
460    ///   - [`MsgType::TeardownBarrierAck`] — host→guest-only reply to
461    ///     that fence.
462    ///   - [`MsgType::SysRdy`] — its only semantic is the eventfd
463    ///     promotion that releases the monitor's pre-sample
464    ///     `epoll_wait`.
465    ///   - [`MsgType::SchedSwapNotify`] — its only semantic is the
466    ///     synchronous periodic-capture accessor teardown the freeze
467    ///     coordinator performs on a CRC-valid frame; carries no test
468    ///     verdict.
469    ///   - [`MsgType::BpfMapWriteReady`] — releases the configured
470    ///     host-side map writer after guest instrumentation is armed.
471    ///   - [`MsgType::ReadinessWait`] — opens or closes the generic finite
472    ///     guest-prerequisite watchdog overlay.
473    ///   - [`MsgType::AttachAttempt`] — opens or closes the
474    ///     generation-tagged host scheduler-attach watchdog overlay; carries
475    ///     accounting control only, never a test verdict.
476    pub const fn is_coordinator_internal(self) -> bool {
477        matches!(
478            self,
479            MsgType::SnapshotRequest
480                | MsgType::SnapshotReply
481                | MsgType::KernelOpRequest
482                | MsgType::KernelOpReply
483                | MsgType::TeardownBarrier
484                | MsgType::TeardownBarrierAck
485                | MsgType::SysRdy
486                | MsgType::BpfMapWriteReady
487                | MsgType::ReadinessWait
488                | MsgType::SchedSwapNotify
489                | MsgType::AttachAttempt
490        )
491    }
492}
493
494// ---------------------------------------------------------------------------
495// Finite guest prerequisite/readiness-wait protocol
496// ---------------------------------------------------------------------------
497
498/// Version byte in the fixed-size [`ReadinessWaitEvent`] payload.
499pub const READINESS_WAIT_WIRE_VERSION: u8 = 1;
500
501/// Fixed payload size for [`ReadinessWaitEvent`]:
502/// `version:u8, transition:u8, kind:u8, reserved:u8, generation:u64_le`.
503pub const READINESS_WAIT_PAYLOAD_SIZE: usize = 12;
504
505/// Diagnostic identity of a finite guest prerequisite.
506///
507/// The host watchdog does not branch on this value: every kind uses the same
508/// explicit finite-wait ownership policy. The kind exists so the host can
509/// close the matching wait when it publishes readiness and so diagnostics
510/// identify the prerequisite that owned progress.
511#[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
512pub enum ReadinessWaitKind {
513    ProbeDump,
514}
515
516impl ReadinessWaitKind {
517    pub const fn wire_value(self) -> u8 {
518        match self {
519            Self::ProbeDump => 1,
520        }
521    }
522
523    pub const fn from_wire(value: u8) -> Option<Self> {
524        match value {
525            1 => Some(Self::ProbeDump),
526            _ => None,
527        }
528    }
529}
530
531/// Boundary represented by one [`ReadinessWaitEvent`].
532#[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
533pub enum ReadinessWaitTransition {
534    Started,
535    Finished,
536}
537
538impl ReadinessWaitTransition {
539    pub const fn wire_value(self) -> u8 {
540        match self {
541            Self::Started => 1,
542            Self::Finished => 2,
543        }
544    }
545
546    pub const fn from_wire(value: u8) -> Option<Self> {
547        match value {
548            1 => Some(Self::Started),
549            2 => Some(Self::Finished),
550            _ => None,
551        }
552    }
553}
554
555/// One generation-tagged finite guest prerequisite boundary.
556///
557/// A generation is non-zero and monotonically allocated by the guest.
558/// Matching the finish prevents a delayed duplicate from closing a newer wait.
559#[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
560pub struct ReadinessWaitEvent {
561    pub transition: ReadinessWaitTransition,
562    pub kind: ReadinessWaitKind,
563    pub generation: u64,
564}
565
566impl ReadinessWaitEvent {
567    pub fn to_payload(self) -> [u8; READINESS_WAIT_PAYLOAD_SIZE] {
568        let mut payload = [0u8; READINESS_WAIT_PAYLOAD_SIZE];
569        payload[0] = READINESS_WAIT_WIRE_VERSION;
570        payload[1] = self.transition.wire_value();
571        payload[2] = self.kind.wire_value();
572        payload[4..12].copy_from_slice(&self.generation.to_le_bytes());
573        payload
574    }
575
576    /// Decode an exact canonical payload. Unknown versions/discriminants,
577    /// non-zero reserved data, zero generations, and size mismatches are
578    /// rejected.
579    pub fn from_payload(payload: &[u8]) -> Option<Self> {
580        if payload.len() != READINESS_WAIT_PAYLOAD_SIZE
581            || payload[0] != READINESS_WAIT_WIRE_VERSION
582            || payload[3] != 0
583        {
584            return None;
585        }
586        let transition = ReadinessWaitTransition::from_wire(payload[1])?;
587        let kind = ReadinessWaitKind::from_wire(payload[2])?;
588        let generation = u64::from_le_bytes(payload[4..12].try_into().ok()?);
589        if generation == 0 {
590            return None;
591        }
592        Some(Self {
593            transition,
594            kind,
595            generation,
596        })
597    }
598}
599
600// ---------------------------------------------------------------------------
601// Scheduler attach-attempt control protocol
602// ---------------------------------------------------------------------------
603
604/// Version byte in the fixed-size [`AttachAttemptEvent`] payload.
605pub const ATTACH_ATTEMPT_WIRE_VERSION: u8 = 1;
606
607/// Fixed payload size for [`AttachAttemptEvent`]:
608/// `version:u8, transition:u8, kind:u8, reserved:u8, generation:u64_le`.
609pub const ATTACH_ATTEMPT_PAYLOAD_SIZE: usize = 12;
610
611/// Which scheduler spawn path opened an attach attempt.
612#[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
613pub enum AttachAttemptKind {
614    /// Initial scheduler spawned by guest init.
615    Boot,
616    /// `Op::AttachScheduler`.
617    Attach,
618    /// `Op::RestartScheduler`.
619    Restart,
620    /// `Op::ReplaceScheduler`.
621    Replace,
622}
623
624impl AttachAttemptKind {
625    pub const fn wire_value(self) -> u8 {
626        match self {
627            Self::Boot => 1,
628            Self::Attach => 2,
629            Self::Restart => 3,
630            Self::Replace => 4,
631        }
632    }
633
634    pub const fn from_wire(value: u8) -> Option<Self> {
635        match value {
636            1 => Some(Self::Boot),
637            2 => Some(Self::Attach),
638            3 => Some(Self::Restart),
639            4 => Some(Self::Replace),
640            _ => None,
641        }
642    }
643}
644
645/// Boundary represented by one [`AttachAttemptEvent`].
646#[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
647pub enum AttachAttemptTransition {
648    /// Start charging one attach generation.
649    Started,
650    /// Stop charging the attach body and enter the host's separately
651    /// service-accounted `Finishing` rendezvous state.
652    Finished,
653    /// The guest consumed the exact [`AttachControlPacket::FinishedAck`] and
654    /// the host may now close the overlay and resume coarse accounting.
655    Settled,
656}
657
658impl AttachAttemptTransition {
659    pub const fn wire_value(self) -> u8 {
660        match self {
661            Self::Started => 1,
662            Self::Finished => 2,
663            Self::Settled => 3,
664        }
665    }
666
667    pub const fn from_wire(value: u8) -> Option<Self> {
668        match value {
669            1 => Some(Self::Started),
670            2 => Some(Self::Finished),
671            3 => Some(Self::Settled),
672            _ => None,
673        }
674    }
675}
676
677/// One generation-tagged scheduler attach boundary.
678///
679/// The generation is allocated monotonically by the guest and must be
680/// non-zero. Tagging both directions prevents a delayed host cancellation
681/// for an old scheduler from cancelling a later Attach/Replace/Restart.
682#[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
683pub struct AttachAttemptEvent {
684    pub transition: AttachAttemptTransition,
685    pub kind: AttachAttemptKind,
686    pub generation: u64,
687}
688
689impl AttachAttemptEvent {
690    /// Encode the byte-stable fixed-size guest→host payload.
691    pub fn to_payload(self) -> [u8; ATTACH_ATTEMPT_PAYLOAD_SIZE] {
692        let mut payload = [0u8; ATTACH_ATTEMPT_PAYLOAD_SIZE];
693        payload[0] = ATTACH_ATTEMPT_WIRE_VERSION;
694        payload[1] = self.transition.wire_value();
695        payload[2] = self.kind.wire_value();
696        // payload[3] is reserved and remains zero.
697        payload[4..12].copy_from_slice(&self.generation.to_le_bytes());
698        payload
699    }
700
701    /// Decode an exact, canonical payload. Unknown versions/discriminants,
702    /// non-zero reserved data, zero generations, and size mismatches are
703    /// rejected rather than partially interpreted.
704    pub fn from_payload(payload: &[u8]) -> Option<Self> {
705        if payload.len() != ATTACH_ATTEMPT_PAYLOAD_SIZE
706            || payload[0] != ATTACH_ATTEMPT_WIRE_VERSION
707            || payload[3] != 0
708        {
709            return None;
710        }
711        let transition = AttachAttemptTransition::from_wire(payload[1])?;
712        let kind = AttachAttemptKind::from_wire(payload[2])?;
713        let generation = u64::from_le_bytes(payload[4..12].try_into().ok()?);
714        if generation == 0 {
715            return None;
716        }
717        Some(Self {
718            transition,
719            kind,
720            generation,
721        })
722    }
723}
724
725/// Host-authoritative reason for cancelling an attach attempt.
726///
727/// The discriminant is carried by the control packet's prefix rather than in
728/// an untagged side channel, so a guest diagnostic can never accidentally
729/// describe one host budget as another. Scheduler attach currently has one
730/// valid cancellation authority: delivered max-vCPU service.
731#[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
732pub enum AttachCancelCause {
733    ServiceBudget,
734}
735
736impl AttachCancelCause {
737    /// Stable diagnostic label used by the guest's typed failure report.
738    pub const fn label(self) -> &'static str {
739        match self {
740            Self::ServiceBudget => "host-vcpu-service-budget",
741        }
742    }
743}
744
745/// Port-0 prefix for a max-vCPU-service-budget attach cancellation.
746pub const SIGNAL_ATTACH_CANCEL_SERVICE_BUDGET: u8 = 0xAF;
747
748/// Backwards-compatible name for the only currently valid cancellation
749/// prefix. New decoding should use [`AttachControlPacket`].
750pub const SIGNAL_ATTACH_CANCEL: u8 = SIGNAL_ATTACH_CANCEL_SERVICE_BUDGET;
751
752/// Port-0 prefix acknowledging that the host accepted and re-anchored an
753/// attach `Started` boundary.
754pub const SIGNAL_ATTACH_STARTED_ACK: u8 = 0xB0;
755
756/// Port-0 prefix acknowledging that the host accepted and re-anchored an
757/// attach `Finished` boundary.
758pub const SIGNAL_ATTACH_FINISHED_ACK: u8 = 0xB1;
759
760/// Fixed port-0 packet size: one typed prefix plus 16 lowercase hexadecimal
761/// generation digits.
762///
763/// ASCII is intentional: unlike raw `u64` bytes, the suffix cannot alias any
764/// legacy high-byte hvc0 control signal while a split packet is buffered.
765pub const ATTACH_CONTROL_PACKET_SIZE: usize = 17;
766
767pub const ATTACH_CANCEL_PACKET_SIZE: usize = ATTACH_CONTROL_PACKET_SIZE;
768pub const ATTACH_STARTED_ACK_PACKET_SIZE: usize = ATTACH_CONTROL_PACKET_SIZE;
769pub const ATTACH_FINISHED_ACK_PACKET_SIZE: usize = ATTACH_CONTROL_PACKET_SIZE;
770
771/// One typed, generation-tagged host→guest scheduler-attach control packet.
772#[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
773pub enum AttachControlPacket {
774    StartedAck {
775        generation: u64,
776    },
777    FinishedAck {
778        generation: u64,
779    },
780    Cancel {
781        generation: u64,
782        cause: AttachCancelCause,
783    },
784}
785
786impl AttachControlPacket {
787    pub const fn generation(self) -> u64 {
788        match self {
789            Self::StartedAck { generation }
790            | Self::FinishedAck { generation }
791            | Self::Cancel { generation, .. } => generation,
792        }
793    }
794
795    pub const fn signal(self) -> u8 {
796        match self {
797            Self::StartedAck { .. } => SIGNAL_ATTACH_STARTED_ACK,
798            Self::FinishedAck { .. } => SIGNAL_ATTACH_FINISHED_ACK,
799            Self::Cancel {
800                cause: AttachCancelCause::ServiceBudget,
801                ..
802            } => SIGNAL_ATTACH_CANCEL_SERVICE_BUDGET,
803        }
804    }
805
806    pub const fn from_signal(signal: u8, generation: u64) -> Option<Self> {
807        if generation == 0 {
808            return None;
809        }
810        match signal {
811            SIGNAL_ATTACH_STARTED_ACK => Some(Self::StartedAck { generation }),
812            SIGNAL_ATTACH_FINISHED_ACK => Some(Self::FinishedAck { generation }),
813            SIGNAL_ATTACH_CANCEL_SERVICE_BUDGET => Some(Self::Cancel {
814                generation,
815                cause: AttachCancelCause::ServiceBudget,
816            }),
817            _ => None,
818        }
819    }
820}
821
822/// Whether a byte begins one of the fixed-size attach control packets.
823pub const fn is_attach_control_signal(signal: u8) -> bool {
824    matches!(
825        signal,
826        SIGNAL_ATTACH_STARTED_ACK
827            | SIGNAL_ATTACH_FINISHED_ACK
828            | SIGNAL_ATTACH_CANCEL_SERVICE_BUDGET
829    )
830}
831
832fn encode_generation_control(signal: u8, generation: u64) -> [u8; ATTACH_CONTROL_PACKET_SIZE] {
833    const HEX: &[u8; 16] = b"0123456789abcdef";
834    let mut packet = [b'0'; ATTACH_CONTROL_PACKET_SIZE];
835    packet[0] = signal;
836    for (index, slot) in packet[1..].iter_mut().enumerate() {
837        let shift = (15 - index) * 4;
838        *slot = HEX[((generation >> shift) & 0xf) as usize];
839    }
840    packet
841}
842
843fn decode_generation_control(packet: &[u8]) -> Option<(u8, u64)> {
844    if packet.len() != ATTACH_CONTROL_PACKET_SIZE || !is_attach_control_signal(packet[0]) {
845        return None;
846    }
847    let mut generation = 0u64;
848    for &digit in &packet[1..] {
849        let nibble = match digit {
850            b'0'..=b'9' => digit - b'0',
851            b'a'..=b'f' => digit - b'a' + 10,
852            _ => return None,
853        };
854        generation = generation.checked_mul(16)?.checked_add(u64::from(nibble))?;
855    }
856    (generation != 0).then_some((packet[0], generation))
857}
858
859/// Encode any typed generation control packet.
860pub fn encode_attach_control(packet: AttachControlPacket) -> [u8; ATTACH_CONTROL_PACKET_SIZE] {
861    encode_generation_control(packet.signal(), packet.generation())
862}
863
864/// Decode one exact typed generation control packet.
865pub fn decode_attach_control(packet: &[u8]) -> Option<AttachControlPacket> {
866    let (signal, generation) = decode_generation_control(packet)?;
867    AttachControlPacket::from_signal(signal, generation)
868}
869
870/// Encode a generation-tagged host→guest attach cancellation packet.
871pub fn encode_attach_cancel(
872    generation: u64,
873    cause: AttachCancelCause,
874) -> [u8; ATTACH_CANCEL_PACKET_SIZE] {
875    encode_attach_control(AttachControlPacket::Cancel { generation, cause })
876}
877
878/// Decode one exact host→guest attach cancellation packet.
879pub fn decode_attach_cancel(packet: &[u8]) -> Option<(u64, AttachCancelCause)> {
880    match decode_attach_control(packet)? {
881        AttachControlPacket::Cancel { generation, cause } => Some((generation, cause)),
882        AttachControlPacket::StartedAck { .. } | AttachControlPacket::FinishedAck { .. } => None,
883    }
884}
885
886/// Encode the host rendezvous which proves it accepted and re-anchored the
887/// matching attach `Started` generation.
888pub fn encode_attach_started_ack(generation: u64) -> [u8; ATTACH_STARTED_ACK_PACKET_SIZE] {
889    encode_attach_control(AttachControlPacket::StartedAck { generation })
890}
891
892/// Decode one exact generation-tagged attach Started acknowledgement.
893pub fn decode_attach_started_ack(packet: &[u8]) -> Option<u64> {
894    match decode_attach_control(packet)? {
895        AttachControlPacket::StartedAck { generation } => Some(generation),
896        AttachControlPacket::FinishedAck { .. } | AttachControlPacket::Cancel { .. } => None,
897    }
898}
899
900/// Encode the host rendezvous which proves it accepted and re-anchored the
901/// matching attach `Finished` generation.
902pub fn encode_attach_finished_ack(generation: u64) -> [u8; ATTACH_FINISHED_ACK_PACKET_SIZE] {
903    encode_attach_control(AttachControlPacket::FinishedAck { generation })
904}
905
906/// Decode one exact generation-tagged attach Finished acknowledgement.
907pub fn decode_attach_finished_ack(packet: &[u8]) -> Option<u64> {
908    match decode_attach_control(packet)? {
909        AttachControlPacket::FinishedAck { generation } => Some(generation),
910        AttachControlPacket::StartedAck { .. } | AttachControlPacket::Cancel { .. } => None,
911    }
912}
913
914/// Lifecycle phase carried in the 1-byte header of a
915/// [`MsgType::Lifecycle`] payload. Replaces the prior
916/// `KTSTR_INIT_STARTED` / `KTSTR_PAYLOAD_STARTING` /
917/// `SCHEDULER_DIED` / `SCHEDULER_NOT_ATTACHED` COM2 sentinels.
918///
919/// `SchedulerNotAttached` carries an optional UTF-8 reason suffix
920/// (the bytes following the 1-byte phase header in the TLV
921/// payload) — every other variant has an empty suffix.
922#[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
923pub enum LifecyclePhase {
924    /// Init started — devtmpfs mounted, initramfs verified,
925    /// equivalent to the legacy `KTSTR_INIT_STARTED` sentinel.
926    InitStarted,
927    /// Payload starting — guest dispatch is about to invoke the
928    /// `#[ktstr_test]` body. Equivalent to the legacy
929    /// `KTSTR_PAYLOAD_STARTING` sentinel.
930    PayloadStarting,
931    /// Scheduler process exited during startup. Equivalent to the
932    /// legacy `SCHEDULER_DIED` sentinel.
933    SchedulerDied,
934    /// Scheduler stayed alive but never attached to sched_ext (BPF
935    /// verifier reject, ops mismatch, sysfs absent). Equivalent to
936    /// the legacy `SCHEDULER_NOT_ATTACHED:<reason>` sentinel; the
937    /// reason suffix lives in the bytes after the 1-byte phase
938    /// header.
939    SchedulerNotAttached,
940    /// The injected verifier workload made forward progress: at least one
941    /// worker of the `--ktstr-verifier-workload` run advanced on-CPU after
942    /// requesting SCHED_EXT policy. Combined with `SchedulerAttached`, it
943    /// is a positive, scheduler-agnostic dispatch proof. Alone it is not
944    /// attach proof: schedulerless SCHED_EXT tasks may run through the
945    /// kernel fallback. Given a `SchedulerAttached` frame, the ABSENCE of
946    /// this frame means the scheduler attached (sched_ext `enabled`) but
947    /// never dispatched the workload — a distinct failure from never
948    /// attaching. Carries an empty suffix. Has no legacy COM2 sentinel
949    /// equivalent.
950    WorkloadDispatched,
951    /// A real sched_ext scheduler attached: the scheduler process is
952    /// alive AND `poll_scx_attached` observed `root/ops` registered with
953    /// `state == Enabled` (see `try_spawn_scheduler`). Emitted by the boot
954    /// wrapper `spawn_scheduler_from_paths` on its `Ok(Some(..))` success
955    /// arm — the single site where attach is definitively known with a
956    /// live child — so it is NOT emitted for a no-scheduler / EEVDF run
957    /// (binary absent → `Ok(None)`) nor when the scheduler died or never
958    /// bound (those emit `SchedulerDied` / `SchedulerNotAttached`
959    /// instead). Distinct from `PayloadStarting`: this frame lands at
960    /// Phase-3 end (before `PayloadStarting`, which the guest emits at
961    /// Phase 5 for EVERY run regardless of attach), so its presence is a
962    /// positive, live-scheduler attach proof the host uses to arm the
963    /// progress watchdog's workload deadline from the confirmed-attach
964    /// moment (see `freeze_coord::dispatch`'s Lifecycle arm). Carries an
965    /// empty suffix. The post-hoc `AttachOutcome` verdict scan keys on
966    /// this definitive frame rather than `PayloadStarting`, which is also
967    /// emitted for schedulerless runs.
968    SchedulerAttached,
969}
970
971impl LifecyclePhase {
972    /// 1-byte on-wire discriminant. `0` is reserved as the
973    /// "unknown / invalid" sentinel — host parsers reject zero
974    /// rather than silently mapping it to a known phase.
975    pub const fn wire_value(self) -> u8 {
976        match self {
977            LifecyclePhase::InitStarted => 1,
978            LifecyclePhase::PayloadStarting => 2,
979            LifecyclePhase::SchedulerDied => 3,
980            LifecyclePhase::SchedulerNotAttached => 4,
981            LifecyclePhase::WorkloadDispatched => 5,
982            LifecyclePhase::SchedulerAttached => 6,
983        }
984    }
985
986    /// Reverse the wire mapping. Returns `None` for `0`
987    /// (reserved sentinel) or any value not present in the variant
988    /// list — host parsers skip unknown phases and log them rather
989    /// than panicking.
990    pub const fn from_wire(value: u8) -> Option<Self> {
991        match value {
992            1 => Some(LifecyclePhase::InitStarted),
993            2 => Some(LifecyclePhase::PayloadStarting),
994            3 => Some(LifecyclePhase::SchedulerDied),
995            4 => Some(LifecyclePhase::SchedulerNotAttached),
996            5 => Some(LifecyclePhase::WorkloadDispatched),
997            6 => Some(LifecyclePhase::SchedulerAttached),
998            _ => None,
999        }
1000    }
1001}
1002
1003// ---------------------------------------------------------------------------
1004// On-wire u32 discriminants
1005// ---------------------------------------------------------------------------
1006//
1007// Kept as `pub const` for callers that compare a parsed frame's
1008// `msg_type` field directly (e.g. the freeze coordinator's stream
1009// filter). [`MsgType::wire_value`] is the typed entry point; the
1010// constants are the same values exposed for raw-byte comparisons.
1011
1012/// Stimulus event from the guest step executor (step START frame).
1013pub const MSG_TYPE_STIMULUS: u32 = 0x5354_494D; // "STIM"
1014
1015/// Per-step END frame from the guest step executor (reuses the
1016/// [`StimulusPayload`] body; see [`MsgType::StepEnd`]).
1017pub const MSG_TYPE_STEP_END: u32 = 0x5354_454E; // "STEN"
1018
1019/// Scenario start marker.
1020pub const MSG_TYPE_SCENARIO_START: u32 = 0x5343_5354; // "SCST"
1021
1022/// Pause watchdog clock.
1023pub const MSG_TYPE_SCENARIO_PAUSE: u32 = 0x5343_5050; // "SCPP"
1024
1025/// Resume watchdog clock after pause.
1026pub const MSG_TYPE_SCENARIO_RESUME: u32 = 0x5343_5252; // "SCRR"
1027
1028/// Scenario end marker.
1029pub const MSG_TYPE_SCENARIO_END: u32 = 0x5343_454E; // "SCEN"
1030
1031/// Guest exit code (payload: 4-byte i32).
1032pub const MSG_TYPE_EXIT: u32 = 0x4558_4954; // "EXIT"
1033
1034/// Test result (payload: postcard-encoded AssertResult).
1035pub const MSG_TYPE_TEST_RESULT: u32 = 0x5445_5354; // "TEST"
1036
1037/// Scheduler process exit (payload: 4-byte i32 exit code).
1038pub const MSG_TYPE_SCHED_EXIT: u32 = 0x5343_4458; // "SCDX"
1039
1040/// Guest crash diagnostic (payload: UTF-8 panic + backtrace).
1041pub const MSG_TYPE_CRASH: u32 = 0x4352_5348; // "CRSH"
1042
1043/// Per-payload-invocation metrics
1044/// (payload: postcard-encoded `crate::test_support::PayloadMetrics`).
1045pub const MSG_TYPE_PAYLOAD_METRICS: u32 = 0x504d_4554; // "PMET"
1046
1047/// Coverage profraw blob (payload: raw `.profraw` bytes serialized by
1048/// `__llvm_profile_write_buffer`).
1049pub const MSG_TYPE_PROFRAW: u32 = 0x5052_4157; // "PRAW"
1050
1051/// wprof Perfetto-format trace blob (payload: raw `.pb` bytes
1052/// produced by `/bin/wprof -T trace.pb` during auto-repro). The
1053/// host's freeze coordinator writes the payload to a sibling of
1054/// the failure-dump file so the operator finds it under
1055/// [`crate::test_support::sidecar_dir`] alongside the JSON dump.
1056pub const MSG_TYPE_WPROF_TRACE: u32 = 0x5750_5246; // "WPRF"
1057
1058/// Guest→host wprof trace CHUNK (one ordered slice of a `.pb` too large
1059/// for a single bulk frame; the stream is terminated by a
1060/// [`MSG_TYPE_WPROF_TRACE`] frame carrying the final slice). See
1061/// [`MsgType::WprofTraceChunk`].
1062pub const MSG_TYPE_WPROF_TRACE_CHUNK: u32 = 0x5750_5243; // "WPRC"
1063
1064/// Guest→host ordered teardown barrier (payload: empty).
1065///
1066/// Tag spelled `"TDBR"` (TeaDown BaRrier). The coordinator replies
1067/// with [`MSG_TYPE_TEARDOWN_BARRIER_ACK`] only after all preceding
1068/// guest frames are persisted and the lifecycle is in Teardown.
1069pub const MSG_TYPE_TEARDOWN_BARRIER: u32 = 0x5444_4252; // "TDBR"
1070
1071/// Host→guest acknowledgement for [`MSG_TYPE_TEARDOWN_BARRIER`]
1072/// (payload: empty). Tag spelled `"TDBA"` (TeaDown Barrier Ack).
1073pub const MSG_TYPE_TEARDOWN_BARRIER_ACK: u32 = 0x5444_4241; // "TDBA"
1074
1075/// Guest→host on-demand snapshot request
1076/// (payload: [`SnapshotRequestPayload`]).
1077pub const MSG_TYPE_SNAPSHOT_REQUEST: u32 = 0x534e_5251; // "SNRQ"
1078
1079/// Host→guest on-demand snapshot reply
1080/// (payload: [`SnapshotReplyPayload`]).
1081pub const MSG_TYPE_SNAPSHOT_REPLY: u32 = 0x534e_5250; // "SNRP"
1082
1083/// Guest→host system-ready signal (payload: empty).
1084///
1085/// Tag spelled `"SRDY"` in hex digits; on-wire bytes (LE) are
1086/// `0x59 0x44 0x52 0x53` (`"YDRS"` byte-by-byte). The freeze
1087/// coordinator's bulk-drain dispatch promotes a CRC-valid
1088/// `MSG_TYPE_SYS_RDY` frame into the monitor's boot-complete
1089/// eventfd. See [`MsgType::SysRdy`] for the protocol contract.
1090pub const MSG_TYPE_SYS_RDY: u32 = 0x5352_4459; // "SRDY"
1091
1092/// Guest→host readiness edge for configured host BPF-map writes.
1093/// Empty payload; promoted to a dedicated host eventfd only after CRC and
1094/// shape validation. The guest emits it after probes and optional wprof are
1095/// ready, immediately before ScenarioStart.
1096pub const MSG_TYPE_BPF_MAP_WRITE_READY: u32 = 0x424D_5259; // "BMRY"
1097
1098/// Guest→host finite prerequisite/readiness-wait boundary.
1099///
1100/// Tag spelled `"RDWT"` (ReaDiness WaiT). The payload is
1101/// [`READINESS_WAIT_PAYLOAD_SIZE`] bytes and decodes through
1102/// [`ReadinessWaitEvent::from_payload`].
1103pub const MSG_TYPE_READINESS_WAIT: u32 = 0x5244_5754; // "RDWT"
1104
1105/// Guest→host scheduler-swap notification (payload: empty).
1106///
1107/// Tag spelled `"SCSW"` (SCheduler SWap) in hex digits; on-wire bytes
1108/// (LE) are `0x57 0x53 0x43 0x53` (`"WSCS"` byte-by-byte). Emitted by
1109/// the guest's `kill_current_scheduler` after `wait_for_scx_disabled`
1110/// returns (so `*scx_root` is already NULL); the freeze coordinator
1111/// synchronously invalidates the periodic-capture accessor on a
1112/// CRC-valid frame. See [`MsgType::SchedSwapNotify`] for the protocol
1113/// contract.
1114pub const MSG_TYPE_SCHED_SWAP_NOTIFY: u32 = 0x5343_5357; // "SCSW"
1115
1116/// Guest→host scheduler attach-attempt boundary.
1117///
1118/// Tag spelled `"ATTA"` (ATtach ATtempt) in hex digits. The payload is
1119/// [`ATTACH_ATTEMPT_PAYLOAD_SIZE`] bytes and decodes through
1120/// [`AttachAttemptEvent::from_payload`].
1121pub const MSG_TYPE_ATTACH_ATTEMPT: u32 = 0x4154_5441; // "ATTA"
1122
1123/// Guest→host stdout chunk (payload: opaque UTF-8 bytes).
1124///
1125/// Replaces the prior COM2 stdout redirect: the guest dups fd 1
1126/// onto the write-end of an internal pipe and a forwarder thread
1127/// chunks the pipe's read-end into TLV frames bounded by
1128/// [`super::bulk::MAX_BULK_FRAME_PAYLOAD`].
1129pub const MSG_TYPE_STDOUT: u32 = 0x534f_5554; // "SOUT"
1130
1131/// Guest→host stderr chunk (payload: opaque UTF-8 bytes).
1132///
1133/// Same chunked redirect semantics as [`MSG_TYPE_STDOUT`], applied
1134/// to fd 2.
1135pub const MSG_TYPE_STDERR: u32 = 0x5345_5252; // "SERR"
1136
1137/// Guest→host scheduler-log chunk (payload: opaque UTF-8 bytes).
1138///
1139/// Replaces the prior COM2 SCHED_OUTPUT_START/END dump in
1140/// `dump_sched_output`. The host concatenates chunks in arrival
1141/// order; the embedded `SCHED_OUTPUT_START` / `SCHED_OUTPUT_END`
1142/// markers and the BPF verifier section travel verbatim inside
1143/// the chunk bytes.
1144pub const MSG_TYPE_SCHED_LOG: u32 = 0x5343_4c47; // "SCLG"
1145
1146/// Guest→host scheduler-STDOUT chunk (payload: opaque UTF-8 bytes).
1147///
1148/// Live per-read chunk of the scheduler child's stdout, shipped as it
1149/// arrives so the stream survives a watchdog timeout that never reaches
1150/// the teardown `dump_sched_output`. See [`MsgType::SchedStdout`].
1151/// Distinct from [`MSG_TYPE_SCHED_LOG`]: no `SCHED_OUTPUT_START/END`
1152/// framing travels in these frames — the payload is the raw child
1153/// stream, delimited only by frame boundaries.
1154pub const MSG_TYPE_SCHED_STDOUT: u32 = 0x5353_544f; // "SSTO"
1155
1156/// Guest→host scheduler-STDERR chunk (payload: opaque UTF-8 bytes).
1157///
1158/// Same live streaming semantics as [`MSG_TYPE_SCHED_STDOUT`], applied
1159/// to the scheduler child's stderr (where libbpf / log-crate output —
1160/// including the BPF verifier log region — typically lands). See
1161/// [`MsgType::SchedStderr`].
1162pub const MSG_TYPE_SCHED_STDERR: u32 = 0x5353_5445; // "SSTE"
1163
1164/// Guest→host authoritative terminal scheduler-STDOUT chunk.
1165///
1166/// The payload begins with [`SCHED_STREAM_FINAL_CHUNK_HEADER_SIZE`] bytes:
1167/// total stream length (`u64` LE), then this chunk's byte offset (`u64` LE),
1168/// followed by the raw stdout bytes. A zero-length stream is represented by
1169/// one header-only frame with both fields zero. The host selects the terminal
1170/// stream only after receiving a contiguous `0..total_len` transaction.
1171pub const MSG_TYPE_SCHED_STDOUT_FINAL: u32 = 0x5353_4f46; // "SSOF"
1172
1173/// Guest→host authoritative terminal scheduler-STDERR chunk.
1174///
1175/// Same completion-aware payload format as
1176/// [`MSG_TYPE_SCHED_STDOUT_FINAL`], applied to stderr.
1177pub const MSG_TYPE_SCHED_STDERR_FINAL: u32 = 0x5353_4546; // "SSEF"
1178
1179/// Header bytes prepended to every authoritative terminal scheduler-stream
1180/// chunk: total stream length (`u64` LE) + chunk offset (`u64` LE).
1181pub const SCHED_STREAM_FINAL_CHUNK_HEADER_SIZE: usize = 16;
1182
1183/// Encode one authoritative terminal scheduler-stream chunk.
1184///
1185/// `offset + bytes.len()` must stay within `total_len`. The transport's TLV
1186/// CRC authenticates the complete returned payload; the embedded lengths let
1187/// the host reject an interrupted multi-frame replay as a whole.
1188pub(crate) fn encode_sched_stream_final_chunk(
1189    total_len: u64,
1190    offset: u64,
1191    bytes: &[u8],
1192) -> Vec<u8> {
1193    let chunk_end = offset
1194        .checked_add(bytes.len() as u64)
1195        .expect("scheduler stream chunk offset overflowed u64");
1196    assert!(
1197        chunk_end <= total_len,
1198        "scheduler stream chunk {offset}..{chunk_end} exceeds total length {total_len}"
1199    );
1200    let mut payload = Vec::with_capacity(SCHED_STREAM_FINAL_CHUNK_HEADER_SIZE + bytes.len());
1201    payload.extend_from_slice(&total_len.to_le_bytes());
1202    payload.extend_from_slice(&offset.to_le_bytes());
1203    payload.extend_from_slice(bytes);
1204    payload
1205}
1206
1207/// Decode one authoritative terminal scheduler-stream chunk.
1208///
1209/// Returns `(total_len, offset, bytes)` only when the fixed-width header is
1210/// present and the chunk range is contained by `total_len`.
1211pub(crate) fn decode_sched_stream_final_chunk(payload: &[u8]) -> Option<(u64, u64, &[u8])> {
1212    let (header, bytes) = payload.split_at_checked(SCHED_STREAM_FINAL_CHUNK_HEADER_SIZE)?;
1213    let total_len = u64::from_le_bytes(header[..8].try_into().ok()?);
1214    let offset = u64::from_le_bytes(header[8..].try_into().ok()?);
1215    let chunk_end = offset.checked_add(bytes.len() as u64)?;
1216    (chunk_end <= total_len).then_some((total_len, offset, bytes))
1217}
1218
1219/// Guest→host lifecycle phase event.
1220///
1221/// Payload layout: 1-byte [`LifecyclePhase`] discriminant followed
1222/// by an optional UTF-8 reason buffer (used by
1223/// `SchedulerNotAttached`'s suffix detail; empty for every other
1224/// phase). Replaces the COM2 `KTSTR_INIT_STARTED` /
1225/// `KTSTR_PAYLOAD_STARTING` / `SCHEDULER_DIED` /
1226/// `SCHEDULER_NOT_ATTACHED` sentinel strings.
1227pub const MSG_TYPE_LIFECYCLE: u32 = 0x4c49_4645; // "LIFE"
1228
1229/// Guest→host kernel address parameters (payload: 24 bytes LE).
1230///
1231/// Sent BEFORE `MSG_TYPE_SYS_RDY` so the monitor has `phys_base`
1232/// and `page_offset_base` before its first sample iteration.
1233/// Payload layout: 24 bytes encoded by [`KernAddrs::to_payload`]:
1234///   `[phys_base + 1 : u64 LE, page_offset_base : u64 LE, kernel_text_runtime_kva + 1 : u64 LE]`
1235/// The guest reads these from `/proc/iomem` and `/proc/kallsyms`
1236/// after `mount_filesystems` — by that point `__startup_64`,
1237/// `kernel_randomize_memory`, `cpu_init → syscall_init`, and the
1238/// post-relocation kallsyms table population have all run, so the
1239/// values are final regardless of KASLR configuration.
1240pub const MSG_TYPE_KERN_ADDRS: u32 = 0x4b41_4452; // "KADR"
1241
1242/// Guest→host: the running kernel's GNU build-id (from
1243/// `/sys/kernel/notes`, `NT_GNU_BUILD_ID`), sent so the host can prove
1244/// the vmlinux it is deriving symbols/offsets from is the SAME BUILD as
1245/// the booted kernel. A stale/mismatched cache entry (a vmlinux whose
1246/// struct layout or symbol addresses differ from the running Image)
1247/// otherwise makes every host-side introspection read silent garbage
1248/// with no error — see the host-side comparison in `freeze_coord`. The
1249/// payload is the raw build-id bytes (typically a 20-byte SHA-1, capped
1250/// at [`KERN_BUILD_ID_MAX`]); empty when the guest could not read it
1251/// (the host then skips the check rather than false-failing).
1252pub const MSG_TYPE_KERN_BUILD_ID: u32 = 0x4b42_4944; // "KBID"
1253
1254/// Upper bound on a GNU build-id payload. The `--build-id` styles the
1255/// kernel uses are `sha1` (20 bytes) and `md5`/`uuid` (16); 64 leaves
1256/// generous headroom for any future style without an unbounded read.
1257pub const KERN_BUILD_ID_MAX: usize = 64;
1258
1259/// Guest→host workload-progress heartbeat: the guest's own scenario-elapsed
1260/// time in milliseconds (8-byte LE u64), emitted on a fixed GUEST-time
1261/// cadence from scenario start through the workload. The host uses it to
1262/// place periodic captures on the GUEST clock rather than host wall-clock,
1263/// so under host oversubscription the fixed `num_snapshots` samples still
1264/// spread across the guest's real phases instead of clustering in whatever
1265/// phase the dilated guest is stuck in. It is a HINT, never a trigger: the
1266/// host always retains capture control and falls back to wall-clock when
1267/// the heartbeats go stale (a wedged scheduler stops running the guest
1268/// thread that emits them) so a degraded guest is still captured.
1269/// Coordinator-internal — never bucketed into the verdict frame log.
1270pub const MSG_TYPE_WORKLOAD_PROGRESS: u32 = 0x5750_5247; // "WPRG"
1271
1272/// Typed payload for [`MSG_TYPE_KERN_ADDRS`].
1273///
1274/// Three u64 fields published by the guest at boot so the host can
1275/// translate kernel virtual addresses without walking guest page
1276/// tables and recover the virt-KASLR slide without a separate
1277/// in-VMM derivation. The wire layout uses bias-by-1 on the
1278/// `phys_base` and `kernel_text_runtime_kva` slots so 0 stays the
1279/// "not yet received / could not derive" sentinel; `page_offset_base`
1280/// is unbiased (today the guest always sends 0 and the host
1281/// re-derives via page-table walk — left in the layout for a future
1282/// extension that bypasses the walk).
1283///
1284/// Constructors:
1285///   - [`Self::new`]: bare fields, no sentinel logic. Used by
1286///     [`crate::vmm::guest_comms::send_kern_addrs`] on the guest
1287///     side.
1288///   - [`Self::from_payload`]: decodes a 24-byte payload, strips
1289///     the +1 bias on the biased slots, validates the length. Used
1290///     by the host dispatch arm in
1291///     `crate::vmm::freeze_coord::dispatch::dispatch_bulk_message`.
1292///
1293/// Field semantics:
1294///   - `phys_base = 0` is a legitimate KASLR-off value (the
1295///     payload encodes it biased as `1`, decoder strips back to
1296///     `0`). [`Self::has_phys_present_bit`] reports whether the
1297///     guest sent a non-zero biased phys_base (i.e. the payload
1298///     carries phys_base data at all).
1299///   - `kernel_text_runtime_kva` is wrapped in `Option<u64>` so
1300///     the decoder distinguishes "guest could not read kallsyms"
1301///     (`None`) from "guest read kallsyms and KASLR is off"
1302///     (`Some(link_kva)`). The bias-by-1 encoding handles the
1303///     former (biased 0 → `None`); a non-zero biased value
1304///     decodes to `Some(raw)`.
1305#[derive(Debug, Clone, Copy)]
1306pub struct KernAddrs {
1307    /// Guest-derived `phys_base` (the KASLR-physical slide), or 0
1308    /// when KASLR-physical is off (`__startup_64` left
1309    /// `phys_base = 0`). Compare with the host's expected
1310    /// load-address to recover the physical KASLR offset.
1311    pub phys_base: u64,
1312    /// Symbol KVA of the guest's `page_offset_base` global (NOT the
1313    /// runtime value the symbol points at — host dereferences via
1314    /// `monitor::symbols::text_kva_to_pa_with_base` + `read_u64` once
1315    /// it has `phys_base` resolved). Read by
1316    /// `crate::vmm::guest_comms::read_kernel_page_offset_base_from_kallsyms`
1317    /// (called from `vmm::rust_init::init`) from `/proc/kallsyms`.
1318    /// Storage class: `.data..ro_after_init` per
1319    /// `arch/x86/kernel/head64.c:63` — written during
1320    /// `kernel_randomize_memory()` in `start_kernel`, frozen after
1321    /// `mark_rodata_ro`. `0` means (a) arm64 (no `page_offset_base`
1322    /// global — `PAGE_OFFSET` is compile-time per
1323    /// `arch/arm64/include/asm/memory.h:43-45`), (b)
1324    /// CONFIG_RANDOMIZE_MEMORY=n (symbol absent), or (c) kallsyms
1325    /// unreadable (kptr_restrict elevated); the host falls back to
1326    /// `resolve_page_offset_with_tcr` (the page-table walk) in
1327    /// every 0 case.
1328    pub page_offset_base: u64,
1329    /// Runtime KVA of `_text` (the kernel image start symbol)
1330    /// from the guest's `/proc/kallsyms`, when readable. The
1331    /// host derives `virt_kaslr = runtime - link_text_kva` using
1332    /// the link-time KVA extracted from vmlinux at coordinator
1333    /// init. `None` when the guest could not read kallsyms
1334    /// (kptr_restrict masked, /proc not mountable, symbol absent).
1335    pub kernel_text_runtime_kva: Option<u64>,
1336}
1337
1338impl KernAddrs {
1339    /// Wire-format byte length. Exact-match check on the receive
1340    /// side so a future payload extension trips a decoder
1341    /// rejection rather than silently dropping the new bytes.
1342    pub const WIRE_LEN: usize = 24;
1343
1344    /// Construct from bare field values. Caller owns the
1345    /// "did I read kallsyms?" decision via the `Option` on
1346    /// `kernel_text_runtime_kva`.
1347    pub fn new(
1348        phys_base: u64,
1349        page_offset_base: u64,
1350        kernel_text_runtime_kva: Option<u64>,
1351    ) -> Self {
1352        Self {
1353            phys_base,
1354            page_offset_base,
1355            kernel_text_runtime_kva,
1356        }
1357    }
1358
1359    /// Encode to a 24-byte LE payload with `+1` bias on the
1360    /// biased slots. Caller transmits this on the wire. Takes
1361    /// `self` by value since [`Self`] is `Copy` and the encoder
1362    /// reads each field at most once.
1363    pub fn to_payload(self) -> [u8; Self::WIRE_LEN] {
1364        let mut buf = [0u8; Self::WIRE_LEN];
1365        buf[..8].copy_from_slice(&(self.phys_base.wrapping_add(1)).to_le_bytes());
1366        buf[8..16].copy_from_slice(&self.page_offset_base.to_le_bytes());
1367        // bias 0 → encodes as 0 (sentinel: guest could not derive)
1368        let runtime_biased = match self.kernel_text_runtime_kva {
1369            Some(kva) => kva.wrapping_add(1),
1370            None => 0,
1371        };
1372        buf[16..24].copy_from_slice(&runtime_biased.to_le_bytes());
1373        buf
1374    }
1375
1376    /// Decode from a wire payload. Returns `None` on length
1377    /// mismatch (exact match required — short payloads never
1378    /// publish either slot to avoid a partial-init race; longer
1379    /// payloads indicate a protocol extension the decoder
1380    /// doesn't understand).
1381    pub fn from_payload(payload: &[u8]) -> Option<Self> {
1382        if payload.len() != Self::WIRE_LEN {
1383            return None;
1384        }
1385        let phys_biased = u64::from_le_bytes(payload[..8].try_into().ok()?);
1386        let page_offset_base = u64::from_le_bytes(payload[8..16].try_into().ok()?);
1387        let runtime_biased = u64::from_le_bytes(payload[16..24].try_into().ok()?);
1388        Some(Self {
1389            // biased 0 means "guest didn't send" — but the
1390            // unbiased phys_base = 0 is legitimate (KASLR off).
1391            // `has_phys_present_bit` distinguishes the two on the
1392            // host side.
1393            phys_base: phys_biased.wrapping_sub(1),
1394            page_offset_base,
1395            kernel_text_runtime_kva: if runtime_biased == 0 {
1396                None
1397            } else {
1398                Some(runtime_biased.wrapping_sub(1))
1399            },
1400        })
1401    }
1402
1403    /// True iff the encoded payload had a non-zero biased
1404    /// `phys_base` slot (i.e. the guest sent phys_base data).
1405    /// Distinguishes "guest sent phys_base = 0" (KASLR off, valid)
1406    /// from "guest didn't send phys_base at all" (truncated wire
1407    /// path, treat as absent). Computed from the post-decode
1408    /// `phys_base` field: encoded `phys_biased = phys_base + 1`
1409    /// is non-zero iff `phys_base != u64::MAX`. Wrap-around case
1410    /// (`phys_base = u64::MAX` encodes to biased 0) is impossible
1411    /// in practice — kernel `phys_base` is a low physical address,
1412    /// never the all-ones sentinel.
1413    pub fn has_phys_present_bit(&self) -> bool {
1414        self.phys_base != u64::MAX
1415    }
1416}
1417
1418/// Guest→host shell-exec exit code (payload: 4-byte LE i32).
1419///
1420/// Replaces the prior COM2 `KTSTR_EXEC_EXIT=N` sentinel line
1421/// emitted by `cargo ktstr shell --exec <cmd>`.
1422pub const MSG_TYPE_EXEC_EXIT: u32 = 0x4558_4358; // "EXCX"
1423
1424/// Guest→host kernel ring-buffer dump (payload: opaque UTF-8 bytes).
1425///
1426/// Sent on the initramfs-extraction failure path so the host sees
1427/// the kernel OOM messages without scraping COM2.
1428pub const MSG_TYPE_DMESG: u32 = 0x444d_5347; // "DMSG"
1429
1430/// Guest→host probe-pipeline JSON output (payload: opaque UTF-8
1431/// bytes).
1432///
1433/// Replaces the prior COM2 ProbeDrain path so probe output and
1434/// scheduler-log dumps stop interleaving on the same serial port.
1435pub const MSG_TYPE_PROBE_OUTPUT: u32 = 0x5052_4f42; // "PROB"
1436
1437/// Guest→host kernel-memory write/read op request (payload:
1438/// postcard-encoded [`KernelOpRequestPayload`]).
1439///
1440/// Carries an [`Op::WriteKernelHot`](crate::scenario::ops::Op::WriteKernelHot)
1441/// / [`Op::WriteKernelCold`](crate::scenario::ops::Op::WriteKernelCold)
1442/// / [`Op::ReadKernelHot`](crate::scenario::ops::Op::ReadKernelHot)
1443/// / [`Op::ReadKernelCold`](crate::scenario::ops::Op::ReadKernelCold)
1444/// request from the guest's step executor to the host coordinator.
1445/// Variable-length payload (target + value bytes do not fit in the
1446/// 72-byte [`SnapshotRequestPayload`]), so this rides a distinct
1447/// MSG_TYPE_* with a postcard-encoded body rather than extending the
1448/// fixed-size snapshot envelope.
1449pub const MSG_TYPE_KERNEL_OP_REQUEST: u32 = 0x4b4f_5251; // "KORQ"
1450
1451/// Host→guest reply to a [`MSG_TYPE_KERNEL_OP_REQUEST`] (payload:
1452/// postcard-encoded [`KernelOpReplyPayload`]). Echoes the request id
1453/// the guest stamped, carries the status + reason + (for reads) the
1454/// value bytes the host coordinator read.
1455pub const MSG_TYPE_KERNEL_OP_REPLY: u32 = 0x4b4f_5250; // "KORP"
1456
1457// ---------------------------------------------------------------------------
1458// ShmMessage — TLV header
1459// ---------------------------------------------------------------------------
1460
1461/// 16-byte TLV header preceding each payload on the wire.
1462///
1463/// Used as the framing header for the bulk virtio-console port-1
1464/// channel; the type name `ShmMessage` is retained from the
1465/// predecessor SHM ring transport (now removed in favour of the
1466/// virtio-console port). CRC32 covers payload bytes only (not the
1467/// header).
1468///
1469/// SAFETY: `repr(C)` with four `u32` fields produces a 16-byte struct
1470/// with no padding (every field is 4-aligned). `_pad` is reserved for
1471/// future schema use; current writers MUST set it to 0 and current
1472/// readers ignore it. zerocopy derives produce no panics — every bit
1473/// pattern is valid for `u32`.
1474#[repr(C)]
1475#[derive(
1476    Clone, Copy, Default, Debug, FromBytes, IntoBytes, zerocopy::Immutable, zerocopy::KnownLayout,
1477)]
1478pub struct ShmMessage {
1479    pub msg_type: u32,
1480    pub length: u32,
1481    pub crc32: u32,
1482    pub _pad: u32,
1483}
1484
1485const _SHM_MESSAGE_SIZE: () = assert!(std::mem::size_of::<ShmMessage>() == 16);
1486
1487/// Size in bytes of the on-wire [`ShmMessage`] header.
1488pub const FRAME_HEADER_SIZE: usize = std::mem::size_of::<ShmMessage>();
1489
1490// ---------------------------------------------------------------------------
1491// ShmEntry — parsed TLV entry
1492// ---------------------------------------------------------------------------
1493
1494/// A single parsed message extracted from the bulk byte stream.
1495///
1496/// `crc_ok` is `true` when the recomputed payload CRC matched the
1497/// guest's stored value. CRC mismatches do not stop the walk — the
1498/// parser yields the entry with `crc_ok=false` and continues with the
1499/// next frame. Downstream consumers may filter on `crc_ok` to drop
1500/// corrupted entries.
1501#[derive(Debug, Clone)]
1502pub struct ShmEntry {
1503    pub msg_type: u32,
1504    pub payload: Vec<u8>,
1505    /// `true` when the recomputed payload CRC matched the on-wire CRC.
1506    pub crc_ok: bool,
1507}
1508
1509// ---------------------------------------------------------------------------
1510// Stimulus payload — guest step executor → host
1511// ---------------------------------------------------------------------------
1512
1513/// Payload for stimulus events written by the guest step executor.
1514///
1515/// Compact 24-byte struct describing the state after each step's ops
1516/// are applied. The host correlates these with monitor samples to map
1517/// scheduler telemetry to scenario phases.
1518#[repr(C)]
1519#[derive(Clone, Copy, Default, Debug, IntoBytes, zerocopy::Immutable, zerocopy::KnownLayout)]
1520pub struct StimulusPayload {
1521    /// Milliseconds since scenario start.
1522    pub elapsed_ms: u32,
1523    /// Index of the step that was just applied.
1524    pub step_index: u16,
1525    /// Number of ops applied in this step.
1526    pub op_count: u16,
1527    /// Bitmask of Op variant discriminants present in this step.
1528    pub op_kinds: u32,
1529    /// Number of live cgroups after this step: sum of step-local
1530    /// cgroups (from the current Step's `CgroupDef`s + `Op`s) and
1531    /// Backdrop-owned cgroups that persist across every Step.
1532    pub cgroup_count: u16,
1533    /// Total worker handles after this step: sum of step-local
1534    /// workers and Backdrop-spawned workers that persist across
1535    /// every Step.
1536    pub worker_count: u16,
1537    /// Sum of all workers' iteration counts at this step boundary.
1538    /// Read from shared MAP_SHARED counters in the step executor.
1539    pub total_iterations: u64,
1540}
1541
1542const _STIMULUS_SIZE: () = assert!(std::mem::size_of::<StimulusPayload>() == 24);
1543
1544/// Deserialized stimulus event.
1545#[derive(Debug, Clone)]
1546pub struct StimulusEvent {
1547    pub elapsed_ms: u32,
1548    pub step_index: u16,
1549    pub op_count: u16,
1550    pub op_kinds: u32,
1551    pub cgroup_count: u16,
1552    pub worker_count: u16,
1553    pub total_iterations: u64,
1554}
1555
1556impl StimulusEvent {
1557    /// Deserialize from raw payload bytes. Requires EXACTLY a
1558    /// [`StimulusPayload`]-sized (24-byte) buffer — a shorter buffer would
1559    /// truncate and a longer one would carry trailing bytes the guest
1560    /// never frames (`send_stimulus`/`send_step_end` always write exactly
1561    /// 24 bytes), so both are rejected (matching [`KernAddrs::from_payload`]'s
1562    /// exact-length gate). A torn or hostile oversized frame is dropped
1563    /// rather than promoted by reading a 24-byte prefix.
1564    pub fn from_payload(data: &[u8]) -> Option<Self> {
1565        if data.len() != std::mem::size_of::<StimulusPayload>() {
1566            return None;
1567        }
1568        Some(StimulusEvent {
1569            elapsed_ms: u32::from_ne_bytes(data[0..4].try_into().ok()?),
1570            step_index: u16::from_ne_bytes(data[4..6].try_into().ok()?),
1571            op_count: u16::from_ne_bytes(data[6..8].try_into().ok()?),
1572            op_kinds: u32::from_ne_bytes(data[8..12].try_into().ok()?),
1573            cgroup_count: u16::from_ne_bytes(data[12..14].try_into().ok()?),
1574            worker_count: u16::from_ne_bytes(data[14..16].try_into().ok()?),
1575            total_iterations: u64::from_ne_bytes(data[16..24].try_into().ok()?),
1576        })
1577    }
1578}
1579
1580/// Size in bytes of the [`MsgType::ScenarioEnd`] payload: two
1581/// little-endian `u64`s — scenario-relative elapsed milliseconds
1582/// followed by the final cumulative worker iteration count.
1583pub const SCENARIO_END_PAYLOAD_SIZE: usize = 16;
1584
1585/// Parse the [`MsgType::ScenarioEnd`] payload written by
1586/// [`crate::vmm::guest_comms::send_scenario_end`]: `elapsed_ms`
1587/// (LE `u64`, scenario-relative) followed by `total_iterations`
1588/// (LE `u64`, the cumulative worker iteration count summed across
1589/// every live handle at the LAST step's end). The host preserves the pair as a
1590/// terminal [`crate::timeline::StimulusEvent`]; it is boundary telemetry, not
1591/// the CPU-denominated iteration-rate source. Returns `None` for a short/torn
1592/// payload so a CRC-bad or truncated frame is skipped rather than misread.
1593pub fn parse_scenario_end(payload: &[u8]) -> Option<(u64, u64)> {
1594    if payload.len() < SCENARIO_END_PAYLOAD_SIZE {
1595        return None;
1596    }
1597    let elapsed_ms = u64::from_le_bytes(payload[0..8].try_into().ok()?);
1598    let total_iterations = u64::from_le_bytes(payload[8..16].try_into().ok()?);
1599    Some((elapsed_ms, total_iterations))
1600}
1601
1602// ---------------------------------------------------------------------------
1603// Snapshot request/reply TLV payloads
1604// ---------------------------------------------------------------------------
1605
1606/// Maximum length, in bytes, of a snapshot tag (capture name or
1607/// watchpoint symbol path) carried inside the
1608/// [`SnapshotRequestPayload`]. Tags longer than this bound are
1609/// truncated by the guest before publishing; the host treats the
1610/// first NUL as the boundary, or stops at this size if no NUL is
1611/// present.
1612pub const SNAPSHOT_TAG_MAX: usize = 64;
1613
1614/// Maximum length, in bytes, of a host-supplied reason string carried
1615/// inside the [`SnapshotReplyPayload`]. Same semantics as the tag
1616/// buffer (NUL-terminated when shorter, truncated when longer). Sized
1617/// to hold typed-Err diagnostics that name the failing condition
1618/// (e.g. `kaslr_offset == 0`, `kern_virt_kaslr` Arc state) PLUS the
1619/// failing symbol + KVA PLUS the actionable remediation tip (e.g.
1620/// `set #[ktstr_test(kaslr = false)]`). The longest such diagnostic
1621/// today — Fix C's high-half/zero-offset rejection at
1622/// `crate::vmm::freeze_coord::snapshot::arm_user_watchpoint` — is
1623/// ~343 bytes when rendered with a typical symbol + KVA; 512 gives
1624/// ~170 bytes of headroom for future diagnostics. The original
1625/// 64-byte buffer and an intermediate 256-byte size both truncated
1626/// this message before the remediation tail.
1627pub const SNAPSHOT_REASON_MAX: usize = 512;
1628
1629/// Snapshot request kind: no request pending. Used as the sentinel
1630/// value for an uninitialised request slot (this discriminant must
1631/// not appear on the wire — the framing of a TLV with
1632/// `MSG_TYPE_SNAPSHOT_REQUEST` already implies a request).
1633pub const SNAPSHOT_KIND_NONE: u32 = 0;
1634
1635/// Snapshot request kind: capture-now. The host runs
1636/// `freeze_and_dispatch(FreezeMode::Capture { gate_on_exit_kind: false })` and stores the resulting
1637/// `FailureDumpReport` on the bridge keyed by the request tag.
1638pub const SNAPSHOT_KIND_CAPTURE: u32 = 1;
1639
1640/// Snapshot request kind: hardware-watchpoint registration. The host
1641/// resolves the symbol path through the vmlinux ELF symtab,
1642/// allocates a free user watchpoint slot, programs the hardware
1643/// watchpoint via `KVM_SET_GUEST_DEBUG`, and replies. A future
1644/// guest write to the resolved KVA fires the corresponding debug
1645/// exit and synthesises a snapshot tagged by the symbol.
1646pub const SNAPSHOT_KIND_WATCH: u32 = 2;
1647
1648/// Reply status: success — the host completed the requested action
1649/// (capture stored, or watchpoint armed).
1650pub const SNAPSHOT_STATUS_OK: u32 = 1;
1651
1652/// Reply status: failure — the host rejected or could not complete
1653/// the request. The reason buffer carries a UTF-8 diagnostic.
1654pub const SNAPSHOT_STATUS_ERR: u32 = 2;
1655
1656/// Outcome of a guest-driven snapshot request: ok, error with reason,
1657/// or transport failure (port unavailable / not in guest / timeout).
1658#[derive(Debug)]
1659pub enum SnapshotRequestResult {
1660    /// Host completed the request. For
1661    /// [`SNAPSHOT_KIND_CAPTURE`] this means the report
1662    /// was stored on the bridge under the supplied tag; for
1663    /// [`SNAPSHOT_KIND_WATCH`] this means the hardware
1664    /// watchpoint was armed.
1665    Ok,
1666    /// Host accepted the request but completed it as a failure. The
1667    /// reason carries the host-supplied diagnostic text (truncated to
1668    /// [`SNAPSHOT_REASON_MAX`] bytes).
1669    HostError { reason: String },
1670    /// Transport failed (called from host context, port not yet open,
1671    /// host did not reply within `timeout`, malformed reply frame).
1672    /// The supplied diagnostic names the underlying cause.
1673    TransportError { reason: String },
1674}
1675
1676/// Snapshot request payload (72 bytes).
1677///
1678/// Sent guest→host as the payload of a [`MsgType::SnapshotRequest`]
1679/// frame on virtio-console port 1 TX. The guest fills every field
1680/// before publishing; the trailing zeros in `tag` form the NUL
1681/// terminator when the supplied tag is shorter than
1682/// [`SNAPSHOT_TAG_MAX`].
1683///
1684/// SAFETY: `repr(C)` with `u32 + u32 + [u8; 64]` produces a 72-byte
1685/// struct with no padding (every field is naturally aligned;
1686/// trailing array of `u8` requires no end-of-struct padding).
1687/// Every bit pattern is valid for `u32` and `u8`. zerocopy derives
1688/// produce no panics.
1689#[repr(C)]
1690#[derive(Copy, Clone, Debug, FromBytes, IntoBytes, zerocopy::Immutable, zerocopy::KnownLayout)]
1691pub struct SnapshotRequestPayload {
1692    /// Monotonic request id the guest stamped before publishing.
1693    /// The host echoes this value into the matching
1694    /// [`SnapshotReplyPayload::request_id`] so the guest's blocking
1695    /// reader can pair against the original request.
1696    pub request_id: u32,
1697    /// Request kind: one of [`SNAPSHOT_KIND_CAPTURE`] /
1698    /// [`SNAPSHOT_KIND_WATCH`]. [`SNAPSHOT_KIND_NONE`] is invalid on
1699    /// the wire — the host rejects it with [`SNAPSHOT_STATUS_ERR`].
1700    pub kind: u32,
1701    /// Tag — UTF-8, NUL-terminated when shorter than the buffer;
1702    /// truncated to [`SNAPSHOT_TAG_MAX`] when longer. For
1703    /// [`SNAPSHOT_KIND_CAPTURE`] the tag is the snapshot name (key
1704    /// the bridge stores the report under); for
1705    /// [`SNAPSHOT_KIND_WATCH`] the tag is the symbol path the host
1706    /// resolves through vmlinux ELF.
1707    pub tag: [u8; SNAPSHOT_TAG_MAX],
1708}
1709
1710const _SNAPSHOT_REQUEST_PAYLOAD_SIZE: () =
1711    assert!(std::mem::size_of::<SnapshotRequestPayload>() == 8 + SNAPSHOT_TAG_MAX);
1712
1713/// Snapshot reply payload (520 bytes: `u32 request_id + u32 status + [u8; 512] reason`).
1714///
1715/// Sent host→guest as the payload of a [`MsgType::SnapshotReply`]
1716/// frame on virtio-console port 1 RX. Mirrors the request layout —
1717/// the guest matches `request_id` against its outstanding request
1718/// and reads `status`/`reason` to surface the host's verdict.
1719///
1720/// SAFETY: identical layout reasoning as [`SnapshotRequestPayload`].
1721#[repr(C)]
1722#[derive(Copy, Clone, Debug, FromBytes, IntoBytes, zerocopy::Immutable, zerocopy::KnownLayout)]
1723pub struct SnapshotReplyPayload {
1724    /// Echo of the request's `request_id`. The guest's blocking
1725    /// reader spins until it observes this value match its
1726    /// outstanding request.
1727    pub request_id: u32,
1728    /// Reply status: [`SNAPSHOT_STATUS_OK`] when the host completed
1729    /// the request, [`SNAPSHOT_STATUS_ERR`] otherwise.
1730    pub status: u32,
1731    /// Reason — UTF-8, NUL-terminated when shorter than the buffer;
1732    /// truncated to [`SNAPSHOT_REASON_MAX`] when longer. Empty
1733    /// (all-zero) on the success path.
1734    pub reason: [u8; SNAPSHOT_REASON_MAX],
1735}
1736
1737const _SNAPSHOT_REPLY_PAYLOAD_SIZE: () =
1738    assert!(std::mem::size_of::<SnapshotReplyPayload>() == 8 + SNAPSHOT_REASON_MAX);
1739
1740// ---------------------------------------------------------------------------
1741// KernelOp request/reply payloads (postcard-encoded, variable-length)
1742// ---------------------------------------------------------------------------
1743
1744/// Hot/cold orchestration discriminant for kernel-memory ops on the
1745/// wire. Encoded inside [`KernelOpRequestPayload`].
1746#[derive(Copy, Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
1747pub enum KernelOpMode {
1748    /// Hot: dispatched on a host worker thread without freeze
1749    /// rendezvous. Mirrors `Op::WriteKernelHot` / `Op::ReadKernelHot`
1750    /// orchestration. Caller is responsible for guest-side sync.
1751    Hot,
1752    /// Cold: dispatched inside a freeze rendezvous with every vCPU
1753    /// parked. Mirrors `Op::WriteKernelCold` / `Op::ReadKernelCold`
1754    /// orchestration. Coherent with respect to guest state.
1755    Cold,
1756}
1757
1758/// Direction discriminant: write vs read. Inside
1759/// [`KernelOpRequestPayload`] the kind picks WHICH `GuestKernel::*`
1760/// method family the host dispatcher invokes.
1761#[derive(Copy, Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
1762pub enum KernelOpDirection {
1763    /// Write: `values` contains the bytes to write; reply carries
1764    /// success/error and the per-write byte count.
1765    Write,
1766    /// Read: `values` is empty; reply carries the bytes read into
1767    /// `KernelOpReplyPayload::read_values`.
1768    Read,
1769}
1770
1771/// Wire-encoded [`crate::scenario::ops::KernelTarget`] variant tag.
1772/// Mirrors the `KernelTarget` enum variants 1:1; postcard encodes
1773/// the tag + the variant payload that follows in [`KernelOpTarget`].
1774#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
1775pub enum KernelOpTarget {
1776    /// Kernel symbol (text/data/bss), resolved at dispatch via
1777    /// runtime kernel image base + KASLR.
1778    Symbol(String),
1779    /// Direct-mapped KVA; translated via `kva - PAGE_OFFSET`.
1780    Direct(u64),
1781    /// Vmalloc'd KVA; translated via page-table walk through CR3.
1782    Kva(u64),
1783    /// Per-CPU field of a kernel struct. Resolved at dispatch via
1784    /// `symbol_kva + __per_cpu_offset[cpu] + BTF byte offset of field`.
1785    PerCpuField {
1786        /// Symbol naming the per-CPU template (e.g. `"runqueues"`).
1787        symbol: String,
1788        /// Field within the symbol's struct (e.g. `"clock"`).
1789        field: String,
1790        /// CPU index whose per-CPU instance to address.
1791        cpu: u32,
1792    },
1793    /// Per-task field of a `struct task_struct` — SCX-managed tasks
1794    /// only. Resolved at dispatch time by walking `init_task.tasks`
1795    /// plus each leader's `signal->thread_head` to locate the
1796    /// `task_struct *` whose `pid` matches AND whose `start_time`
1797    /// matches `expected_start_time_ns` (anti-PID-reuse identity
1798    /// guard), then adding the BTF-resolved nested-path byte offset
1799    /// of `field` within `struct task_struct`.
1800    ///
1801    /// `pid` is the GUEST-side `pid_t` (positive). Both
1802    /// thread-group leaders AND non-leader threads are addressable:
1803    /// the walker iterates leaders via `for_each_process` semantics
1804    /// (`include/linux/sched/signal.h:639`), and for each leader
1805    /// also walks `leader->signal->thread_head` via
1806    /// `for_each_thread` semantics (same header L654-659).
1807    ///
1808    /// `expected_start_time_ns` is the value `task->start_time` had
1809    /// at WorkSpec spawn time. The kernel sets `start_time` once via
1810    /// `ktime_get_ns()` in `kernel/fork.c::copy_process`
1811    /// (`include/linux/sched.h:1127`); the value never changes
1812    /// after that. Caller records it at spawn time (e.g. via
1813    /// `/proc/<pid>/stat` field 22 + sysconf-to-ns conversion).
1814    /// The dispatcher rejects writes when the observed
1815    /// `task->start_time` differs — catches the PID-reuse hazard
1816    /// where the original worker exited and the kernel recycled
1817    /// the PID for an unrelated task.
1818    ///
1819    /// `field` is a dot-separated nested-member path. **SCX-only**:
1820    /// the dispatcher's class gate accepts ONLY tasks whose
1821    /// `sched_class` is `ext_sched_class`. Recommended fields:
1822    /// - `"scx.dsq_vtime"` — SCX DSQ priority-queue ordering key;
1823    ///   preserved across dequeue/enqueue cycles
1824    ///   (`kernel/sched/ext.c`).
1825    /// - `"start_boottime"` — task fork timestamp; observable in
1826    ///   `/proc/<pid>/stat` field 22.
1827    ///
1828    /// **DO NOT** write `"se.vruntime"` — EEVDF's `place_entity`
1829    /// (`kernel/sched/fair.c:5329-5414`, since 6.6) overwrites
1830    /// `se->vruntime` on every enqueue via `avg_vruntime(cfs_rq) -
1831    /// se->vlag`. Direct vruntime writes are silently discarded for
1832    /// sleeping tasks (which is our validation gate). TaskField
1833    /// rejects non-SCX tasks before reaching this field anyway.
1834    ///
1835    /// Eight-layer task validation before any write/read lands:
1836    /// 1. `task->pid == requested_pid` (anti-mismatch),
1837    /// 2. `task->start_time` within
1838    ///    `[expected_start_time_ns, expected_start_time_ns + 10ms)`
1839    ///    (anti-PID-reuse identity; the 10ms window absorbs the
1840    ///    `/proc/<pid>/stat` CLK_TCK quantization since the kernel's
1841    ///    `start_time` carries sub-tick ns precision while the
1842    ///    caller's value is rounded down to a tick boundary),
1843    /// 3. `task->__state & TASK_DEAD == 0` (lifetime),
1844    /// 4. `task->on_rq == 0` (rb-tree / DSQ ordering safety per
1845    ///    `task_on_rq_queued` at `kernel/sched/sched.h:2399`),
1846    /// 5. `task->scx.dsq == NULL` AND `task->scx.runnable_node` is
1847    ///    list-empty (SCX maintains `runnable_node` linkage
1848    ///    independent of dsq pointer per
1849    ///    `include/linux/sched/ext.h:227`),
1850    /// 6. `task->sched_class == &ext_sched_class` (the canonical
1851    ///    SCX-managed gate),
1852    /// 7. (REMOVED) a former `task->policy == SCHED_EXT` gate: SCX
1853    ///    claims fair-policy tasks via `sched_class` without changing
1854    ///    `task->policy`, so a policy check would wrongly reject
1855    ///    SCX-managed tasks that forked under `SCHED_NORMAL`. The
1856    ///    number is kept so the surviving gates retain their labels.
1857    /// 8. `task->start_boottime != 0` (anti-slab-recycle: a
1858    ///    freshly-zeroed slab page reads zero; live tasks have this
1859    ///    set to non-zero `ktime_get_boottime_ns()` at fork).
1860    TaskField {
1861        /// Guest-side PID of the target task. Both leaders and
1862        /// non-leader threads are addressable via the dispatcher's
1863        /// per-thread walker.
1864        pid: u32,
1865        /// `task->start_time` (`u64`, nanoseconds) recorded at
1866        /// WorkSpec spawn time. Used by the L2 anti-PID-reuse
1867        /// identity check.
1868        expected_start_time_ns: u64,
1869        /// Nested member path within `struct task_struct`. Dot-
1870        /// separated; first segment is a direct member of
1871        /// `task_struct`, subsequent segments descend through named
1872        /// composite members.
1873        field: String,
1874    },
1875}
1876
1877/// Wire-encoded [`crate::scenario::ops::KernelValue`] variant tag.
1878/// Mirrors the four `KernelValue` enum variants 1:1.
1879#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
1880pub enum KernelOpValue {
1881    /// 32-bit unsigned, little-endian on the wire and at the
1882    /// resolved PA. Atomic when the resolved host PA is 4-byte
1883    /// aligned (see `GuestKernel::write_*_u32` doc).
1884    U32(u32),
1885    /// 64-bit unsigned, little-endian. Atomic at 8-byte alignment.
1886    U64(u64),
1887    /// Variable-length byte payload. Written non-atomically; the
1888    /// dispatcher emits a Release fence after the copy.
1889    Bytes(Vec<u8>),
1890    /// 32-bit unsigned read-modify-write OR mask. The cold-path
1891    /// dispatcher reads the live u32 at the resolved host PA,
1892    /// ORs the carried mask into it, and writes the new value
1893    /// back as two separate `read_u32` / `write_u32` calls —
1894    /// atomic by quiesce because the freeze rendezvous parks
1895    /// every guest vCPU before the RMW runs (no concurrent
1896    /// kernel writer can interleave). No `compare_exchange` loop
1897    /// in the cold path. Mirrors
1898    /// [`crate::scenario::ops::KernelValue::OrU32`] — see that
1899    /// variant's doc for the full atomicity, ordering, and
1900    /// width-correctness contract (the canonical
1901    /// `SCX_RQ_CLK_VALID` use case + the
1902    /// `kernel/sched/sched.h:802` u32-width citation for the
1903    /// `struct scx_rq.flags` field that motivated keeping the
1904    /// variant u32 rather than u64). Hot-path support is a
1905    /// future variant — it would require `AtomicU32::from_ptr`
1906    /// + cmpxchg + strict alignment rejection.
1907    OrU32(u32),
1908}
1909
1910/// One write/read pair inside a [`KernelOpRequestPayload`] batch.
1911/// `value` is the bytes to write for a [`KernelOpDirection::Write`]
1912/// request and a placeholder ignored by the dispatcher for a
1913/// [`KernelOpDirection::Read`] request (the value-width discriminant
1914/// IS still load-bearing for reads — it picks the read method
1915/// family).
1916#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
1917pub struct KernelOpEntry {
1918    /// Address to write or read.
1919    pub target: KernelOpTarget,
1920    /// Value to write (or value-width hint for a read).
1921    pub value: KernelOpValue,
1922}
1923
1924/// Postcard-encoded payload for [`MsgType::KernelOpRequest`].
1925///
1926/// Carries an entire `Op::WriteKernel{Hot,Cold}` /
1927/// `Op::ReadKernel{Hot,Cold}` invocation including the full
1928/// `Vec<(KernelTarget, KernelValue)>` batch — variable-length, hence
1929/// the postcard encoding rather than a zerocopy fixed-size struct.
1930///
1931/// For write-direction payloads the executor's adjacent-cold-op
1932/// auto-merge pre-pass folds N adjacent `Op::WriteKernelCold`
1933/// singletons into one payload with N entries — multi-CPU seeds
1934/// (e.g. `with_uptime` writing per-CPU `rq.clock` on every CPU)
1935/// land in ONE freeze rendezvous with no inter-CPU skew. Reads
1936/// remain one-per-rendezvous until a follow-up batch adds
1937/// per-entry direction + tag.
1938#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
1939pub struct KernelOpRequestPayload {
1940    /// Monotonic request id; the host echoes it into the matching
1941    /// [`KernelOpReplyPayload::request_id`].
1942    pub request_id: u32,
1943    /// Hot vs cold orchestration.
1944    pub mode: KernelOpMode,
1945    /// Write vs read direction.
1946    pub direction: KernelOpDirection,
1947    /// Bridge-keyed tag for the response. For reads the tag becomes
1948    /// the bridge entry key; for writes the tag is informational
1949    /// only (the executor surfaces it in the success record).
1950    pub tag: String,
1951    /// Ordered batch entries. For [`KernelOpDirection::Write`] all
1952    /// entries' `value` carries the bytes to write; for
1953    /// [`KernelOpDirection::Read`] only `target` + the value-width
1954    /// discriminant are load-bearing.
1955    pub entries: Vec<KernelOpEntry>,
1956}
1957
1958/// Postcard-encoded payload for `MsgType::KernelOpReply`.
1959///
1960/// Mirrors the request id so the guest's blocking reader can pair
1961/// against the original request. Status carries success/failure; on
1962/// failure `reason` describes the host-side error. For
1963/// `KernelOpDirection::Read` requests `read_values` carries the
1964/// per-entry bytes the host coordinator read; empty for writes.
1965#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
1966pub struct KernelOpReplyPayload {
1967    /// Echo of the request's `request_id`.
1968    pub request_id: u32,
1969    /// `true` when the host completed every entry in the batch;
1970    /// `false` when any entry failed (reason describes the first
1971    /// failure).
1972    pub success: bool,
1973    /// Human-readable diagnostic on the failure path; empty on
1974    /// success.
1975    pub reason: String,
1976    /// For a `KernelOpDirection::Read` request: one
1977    /// [`KernelOpValue`] per request entry in iteration order. Empty
1978    /// for writes.
1979    pub read_values: Vec<KernelOpValue>,
1980}
1981
1982/// Upper bound on the on-wire size of a postcard-encoded
1983/// [`KernelOpReplyPayload`] frame the guest accepts on port-1 RX.
1984///
1985/// 1 MiB covers every realistic batch shape:
1986/// * `with_uptime` writing per-CPU `rq.clock` on 1024 CPUs:
1987///   ~9 KiB (well under cap).
1988/// * Bulk `read_*_bytes` of a struct page (4 KiB) per CPU on a
1989///   128-CPU host: ~520 KiB (within cap).
1990/// * Per-CPU 1 KiB `Bytes` read on 1024 CPUs: ~1 MiB (right at cap).
1991///
1992/// **Per-op entry budget**: callers that need replies larger than
1993/// 1 MiB must split the request across multiple ops; the cap
1994/// rejects forged or accidentally-huge lengths BEFORE the
1995/// `vec![0u8; length]` allocation in
1996/// [`crate::vmm::guest_comms`]'s frame reader, so a hostile or
1997/// buggy host cannot OOM the guest's PID 1 init.
1998pub const KERNEL_OP_REPLY_MAX: usize = 1024 * 1024;
1999
2000/// Upper bound on [`KernelOpRequestPayload::tag`] bytes.
2001/// `req.tag` is a `String` and downstream formatters (the reply
2002/// `reason` field, tracing emits) embed it inline. Without a
2003/// bound, a framework bug or test-author misuse producing a
2004/// multi-megabyte tag would inflate the postcard-encoded reply
2005/// past [`KERNEL_OP_REPLY_MAX`] and the reply would silently
2006/// drop at the guest's RX cap, surfacing only as a 30-second
2007/// transport timeout. Tags longer than this cap are truncated at
2008/// decode time in `src/vmm/freeze_coord/dispatch.rs`'s
2009/// `MsgType::KernelOpRequest` arm with a UTF-8 char-boundary
2010/// walk-down to avoid the `String::truncate` mid-codepoint panic.
2011/// 256 bytes fits operator-readable test-name and scenario-phase
2012/// labels with headroom; framework code that benignly produces
2013/// longer tags loses suffix bytes from the diagnostic but the op
2014/// itself continues normally.
2015pub const KERNEL_OP_TAG_MAX: usize = 256;
2016/// Upper bound on [`KernelOpReplyPayload::reason`] bytes. Pairs
2017/// with [`KERNEL_OP_TAG_MAX`] for the reply-side bound:
2018/// coordinator-generated reasons embed the request tag inline and
2019/// otherwise format diagnostic text from typed-error payloads.
2020/// 256 bytes fits diagnostic messages like
2021/// "PA validation rejected: pa=0x... reason=wrong-half" plus the
2022/// request_id and the truncated tag.
2023pub const KERNEL_OP_REASON_MAX: usize = 256;
2024
2025/// Outcome of a guest-driven kernel-memory op request: the host
2026/// returned a reply (caller inspects [`KernelOpReplyPayload::success`])
2027/// or the transport failed (port not open, timeout, malformed frame).
2028///
2029/// Distinct from a `host_error` variant the way [`SnapshotRequestResult`]
2030/// distinguishes — kernel-op replies are postcard-encoded with
2031/// arbitrary structure, so the "host completed but op failed" carrier
2032/// is the reply payload's `success: false` + `reason`. The
2033/// `TransportError` arm covers cases where the guest never receives a
2034/// usable reply at all.
2035#[derive(Debug)]
2036pub enum KernelOpRequestResult {
2037    /// Host returned a postcard-decoded reply. The caller inspects
2038    /// `reply.success` to distinguish op success from host-side op
2039    /// failure; `reply.reason` carries the failure diagnostic when
2040    /// `success == false`.
2041    Ok(KernelOpReplyPayload),
2042    /// Transport failed (called from host context, port not yet open,
2043    /// host did not reply within `timeout`, malformed reply frame).
2044    /// The supplied diagnostic names the underlying cause.
2045    TransportError { reason: String },
2046}
2047
2048// ---------------------------------------------------------------------------
2049// ControlEvent — multiport control protocol discriminants
2050// ---------------------------------------------------------------------------
2051
2052/// Multiport control-event discriminant. Mirrors the kernel uapi
2053/// `enum virtio_console_event` in `include/uapi/linux/virtio_console.h`.
2054///
2055/// The on-wire value is a u16. [`Self::wire_value`] returns the value
2056/// the kernel and the host VMM exchange on the c_ivq / c_ovq queues;
2057/// [`Self::from_wire`] reverses the mapping for a host-side parser.
2058#[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
2059pub enum ControlEvent {
2060    /// Guest-side: driver finished probing, host may begin port
2061    /// enumeration.
2062    DeviceReady,
2063    /// Host-side: announce a new port to the guest.
2064    PortAdd,
2065    /// Host-side: tear down a port.
2066    PortRemove,
2067    /// Guest-side: per-port driver finished setup.
2068    PortReady,
2069    /// Host-side: mark a port as the system console.
2070    ConsolePort,
2071    /// Host-side: terminal resize event.
2072    Resize,
2073    /// Bidirectional: open/close indication for a port.
2074    PortOpen,
2075    /// Host-side: PORT_NAME header followed by name bytes.
2076    PortName,
2077}
2078
2079impl ControlEvent {
2080    /// 16-bit on-wire discriminant. Values match the kernel uapi
2081    /// constants `VIRTIO_CONSOLE_*`.
2082    pub const fn wire_value(self) -> u16 {
2083        match self {
2084            ControlEvent::DeviceReady => 0,
2085            ControlEvent::PortAdd => 1,
2086            ControlEvent::PortRemove => 2,
2087            ControlEvent::PortReady => 3,
2088            ControlEvent::ConsolePort => 4,
2089            ControlEvent::Resize => 5,
2090            ControlEvent::PortOpen => 6,
2091            ControlEvent::PortName => 7,
2092        }
2093    }
2094
2095    /// Reverse the wire mapping. Returns `None` for unknown
2096    /// discriminants — the host parser is expected to log + skip such
2097    /// frames rather than panic.
2098    pub const fn from_wire(value: u16) -> Option<Self> {
2099        match value {
2100            0 => Some(ControlEvent::DeviceReady),
2101            1 => Some(ControlEvent::PortAdd),
2102            2 => Some(ControlEvent::PortRemove),
2103            3 => Some(ControlEvent::PortReady),
2104            4 => Some(ControlEvent::ConsolePort),
2105            5 => Some(ControlEvent::Resize),
2106            6 => Some(ControlEvent::PortOpen),
2107            7 => Some(ControlEvent::PortName),
2108            _ => None,
2109        }
2110    }
2111}
2112
2113// ---------------------------------------------------------------------------
2114// VirtioConsoleControl — wire-format control message
2115// ---------------------------------------------------------------------------
2116
2117/// Wire-format control message exchanged on c_ivq / c_ovq.
2118///
2119/// Mirrors `struct virtio_console_control` in
2120/// `include/uapi/linux/virtio_console.h`: id (u32), event (u16),
2121/// value (u16). The kernel's wire format is little-endian; on the LE
2122/// hosts ktstr targets (x86_64, aarch64), `repr(C)` produces the
2123/// correct byte order via zerocopy `IntoBytes` / `FromBytes`.
2124///
2125/// SAFETY: `repr(C)` produces an 8-byte struct with no padding when
2126/// every field is naturally aligned (u32 at offset 0, u16 at offset
2127/// 4, u16 at offset 6). The `packed` qualifier is unnecessary because
2128/// the natural alignment matches the kernel's expected wire layout
2129/// and is checked by [`std::mem::size_of`] below. Every bit pattern
2130/// is valid for u32/u16. zerocopy derives produce no panics.
2131#[repr(C)]
2132#[derive(Copy, Clone, Debug, FromBytes, IntoBytes, zerocopy::Immutable, zerocopy::KnownLayout)]
2133pub struct VirtioConsoleControl {
2134    pub id: u32,
2135    pub event: u16,
2136    pub value: u16,
2137}
2138
2139const _VIRTIO_CONSOLE_CONTROL_SIZE: () = assert!(std::mem::size_of::<VirtioConsoleControl>() == 8);
2140
2141// ---------------------------------------------------------------------------
2142// Multiport device constants
2143// ---------------------------------------------------------------------------
2144
2145/// Number of multiport ports the device exposes.
2146///
2147/// Port 0 is the kernel console (`/dev/hvc0`); port 1 is the
2148/// host-bound bulk TLV stream advertised as [`PORT1_NAME`]; port 2 is the
2149/// scheduler stats bridge advertised as [`PORT2_NAME`], carrying raw byte
2150/// passthrough between the host's [`super::sched_stats::SchedStatsClient`]
2151/// and the guest's `scx_stats` Unix-socket relay. Three ports →
2152/// eight queues per virtio-v1.2 §5.3.5 (`2 + 2 * num_ports`).
2153pub const NUM_PORTS: u32 = 3;
2154
2155/// Port-1 device-name advertised to the guest. The kernel exposes
2156/// this as `/sys/class/virtio-ports/vportNpM/name`; the guest init
2157/// reads from this path to discover the bulk channel device node.
2158pub const PORT1_NAME: &str = "ktstr-bulk";
2159
2160/// Port-2 device-name advertised to the guest. The kernel exposes
2161/// this as `/sys/class/virtio-ports/vportNpM/name`; the guest init
2162/// reads from this path to discover the scheduler-stats relay
2163/// device node and connects it to the scheduler's
2164/// `/var/run/scx/root/stats` Unix socket.
2165pub const PORT2_NAME: &str = "ktstr-stats";
2166
2167#[cfg(test)]
2168mod tests {
2169    use super::*;
2170
2171    /// `parse_scenario_end` round-trips the two LE u64s the guest
2172    /// writes, and rejects a short/torn payload (returns None rather
2173    /// than misreading) before the host builds terminal boundary telemetry.
2174    #[test]
2175    fn parse_scenario_end_round_trip_and_short_payload() {
2176        let mut payload = [0u8; SCENARIO_END_PAYLOAD_SIZE];
2177        payload[0..8].copy_from_slice(&12_345u64.to_le_bytes());
2178        payload[8..16].copy_from_slice(&987_654u64.to_le_bytes());
2179        assert_eq!(parse_scenario_end(&payload), Some((12_345, 987_654)));
2180        // A short payload (e.g. only the elapsed field) is rejected.
2181        assert_eq!(parse_scenario_end(&payload[..8]), None);
2182        assert_eq!(parse_scenario_end(&[]), None);
2183    }
2184
2185    /// `ShmMessage` round-trips through bytes — guards against an
2186    /// accidental field reorder or a stray padding byte that would
2187    /// shift the on-wire layout for both guest writer and host
2188    /// reader.
2189    #[test]
2190    fn shm_message_round_trip_through_bytes() {
2191        let f = ShmMessage {
2192            msg_type: MSG_TYPE_EXIT,
2193            length: 4,
2194            crc32: 0xDEAD_BEEF,
2195            _pad: 0,
2196        };
2197        let bytes = f.as_bytes();
2198        assert_eq!(bytes.len(), FRAME_HEADER_SIZE);
2199        let back = ShmMessage::read_from_bytes(bytes).expect("16-byte slice deserializes");
2200        let msg_type = back.msg_type;
2201        let length = back.length;
2202        let crc32 = back.crc32;
2203        let pad = back._pad;
2204        assert_eq!(msg_type, MSG_TYPE_EXIT);
2205        assert_eq!(length, 4);
2206        assert_eq!(crc32, 0xDEAD_BEEF);
2207        assert_eq!(pad, 0);
2208    }
2209
2210    /// Every msg_type constant is distinct — a copy/paste error
2211    /// that aliased two ids would silently misroute messages.
2212    #[test]
2213    fn msg_type_constants_are_unique() {
2214        let ids = [
2215            MSG_TYPE_STIMULUS,
2216            MSG_TYPE_STEP_END,
2217            MSG_TYPE_SCENARIO_START,
2218            MSG_TYPE_SCENARIO_END,
2219            MSG_TYPE_SCENARIO_PAUSE,
2220            MSG_TYPE_SCENARIO_RESUME,
2221            MSG_TYPE_EXIT,
2222            MSG_TYPE_TEST_RESULT,
2223            MSG_TYPE_SCHED_EXIT,
2224            MSG_TYPE_CRASH,
2225            MSG_TYPE_PAYLOAD_METRICS,
2226            MSG_TYPE_PROFRAW,
2227            MSG_TYPE_WPROF_TRACE,
2228            MSG_TYPE_WPROF_TRACE_CHUNK,
2229            MSG_TYPE_SNAPSHOT_REQUEST,
2230            MSG_TYPE_SNAPSHOT_REPLY,
2231            MSG_TYPE_KERNEL_OP_REQUEST,
2232            MSG_TYPE_KERNEL_OP_REPLY,
2233            MSG_TYPE_SYS_RDY,
2234            MSG_TYPE_BPF_MAP_WRITE_READY,
2235            MSG_TYPE_READINESS_WAIT,
2236            MSG_TYPE_SCHED_SWAP_NOTIFY,
2237            MSG_TYPE_ATTACH_ATTEMPT,
2238            MSG_TYPE_STDOUT,
2239            MSG_TYPE_STDERR,
2240            MSG_TYPE_SCHED_LOG,
2241            MSG_TYPE_SCHED_STDOUT,
2242            MSG_TYPE_SCHED_STDERR,
2243            MSG_TYPE_SCHED_STDOUT_FINAL,
2244            MSG_TYPE_SCHED_STDERR_FINAL,
2245            MSG_TYPE_LIFECYCLE,
2246            MSG_TYPE_EXEC_EXIT,
2247            MSG_TYPE_DMESG,
2248            MSG_TYPE_PROBE_OUTPUT,
2249        ];
2250        for (i, a) in ids.iter().enumerate() {
2251            for b in &ids[i + 1..] {
2252                assert_ne!(a, b, "duplicate MSG_TYPE id 0x{a:08x}");
2253            }
2254        }
2255    }
2256
2257    /// Pin the on-wire byte order of `msg_type` to little-endian.
2258    /// The integer literal `0x4558_4954` spells `"EXIT"` in hex digits
2259    /// (`45`='E', `58`='X', `49`='I', `54`='T'), but the LE encoding
2260    /// places the least-significant byte first — so a raw byte dump
2261    /// of a serialized `ShmMessage` shows `[0x54, 0x49, 0x58, 0x45]`,
2262    /// which spells `"TIXE"` byte-by-byte. A future change that
2263    /// flipped the host to big-endian or switched zerocopy's
2264    /// serialization order would silently break the wire contract
2265    /// with the kernel virtio_console driver and every existing
2266    /// guest writer; this test fails loudly instead.
2267    #[test]
2268    fn msg_type_exit_wire_bytes_are_le() {
2269        let f = ShmMessage {
2270            msg_type: MSG_TYPE_EXIT,
2271            length: 0,
2272            crc32: 0,
2273            _pad: 0,
2274        };
2275        let bytes = f.as_bytes();
2276        // First 4 bytes of the header are msg_type as a u32 LE.
2277        assert_eq!(&bytes[..4], &MSG_TYPE_EXIT.to_le_bytes());
2278        // Spell-out check: the LE byte sequence is "TIXE", not "EXIT".
2279        // If the wire ever flips to BE, this assertion fails before the
2280        // guest driver sees the malformed frame.
2281        assert_eq!(&bytes[..4], b"TIXE");
2282    }
2283
2284    /// `ShmMessage` header is exactly 16 bytes with no padding.
2285    #[test]
2286    fn shm_message_size_is_16() {
2287        assert_eq!(FRAME_HEADER_SIZE, 16);
2288        assert_eq!(std::mem::size_of::<ShmMessage>(), 16);
2289    }
2290
2291    #[test]
2292    fn scheduler_stream_final_chunk_header_round_trips_and_bounds_ranges() {
2293        let payload = encode_sched_stream_final_chunk(11, 5, b" world");
2294        assert_eq!(payload.len(), SCHED_STREAM_FINAL_CHUNK_HEADER_SIZE + 6);
2295        assert_eq!(
2296            decode_sched_stream_final_chunk(&payload),
2297            Some((11, 5, b" world".as_slice()))
2298        );
2299        assert_eq!(
2300            decode_sched_stream_final_chunk(&encode_sched_stream_final_chunk(0, 0, b"")),
2301            Some((0, 0, b"".as_slice())),
2302            "an empty authoritative stream needs an explicit complete frame"
2303        );
2304        assert!(
2305            decode_sched_stream_final_chunk(&payload[..15]).is_none(),
2306            "a truncated fixed-width header must be rejected"
2307        );
2308        let mut out_of_range = payload;
2309        out_of_range[..8].copy_from_slice(&10u64.to_le_bytes());
2310        assert!(
2311            decode_sched_stream_final_chunk(&out_of_range).is_none(),
2312            "offset + chunk bytes beyond total_len must be rejected"
2313        );
2314    }
2315
2316    /// Every [`MsgType`] variant round-trips through
2317    /// `wire_value` → `from_wire`.
2318    #[test]
2319    fn msg_type_round_trips() {
2320        let all = [
2321            MsgType::Stimulus,
2322            MsgType::StepEnd,
2323            MsgType::ScenarioStart,
2324            MsgType::ScenarioEnd,
2325            MsgType::ScenarioPause,
2326            MsgType::ScenarioResume,
2327            MsgType::Exit,
2328            MsgType::TestResult,
2329            MsgType::SchedExit,
2330            MsgType::Crash,
2331            MsgType::PayloadMetrics,
2332            MsgType::Profraw,
2333            MsgType::WprofTrace,
2334            MsgType::WprofTraceChunk,
2335            MsgType::TeardownBarrier,
2336            MsgType::TeardownBarrierAck,
2337            MsgType::SnapshotRequest,
2338            MsgType::SnapshotReply,
2339            MsgType::KernelOpRequest,
2340            MsgType::KernelOpReply,
2341            MsgType::SysRdy,
2342            MsgType::BpfMapWriteReady,
2343            MsgType::ReadinessWait,
2344            MsgType::SchedSwapNotify,
2345            MsgType::AttachAttempt,
2346            MsgType::Stdout,
2347            MsgType::Stderr,
2348            MsgType::SchedLog,
2349            MsgType::SchedStdout,
2350            MsgType::SchedStderr,
2351            MsgType::SchedStdoutFinal,
2352            MsgType::SchedStderrFinal,
2353            MsgType::Lifecycle,
2354            MsgType::ExecExit,
2355            MsgType::Dmesg,
2356            MsgType::ProbeOutput,
2357        ];
2358        for variant in all {
2359            let v = variant.wire_value();
2360            assert_eq!(MsgType::from_wire(v), Some(variant));
2361        }
2362    }
2363
2364    /// `MsgType::from_wire` returns `None` for an unrecognised
2365    /// discriminant — the bulk parser must surface unknown tags as
2366    /// errors rather than treat them as a known variant.
2367    #[test]
2368    fn msg_type_from_wire_unknown_returns_none() {
2369        assert_eq!(MsgType::from_wire(0xDEAD_BEEF), None);
2370        assert_eq!(MsgType::from_wire(0), None);
2371    }
2372
2373    /// `MsgType::wire_value` matches the corresponding `MSG_TYPE_*`
2374    /// constant — guards against a typo that would diverge the typed
2375    /// API from the on-wire constant.
2376    #[test]
2377    fn msg_type_wire_value_matches_constants() {
2378        assert_eq!(MsgType::Stimulus.wire_value(), MSG_TYPE_STIMULUS);
2379        assert_eq!(MsgType::StepEnd.wire_value(), MSG_TYPE_STEP_END);
2380        assert_eq!(MsgType::ScenarioStart.wire_value(), MSG_TYPE_SCENARIO_START);
2381        assert_eq!(MsgType::ScenarioPause.wire_value(), MSG_TYPE_SCENARIO_PAUSE);
2382        assert_eq!(
2383            MsgType::ScenarioResume.wire_value(),
2384            MSG_TYPE_SCENARIO_RESUME
2385        );
2386        assert_eq!(MsgType::ScenarioEnd.wire_value(), MSG_TYPE_SCENARIO_END);
2387        assert_eq!(MsgType::Exit.wire_value(), MSG_TYPE_EXIT);
2388        assert_eq!(MsgType::TestResult.wire_value(), MSG_TYPE_TEST_RESULT);
2389        assert_eq!(MsgType::SchedExit.wire_value(), MSG_TYPE_SCHED_EXIT);
2390        assert_eq!(MsgType::Crash.wire_value(), MSG_TYPE_CRASH);
2391        assert_eq!(
2392            MsgType::PayloadMetrics.wire_value(),
2393            MSG_TYPE_PAYLOAD_METRICS
2394        );
2395        assert_eq!(MsgType::Profraw.wire_value(), MSG_TYPE_PROFRAW);
2396        assert_eq!(MsgType::WprofTrace.wire_value(), MSG_TYPE_WPROF_TRACE);
2397        assert_eq!(
2398            MsgType::WprofTraceChunk.wire_value(),
2399            MSG_TYPE_WPROF_TRACE_CHUNK
2400        );
2401        assert_eq!(
2402            MsgType::TeardownBarrier.wire_value(),
2403            MSG_TYPE_TEARDOWN_BARRIER
2404        );
2405        assert_eq!(
2406            MsgType::TeardownBarrierAck.wire_value(),
2407            MSG_TYPE_TEARDOWN_BARRIER_ACK
2408        );
2409        assert_eq!(
2410            MsgType::SnapshotRequest.wire_value(),
2411            MSG_TYPE_SNAPSHOT_REQUEST
2412        );
2413        assert_eq!(MsgType::SnapshotReply.wire_value(), MSG_TYPE_SNAPSHOT_REPLY);
2414        assert_eq!(
2415            MsgType::KernelOpRequest.wire_value(),
2416            MSG_TYPE_KERNEL_OP_REQUEST
2417        );
2418        assert_eq!(
2419            MsgType::KernelOpReply.wire_value(),
2420            MSG_TYPE_KERNEL_OP_REPLY
2421        );
2422        assert_eq!(MsgType::SysRdy.wire_value(), MSG_TYPE_SYS_RDY);
2423        assert_eq!(
2424            MsgType::BpfMapWriteReady.wire_value(),
2425            MSG_TYPE_BPF_MAP_WRITE_READY
2426        );
2427        assert_eq!(MsgType::ReadinessWait.wire_value(), MSG_TYPE_READINESS_WAIT);
2428        assert_eq!(MsgType::Stdout.wire_value(), MSG_TYPE_STDOUT);
2429        assert_eq!(MsgType::Stderr.wire_value(), MSG_TYPE_STDERR);
2430        assert_eq!(MsgType::SchedLog.wire_value(), MSG_TYPE_SCHED_LOG);
2431        assert_eq!(MsgType::SchedStdout.wire_value(), MSG_TYPE_SCHED_STDOUT);
2432        assert_eq!(MsgType::SchedStderr.wire_value(), MSG_TYPE_SCHED_STDERR);
2433        assert_eq!(
2434            MsgType::SchedStdoutFinal.wire_value(),
2435            MSG_TYPE_SCHED_STDOUT_FINAL
2436        );
2437        assert_eq!(
2438            MsgType::SchedStderrFinal.wire_value(),
2439            MSG_TYPE_SCHED_STDERR_FINAL
2440        );
2441        assert_eq!(MsgType::Lifecycle.wire_value(), MSG_TYPE_LIFECYCLE);
2442        assert_eq!(MsgType::ExecExit.wire_value(), MSG_TYPE_EXEC_EXIT);
2443        assert_eq!(MsgType::Dmesg.wire_value(), MSG_TYPE_DMESG);
2444        assert_eq!(MsgType::ProbeOutput.wire_value(), MSG_TYPE_PROBE_OUTPUT);
2445        assert_eq!(
2446            MsgType::SchedSwapNotify.wire_value(),
2447            MSG_TYPE_SCHED_SWAP_NOTIFY
2448        );
2449        assert_eq!(MsgType::AttachAttempt.wire_value(), MSG_TYPE_ATTACH_ATTEMPT);
2450    }
2451
2452    /// `is_coordinator_internal` flips on for SnapshotRequest,
2453    /// SnapshotReply, KernelOpRequest, KernelOpReply, TeardownBarrier,
2454    /// TeardownBarrierAck, SysRdy, BpfMapWriteReady, ReadinessWait,
2455    /// SchedSwapNotify, and AttachAttempt and stays off for every
2456    /// test-verdict-bearing
2457    /// variant. The
2458    /// Reply variants are host→guest only on port-1 RX; a guest TX
2459    /// frame stamped with one of those tags is illegitimate and
2460    /// must be dropped rather than bucketed as a phantom verdict
2461    /// entry. Pinning this matrix here means a future contributor
2462    /// adding a new control frame must explicitly opt into the
2463    /// gate (or explicitly opt out by adding a "verdict-bearing"
2464    /// entry to the test) — the freeze coord's mid-run filter and
2465    /// `collect_results`'s post-run drain both key on this single
2466    /// classifier (search for `is_coordinator_internal` in
2467    /// `crate::vmm::freeze_coord`).
2468    #[test]
2469    fn is_coordinator_internal_matches_filter_set() {
2470        let internal = [
2471            MsgType::SnapshotRequest,
2472            MsgType::SnapshotReply,
2473            MsgType::KernelOpRequest,
2474            MsgType::KernelOpReply,
2475            MsgType::TeardownBarrier,
2476            MsgType::TeardownBarrierAck,
2477            MsgType::SysRdy,
2478            MsgType::BpfMapWriteReady,
2479            MsgType::ReadinessWait,
2480            MsgType::SchedSwapNotify,
2481            MsgType::AttachAttempt,
2482        ];
2483        let verdict = [
2484            MsgType::Stimulus,
2485            MsgType::StepEnd,
2486            MsgType::ScenarioStart,
2487            MsgType::ScenarioEnd,
2488            MsgType::ScenarioPause,
2489            MsgType::ScenarioResume,
2490            MsgType::Exit,
2491            MsgType::TestResult,
2492            MsgType::SchedExit,
2493            MsgType::Crash,
2494            MsgType::PayloadMetrics,
2495            MsgType::Profraw,
2496            MsgType::WprofTrace,
2497            MsgType::WprofTraceChunk,
2498            MsgType::Stdout,
2499            MsgType::Stderr,
2500            MsgType::SchedLog,
2501            MsgType::SchedStdout,
2502            MsgType::SchedStderr,
2503            MsgType::SchedStdoutFinal,
2504            MsgType::SchedStderrFinal,
2505            MsgType::Lifecycle,
2506            MsgType::ExecExit,
2507            MsgType::Dmesg,
2508            MsgType::ProbeOutput,
2509        ];
2510        for v in internal {
2511            assert!(
2512                v.is_coordinator_internal(),
2513                "{v:?} must be classified as coordinator-internal"
2514            );
2515        }
2516        for v in verdict {
2517            assert!(
2518                !v.is_coordinator_internal(),
2519                "{v:?} carries test verdict data and must NOT be filtered out"
2520            );
2521        }
2522    }
2523
2524    /// `MsgType::SchedSwapNotify` round-trips `wire_value` →
2525    /// `from_wire`, carries the stable `"SCSW"` (0x5343_5357)
2526    /// discriminant, and is classified coordinator-internal so the
2527    /// freeze coord's mid-run filter and `collect_results`'s post-run
2528    /// drain both drop it rather than bucketing a phantom verdict.
2529    #[test]
2530    fn sched_swap_notify_round_trips() {
2531        assert_eq!(
2532            MsgType::from_wire(MsgType::SchedSwapNotify.wire_value()),
2533            Some(MsgType::SchedSwapNotify)
2534        );
2535        assert_eq!(MsgType::SchedSwapNotify.wire_value(), 0x5343_5357);
2536        assert!(MsgType::SchedSwapNotify.is_coordinator_internal());
2537    }
2538
2539    #[test]
2540    fn readiness_wait_protocol_round_trips_and_rejects_noncanonical_payloads() {
2541        for transition in [
2542            ReadinessWaitTransition::Started,
2543            ReadinessWaitTransition::Finished,
2544        ] {
2545            let event = ReadinessWaitEvent {
2546                transition,
2547                kind: ReadinessWaitKind::ProbeDump,
2548                generation: u64::MAX,
2549            };
2550            assert_eq!(
2551                ReadinessWaitEvent::from_payload(&event.to_payload()),
2552                Some(event)
2553            );
2554        }
2555
2556        let canonical = ReadinessWaitEvent {
2557            transition: ReadinessWaitTransition::Started,
2558            kind: ReadinessWaitKind::ProbeDump,
2559            generation: 1,
2560        }
2561        .to_payload();
2562        for index in [0usize, 1, 2, 3] {
2563            let mut malformed = canonical;
2564            malformed[index] = 0xff;
2565            assert_eq!(ReadinessWaitEvent::from_payload(&malformed), None);
2566        }
2567        let mut zero_generation = canonical;
2568        zero_generation[4..12].fill(0);
2569        assert_eq!(ReadinessWaitEvent::from_payload(&zero_generation), None);
2570        assert_eq!(
2571            ReadinessWaitEvent::from_payload(&canonical[..canonical.len() - 1]),
2572            None
2573        );
2574    }
2575
2576    #[test]
2577    fn attach_attempt_protocol_round_trips_and_rejects_noncanonical_payloads() {
2578        for transition in [
2579            AttachAttemptTransition::Started,
2580            AttachAttemptTransition::Finished,
2581            AttachAttemptTransition::Settled,
2582        ] {
2583            for kind in [
2584                AttachAttemptKind::Boot,
2585                AttachAttemptKind::Attach,
2586                AttachAttemptKind::Restart,
2587                AttachAttemptKind::Replace,
2588            ] {
2589                let event = AttachAttemptEvent {
2590                    transition,
2591                    kind,
2592                    generation: u64::MAX,
2593                };
2594                assert_eq!(
2595                    AttachAttemptEvent::from_payload(&event.to_payload()),
2596                    Some(event)
2597                );
2598            }
2599        }
2600
2601        let canonical = AttachAttemptEvent {
2602            transition: AttachAttemptTransition::Started,
2603            kind: AttachAttemptKind::Boot,
2604            generation: 1,
2605        }
2606        .to_payload();
2607        for index in [0usize, 1, 2, 3] {
2608            let mut malformed = canonical;
2609            malformed[index] = 0xff;
2610            assert_eq!(AttachAttemptEvent::from_payload(&malformed), None);
2611        }
2612        let mut zero_generation = canonical;
2613        zero_generation[4..12].fill(0);
2614        assert_eq!(AttachAttemptEvent::from_payload(&zero_generation), None);
2615        assert_eq!(
2616            AttachAttemptEvent::from_payload(&canonical[..canonical.len() - 1]),
2617            None
2618        );
2619    }
2620
2621    #[test]
2622    fn attach_cancel_packet_is_generation_tagged_ascii_and_strict() {
2623        for generation in [1, 0xAFD3_BFAC_ADAE_D1D3, u64::MAX] {
2624            let packet = encode_attach_cancel(generation, AttachCancelCause::ServiceBudget);
2625            assert_eq!(packet[0], SIGNAL_ATTACH_CANCEL);
2626            assert!(packet[1..].iter().all(u8::is_ascii_hexdigit));
2627            assert_eq!(
2628                decode_attach_cancel(&packet),
2629                Some((generation, AttachCancelCause::ServiceBudget))
2630            );
2631            assert_eq!(
2632                decode_attach_control(&packet),
2633                Some(AttachControlPacket::Cancel {
2634                    generation,
2635                    cause: AttachCancelCause::ServiceBudget,
2636                })
2637            );
2638            // None of the generation bytes can alias a legacy high-byte hvc0
2639            // signal while the guest buffers a split cancellation packet.
2640            assert!(packet[1..].iter().all(|byte| *byte < 0x80));
2641        }
2642
2643        assert_eq!(
2644            decode_attach_cancel(&encode_attach_cancel(0, AttachCancelCause::ServiceBudget)),
2645            None
2646        );
2647        let mut uppercase = encode_attach_cancel(1, AttachCancelCause::ServiceBudget);
2648        uppercase[1] = b'A';
2649        assert_eq!(decode_attach_cancel(&uppercase), None);
2650        assert_eq!(
2651            decode_attach_cancel(
2652                &encode_attach_cancel(1, AttachCancelCause::ServiceBudget)
2653                    [..ATTACH_CANCEL_PACKET_SIZE - 1]
2654            ),
2655            None
2656        );
2657    }
2658
2659    #[test]
2660    fn attach_boundary_acks_are_generation_tagged_ascii_and_disjoint() {
2661        let generation = 0x1234_abcd_9876_ef01;
2662        let started = encode_attach_started_ack(generation);
2663        let finished = encode_attach_finished_ack(generation);
2664        let cancel = encode_attach_cancel(generation, AttachCancelCause::ServiceBudget);
2665        assert_eq!(started[0], SIGNAL_ATTACH_STARTED_ACK);
2666        assert_eq!(finished[0], SIGNAL_ATTACH_FINISHED_ACK);
2667        assert!(started[1..].iter().all(u8::is_ascii_hexdigit));
2668        assert!(finished[1..].iter().all(u8::is_ascii_hexdigit));
2669        assert_eq!(decode_attach_started_ack(&started), Some(generation));
2670        assert_eq!(decode_attach_finished_ack(&finished), Some(generation));
2671        assert_eq!(decode_attach_finished_ack(&started), None);
2672        assert_eq!(decode_attach_started_ack(&finished), None);
2673        assert_eq!(decode_attach_cancel(&started), None);
2674        assert_eq!(decode_attach_cancel(&finished), None);
2675        assert_eq!(decode_attach_started_ack(&cancel), None,);
2676        assert_eq!(
2677            decode_attach_started_ack(&encode_attach_started_ack(0)),
2678            None
2679        );
2680        assert_eq!(
2681            decode_attach_finished_ack(&encode_attach_finished_ack(0)),
2682            None
2683        );
2684        assert_eq!(
2685            decode_attach_control(&[crate::vmm::virtio_console::SIGNAL_VC_DUMP]),
2686            None
2687        );
2688    }
2689
2690    /// `LifecyclePhase` round-trips through `wire_value` →
2691    /// `from_wire`. Phase values are byte-stable across builds so
2692    /// the host never silently misclassifies a future guest's
2693    /// phase signal.
2694    #[test]
2695    fn lifecycle_phase_round_trips() {
2696        let all = [
2697            LifecyclePhase::InitStarted,
2698            LifecyclePhase::PayloadStarting,
2699            LifecyclePhase::SchedulerDied,
2700            LifecyclePhase::SchedulerNotAttached,
2701            LifecyclePhase::WorkloadDispatched,
2702            LifecyclePhase::SchedulerAttached,
2703        ];
2704        for p in all {
2705            let v = p.wire_value();
2706            assert_eq!(LifecyclePhase::from_wire(v), Some(p));
2707        }
2708    }
2709
2710    /// `LifecyclePhase::from_wire(0)` returns `None` — `0` is
2711    /// reserved as the unknown / invalid sentinel so a
2712    /// zero-initialised payload byte never silently maps to
2713    /// `InitStarted`.
2714    #[test]
2715    fn lifecycle_phase_zero_is_reserved() {
2716        assert_eq!(LifecyclePhase::from_wire(0), None);
2717        assert_eq!(LifecyclePhase::from_wire(0xFF), None);
2718    }
2719
2720    /// Pin the `LifecyclePhase` discriminants. Wire values are part
2721    /// of the protocol contract — a future change that reorders
2722    /// the enum variants would silently shift this mapping unless
2723    /// pinned by an explicit assertion here.
2724    #[test]
2725    fn lifecycle_phase_wire_values_are_stable() {
2726        assert_eq!(LifecyclePhase::InitStarted.wire_value(), 1);
2727        assert_eq!(LifecyclePhase::PayloadStarting.wire_value(), 2);
2728        assert_eq!(LifecyclePhase::SchedulerDied.wire_value(), 3);
2729        assert_eq!(LifecyclePhase::SchedulerNotAttached.wire_value(), 4);
2730        assert_eq!(LifecyclePhase::WorkloadDispatched.wire_value(), 5);
2731        assert_eq!(LifecyclePhase::SchedulerAttached.wire_value(), 6);
2732    }
2733
2734    /// `SnapshotRequestPayload` round-trips through bytes — guards
2735    /// against an accidental field reorder or a stray padding byte
2736    /// that would shift the on-wire layout for both guest writer
2737    /// and host parser.
2738    #[test]
2739    fn snapshot_request_payload_round_trip_through_bytes() {
2740        let mut tag = [0u8; SNAPSHOT_TAG_MAX];
2741        tag[..6].copy_from_slice(b"hello!");
2742        let p = SnapshotRequestPayload {
2743            request_id: 0xDEAD_BEEF,
2744            kind: SNAPSHOT_KIND_CAPTURE,
2745            tag,
2746        };
2747        let bytes = p.as_bytes();
2748        assert_eq!(bytes.len(), 8 + SNAPSHOT_TAG_MAX);
2749        let back = SnapshotRequestPayload::read_from_bytes(bytes).expect("payload deserializes");
2750        let request_id = back.request_id;
2751        let kind = back.kind;
2752        assert_eq!(request_id, 0xDEAD_BEEF);
2753        assert_eq!(kind, SNAPSHOT_KIND_CAPTURE);
2754        assert_eq!(&back.tag[..6], b"hello!");
2755    }
2756
2757    /// `SnapshotReplyPayload` round-trips through bytes.
2758    #[test]
2759    fn snapshot_reply_payload_round_trip_through_bytes() {
2760        let mut reason = [0u8; SNAPSHOT_REASON_MAX];
2761        reason[..4].copy_from_slice(b"oops");
2762        let p = SnapshotReplyPayload {
2763            request_id: 0xCAFE_BABE,
2764            status: SNAPSHOT_STATUS_ERR,
2765            reason,
2766        };
2767        let bytes = p.as_bytes();
2768        assert_eq!(bytes.len(), 8 + SNAPSHOT_REASON_MAX);
2769        let back = SnapshotReplyPayload::read_from_bytes(bytes).expect("payload deserializes");
2770        let request_id = back.request_id;
2771        let status = back.status;
2772        assert_eq!(request_id, 0xCAFE_BABE);
2773        assert_eq!(status, SNAPSHOT_STATUS_ERR);
2774        assert_eq!(&back.reason[..4], b"oops");
2775    }
2776
2777    /// Snapshot kind constants are distinct.
2778    #[test]
2779    fn snapshot_kind_constants_are_unique() {
2780        assert_ne!(SNAPSHOT_KIND_NONE, SNAPSHOT_KIND_CAPTURE);
2781        assert_ne!(SNAPSHOT_KIND_NONE, SNAPSHOT_KIND_WATCH);
2782        assert_ne!(SNAPSHOT_KIND_CAPTURE, SNAPSHOT_KIND_WATCH);
2783    }
2784
2785    /// Snapshot status constants are distinct.
2786    #[test]
2787    fn snapshot_status_constants_are_unique() {
2788        assert_ne!(SNAPSHOT_STATUS_OK, SNAPSHOT_STATUS_ERR);
2789    }
2790
2791    /// Every [`ControlEvent`] variant round-trips through
2792    /// `wire_value` → `from_wire`.
2793    #[test]
2794    fn control_event_round_trips() {
2795        let all = [
2796            ControlEvent::DeviceReady,
2797            ControlEvent::PortAdd,
2798            ControlEvent::PortRemove,
2799            ControlEvent::PortReady,
2800            ControlEvent::ConsolePort,
2801            ControlEvent::Resize,
2802            ControlEvent::PortOpen,
2803            ControlEvent::PortName,
2804        ];
2805        for variant in all {
2806            let v = variant.wire_value();
2807            assert_eq!(ControlEvent::from_wire(v), Some(variant));
2808        }
2809    }
2810
2811    /// `ControlEvent::from_wire` returns `None` for unknown values.
2812    #[test]
2813    fn control_event_from_wire_unknown_returns_none() {
2814        assert_eq!(ControlEvent::from_wire(8), None);
2815        assert_eq!(ControlEvent::from_wire(0xFFFF), None);
2816    }
2817
2818    /// `ControlEvent` discriminants match the kernel uapi numbers
2819    /// (`VIRTIO_CONSOLE_*` in `include/uapi/linux/virtio_console.h`).
2820    #[test]
2821    fn control_event_discriminants_match_uapi() {
2822        assert_eq!(ControlEvent::DeviceReady.wire_value(), 0);
2823        assert_eq!(ControlEvent::PortAdd.wire_value(), 1);
2824        assert_eq!(ControlEvent::PortRemove.wire_value(), 2);
2825        assert_eq!(ControlEvent::PortReady.wire_value(), 3);
2826        assert_eq!(ControlEvent::ConsolePort.wire_value(), 4);
2827        assert_eq!(ControlEvent::Resize.wire_value(), 5);
2828        assert_eq!(ControlEvent::PortOpen.wire_value(), 6);
2829        assert_eq!(ControlEvent::PortName.wire_value(), 7);
2830    }
2831
2832    /// `VirtioConsoleControl` is exactly 8 bytes — matches the
2833    /// kernel uapi struct.
2834    #[test]
2835    fn virtio_console_control_size_is_8() {
2836        assert_eq!(std::mem::size_of::<VirtioConsoleControl>(), 8);
2837    }
2838
2839    /// `VirtioConsoleControl` round-trips through bytes — pins the
2840    /// repr(C) layout against an accidental field reorder that would
2841    /// produce malformed control frames on the c_ivq / c_ovq queues.
2842    #[test]
2843    fn virtio_console_control_round_trip() {
2844        let c = VirtioConsoleControl {
2845            id: 1,
2846            event: ControlEvent::PortOpen.wire_value(),
2847            value: 1,
2848        };
2849        let bytes = c.as_bytes();
2850        assert_eq!(bytes.len(), 8);
2851        let back = VirtioConsoleControl::read_from_bytes(bytes).unwrap();
2852        let id = back.id;
2853        let event = back.event;
2854        let value = back.value;
2855        assert_eq!(id, 1);
2856        assert_eq!(event, ControlEvent::PortOpen.wire_value());
2857        assert_eq!(value, 1);
2858    }
2859
2860    /// `KernelOpRequestPayload` round-trips through postcard with
2861    /// every `KernelOpTarget` + `KernelOpValue` variant present —
2862    /// pins encode/decode against an accidental serde derive
2863    /// breakage on either side. The wire format the freeze coord
2864    /// (host) decodes is exactly what the guest's
2865    /// [`crate::vmm::guest_comms::request_kernel_op`] encodes, so a
2866    /// round-trip mismatch surfaces as a silent host-side parse
2867    /// failure rather than a typed error.
2868    #[test]
2869    fn kernel_op_request_payload_postcard_round_trip() {
2870        let payload = KernelOpRequestPayload {
2871            request_id: 0xCAFEBABE,
2872            mode: KernelOpMode::Cold,
2873            direction: KernelOpDirection::Write,
2874            tag: "with_uptime".into(),
2875            entries: vec![
2876                KernelOpEntry {
2877                    target: KernelOpTarget::Symbol("jiffies".into()),
2878                    value: KernelOpValue::U64(42),
2879                },
2880                KernelOpEntry {
2881                    target: KernelOpTarget::Direct(0xffff_8000_0000_1000),
2882                    value: KernelOpValue::U32(7),
2883                },
2884                KernelOpEntry {
2885                    target: KernelOpTarget::Kva(0xffff_c000_dead_beef),
2886                    value: KernelOpValue::Bytes(vec![1, 2, 3, 4, 5]),
2887                },
2888                KernelOpEntry {
2889                    target: KernelOpTarget::PerCpuField {
2890                        symbol: "runqueues".into(),
2891                        field: "clock".into(),
2892                        cpu: 3,
2893                    },
2894                    value: KernelOpValue::U64(0xDEAD_BEEF_CAFE_F00D),
2895                },
2896                KernelOpEntry {
2897                    target: KernelOpTarget::TaskField {
2898                        pid: 12345,
2899                        expected_start_time_ns: 1_700_000_000_000,
2900                        field: "scx.dsq_vtime".into(),
2901                    },
2902                    value: KernelOpValue::U64(30 * 86400 * 1_000_000_000),
2903                },
2904            ],
2905        };
2906        let bytes = postcard::to_allocvec(&payload).expect("encode");
2907        let back: KernelOpRequestPayload = postcard::from_bytes(&bytes).expect("decode");
2908        assert_eq!(back, payload);
2909    }
2910
2911    /// `KernelOpReplyPayload` round-trips through postcard. The
2912    /// reply carries success/failure + (for reads) the per-entry
2913    /// values the host coordinator read — both code paths must
2914    /// survive encode/decode unchanged.
2915    #[test]
2916    fn kernel_op_reply_payload_postcard_round_trip() {
2917        let success = KernelOpReplyPayload {
2918            request_id: 0x1234_5678,
2919            success: true,
2920            reason: String::new(),
2921            read_values: vec![
2922                KernelOpValue::U64(100),
2923                KernelOpValue::U32(200),
2924                KernelOpValue::Bytes(vec![0xAB, 0xCD, 0xEF]),
2925            ],
2926        };
2927        let bytes = postcard::to_allocvec(&success).expect("encode success");
2928        let back: KernelOpReplyPayload = postcard::from_bytes(&bytes).expect("decode success");
2929        assert_eq!(back, success);
2930
2931        let failure = KernelOpReplyPayload {
2932            request_id: 0xFEED_FACE,
2933            success: false,
2934            reason: "host: symbol 'jiffies' not found in vmlinux".into(),
2935            read_values: vec![],
2936        };
2937        let bytes = postcard::to_allocvec(&failure).expect("encode failure");
2938        let back: KernelOpReplyPayload = postcard::from_bytes(&bytes).expect("decode failure");
2939        assert_eq!(back, failure);
2940    }
2941
2942    /// `KERNEL_OP_REPLY_MAX` envelope check: a representative
2943    /// large reply (1024-CPU per-CPU u64) fits comfortably; the
2944    /// cap is 1 MiB which bounds OOM exposure while accommodating
2945    /// realistic batch shapes. A regression that shrunk the cap
2946    /// below ~10 KiB would silently truncate large kernel-op
2947    /// replies; one that grew it beyond 1 MiB would widen the
2948    /// OOM-attack surface.
2949    #[test]
2950    fn kernel_op_reply_max_envelope_check() {
2951        // 1024 CPUs * KernelOpValue::U64 (~9 bytes each + bookkeeping)
2952        // is well under 1 MiB. Build a representative reply and
2953        // verify its encoded size sits inside the cap.
2954        let big = KernelOpReplyPayload {
2955            request_id: 1,
2956            success: true,
2957            reason: String::new(),
2958            read_values: (0..1024u64).map(KernelOpValue::U64).collect(),
2959        };
2960        let bytes = postcard::to_allocvec(&big).expect("encode 1024-CPU reply");
2961        assert!(
2962            bytes.len() < KERNEL_OP_REPLY_MAX,
2963            "1024-CPU kernel-op reply ({} bytes) must fit under \
2964             KERNEL_OP_REPLY_MAX ({KERNEL_OP_REPLY_MAX} bytes)",
2965            bytes.len(),
2966        );
2967        // The cap is exactly 1 MiB — large enough for per-CPU 1 KiB
2968        // Bytes reads on 1024 CPUs, small enough to keep OOM
2969        // exposure bounded for a forged frame.
2970        assert_eq!(KERNEL_OP_REPLY_MAX, 1024 * 1024);
2971    }
2972
2973    // ----- KernAddrs wire-format pins -----
2974    //
2975    // Pin both the typed encode/decode contract AND the on-wire
2976    // byte layout. The byte-layout pin (last test) catches slot-
2977    // swap regressions that a roundtrip-equality test alone would
2978    // miss when encoder and decoder both flip the same way.
2979
2980    #[test]
2981    fn kern_addrs_roundtrip_all_present() {
2982        let a = KernAddrs::new(
2983            0x12345678u64,
2984            0xffff_8880_0000_0000u64,
2985            Some(0xffff_ffff_8200_0000u64),
2986        );
2987        let payload = a.to_payload();
2988        assert_eq!(payload.len(), KernAddrs::WIRE_LEN);
2989        let b = KernAddrs::from_payload(&payload).expect("decode");
2990        assert_eq!(b.phys_base, a.phys_base);
2991        assert_eq!(b.page_offset_base, a.page_offset_base);
2992        assert_eq!(b.kernel_text_runtime_kva, a.kernel_text_runtime_kva);
2993        assert!(b.has_phys_present_bit());
2994    }
2995
2996    #[test]
2997    fn kern_addrs_roundtrip_kallsyms_absent() {
2998        // The None branch on kernel_text_runtime_kva must decode
2999        // back to None (NOT Some(u64::MAX) via wrapping_sub(1) on
3000        // a raw-0 biased slot). The biased-0 sentinel is the
3001        // wire-format "guest could not derive" marker.
3002        let a = KernAddrs::new(0u64, 0u64, None);
3003        let payload = a.to_payload();
3004        let b = KernAddrs::from_payload(&payload).expect("decode");
3005        assert_eq!(
3006            b.kernel_text_runtime_kva, None,
3007            "biased-0 runtime slot must decode to None"
3008        );
3009        // phys_base = 0 IS a valid KASLR-off value; the biased
3010        // encoder writes 1 (non-zero) so has_phys_present_bit
3011        // surfaces present.
3012        assert!(b.has_phys_present_bit());
3013    }
3014
3015    #[test]
3016    fn kern_addrs_from_payload_rejects_length_mismatch() {
3017        // Exact-length match required so a protocol-extension
3018        // partial write or truncated wire surfaces as None,
3019        // never as a zero-padded silent decode.
3020        assert!(KernAddrs::from_payload(&[]).is_none());
3021        assert!(KernAddrs::from_payload(&[0u8; KernAddrs::WIRE_LEN - 1]).is_none());
3022        assert!(KernAddrs::from_payload(&[0u8; KernAddrs::WIRE_LEN + 1]).is_none());
3023    }
3024
3025    #[test]
3026    fn stimulus_from_payload_requires_exact_24_bytes() {
3027        // Exact-length match (24 bytes): an undersized buffer would
3028        // truncate and an oversized one carries bytes the guest never
3029        // frames (send_stimulus/send_step_end write exactly 24), so a
3030        // torn / hostile frame is dropped, not promoted by a prefix read.
3031        let n = std::mem::size_of::<StimulusPayload>();
3032        assert_eq!(n, 24);
3033        assert!(StimulusEvent::from_payload(&[0u8; 23]).is_none());
3034        assert!(StimulusEvent::from_payload(&[0u8; 25]).is_none());
3035        assert!(StimulusEvent::from_payload(&[0u8; 24]).is_some());
3036    }
3037
3038    #[test]
3039    fn kern_addrs_has_phys_present_bit_distinguishes_zero_vs_absent() {
3040        // Pins the bias-sentinel contract on the present-bit
3041        // accessor. A struct constructed via KernAddrs::new with
3042        // phys_base=0 surfaces as present (encoded biased = 1).
3043        // A hand-decoded all-zero payload (the "guest never
3044        // sent" wire state) surfaces as absent (raw biased 0 →
3045        // wrapping_sub(1) = u64::MAX → has_phys_present_bit
3046        // returns false).
3047        let present = KernAddrs::new(0u64, 0u64, None);
3048        assert!(present.has_phys_present_bit());
3049        let absent = KernAddrs::from_payload(&[0u8; KernAddrs::WIRE_LEN])
3050            .expect("zero-length payload decodes; shape is valid");
3051        assert!(
3052            !absent.has_phys_present_bit(),
3053            "zero-bias slot decodes to u64::MAX; has_phys_present_bit must surface absent"
3054        );
3055    }
3056
3057    #[test]
3058    fn kern_addrs_to_payload_byte_layout_is_le_phys_first() {
3059        // Pin the on-wire byte layout directly via slot offsets.
3060        // A reordering refactor that swapped slots would silently
3061        // pass the roundtrip-equality tests above (encoder and
3062        // decoder would flip together) — this test catches the
3063        // slot-swap class by asserting against fixed byte
3064        // positions.
3065        let a = KernAddrs::new(
3066            0x1111_2222_3333_4444u64,
3067            0xaaaa_bbbb_cccc_ddddu64,
3068            Some(0x5555_6666_7777_8888u64),
3069        );
3070        let p = a.to_payload();
3071        // phys_base biased: ...4444 + 1 = ...4445; LE first byte = 0x45.
3072        assert_eq!(p[0], 0x45, "phys_base slot is [0..8] LE biased");
3073        assert_eq!(
3074            u64::from_le_bytes(p[..8].try_into().unwrap()),
3075            0x1111_2222_3333_4445
3076        );
3077        assert_eq!(
3078            u64::from_le_bytes(p[8..16].try_into().unwrap()),
3079            0xaaaa_bbbb_cccc_ddddu64
3080        );
3081        // kernel_text_runtime_kva biased: ...8888 + 1 = ...8889.
3082        assert_eq!(
3083            u64::from_le_bytes(p[16..24].try_into().unwrap()),
3084            0x5555_6666_7777_8889u64
3085        );
3086    }
3087
3088    #[test]
3089    fn kern_addrs_u64_max_runtime_collapses_to_absent_roundtrip() {
3090        // Documents the bias-encoding boundary collision: a
3091        // `kernel_text_runtime_kva` of `u64::MAX` wraps to biased 0
3092        // on encode, which the decoder reads as the "guest could
3093        // not derive" sentinel (None). u64::MAX is non-canonical
3094        // and impossible as a real `_text` KVA, AND the
3095        // downstream KERN_ADDRS dispatch arm in dispatch.rs
3096        // triple-gates derived offsets (kernel-half threshold +
3097        // non-negative slide + ≤1GiB max-slide-bound + link
3098        // canonical) which catch any synthesized variant of this
3099        // collision before it reaches the shared Arc. Test pins
3100        // the symmetric collapse so a future encoder refactor
3101        // that broke the "absent sentinel = biased 0" contract
3102        // (e.g. switched to a different sentinel value) trips
3103        // here loudly.
3104        let max_runtime = KernAddrs::new(0u64, 0u64, Some(u64::MAX));
3105        let payload = max_runtime.to_payload();
3106        // Biased slot reads 0 — collides with the absent encoding.
3107        assert_eq!(
3108            u64::from_le_bytes(payload[16..24].try_into().unwrap()),
3109            0,
3110            "Some(u64::MAX) biased-add wraps to 0; collides with absent sentinel"
3111        );
3112        // Roundtrip surfaces it as None, not Some(u64::MAX).
3113        let decoded = KernAddrs::from_payload(&payload).expect("decode");
3114        assert_eq!(
3115            decoded.kernel_text_runtime_kva, None,
3116            "u64::MAX runtime decodes to None via the bias collision"
3117        );
3118    }
3119}