Crate qcode 

Typed SSA-style p-code IR for binary analysis.

qcode models the semantics of lifted machine code. It is inspired by Ghidra’s p-code, with additional first-class values for instructions, basic blocks, functions, and literals. The crate contains the IR, its builder, the QCode text-format lowering API, and integrity checks. Optimization and execution live separately: see qcode_passes for block-local cleanup, qcode_emulator to interpret QCode, and qcode_vm to run a guest program under an MMU.

Getting started

A Context owns a QCode module. Create one, then construct IR with a Builder or parse QCode source through lower::lower_str.

use qcode::context::Context;

let _context = Context::new();

Core concepts

• A Space is a uniformly addressed memory region, such as RAM or a register file.
• A ValueId identifies every IR value: literals, SSA instructions, varnodes, blocks, and functions.
• A FunctionBody owns a function’s instructions, blocks, and block parameters; module-wide values are owned by the Context.
• A Builder emits instructions and constructs control flow in a block.

Reference types such as InstructionRef, BlockRef, and FunctionRef borrow their owning context, so they cannot outlive the IR arena.

QCode source

lower::lower_str parses QCode source at runtime. For source literals, the re-exported qcode! macro performs the same lowering and binds names declared in the source into the surrounding Rust scope.

Modules

address_index

Disposable address lookup over an immutable qcode module snapshot.

assumption

Heuristic assumptions and proven knowledge shared by analysis passes.

builder

Fluent IR builder: emit instructions into a BasicBlock.

context

The central arena for all IR state: Context.

discovery

Typed queue of code addresses discovered during lifting/analysis but not yet lifted into the IR.

error

intrinsics

Built-in pure intrinsics.

lower

Runtime lowering of parsed QCode text into qcode IR.

memory_image

A serializable snapshot of a binary’s initialized memory.

obligation

Stable identity for a reconstruction obligation: an unresolved control transfer that reconstruction still owes an answer for.

pass_scope

Thread-local identity of the currently-running analysis pass.

space

Memory spaces: uniformly-addressed regions that varnodes live in.

types

First-class type system for qcode IR values.

value

IR value types and the central ValueId discriminant.

Macros

composite_id

Declares a composite IR ID: a { func: FunctionId, local: LocalX } pair.

pass_log

Log a message attributed to the current pass: the log target is the pass name (so RUST_LOG=mem2reg=debug filters per pass) and the message is prefixed with it.

qcode

register_intrinsic

Register a built-in intrinsic with the global registry.

stat

Add to a named counter of the current pass; the driver aggregates and logs them per round. stat!("slots_promoted") increments by 1.

Functions

verify_body_arena_integrity

Validate the ownership and cross-reference invariants of every function body’s block, instruction, parameter, CFG-edge, and temporary arenas.

verify_body_arena_integrity_scoped

verify_body_arena_integrity, restricted to the functions in scope (None means every function). Arena invariants are strictly per-body, so a caller that knows which functions changed can skip the rest.