Skip to main content

mimir_node_map/
lib.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2//! Shared node-map wire format. This crate carries no image reader or binding engine.
3pub mod merged_extent;
4
5use serde::{Deserialize, Serialize};
6pub mod source_file;
7pub use source_file::{clean_source_path, same_source_file};
8pub mod inline;
9pub use inline::*;
10pub mod contraction;
11pub mod position;
12pub mod proof;
13pub mod reach;
14mod refusal;
15pub use refusal::{BindingRefusal, BindingRefusalKind, BindingRefusals};
16
17/// How a call site was tied to instructions.
18#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
19#[serde(rename_all = "kebab-case")]
20pub enum MapHow {
21    /// Call instructions at the row's line.
22    Call,
23    /// `syscall` instructions at the row's line (the row's callee is inline assembly).
24    Syscall,
25    /// The callee was inlined: the entries of the inlined subroutines called at the row's line.
26    Inlined,
27    /// No call at the row's line, but a jump through a register there: a call through a
28    /// pointer compiled as a tail jump (a jump table is a jump through memory, not taken).
29    TailJump,
30    /// A call through a pointer that is a link-time constant (`PROOF_SITE_POINTER`).
31    PointerConstant,
32}
33
34/// One mapped call site.
35#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
36pub struct MappedSite {
37    /// Pinned producer observations; no acceptance implied.
38    #[serde(default, skip_serializing_if = "Option::is_none")]
39    pub inline_binding: Option<InlineBinding>,
40    /// The exec call site's ordinal (`exec.nodes` column `site`).
41    pub site: u32,
42    pub node: String,
43    pub how: MapHow,
44    /// The instructions (sorted): every copy of the instance holding the call.
45    pub addresses: Vec<u64>,
46    /// The copies of the instance in the image, and how many of them hold the call (a copy
47    /// may have none: the optimizer removed the call there).
48    pub copies: u32,
49    pub copies_with_call: u32,
50    /// What proves it: `PROOF_SITE`.
51    #[serde(with = "proof::wire")]
52    pub proof: String,
53    /// Enforce needs it: the call site makes a system call (its `syscalls` are not empty), so
54    /// the follower ties the kernel's reported address to it.
55    pub required: bool,
56    /// The addresses the kernel reports for this call site's system calls (a `syscall`
57    /// instruction's address + 2), sorted: for `syscall`, its own instructions; for `call`,
58    /// `pointer-constant` and `tail-jump`, every `syscall` instruction of the site table the
59    /// call reaches whose numbers include one of the node's (`PROOF_KERNEL_IPS`; through an
60    /// indirect transfer, the sections it opens: `PROOF_KERNEL_IPS_OPENS`).
61    #[serde(default)]
62    pub kernel_ips: Vec<u64>,
63    #[serde(default, skip_serializing_if = "Option::is_none")]
64    #[serde(with = "proof::optional_wire")]
65    pub ips_proof: Option<String>,
66    /// Why `kernel_ips` is not proven (a required site without it is not bound for Enforce).
67    #[serde(default, skip_serializing_if = "Option::is_none")]
68    pub ips_why: Option<String>,
69}
70
71/// The proof of the kernel addresses of a `syscall` call site.
72pub const PROOF_KERNEL_IPS_ASM: &str = "the site's own syscall instructions: address + 2";
73
74/// The proof of the kernel addresses of a `call` or `pointer-constant` call site.
75pub const PROOF_KERNEL_IPS: &str = "the call instructions' direct targets and every function the static analysis's report reaches from them by calls and tail jumps, none holding an unresolved transfer (a hole of the site table); the site table's syscall instructions in those functions whose numbers (proven, the callers' constants of an argument site, jump-table arms) include one of the node's; ip = address + 2";
76
77/// A call site whose every call is to address 0 (a weak symbol the link left undefined)
78/// reaches no syscall instruction: its kernel IP list is proven empty.
79pub const PROOF_KERNEL_IPS_NULL: &str = "every call instruction of the site is a direct call to address 0 (a weak symbol the link left undefined) and no executable segment of the image holds address 0: the call faults before any instruction runs, so no syscall instruction is reached from it; the list is empty";
80
81/// The proof of the kernel addresses of a call site whose reach passes an indirect transfer
82/// (the call itself, or a hole of the site table in a reached function).
83pub const PROOF_KERNEL_IPS_OPENS: &str = "the call instructions' direct targets and every function the static analysis's report reaches from them by calls and tail jumps; an indirect transfer there (the call itself, or a hole of the site table in a reached function) enters the functions of the sections the site table says it opens (`fallback`: every blind section, the reach of every address-taken function, the site floor's premise that an indirect transfer enters only an address-taken function), and so on until no new hole is reached; the site table's syscall instructions in all those functions whose numbers (proven, the callers' constants of an argument site, jump-table arms) include one of the node's; ip = address + 2";
84
85/// How a call through a callee-saved register gets its target (`register_constants`).
86pub const PROOF_REGISTER_CONSTANT: &str = "a call through a callee-saved register (rbx, rbp, r12-r15) whose every reaching definition in its function sets the same constant: a `mov` of an immediate, a `lea` of a RIP-relative address, or a `mov` of the 8-byte word at a RIP-relative address in a segment the image does not let be written or in the PT_GNU_RELRO range of a static ET_EXEC image (no PT_DYNAMIC: no relocation writes it); reaching definitions over the report's blocks and successors, a block entered from outside the function or with no predecessor in it (the entry, a landing pad) starting with every register unknown, and a call preserving these registers (the SysV ABI)";
87
88/// The proof of a mapped call site.
89pub const PROOF_SITE: &str = "DWARF scope with the instance's symbol as linkage name (up to v0's instantiating crate); line-table row = the call site's file and line; the instruction's kind and direct target (a call through a callee-saved register: the one constant every definition reaching it sets, PROOF_REGISTER_CONSTANT)";
90
91/// The proof of an inline-assembly call site whose system-call wrapper was inlined at its line.
92pub const PROOF_SITE_ASM_INLINED: &str = "DWARF scope with the instance's symbol as linkage name (up to v0's instantiating crate); the row is inline assembly at a call of a system-call wrapper (mimir-exec makes a wrapper whose number is its parameter a site of each caller); the syscall instructions of the copy's own code at the row's file and line, and every syscall instruction inside a subroutine DWARF says is inlined at that file and line (its call file and line)";
93
94/// The proof of an instance's only inline-assembly call site that takes the syscall
95/// instructions of the wrappers inlined into it.
96pub const PROOF_SITE_ASM_ONLY: &str = "DWARF scope with the instance's symbol as linkage name (up to v0's instantiating crate); the row is the instance's only inline-assembly call site (mimir-exec makes a system-call wrapper whose number is its parameter a site of each caller, so the wrapper has no row of its own); the syscall instructions of the copy's own code at the row's file and line, and every syscall instruction inside a subroutine DWARF says is inlined into the copy whose instance has no exec row (a wrapper; the macro that calls it gives DWARF the macro body's line), less those inside a subroutine inlined there whose instance has exec rows (that instance's own sites)";
97
98/// The proof of a process entry's address when its instance has no code of its own.
99pub const PROOF_ENTRY_MAIN: &str = "the kernel starts the main thread at the image's entry, and the main thread runs the process entry (site table thread start, role main)";
100
101/// The proof of an inlined entry's addresses.
102pub const PROOF_ENTRY_DWARF: &str = "DWARF scopes with the instance's symbol as linkage name (up to v0's instantiating crate) (its copies; no function of its own)";
103
104/// The proof of a `MapHow::PointerConstant` call site.
105pub const PROOF_SITE_POINTER: &str = "DWARF scopes with the instance's symbol as linkage name (up to v0's instantiating crate); no line ties any instruction to the call site, and it is the instance's only such call site; a target some copy first tests against zero (`mov $t,%r; test %r,%r`) and then calls is a pointer whose value the link fixed (a weak symbol), which no direct call is (a function's address is never tested against zero); in each copy, the one direct call to that target (the compiler may share the test between copies)";
106
107/// The proof of an entry's address.
108pub const PROOF_ENTRY: &str =
109    "the instance's symbol is a function of the image (the static analysis's function list)";
110
111/// Why a call site is not mapped.
112#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
113#[serde(rename_all = "kebab-case", tag = "why")]
114pub enum Unmapped {
115    /// The image has no DWARF scopes.
116    NoDwarf,
117    /// No DWARF scope has the instance's symbol as its linkage name.
118    InstanceAbsent,
119    /// The instance's copies hold no call (or `syscall`) instruction and no inlined
120    /// subroutine at the row's line.
121    NoInstruction,
122    /// Another call site of the instance has the same line and the same kind of target.
123    LineShared { with: Vec<u32> },
124    /// The row has no file and line (a start row the analysis wrote for an entry).
125    NoSource,
126    /// A row without source whose instance is these entries' instance: it is bound by them
127    /// (`entries`), not by an instruction.
128    EntryStart { entries: Vec<u32> },
129}
130
131impl Unmapped {
132    /// The kebab-case name (as in the file).
133    pub fn name(&self) -> &'static str {
134        match self {
135            Unmapped::NoDwarf => "no-dwarf",
136            Unmapped::InstanceAbsent => "instance-absent",
137            Unmapped::NoInstruction => "no-instruction",
138            Unmapped::LineShared { .. } => "line-shared",
139            Unmapped::NoSource => "no-source",
140            Unmapped::EntryStart { .. } => "entry-start",
141        }
142    }
143}
144
145/// One call site the map does not tie to instructions.
146#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
147pub struct UnmappedSite {
148    pub site: u32,
149    pub node: String,
150    #[serde(flatten)]
151    pub why: Unmapped,
152    /// Enforce needs it (as `MappedSite::required`): it is missing.
153    pub required: bool,
154}
155
156/// What the instruction at a hole is, as decoded (never inferred).
157#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
158#[serde(rename_all = "kebab-case")]
159pub enum HoleKind {
160    /// An indirect call: execution comes back at the continuation (unless the callee does
161    /// not return), into the call site mapped there.
162    Call,
163    /// An indirect jump (a tail jump, a jump table the analysis did not bound): execution
164    /// does not come back here.
165    Jump,
166    /// Not proven either way (the instruction cannot be decoded, or is neither).
167    Unproven,
168}
169
170/// One hole of the site table and where execution comes back after it.
171#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
172pub struct HoleReturn {
173    /// Candidate-specific R1 incoming-transfer coverage.
174    #[serde(default, skip_serializing_if = "Option::is_none")]
175    pub merged_guard: Option<merged_extent::ExtentGuard>,
176    /// Complete machine-entry scan supporting an outside-reach claim.
177    #[serde(default, skip_serializing_if = "Option::is_none")]
178    pub outside_guard: Option<outside::OutsideGuard>,
179    /// Report function whose call closure supplies this merged position.
180    #[serde(default, skip_serializing_if = "Option::is_none")]
181    pub merged_function: Option<u64>,
182    /// R3: a positively identified scope ancestor is not reached.
183    #[serde(
184        default,
185        skip_serializing_if = "Option::is_none",
186        with = "proof::optional_wire"
187    )]
188    pub outside: Option<String>,
189    /// Typed assumptions used by this binding; unknown names are refused.
190    #[serde(default)]
191    pub premises: Vec<proof::Premise>,
192    pub address: u64,
193    pub kind: HoleKind,
194    /// A call: the return address (the instruction after it). None for a jump.
195    #[serde(default, skip_serializing_if = "Option::is_none")]
196    pub continuation: Option<u64>,
197    /// The exec call sites mapped to the instruction (the node the call returns into).
198    #[serde(default)]
199    pub sites: Vec<u32>,
200    /// Why there is no continuation or no call site, when there is none.
201    #[serde(default, skip_serializing_if = "Option::is_none")]
202    pub reason: Option<String>,
203    /// Where the instruction is in the source (DWARF), innermost first: the instance holding
204    /// it at the line-table row, then each instance it is inlined into at its call line. The
205    /// exec graph has nodes only at system-call sites, assembly and C imports, so a call
206    /// through a pointer in Rust code is no node: it returns into the instance named here.
207    #[serde(default)]
208    pub at: Vec<Frame>,
209    /// The hole nodes of the exec graph bound to this instruction (`HoleNode::site`).
210    #[serde(default)]
211    pub hole_nodes: Vec<u32>,
212    /// A call whose one target is a C function that makes no system call (`pure_calls`): the
213    /// call and its target, as a direct call to it.
214    #[serde(default, skip_serializing_if = "Option::is_none")]
215    pub direct: Option<DirectCall>,
216    /// Why Enforce needs no binding of it (`PROOF_HOLE_PURE_CALL`).
217    #[serde(default, skip_serializing_if = "Option::is_none")]
218    #[serde(with = "proof::optional_wire")]
219    pub proof: Option<String>,
220    /// Enforce needs every hole bound: a call to its call site or to a hole node (`at` alone
221    /// names no graph position), or proven a jump; not a call to a function that makes no system
222    /// call (`pure_calls`).
223    pub required: bool,
224}
225
226/// How a hole node's call was tied to instructions.
227#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
228#[serde(rename_all = "kebab-case")]
229pub enum HoleHow {
230    /// An indirect call (`call *…`) at the node's line in every copy holding it.
231    Call,
232    /// A jump through a register (or a direct jump to one of the hole's targets) at the line in
233    /// some copy: the call compiled as a tail call.
234    TailJump,
235    /// A direct call at the line in every copy holding it, to one of the hole's targets: the
236    /// compiler made the call through a pointer direct (`direct`).
237    Devirtualized,
238    /// In every copy, no call at the line: one of the hole's targets is inlined there (the
239    /// compiler knew the pointer and inlined its function); `addresses` are those subroutines'
240    /// entries (`PROOF_HOLE_INLINED`).
241    Inlined,
242}
243
244/// A copy where the compiler made a hole's call direct: the call (or jump) instruction and
245/// its target, a function whose symbol is among the hole node's targets.
246#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
247pub struct DirectCall {
248    pub address: u64,
249    pub target: u64,
250    pub symbol: String,
251}
252
253/// One hole node pair of the exec graph: a call through a pointer (`site`, kind `hole`) and
254/// its continuation (`return_site`, kind `hole-return`).
255#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
256pub struct HoleNode {
257    /// Pinned producer observations; no acceptance implied.
258    #[serde(default, skip_serializing_if = "Option::is_none")]
259    pub inline_binding: Option<InlineBinding>,
260    /// Additional conditional positions, never substituted for own addresses.
261    #[serde(default, skip_serializing_if = "Vec::is_empty")]
262    pub merged: Vec<MergedPosition>,
263    /// Typed assumptions used by this binding; unknown names are refused.
264    #[serde(default)]
265    pub premises: Vec<proof::Premise>,
266    pub site: u32,
267    pub node: String,
268    #[serde(default, skip_serializing_if = "Option::is_none")]
269    pub return_site: Option<u32>,
270    #[serde(default, skip_serializing_if = "Option::is_none")]
271    pub return_node: Option<String>,
272    #[serde(default, skip_serializing_if = "Option::is_none")]
273    pub how: Option<HoleHow>,
274    /// The call (or tail jump) instructions, one per copy holding it, sorted.
275    #[serde(default)]
276    pub addresses: Vec<u64>,
277    /// The return addresses (the instruction after each call), sorted.
278    #[serde(default)]
279    pub continuations: Vec<u64>,
280    /// The copies whose call was made direct (`PROOF_HOLE_DIRECT`), sorted by address.
281    #[serde(default, skip_serializing_if = "Vec::is_empty")]
282    pub direct: Vec<DirectCall>,
283    pub copies: u32,
284    pub copies_with_call: u32,
285    /// The call binding: what proves it (`PROOF_HOLE`), or why it is not proven.
286    #[serde(default, skip_serializing_if = "Option::is_none")]
287    #[serde(with = "proof::optional_wire")]
288    pub proof: Option<String>,
289    #[serde(default, skip_serializing_if = "Option::is_none")]
290    pub why: Option<String>,
291    /// The continuation binding: what proves it (`PROOF_HOLE_RETURN`), or why not.
292    #[serde(default, skip_serializing_if = "Option::is_none")]
293    #[serde(with = "proof::optional_wire")]
294    pub return_proof: Option<String>,
295    #[serde(default, skip_serializing_if = "Option::is_none")]
296    pub return_why: Option<String>,
297    /// Enforce needs both (exact mode enters and leaves the hole by them).
298    pub required: bool,
299    /// Graph-path annotation; this does not establish boundary absence.
300    #[serde(default, skip_serializing_if = "Option::is_none")]
301    #[serde(with = "proof::optional_wire")]
302    pub quiet: Option<String>,
303}
304
305/// The proof of a hole node's call binding.
306pub const PROOF_HOLE: &str = "DWARF scope with the instance's symbol as linkage name (up to v0's instantiating crate); line-table row = the hole node's file and line (the MIR call through a pointer); in each copy, the one indirect call there not held by another call site, or else the one jump through a register there (a tail call)";
307
308/// The proof of a hole node's call binding where some copy's call was made direct.
309pub const PROOF_HOLE_DIRECT: &str = "DWARF scope with the instance's symbol as linkage name (up to v0's instantiating crate); line-table row = the hole node's file and line (the MIR call through a pointer); in each copy, the one indirect call there not held by another call site, or else the one jump through a register there (a tail call), or else the one direct call (or jump) there not held by another call site whose target is a function (a DWARF subprogram's linkage name, or the report's link name or alias at that address) whose symbol the exec row names among the hole's targets (exec.nodes callee: the instances the call through a pointer may reach): the compiler made the call direct, to that target";
310
311/// The proof of a hole node's call binding when its exec block is also a mapped call site.
312pub const PROOF_HOLE_SITE: &str = "the hole node and a mapped call site are one exec block (node ids `<instance>#<block>:hole` and `<instance>#<block>`): one MIR call through a pointer, which the call site's binding ties to its instructions (its proof); the hole node takes its call and jump instructions, one per copy (an address that is no call or jump is the entry of a subroutine inlined at the line: another call there)";
313
314/// The proof of a hole node's continuation binding.
315pub const PROOF_HOLE_RETURN: &str =
316    "the address after each bound call instruction: where that call returns";
317
318/// The proof of a hole node's call binding where a copy holds the call more than once.
319pub const PROOF_HOLE_DUPLICATED: &str = "DWARF scope with the instance's symbol as linkage name (up to v0's instantiating crate); line-table row = the hole node's file and line; the hole node is the instance's only exec row at that line (no other call site, hole or drop there), so every indirect call there not held by another call site is that one MIR call: a copy holding several (the compiler duplicated the call, as when it copies a loop) is bound at each, and each returns after itself";
320
321/// Why a hole node pair whose target was inlined is bound and no position of a followed thread.
322pub const PROOF_HOLE_INLINED: &str = "a checked inline-hole certificate joins each observed copy by exact instance, call file, line, column and target identity; a complete decoded instruction inventory contains no residual boundary transfer; descendant observable nodes remain in the graph";
323
324/// Why a hole the site table lists needs no binding (`pure_calls`).
325pub const PROOF_HOLE_PURE_CALL: &str = "a call through a callee-saved register whose every reaching definition sets the same constant (PROOF_REGISTER_CONSTANT), the start of a function of the static analysis's report whose name (its link name or a linker alias) is a C function that makes no system call (the pure functions of the boundary map, nornir mimir-ingest `libc_map::PURE`: Mímir's executor writes no call site for a call of one); the call is a direct call to it, which no followed thread stands at (as a direct call to it is no call site)";
326
327/// Why a hole node pair is no position of a followed thread (`quiet_holes`).
328pub const PROOF_HOLE_QUIET: &str = "every exec.edges pair out of the hole node goes to its own return node; this graph-path observation alone proves neither machine boundary absence nor a complete syscall bound";
329
330/// The proof of a hole node's continuation where some copy is a tail jump (`tail_returns`).
331pub const PROOF_HOLE_RETURN_TAIL: &str = "the address after each bound call instruction; for a copy compiled as a tail jump, the jump replaced its function's frame, so the code it enters returns where that function returns: the address after each direct call to the function (every function of the static analysis's report decoded; each function the report says calls it, a tail call included, holds a decoded call or jump to it), and a function that enters it by a tail jump or a fall-through (a jump to its start, or the report's successor into its start, from another function, or the report's call into its start from the function that ends there) returns to its own callers in turn; an address-taken function on the way (the report's) returns after each hole of the site table that may enter it too (a hole that opens a blind section the function is an entry of, by name or as a `fallback` hole: the site floor's premise that an indirect transfer enters only an address-taken function), or where the function holding it returns when that hole is a jump, and, as a signal handler the kernel may enter, at the start of each function that issues rt_sigreturn (the sa_restorer; no system call whose number is not known); no function on the way is the process entry (a thread start is no kernel entry: the clone child resumes after its syscall)";
332
333/// The proof of a pair into or out of a hole node.
334pub const PROOF_HOLE_EDGE: &str = "an exec.edges pair of the order pass with hole nodes (mimir-exec --holes: Next over the MIR CFG), both of whose ends are bound to instructions (or a start by its entries)";
335
336/// One `exec.edges` pair into or out of a hole node.
337#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
338pub struct HoleEdge {
339    pub from: u32,
340    pub to: u32,
341    pub from_node: String,
342    pub to_node: String,
343    /// The exec entries the pair is in.
344    pub entries: Vec<u32>,
345    /// Enforce needs it: both ends are positions a followed thread stands at (a hole end, a
346    /// call site that makes a system call, a start).
347    pub required: bool,
348    #[serde(default, skip_serializing_if = "Option::is_none")]
349    #[serde(with = "proof::optional_wire")]
350    pub proof: Option<String>,
351    #[serde(default, skip_serializing_if = "Option::is_none")]
352    pub why: Option<String>,
353}
354
355/// One place in the source: an instance (its symbol), a file and a line.
356#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
357pub struct Frame {
358    #[serde(default, skip_serializing_if = "Option::is_none")]
359    pub symbol: Option<String>,
360    pub file: String,
361    pub line: u32,
362}
363
364/// One exec entry and its function.
365#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
366pub struct EntryFunction {
367    pub entry: u32,
368    /// The entry's kind (`exec.marks` column `what`: process, root, thread, init, signal).
369    pub kind: String,
370    pub instance: String,
371    pub symbol: String,
372    #[serde(default, skip_serializing_if = "Option::is_none")]
373    pub address: Option<u64>,
374    /// Without a function of its own (inlined): the entries of its DWARF copies. A process
375    /// entry with no code of its own: the main thread's start (`PROOF_ENTRY_MAIN`).
376    #[serde(default, skip_serializing_if = "Vec::is_empty")]
377    pub addresses: Vec<u64>,
378    /// The functions holding those copies (each copy's outermost DWARF subprogram): the
379    /// targets a call into the entry reaches.
380    #[serde(default, skip_serializing_if = "Vec::is_empty")]
381    pub functions: Vec<u64>,
382    /// With an address: what proves it (`PROOF_ENTRY`, or `PROOF_ENTRY_DWARF`).
383    #[serde(default, skip_serializing_if = "Option::is_none")]
384    #[serde(with = "proof::optional_wire")]
385    pub how: Option<String>,
386    /// Without one: why.
387    #[serde(default, skip_serializing_if = "Option::is_none")]
388    pub reason: Option<String>,
389    /// Enforce needs it: a place a thread starts running (kinds process, thread, init,
390    /// signal; a `root` is a scope of the analysis, not a start).
391    pub required: bool,
392}
393
394/// The entry kinds Enforce needs an address for.
395pub const REQUIRED_ENTRY_KINDS: [&str; 4] = ["process", "thread", "init", "signal"];
396
397/// A thread start of the site table and the exec entries a thread started there may run.
398#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
399pub struct ThreadEntries {
400    /// Unique exec syscall site whose child is this role.
401    #[serde(default, skip_serializing_if = "Option::is_none")]
402    pub spawn_site: Option<u32>,
403    pub start: u64,
404    #[serde(default, skip_serializing_if = "Option::is_none")]
405    pub function: Option<String>,
406    pub entries: Vec<u32>,
407    /// `function` (proven exact): the start is the function of an entry of its kind (the main
408    /// start: process entries; any other start: thread entries).
409    /// `every-process-entry` / `every-thread-entry` (proven superset): no such entry's function
410    /// is the start, the body is reached from it through a pointer, so a thread started there
411    /// may run any entry of that kind.
412    pub how: String,
413}
414
415/// One edge of the binary CFG of a function no DWARF scope covers.
416#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
417pub struct BinEdge {
418    pub function: u64,
419    pub from: u64,
420    pub to: u64,
421    /// `flow` (a block's successor) or `call`.
422    pub kind: String,
423}
424
425/// The instance has no DWARF copy; its unique symbol-table function extent
426/// in the pinned report contains the sole assembly row's syscall instructions.
427pub const PROOF_SITE_REPORT: &str = "one report symbol-table function extent, no DWARF copy, one assembly row: every syscall instruction in that extent";
428
429/// The instance has no DWARF copy; its unique report function extent holds
430/// one indirect call whose proven targets are all named by the exec hole.
431pub const PROOF_HOLE_REPORT: &str = "one report symbol-table function extent, no DWARF copy, one hole and one indirect call: every proven target is an exec candidate";
432
433/// A node outside every entry's directed closure of its first nodes.
434pub const PROOF_HOLE_UNREACHED: &str = "the node is outside every entry's closure of first nodes over exec.edges; it is no graph position";
435
436/// Conditional on scope-ancestor and exec-reach; absence of a scope is no evidence.
437pub const PROOF_HOLE_OUTSIDE_REACH: &str = "a positive scope names a body whose aliases uniquely match unreached instances in pinned exec.reached; a complete machine-entry scan excludes direct incoming calls and jumps from outside the jointly excluded bodies and excludes runtime starts; subject to the data-held merged-alias limit, scope-ancestor and exec-reach make this instruction no graph position";
438
439/// One merged instruction shared by every reachable candidate in a call closure.
440#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
441pub struct MergedPosition {
442    pub address: u64,
443    pub jump: bool,
444    pub continuation: Option<u64>,
445}
446/// The call closure, rather than a possibly incomplete DWARF scope list, bounds candidates.
447pub const PROOF_HOLE_MERGED: &str = "a line-zero indirect transfer in a report function with positive fitting pointer-call scope evidence; every reachable hole of the complete exec.reached.calls closure of its own instances is a candidate, under code-origin, pointer-call and exec-reach";
448
449pub mod outside;