qcode/
lib.rs

1//! Typed SSA-style p-code IR for binary analysis.
2//!
3//! `qcode` models the semantics of lifted machine code. It is inspired by
4//! Ghidra's p-code, with additional first-class values for instructions, basic
5//! blocks, functions, and literals. The crate contains the IR, its builder,
6//! the QCode text-format lowering API, and integrity checks. Optimization and
7//! execution live separately: see [`qcode_passes`] for block-local cleanup,
8//! [`qcode_emulator`] to interpret QCode, and [`qcode_vm`] to run a guest
9//! program under an MMU.
10//!
11//! # Getting started
12//!
13//! A [`Context`] owns a QCode module. Create one, then construct IR with a
14//! [`Builder`] or parse QCode source through [`lower::lower_str`].
15//!
16//! ```rust
17//! use qcode::context::Context;
18//!
19//! let _context = Context::new();
20//! ```
21//!
22//! # Core concepts
23//!
24//! - A [`Space`] is a uniformly addressed memory region, such as RAM or a
25//!   register file.
26//! - A [`ValueId`] identifies every IR value: literals, SSA instructions,
27//!   varnodes, blocks, and functions.
28//! - A [`FunctionBody`] owns a function's instructions, blocks, and block
29//!   parameters; module-wide values are owned by the [`Context`].
30//! - A [`Builder`] emits instructions and constructs control flow in a block.
31//!
32//! Reference types such as [`InstructionRef`], [`BlockRef`], and
33//! [`FunctionRef`] borrow their owning context, so they cannot outlive the IR
34//! arena.
35//!
36//! # QCode source
37//!
38//! [`lower::lower_str`] parses QCode source at runtime. For source literals,
39//! the re-exported [`qcode!`] macro performs the same lowering and binds names
40//! declared in the source into the surrounding Rust scope.
41//!
42//! [`qcode_passes`]: https://docs.rs/qcode_passes
43//! [`qcode_emulator`]: https://docs.rs/qcode_emulator
44//! [`qcode_vm`]: https://docs.rs/qcode_vm
45//! [`Space`]: crate::space::Space
46//! [`ValueId`]: crate::value::ValueId
47//! [`FunctionBody`]: crate::value::FunctionBody
48//! [`Context`]: crate::context::Context
49//! [`Builder`]: crate::builder::Builder
50//! [`InstructionRef`]: crate::value::InstructionRef
51//! [`BlockRef`]: crate::value::BlockRef
52//! [`FunctionRef`]: crate::value::FunctionRef
53//! [`qcode!`]: macro@qcode
54
55pub mod address_index;
56mod arena_integrity;
57pub mod assumption;
58pub mod builder;
59pub mod context;
60pub mod discovery;
61pub mod error;
62pub mod intrinsics;
63pub mod lower;
64pub mod memory_image;
65pub mod obligation;
66pub mod pass_scope;
67pub mod space;
68pub mod types;
69pub mod value;
70
71pub use arena_integrity::{verify_body_arena_integrity, verify_body_arena_integrity_scoped};
72pub use wazabin_qcode_macro::qcode;
73
74#[cfg(any(test, feature = "testing"))]
75pub mod testing;
76
77/// Re-export for the [`pass_log!`] macro; not public API.
78#[doc(hidden)]
79pub use log as __log;
qcode/lib.rs

qcode/
lib.rs
