Expand description
Lift decoded sleigh::Instructions into QCode.
This crate is the integration boundary between wazabin-sleigh and
qcode. It consumes SLEIGH’s flat p-code API rather
than its source-shaped AST, keeping both core crates independent.
Construct a SleighLifter once per compiled specification. Its
SleighLifter::new_context method clones a prebuilt QCode context with
spaces, registers, and user p-code operations already installed. Reuse an
AddressIndex with SleighLifter::lift_instruction_indexed when
lifting multiple instructions.
§Example
Decode one x86-64 instruction and lift it into a QCode context:
use sleigh::Decoder;
use sleigh_precompile::x64;
use qcode::address_index::AddressIndex;
use wazabin_qcode_sleigh::{FlatPcode, SleighLifter};
let spec = x64::spec();
// `48 89 d8` is `MOV RAX, RBX`.
let instruction = Decoder::new(spec)
.decode_one(0x1000, &[0x48, 0x89, 0xd8], &spec.new_context())
.expect("the bytes decode");
let flat = FlatPcode::lower(&instruction).expect("the semantics emit");
let lifter = SleighLifter::new(spec);
let mut ctx = lifter.new_context();
let mut addresses = AddressIndex::analyze(&ctx);
lifter
.lift_pcode_indexed(&mut ctx, &mut addresses, &flat, None)
.expect("the p-code lowers");
println!("{ctx}");§Memoized lifting
Machine code repeats, and lowering the busiest x86-64 forms costs
hundreds of microseconds each. A cache::LiftCache shared by the
sessions of a lifter remembers what every encoding lowered to and
replays it at any other address, exactly — see the cache module for
how that is measured rather than assumed. A scratch session serves a hit
without decoding or lowering anything:
use std::sync::Arc;
use sleigh_precompile::x64;
use wazabin_qcode_sleigh::{SleighLifter, cache::LiftCache, session::ScratchSession};
let lifter = SleighLifter::new(x64::spec()).with_flat_control_flow();
let cache = Arc::new(LiftCache::new(lifter.spec()));
let mut session = ScratchSession::new(&lifter).with_cache(Arc::clone(&cache));
for address in [0x1000, 0x2000] {
let lifted = session.lift(address, &[0xde, 0xc9]).expect("FMULP lifts");
println!("{} blocks, cached: {}", lifted.blocks().count(), lifted.is_cached());
}
println!("{:?}", cache.stats());The qcode-dump example prints every stage — disassembly text, SLEIGH AST,
flat p-code, and the resulting QCode:
cargo run --example qcode-dump -- 4889d8Modules§
- cache
- Memoized lifting: the QCode of an encoding’s shape, replayed at another address with other operand values.
- decode
- What context an instruction is decoded with.
- session
- Sessions that own the IR they lift into.
- vm_
source - A
CodeSourcethat decodes guest memory with SLEIGH.
Structs§
- Flat
Pcode - Already-flattened p-code of one instruction, with the identity of the specification that produced it.
- Sleigh
Lifter - Specification-specific state reused across all lifting sessions.
Enums§
- Lift
Error - Failure while converting flat p-code to QCode.