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}