Skip to content

Ghidrust provides a hyper fast, AI native reverse engineering platform built in Rust, inspired by Ghidra. Includes experimental GPU kernels to rapidly decompile large files, a decryption suite, and network monitor for packet to binary reverse engineering.

12.3 KB
Raw Blame
//! Architecture-neutral **pcode-like IR** for the Ghidrust decompile pipeline.
//!
//! Inspired by ’s `PcodeOp` / `Varnode` model (reference only — reimplemented
//! in-tree). This crate owns the type surface; SSA, structuring, and emit live
//! elsewhere.
//!
//! # Design notes
//!
//! - **Ops** are a fixed starter set (copy, load/store, integer ALU, control flow).
//!   Unhandled ISA semantics can use [`OpCode::Unimplemented`] until lift coverage grows.
//! - **Varnodes** name a location (`AddrSpace` + offset + size). Constants use
//!   [`AddrSpace::Constant`]; temps use [`AddrSpace::Unique`].
//! - **Basic blocks** are placeholders for CFG construction — not yet wired to SSA.

use serde::{Deserialize, Serialize};

/// Identifier for a named address space in a program IR instance.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
pub struct SpaceId(pub u16);

/// Built-in address spaces.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
pub enum AddrSpace {
    /// Physical / image memory (RAM).
    Ram,
    /// Processor register file; `offset` indexes a register.
    Register,
    /// Immediate / constant pool; `offset` holds the value.
    Constant,
    /// Temporary / unique space for intermediate results.
    Unique,
    /// Abstract stack space (size in bytes; offset relative to frame).
    Stack,
    /// Other named space (extension point).
    Other(SpaceId),
}

/// A typed location: space + offset + width in bytes.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct Varnode {
    pub space: AddrSpace,
    pub offset: u64,
    /// Size in bytes (1, 2, 4, 8, …).
    pub size: u32,
}

impl Varnode {
    pub fn constant(value: u64, size: u32) -> Self {
        Self {
            space: AddrSpace::Constant,
            offset: value,
            size,
        }
    }

    pub fn register(reg_id: u64, size: u32) -> Self {
        Self {
            space: AddrSpace::Register,
            offset: reg_id,
            size,
        }
    }

    pub fn unique(id: u64, size: u32) -> Self {
        Self {
            space: AddrSpace::Unique,
            offset: id,
            size,
        }
    }

    pub fn ram(addr: u64, size: u32) -> Self {
        Self {
            space: AddrSpace::Ram,
            offset: addr,
            size,
        }
    }

    pub fn stack(offset: u64, size: u32) -> Self {
        Self {
            space: AddrSpace::Stack,
            offset,
            size,
        }
    }
}

/// Pcode-like operation codes.
///
/// New ops are added conservatively as lift coverage grows; unknown ISA semantics
/// stay as [`OpCode::Unimplemented`] with the mnemonic preserved in
/// [`PcodeOp::note`] so Stage-0 can still print them.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum OpCode {
    /// `out = in0`
    Copy,
    /// `out = *(in0)` — load from address in0 (address space defaults to RAM).
    Load,
    /// `*(in0) = in1` — store to address in0.
    Store,
    /// `out = in0 + in1` (two's-complement).
    IntAdd,
    /// `out = in0 - in1`.
    IntSub,
    /// `out = in0 ^ in1`.
    IntXor,
    /// `out = in0 & in1`.
    IntAnd,
    /// `out = in0 | in1`.
    IntOr,
    /// `out = in0 * in1` (low half).
    IntMult,
    /// `out = in0 / in1` (unsigned division).
    IntDiv,
    /// `out = in0 / in1` (signed division).
    IntSDiv,
    /// `out = in0 % in1` (unsigned remainder).
    IntRem,
    /// `out = in0 % in1` (signed remainder).
    IntSRem,
    /// `out = in0 << in1` (logical left shift).
    IntLeft,
    /// `out = in0 >> in1` (logical right shift).
    IntRight,
    /// `out = in0 >> in1` (arithmetic right shift).
    IntSRight,
    /// `out = -in0` (two's complement negation).
    IntNegate,
    /// `out = ~in0` (bitwise complement).
    IntNot,
    /// `out = in0 == in1` (bool result, size 1).
    IntEqual,
    /// `out = in0 != in1` (bool result, size 1).
    IntNotEqual,
    /// `out = in0 < in1` (unsigned).
    IntLess,
    /// `out = in0 <= in1` (unsigned).
    IntLessEqual,
    /// `out = in0 < in1` (signed).
    IntSLess,
    /// `out = in0 <= in1` (signed).
    IntSLessEqual,
    /// `out = in0` with sign extension to `out.size`.
    IntSExt,
    /// `out = in0` with zero extension to `out.size`.
    IntZExt,
    /// `out = in0 && in1` (bool AND, boolean inputs).
    BoolAnd,
    /// `out = in0 || in1` (bool OR).
    BoolOr,
    /// `out = !in0` (bool complement).
    BoolNegate,
    /// Unconditional branch to destination (input 0 = target const/addr).
    Branch,
    /// Conditional branch: if in0 != 0 goto in1 (in0 = 1-byte bool).
    CBranch,
    /// Computed / indirect branch (input 0 = target varnode).
    BranchInd,
    /// `call in0` — direct call (input 0 = target const/addr).
    Call,
    /// `call [in0]` — indirect call.
    CallInd,
    /// Return from call (optional return value in inputs).
    Return,
    /// Push value onto stack (modeled explicitly for early lift).
    Push,
    /// Pop into output varnode.
    Pop,
    /// No-op / hint. Preserved so structural passes see the instruction.
    Nop,
    /// Architectural trap (`int3`, `hlt`, `ud2`) — modelled explicitly so
    /// SSA/structuring can decide whether the block terminates. Consumers
    /// treat this as an opaque side-effect with no def.
    Trap,
    /// `out = concat(in0, in1)` — `PIECE`: joins two subwords into a
    /// wider value. `in0` is the high half, `in1` is the low half, and
    /// `out.size == in0.size + in1.size`.
    Piece,
    /// `out = in0 >> (in1 * 8)` truncated to `out.size`
    /// `SUBPIECE`. `in1` names the byte offset from the LSB.
    Subpiece,
    /// `out = in0 + in1 * <element size>` — `PTRADD`. Semantically
    /// identical to `IntAdd` for byte arithmetic but preserves the "array
    /// index" shape so type recovery / emit can print `p[i]`.
    Ptradd,
    /// `out = (T)in0` — `CAST`. Bit-preserving reinterpretation
    /// used when Stage-1 emit needs to insert an explicit `(uint32_t)`.
    Cast,
    /// ISA op not yet lifted — mnemonic preserved in [`PcodeOp::note`].
    Unimplemented,
}

/// One IR operation.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PcodeOp {
    pub opcode: OpCode,
    pub output: Option<Varnode>,
    pub inputs: Vec<Varnode>,
    /// Optional human note (e.g. original mnemonic for `Unimplemented`).
    pub note: Option<String>,
}

impl PcodeOp {
    pub fn new(opcode: OpCode, output: Option<Varnode>, inputs: Vec<Varnode>) -> Self {
        Self {
            opcode,
            output,
            inputs,
            note: None,
        }
    }

    pub fn with_note(mut self, note: impl Into<String>) -> Self {
        self.note = Some(note.into());
        self
    }

    pub fn unimplemented(mnemonic: impl Into<String>) -> Self {
        Self::new(OpCode::Unimplemented, None, vec![]).with_note(mnemonic)
    }
}

/// One op emitted from a single machine instruction, tagged with source address
/// so later CFG / SSA passes can partition and rebuild edges.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct AddressedOp {
    /// Original instruction address the op lifted from.
    pub address: u64,
    /// Byte length of the source machine instruction (0 for synthetic ops).
    pub length: u8,
    pub op: PcodeOp,
}

impl AddressedOp {
    pub fn new(address: u64, length: u8, op: PcodeOp) -> Self {
        Self {
            address,
            length,
            op,
        }
    }
}

/// Basic block used by the SSA / structuring layer.
///
/// `ops` holds the lifted [`PcodeOp`]s. `successors` are resolved block ids for
/// intra-function edges (fall-through, taken branch, indirect targets are left
/// empty until resolved).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct BasicBlock {
    pub id: u32,
    /// Start address in the original image (if known).
    pub start: Option<u64>,
    /// One-past-last-instruction address (if known).
    pub end: Option<u64>,
    pub ops: Vec<PcodeOp>,
    /// Successor block ids (empty until CFG is built).
    pub successors: Vec<u32>,
    /// Predecessor block ids (filled during CFG build).
    pub predecessors: Vec<u32>,
}

impl BasicBlock {
    pub fn new(id: u32) -> Self {
        Self {
            id,
            start: None,
            end: None,
            ops: Vec::new(),
            successors: Vec::new(),
            predecessors: Vec::new(),
        }
    }
}

/// Flat sequence of ops from lifting a linear instruction stream.
///
/// `ops` is the plain fallback view; `addressed` retains per-op source
/// addresses for downstream CFG construction. Both views are kept in sync when
/// callers use [`IrSequence::push_addressed`].
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct IrSequence {
    pub ops: Vec<PcodeOp>,
    pub addressed: Vec<AddressedOp>,
}

impl IrSequence {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn extend(&mut self, ops: impl IntoIterator<Item = PcodeOp>) {
        for op in ops {
            self.ops.push(op);
        }
    }

    pub fn push_addressed(&mut self, address: u64, length: u8, op: PcodeOp) {
        self.ops.push(op.clone());
        self.addressed.push(AddressedOp::new(address, length, op));
    }

    pub fn len(&self) -> usize {
        self.ops.len()
    }

    pub fn is_empty(&self) -> bool {
        self.ops.is_empty()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn varnode_helpers_and_copy_op() {
        let dst = Varnode::register(0 /* rax */, 8);
        let src = Varnode::register(4 /* rsp */, 8);
        let op = PcodeOp::new(OpCode::Copy, Some(dst.clone()), vec![src.clone()]);
        assert_eq!(op.opcode, OpCode::Copy);
        assert_eq!(op.output.as_ref().unwrap().space, AddrSpace::Register);
        assert_eq!(op.inputs[0].offset, 4);
    }

    #[test]
    fn sequence_and_unimplemented() {
        let mut seq = IrSequence::new();
        seq.extend([
            PcodeOp::new(OpCode::Push, None, vec![Varnode::register(5, 8)]),
            PcodeOp::unimplemented("cpuid"),
        ]);
        assert_eq!(seq.len(), 2);
        assert_eq!(seq.ops[1].opcode, OpCode::Unimplemented);
        assert_eq!(seq.ops[1].note.as_deref(), Some("cpuid"));
    }

    #[test]
    fn basic_block_placeholder() {
        let mut bb = BasicBlock::new(0);
        bb.start = Some(0x1000);
        bb.end = Some(0x1001);
        bb.ops.push(PcodeOp::new(OpCode::Return, None, vec![]));
        assert!(bb.successors.is_empty());
        assert!(bb.predecessors.is_empty());
        assert_eq!(bb.ops[0].opcode, OpCode::Return);
    }

    #[test]
    fn ir_sequence_push_addressed_syncs_views() {
        let mut seq = IrSequence::new();
        seq.push_addressed(
            0x1000,
            1,
            PcodeOp::new(OpCode::Push, None, vec![Varnode::register(5, 8)]),
        );
        seq.push_addressed(0x1001, 3, PcodeOp::new(OpCode::Return, None, vec![]));
        assert_eq!(seq.ops.len(), 2);
        assert_eq!(seq.addressed.len(), 2);
        assert_eq!(seq.addressed[0].address, 0x1000);
        assert_eq!(seq.addressed[1].length, 3);
    }

    #[test]
    fn opcode_set_contains_new_arith_and_bool_ops() {
        // Guard against accidental enum churn — pin the new op families.
        for op in [
            OpCode::IntMult,
            OpCode::IntLeft,
            OpCode::IntSRight,
            OpCode::IntEqual,
            OpCode::IntSLess,
            OpCode::IntSExt,
            OpCode::BoolNegate,
            OpCode::BranchInd,
            OpCode::CallInd,
            OpCode::Nop,
        ] {
            let node = PcodeOp::new(op, None, vec![]);
            assert_eq!(node.opcode, op);
        }
    }

    #[test]
    fn opcode_set_covers_division_trap_and_bitops() {
        // Division family, Trap for int3/hlt, and bit-manipulation
        // ops (PIECE/SUBPIECE/PTRADD/CAST) that Stage-1 emit will need as
        // lift coverage grows.
        for op in [
            OpCode::IntDiv,
            OpCode::IntSDiv,
            OpCode::IntRem,
            OpCode::IntSRem,
            OpCode::Trap,
            OpCode::Piece,
            OpCode::Subpiece,
            OpCode::Ptradd,
            OpCode::Cast,
        ] {
            let node = PcodeOp::new(op, None, vec![]);
            assert_eq!(node.opcode, op);
        }
    }
}