Glossary¶

Plain-language definitions of the terms and acronyms used throughout these docs. If a word in the documentation looks unfamiliar, it is probably explained here.

This file is also the single source for the desktop GUI’s in-app term registry (docs/internal/archive/gui/24-one-visual-language.md T3): scripts/gen-terms.py parses the {glossary} directive below into the app’s hoverable tooltips and its searchable Terms pane, so the app’s words and the docs’ words cannot drift. When you add or reword a coined GUI term here, the app follows on the next build.

AAPCS64¶: Procedure Call Standard for the ARM 64-bit Architecture. The ABI (the rulebook for how functions call each other) on AArch64. It is the ARM equivalent of the System V AMD64 ABI.
AArch64¶: The 64-bit version of the ARM processor architecture, used by Apple Silicon Macs, modern phones, and many servers. Also written arm64. asm-test runs on AArch64 as well as x86-64.
ABI¶: Application Binary Interface. The set of low-level rules that lets compiled code from different sources work together: which CPU registers carry function arguments and return values, which registers a function must leave untouched, how the stack is laid out, and so on. asm-test calls your assembly through the real ABI, exactly as a C compiler would.
ABI preservation¶: The requirement that a function restore certain registers (callee-saved registers) to their original values before it returns. asm-test can assert that a routine preserved them, catching a common class of assembly bug.
AMD64¶: Another name for x86-64, the 64-bit Intel/AMD processor architecture found in most desktops, laptops, and servers.
arity¶: The number of arguments a function takes. “Arbitrary arity” means asm-test can call routines with any number of arguments.
ARM¶: A family of processor architectures common in phones, tablets, and newer Macs and servers. See AArch64 (64-bit) and ARM32 (32-bit).
ARM32¶: The older 32-bit ARM architecture (also called A32). Supported by the emulator tier.
ASLR¶: Address Space Layout Randomization. An operating-system defence that loads code at a different address every run. asm-test reports trace offsets relative to a routine’s base precisely so they stay stable despite ASLR.
assembler¶: A program that translates human-readable assembly language into the raw machine-code bytes a CPU executes. asm-test supports two: GAS and NASM.
assembly language¶: The lowest-level human-readable programming language, where each instruction maps almost directly to a single operation the CPU performs. This is the code asm-test is built to test.
AUX¶: The auxiliary buffer of a Linux perf_event — a second ring the kernel maps beside the main data ring for high-bandwidth streams. Hardware trace bytes (Intel PT, CoreSight) land in the AUX ring; the aux_size option on the hardware-trace API (and each binding’s Options) sizes it.
AVX2¶: Advanced Vector Extensions 2. The 256-bit SIMD instruction set on x86-64, widening the 128-bit XMM registers to 256-bit ymm0–ymm15. asm-test captures 256-bit vector returns via ASM_VCALL256n and self-skips on hosts without AVX2.
basic block¶: A straight-line run of instructions with one entry and one exit: control enters at the top and runs to the end without branching in or out. A new block begins at a routine’s entry and after every branch. asm-test’s traces report which basic blocks a run reached; every trace backend normalizes to this same single-entry/ends-at-branch partition. See branch coverage.
BCL¶: Base Class Library. The standard library shipped with .NET (System.Private.CoreLib, System.Console, …). Most of it is precompiled ReadyToRun code the JIT never compiles, so naming executed BCL methods in a trace needs the jitdump rundown (withRundown), not just the in-scope JIT listener.
benchmark mode¶: A mode in which asm-test repeatedly runs a routine and reports how many CPU cycles each call takes, so you can compare implementations for speed.
binding¶: A small adapter that lets a programming language other than C drive asm-test — for example the Python, .NET, Go, Rust, or Java bindings. See also FFI.
born-untraced¶: A value the desktop GUI’s Loom shows entering a computation from outside the traced window — its origin was never recorded, so no lineage can be drawn back to it. Expert synonym: an unrecorded upstream definition. Drawn with a caution glyph, never as if its provenance were known.
branch coverage¶: A measure of how many of the possible decision paths (branches) through a routine were actually exercised by your tests. The emulator tier can report this.
BTF¶: Two unrelated meanings in these docs. (1) Branch Trap Flag — the x86 DebugCtl bit that turns single-step into block-step: one debug exception per taken branch rather than per instruction (the planned PTRACE_SINGLEBLOCK upgrade for the ptrace stepper). (2) BPF Type Format — the kernel’s type metadata for eBPF; the code-image emission detector self-skips where the kernel lacks it (“kernel BTF unavailable”).
call descent¶: An opt-in mode of the out-of-process single-step tracer that follows the calls a traced region makes instead of only stepping over them. Four levels (see descent level): record nothing, record call edges, descend into known callees, or descend into everything. Each descended callee becomes a nested frame.
call edge¶: A recorded (call-site → callee) pair for a call the tracer did not follow (stepped over). At descent level 1+ the edge list is the complete record of un-descended calls, even when depth/budget/allow-set gating declines a descent.
callee-saved register¶: A CPU register that a called function must preserve: if it uses the register, it has to restore the original value before returning. On x86-64 these are rbx, rbp, and r12–r15. Contrast caller-saved register.
caller-saved register¶: A CPU register that a function is free to overwrite. If the caller needs the value afterward, the caller is responsible for saving it first. Contrast callee-saved register.
calling convention¶: The specific rules — part of an ABI — for how one function calls another: where arguments go, where the return value comes back, and who is responsible for which registers.
Capstone¶: A disassembler library asm-test optionally uses to turn machine-code bytes back into readable instruction text — annotating faults, traces, and coverage reports. The single-step and hardware trace backends also use it as an instruction length-decoder. See Disassembly. (Its emulator/assembler siblings are Unicorn and Keystone.)
capture trampoline¶: A small piece of asm-test’s own machinery that calls your routine on the real CPU, then records the CPU registers, flags, and return value immediately afterward so the test can inspect them. This is the “native tier.”
CF¶: Carry Flag. A CPU status flag set when an arithmetic operation produces a carry or borrow out of the most significant bit — for example, when an unsigned addition overflows.
CI¶: Continuous Integration. Automated systems (such as GitHub Actions) that build the project and run its tests on every change. See the CI guide.
CO-RE¶: Compile Once, Run Everywhere — the BPF/eBPF technique that lets one compiled BPF object run across kernels with different internal struct layouts, by relocating field offsets from BTF type information at load time. asm-test’s eBPF programs (the JIT-emission detector and the AMD branch snapshot) are built CO-RE so a single skeleton works on any recent kernel.
conformance corpus¶: A shared set of canonical routines and their expected captures that every language binding must reproduce, keeping all ten bindings faithful and in lock-step.
CoreCLR¶: The runtime engine of .NET — a managed runtime with a JIT compiler. One of the three runtimes asm-test’s foreign-JIT tracer is validated against (with V8 and HotSpot).
CoreSight¶: ARM’s on-chip execution-trace hardware (ETM/ETE trace units that emit branch “waypoints”). One of the hardware trace backends, decoded by OpenCSD. It needs a specific AArch64 board, so asm-test ships it as a self-skipping scaffold.
CPSR¶: Current Program Status Register. The register holding the condition flags on 32-bit ARM32. The AArch64 counterpart is PSTATE; the x86-64 one is RFLAGS.
CPU¶: Central Processing Unit. The processor that executes machine-code instructions. asm-test can run routines on the real CPU (native tier) or a simulated one (the emulator).
CPU register¶: A tiny, extremely fast storage slot inside the CPU that holds a value being worked on. Functions pass arguments and return values through registers, and asm-test can read them after a call.
CTI¶: Control-Transfer Instruction — any instruction that changes the program counter non-sequentially: a jump, a conditional branch, a call, or a return. asm-test’s trace backends end a basic block after every CTI, which is the boundary the LBR, Intel PT, DynamoRIO, and Unicorn partitions all agree on.
cycles per call¶: A speed measurement: the number of CPU clock cycles consumed by a single call to a routine. Reported by benchmark mode.
DBI¶: Dynamic Binary Instrumentation. Rewriting a program’s machine code as it runs in order to observe or modify it, without touching the source. DynamoRIO is the DBI engine asm-test’s native-trace tier uses.
descent level¶: How far call descent follows a traced region’s calls: OFF (step over, record nothing), RECORD_EDGES (record call edges), DESCEND_KNOWN (step into resolvable callees), DESCEND_ALL (step into everything — default off, guarded). Higher levels add nested frames without changing frame 0.
differential testing¶: Testing a routine by running it on many inputs and checking that its output always matches a separate, trusted reference model. Discrepancies reveal bugs. Often combined with property testing and fuzzing.
dim take¶: In the desktop Loom, a value that is present at a step but was not used by it — drawn as a hollow outline (never a filled rectangle, which is reserved for a value in use). Expert synonym: a live-but-unread definition. Contrast hot take.
DWARF¶: A standard debugging-information format embedded in compiled programs, describing how source code maps to machine code. Relevant to stack unwinding and ABI details.
DynamoRIO¶: An open-source DBI engine (often shortened to DR in these docs). asm-test’s DynamoRIO tier attaches it in-process to trace native code as it runs on the real CPU at native speed. It is a native tier-trace back-end, distinct from the emulator. See Native runtime tracing.
eBPF¶: extended Berkeley Packet Filter. A mechanism for running small, kernel-verified programs inside the Linux kernel. asm-test uses an optional eBPF probe to detect the instant a JIT marks freshly generated code executable. Also written BPF.
EFLAGS¶: The 32-bit x86-64 status register — the low half of RFLAGS. Its TF (trap flag) bit, when set, makes the CPU trap after every instruction; that trap (delivered as SIGTRAP) is the mechanism behind the in-process single-step tracer.
eightbyte¶: A single 8-byte slot the System V AMD64 ABI reasons in when deciding how to pass a small struct-by-value: each eightbyte of the struct is classified and placed in a register or spilled to the stack.
ELF¶: Executable and Linkable Format. The standard file format for programs, object files, and libraries on Linux. Compare PE, used on Windows.
emulator¶: A software-simulated CPU (asm-test uses one called Unicorn) that runs your assembly inside a controlled virtual machine. This optional “emulator tier” can read the full register file, pinpoint faults precisely, measure branch coverage, and run architectures your real machine isn’t. See the emulator guide.
fabric¶: The woven 2-D field the desktop Loom draws: lanes running left-to-right as time, worldlines threading through them. Expert synonym: the def-use lineage graph laid out over the step axis. It is the surface; the Loom is the tool that weaves it.
fault¶: A hardware-detected error during execution, such as accessing forbidden memory. On the real CPU these arrive as signals like SIGSEGV; the emulator reports them precisely.
FFI¶: Foreign Function Interface. The mechanism by which one programming language calls functions written in (or compiled to) another. asm-test’s bindings use FFI to reach the C library from Python, Go, and so on.
FFM¶: Foreign Function & Memory API. Java’s modern, built-in FFI mechanism, used by the Java binding.
flag¶
flags¶: Individual status bits the CPU sets as a side effect of operations — recording, for example, whether a result was zero, negative, or overflowed. Collectively stored in the RFLAGS register on x86-64. asm-test can assert on them. See CF, ZF, OF, SF, PF.
floating-point¶: A way of representing numbers with fractional parts (like 3.14) inside a computer. Often abbreviated FP. Comparing floating-point results needs care — see ULP.
fork¶: A POSIX system call that creates a child copy of the running process. asm-test runs each test in its own forked child so a crash or hang in one test can’t take down the rest of the suite.
frame 0¶: The root registered region in a call descent trace — a superset mirror of the flat single-region trace, byte-identical across all descent levels. Descended callees are frames 1..N (nested frames).
fuzzing¶: Feeding a routine many randomly generated inputs to flush out bugs. asm-test’s fuzzing uses a reproducible seed so a failing run can be replayed exactly.
GAS¶: GNU Assembler. One of the two assemblers asm-test supports. It uses AT&T syntax and is the assembler the standard C toolchain (cc) invokes. Compare NASM.
GC¶: Garbage collection. Automatic reclamation of unused memory inside a managed runtime. Its concurrent background threads are one reason tracing a live JVM/.NET/Node process in-process is hazardous — see managed runtime.
general-purpose register¶: A CPU register used for ordinary integer and pointer values (as opposed to a specialized floating-point or SIMD register). Abbreviated GP.
guard page¶: A page of memory deliberately left unmapped next to a buffer, so that a one-past-the-end access lands on it and faults at once (a SIGSEGV) instead of silently corrupting neighbouring data. asmtest_guarded_alloc hands out guard-page-protected buffers.
hardware trace¶: asm-test’s tier that records execution using the CPU’s own trace hardware — Intel PT, AMD LBR, or ARM CoreSight — read through the PMU with near-zero capture overhead. It needs bare metal and perf privilege; the portable single-step backend is the universal fallback. See Hardware tracing.
hexdump¶: A side-by-side display of raw bytes in hexadecimal. asm-test prints one when a memory comparison fails, highlighting exactly which bytes differ.
hollow span¶: A span the desktop Loom draws as an outline only: the route a value took is known but its value is not (it was never captured). Expert synonym: an edge with a known path but no recorded datum. A filled span would look exactly like one carrying a measurement, so the hollow outline keeps them faithfully distinct.
hot take¶: In the desktop Loom, a value a step actually used — drawn as a solid filled rectangle. Expert synonym: a read (consumed) definition. Contrast dim take.
hot-edges¶: A desktop Observer view showing which control-flow edges were taken most often, as a src×dst count heatmap. Expert synonym: edge execution counts — it is a count, not a call stack and not an ordered path. Statistical when its source is a sampled backend.
HotSpot¶: The JIT compiler in OpenJDK (the standard Java runtime). Its optimizing compiler is called C2, and a compiled method as it lives in the code cache is an nmethod. One of the managed runtimes asm-test’s foreign-JIT tracer is validated against.
IBS¶: Instruction-Based Sampling — an AMD PMU facility that tags one micro-op per sampling period and reports rich per-op detail (including, for a retired taken branch, a precise source→target edge). It is statistical, not an ordered complete path, so asm-test treats it as coverage confirmation rather than a trace — and it is the only branch source on Zen 2, which has no LBR.
in-line assembly¶: Assembly code supplied directly as a string and assembled on the fly (via the Keystone library) rather than from a separate .s file.
Intel PT¶: Intel Processor Trace. A hardware feature of Intel x86-64 CPUs that emits a compact branch-trace packet stream at near-zero overhead; the libipt decoder replays the code bytes afterward to reconstruct the instructions executed. The most faithful hardware trace backend, but bare-metal Intel only.
IPC¶: Inter-process communication. In these docs, nearly always the .NET diagnostics IPC: the Unix-domain socket every CoreCLR process exposes. asm-test’s .NET binding speaks the DOTNET_IPC_V1 protocol over it to request the jitdump rundown — no NuGet package, no launch knob.
ISA¶: Instruction Set Architecture. The instructions and registers a processor family understands — x86-64, AArch64, RISC-V, ARM32. “Cross-ISA” means running one ISA’s code on a host of another, which the emulator can do.
jack¶: A connection point in the desktop patch-bay metaphor for tracer contention: a place where a tracer can be “plugged in” to a target. Expert synonym: a trace attachment point / capture slot.
JIT¶: Just-In-Time compilation. Compiling code to machine instructions while the program runs — as the JVM, .NET, and JavaScript engines do — rather than ahead of time. asm-test can trace JIT-generated code; see jitdump, perf-map, and managed runtime.
jitdump¶: A binary file (jit-<pid>.dump) a JIT writes describing each method it compiles — address, size, name, and the actual code bytes — with every record timestamped. asm-test reads it to recover the exact bytes that were live even when an address is reused by re-compilation. Richer than a perf-map, which carries no bytes.
JUnit XML¶: A widely understood XML file format for test results, originally from the JUnit framework. asm-test can emit it so CI dashboards can display the results.
JVM¶: Java Virtual Machine. The managed runtime that executes Java bytecode; HotSpot is the implementation OpenJDK ships. The peer of CoreCLR (.NET) and V8 (Node.js) in the managed-tier docs.
Keystone¶: An assembler library (the counterpart to the Unicorn emulator) that asm-test uses to turn in-line assembly strings into machine code.
knot¶: In the desktop Loom, the point where two worldlines meet — one value derived from another. Expert synonym: a def-use join in the lineage graph.
lane¶: One element of a SIMD vector. A single SIMD register holds several values side by side; each slot is a lane, and asm-test can assert on them individually.
LBR¶: Last Branch Record. An AMD branch-recording facility (Zen 3 BRS, Zen 4–5 LbrExtV2) that keeps a short hardware stack of the most recent branches. asm-test’s AMD LBR hardware trace backend samples it and stitches successive windows (Tier-B stitching) to reconstruct a run past the 16-deep hardware limit.
lcov¶: A common line-coverage report format (from the LCOV tool). asm-test can export a trace as an lcov record — with basic block offsets standing in for line numbers — so standard coverage viewers can display it.
libipt¶: Intel’s BSD-licensed decoder library for Intel PT packet streams. It is linked only when present; without it the PT backend self-skips.
Loom¶: The desktop GUI’s data-flow lineage tool: it weaves a recording’s def-use edges into a fabric of worldlines so you can read where a value came from and what it fed. Expert synonym: data-flow lineage (def-use) — it shows lineage, not control flow.
LR¶: Link Register. On ARM/AArch64, the register that holds the return address — where execution should resume after a function finishes.
managed runtime¶: A language runtime that compiles and manages code for you at run time — the JVM, .NET/CoreCLR, and Node/V8. Their concurrent JIT and GC threads make in-process tracing hazardous, so asm-test traces them out-of-process via ptrace or with a hardware trace backend that observes out of band.
MSR¶: Model-Specific Register. A privileged per-core configuration register the kernel programs (rdmsr/wrmsr) — how AMD’s LBR and the DebugCtl BTF bit are switched on. asm-test never touches MSRs itself; perf_event programs them on its behalf.
mutation testing¶: Deliberately introducing small faults (“mutants”) into a routine and checking that the tests catch them — a way to measure how thorough the tests really are. asm-test runs it contained inside the emulator.
NASM¶: Netwide Assembler. One of the two assemblers asm-test supports. It uses Intel syntax (.asm files). Compare GAS.
native tier¶: Running a routine directly on the real CPU through the capture trampoline, as opposed to inside the emulator. The default execution mode. Not to be confused with the native runtime-trace tiers (DynamoRIO, hardware trace, single-step), which also run on the real CPU but exist to trace which code executed rather than to capture the post-ret register state.
NEON¶: The SIMD instruction set on ARM/AArch64 processors — the ARM equivalent of the XMM-based vector instructions on x86-64.
nested frame¶: A self-contained trace of a callee the tracer descended into during call descent: its own instruction and block offsets, relative to that callee’s base, with a depth and a parent-frame index. Distinct from frame 0, the root.
nmethod¶: A single method compiled by HotSpot, as it lives in the JVM’s code cache (its own entry barrier and safepoint poll wrapped around the body). What asm-test recovers when it traces a JITed Java method.
NMI¶: Non-Maskable Interrupt. An interrupt the CPU cannot defer with the normal interrupt-disable flag. AMD’s IBS and the PMI counter-overflow path deliver through NMIs, which is how they can sample code that is running with ordinary interrupts masked.
NZCV¶: The four main condition flags on AArch64: Negative, Zero, Carry, and oVerflow. The ARM counterpart to the x86 flags in RFLAGS.
OF¶: Overflow Flag. A CPU status flag set when a signed arithmetic operation produces a result too large to fit. Compare CF, which covers unsigned overflow.
OpenCSD¶: The BSD-licensed decoder library for ARM CoreSight trace streams — the CoreSight counterpart to libipt.
P/Invoke¶: Platform Invoke. .NET’s built-in FFI mechanism, used by the .NET binding to reach asm-test’s C library.
PAL¶: Platform Adaptation Layer. CoreCLR’s internal portability layer, which owns process-wide resources on Linux — including the SIGTRAP disposition that the in-process single-step tracer also needs, the root of the managed single-step trade-off (see TF).
patch-bay¶: The desktop metaphor for tracer contention and capture budget: like an audio patch-bay, only so many tracers can be plugged into so many targets at once. Expert synonym: tracer contention / capture-budget arbitration.
patient-zero¶: The desktop GUI’s name for the first divergence between two recordings — the earliest step at which they stop agreeing, the origin of everything downstream that differs. Expert synonym: first divergent step / root difference.
PE¶: Portable Executable. The program and library file format used on Windows. Compare ELF on Linux. Relevant to the Win64 ABI tier.
perf-map¶: A plain-text file (/tmp/perf-<pid>.map) a JIT writes with one start size name line per generated method, so profilers can name JITed code. asm-test parses it to locate a method’s bytes. Simpler than jitdump (it carries no code bytes) but widely emitted.
perf_event¶: The Linux kernel interface (perf_event_open) for programming the PMU and collecting trace data. The Intel PT, LBR, and CoreSight backends use it — which is why they need a lowered perf_event_paranoid or CAP_PERFMON the process cannot grant itself.
PF¶: Parity Flag. A CPU status flag set according to whether the low byte of a result has an even number of 1 bits.
PLT¶: Procedure Linkage Table. The stub table through which a program calls into shared libraries. A traced routine’s calls into PLT stubs are among the call-outs the single-step tracer steps over by default.
PMI¶: Performance Monitoring Interrupt. The interrupt a PMU counter raises on overflow. The AMD LBR backend arms a counter to fire on every taken branch (“freeze-on-PMI”), snapshotting the 16-entry branch stack at each interrupt — the samples Tier-B stitching joins into a continuous trace.
PMU¶: Performance Monitoring Unit. The dedicated counters and trace hardware built into a CPU. The hardware trace backends read it through perf_event.
POSIX¶: Portable Operating System Interface. A family of standards defining a common Unix-like programming interface, shared by Linux and macOS. asm-test relies on POSIX features such as fork and signals.
program counter¶: The CPU register holding the address of the instruction being executed — rip on x86-64, pc on AArch64. Also called the PC or instruction pointer. asm-test’s single-step tracers read it at each step to record the offset that executed.
property testing¶: Testing that a routine upholds a stated property (for example, “sorting twice gives the same result as sorting once”) across many generated inputs, rather than checking hand-written examples one at a time. See Property testing.
PSTATE¶: The processor-state register holding the condition flags (NZCV) on AArch64 — the ARM counterpart to RFLAGS on x86-64 and CPSR on ARM32.
ptrace¶: The POSIX/Linux system call by which one process (the tracer) controls and inspects another (the tracee) — the basis of debuggers. asm-test’s out-of-process single-step tracer uses it to step a target without touching that target’s signal disposition or code cache, the safe path for a managed runtime.
RAII¶: Resource Acquisition Is Initialization. The idiom of tying a resource’s lifetime to a lexical scope. The scoped-tracing constructs are RAII shapes — C#’s using (new AsmTrace()), Java’s try-with-resources, Python’s with — the trace opens in the constructor and renders in the disposer, so the developer footprint stays import + scope.
ReadyToRun¶: R2R. Precompiled native code shipped inside .NET assemblies so the JIT need not compile them at run time. Tracing a precompiled framework method can require forcing the CoreCLR JIT back on (DOTNET_ReadyToRun=0) so it appears in the jitdump/perf-map.
reference model¶: A separate, trusted implementation (usually plain C) of what a routine is supposed to compute. Differential testing compares the assembly routine against it.
Reweave¶: Recomputing the desktop Loom’s fabric after the selection or the step window changes. Expert synonym: re-deriving the lineage layout. The fabric is a pure function of its inputs, so a Reweave is deterministic.
RFLAGS¶: The x86-64 CPU register that holds the status flags (such as CF, ZF, OF, SF, PF).
RIP¶: The x86-64 instruction-pointer register — the architecture’s program counter. A single-step trace is a sequence of RIP values; RIP-relative addressing is how x86-64 code reaches nearby globals, and why JIT bytes must be decoded at the address they ran at.
RISC-V¶: An open, free processor architecture. Its 64-bit variant (RV64) is one of the targets the emulator tier can run.
RNG¶: Random Number Generator. The source of randomness for fuzzing and property testing. asm-test’s RNG is seeded so runs are reproducible.
RVV¶: RISC-V Vector extension. The SIMD instruction set for RISC-V. asm-test’s emulator has no RVV path because Unicorn exposes no vector registers for that guest.
seed¶: A starting value that makes a RNG produce the same sequence every time. Reporting the seed lets a failing random test be replayed exactly.
sentinel¶: A known marker value asm-test writes into callee-saved registers before a native call and checks afterward, to verify the routine restored them — the native-tier form of the ABI preservation check.
SF¶: Sign Flag. A CPU status flag set when the result of an operation is negative (its top bit is 1).
shadow stack¶: The tracer-side stack of return addresses call descent maintains to know when a descended callee has returned to its caller. Each entry records the callee’s return address and the caller’s pre-call stack pointer; a frame is popped when the program counter reaches that return address with the stack pointer restored (or on a non-local exit that raises the stack pointer past it). Internal to the tracer — not the CPU’s hardware shadow stack (CET).
SIGABRT¶: The signal raised when a program deliberately aborts itself (for instance, on a failed internal check).
SIGBUS¶: The signal raised on certain invalid memory accesses, such as a misaligned access the hardware rejects.
signal¶: An asynchronous notification the operating system sends to a process, often to report an error. asm-test catches signals to contain crashes — see SIGSEGV, SIGBUS, SIGABRT.
SIGSEGV¶: Segmentation fault. The signal raised when a program touches memory it isn’t allowed to — the classic symptom of a pointer bug.
SIGTRAP¶: The signal the kernel delivers on a trap-class debug exception — including the per-instruction trap raised when EFLAGS.TF is set. The in-process single-step tracer records one offset per SIGTRAP.
SIMD¶: Single Instruction, Multiple Data. A CPU feature that performs the same operation on several values at once, packed into one wide register. Used for high-performance math. See lane, XMM, NEON.
single-step¶: Executing a routine one instruction at a time so a tracer can record each step, reconstructing the exact instruction and basic block stream. asm-test has two forms: in-process (set EFLAGS.TF and handle each SIGTRAP) and out-of-process (a parent drives the target with ptrace — the W2 path, safe for a managed runtime and the only form on AArch64). Exact but slow — a trap per instruction — so it suits small routines. Contrast step-over vs step-into.
soft-dirty¶: A Linux page-table bit recording whether a memory page has been written since it was last cleared. asm-test uses it to notice when a JIT has re-emitted code, even in another process — the foreign-JIT case.
SP¶: The stack pointer register (rsp on x86-64, sp on AArch64) — points at the top of the call stack. Guest register accessors take it by name (Reg("sp")), and ABI preservation checks assert it is restored on return.
step-over vs step-into¶: Two ways the single-step tracer handles a call. Step-over runs the callee at native speed to its return and records nothing of it (the default, keeping a trace to the region’s own body). Step-into single-steps through the callee, recording it as a nested frame — what call descent does at DESCEND_KNOWN/DESCEND_ALL.
struct return¶: Returning a whole structure from a function. Like struct-by-value, the ABI specifies exactly how, and asm-test handles it.
struct-by-value¶: Passing a whole structure (a bundle of fields) to a function as a copy, rather than passing a pointer to it. The calling convention has detailed rules for this, and asm-test supports it.
suite¶: A collection of related tests built into a single test program (one binary per suite, e.g. build/test_foo).
SVE¶: Scalable Vector Extension. ARM’s length-agnostic SIMD extension for AArch64 — the ARM peer of x86 AVX2 and RISC-V RVV.
System V AMD64 ABI¶: The calling convention used on Linux and macOS for x86-64 programs (the x86-64 psABI). It dictates that the first integer arguments go in specific registers, the return value comes back in rax, and so on. asm-test implements this call model fully. The AAPCS64 is the AArch64 equivalent.
SysV¶: Shorthand for the System V AMD64 ABI — used e.g. in “0–6 SysV integer arguments,” the register-passed argument budget (rdi, rsi, rdx, rcx, r8, r9) asm-test’s call-owning trace entries accept.
TAP¶: Test Anything Protocol. A simple, line-oriented text format for reporting test results (ok 1, not ok 2, …). asm-test prints colored TAP output by default.
terrane¶: A region of the desktop 3-D overview’s address-space terrain — a contiguous block of mapped code or data placed on the plane. Expert synonym: an address-space region / mapped segment. (Spelled as the geological term, a distinct block of crust, to evoke the terrain metaphor.)
TF¶: The trap flag — bit 8 of EFLAGS/RFLAGS. When set, the CPU raises a debug exception (#DB) after every instruction, delivered on Linux as SIGTRAP — the mechanism the in-process single-step backend arms. Because the flag is per-thread but the SIGTRAP disposition is process-wide (and shared with a managed runtime’s own signal handling), arming TF against live managed code is intrusive — the trade-off the scoped-tracing plans’ single-step posture notes discuss.
tier¶: One of asm-test’s execution back-ends. The native tier runs routines on the real CPU; the optional emulator tier runs them inside the emulator; the Win64 tier exercises the Win64 ABI; the native runtime-trace tiers (DynamoRIO, hardware trace, single-step) trace real in-process execution. Beware three unrelated uses of “tier” in these docs: Tier-2 assertions (a binding’s higher-level assertion helpers); Tier-A / Tier-B (asm-test’s naming for a LBR single-shot window vs. its stitched continuation, see Tier-B stitching); and a managed runtime’s tiered compilation levels (see tiered compilation).
Tier-B stitching¶: The technique that lets the AMD LBR backend reconstruct a run longer than the 16-deep hardware branch stack: it joins (“stitches”) successive sampled windows into one continuous trace. The remaining ceiling is the perf_event data ring, not the 16-branch window.
tiered compilation¶: A managed runtime strategy of first compiling a method quickly, then recompiling hot methods with a stronger optimizer (and OSR, on-stack replacement, swapping optimized code in mid-loop). Because it re-emits a method at a possibly reused address, asm-test keys recovered bytes by timestamp — see jitdump.
TLS¶: Thread-local storage — per-thread variables (__thread in C, [ThreadStatic] in C#). The hwtrace scope state lives in TLS, which is why a scope must close on the thread that opened it (both the TF trap flag and the per-thread range stack are thread-local) — a cross-thread close flags the trace truncated. Not the network TLS (Transport Layer Security).
TOS¶: Top of stack — for a LBR branch stack, the newest recorded branch. On AMD LBR (LbrExtV2) internal register renaming pins entry 0 to the TOS, so the 16 entries read out newest-first — the order asm-test’s decoder consumes.
trampoline¶: See capture trampoline.
ULP¶: Unit in the Last Place. The size of the smallest possible step between two representable floating-point numbers. Because floating-point math is inexact, asm-test compares results “to within N ULP” instead of demanding exact equality.
Unicorn¶: The open-source CPU emulator library asm-test uses for its emulator tier. (Its assembler sibling is Keystone.)
V8¶: Google’s JavaScript engine (used by Node.js and Chrome). Its optimizing JIT is TurboFan. One of the managed runtimes asm-test’s foreign-JIT tracer is validated against.
VEH¶: Vectored Exception Handler — the Windows mechanism (AddVectoredExceptionHandler) asm-test’s Win64 single-step front-end uses to catch the EXCEPTION_SINGLE_STEP the Trap Flag raises after each instruction. It is the Windows analogue of the POSIX SIGTRAP path used on Linux and macOS.
W2¶: asm-test’s shorthand for the out-of-process single-step tracer — a ptrace tracer parent stepping a separate tracee — as opposed to the in-process (EFLAGS.TF) stepper. See single-step.
W^X¶: Write-xor-execute. A memory-protection rule that a page may be writable or executable, but never both at once. asm-test maps generated code W^X-correctly (write the bytes, then flip the page to execute-only) before running or tracing it.
watchpoint¶: A guard the emulator places on a memory location (or a register invariant at block entry) that fires the instant a write occurs — catching corruption even if the value is restored before the routine returns.
Win64 ABI¶: The calling convention Microsoft Windows uses on x86-64 (its x64 calling convention). It differs from the System V AMD64 ABI (different argument registers, a shadow-stack area, etc.). asm-test has a dedicated tier for it — see the Win64 guide.
worldline¶: A single value’s path through the desktop Loom’s fabric over time — born at a definition, threading through the steps that read it. Expert synonym: a value’s def-use timeline. Borrowed from the spacetime sense of a particle’s track.
x86-64¶: The 64-bit Intel/AMD processor architecture that powers most PCs and servers. Also called AMD64. One of asm-test’s two primary native targets, alongside AArch64.
XMM¶: The 128-bit SIMD/floating-point registers on x86-64 (xmm0, xmm1, …), used to pass vector and floating-point values.
ZF¶: Zero Flag. A CPU status flag set when the result of an operation is exactly zero.