wazabin-qcode 0.4.0

Typed SSA-style p-code IR for binary analysis, modelled after Ghidra's p-code
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

//! 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`].
//!
//! ```rust
//! 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.
//!
//! [`qcode_passes`]: https://docs.rs/qcode_passes
//! [`qcode_emulator`]: https://docs.rs/qcode_emulator
//! [`qcode_vm`]: https://docs.rs/qcode_vm
//! [`Space`]: crate::space::Space
//! [`ValueId`]: crate::value::ValueId
//! [`FunctionBody`]: crate::value::FunctionBody
//! [`Context`]: crate::context::Context
//! [`Builder`]: crate::builder::Builder
//! [`InstructionRef`]: crate::value::InstructionRef
//! [`BlockRef`]: crate::value::BlockRef
//! [`FunctionRef`]: crate::value::FunctionRef
//! [`qcode!`]: macro@qcode

pub mod address_index;
mod arena_integrity;
pub mod assumption;
pub mod builder;
pub mod context;
pub mod discovery;
pub mod error;
pub mod intrinsics;
pub mod lower;
pub mod memory_image;
pub mod obligation;
pub mod pass_scope;
pub mod space;
pub mod types;
pub mod value;

pub use arena_integrity::{verify_body_arena_integrity, verify_body_arena_integrity_scoped};
pub use wazabin_qcode_macro::qcode;

#[cfg(any(test, feature = "testing"))]
pub mod testing;

/// Re-export for the [`pass_log!`] macro; not public API.
#[doc(hidden)]
pub use log as __log;