chore: Trait Cleanup and PcodeOpRef (#133)

Cleaned up some unused CPA trait items left-over from the Residue refactor

Added some doc comments

Compound Analyses are still () tuples of analyses, but their inner states are now a CompoundState tuple struct instead of a raw Tuple. The raw tuple is nice but prevents things like implementing Display automatially for compound states, so trying out using our own type. The named tuple is a little grosser, but users mostly don't interact directly with the states anyway? Perhaps there's a nice way to use that type internally but still give the user a () tuple to work with.

We inject BRANCH instructions representing follow-through. Changed the SleighContext to inject these branches on construction of Instruction instead of dynamically on access to an invalid index. This allows returning a reference to these injected operations instead of a value.

Re-implemented the unwinding analysis as a generic wrapper around other analyses

Added a PcodeOpRef type that wraps a Cow<PcodeOperation>; made all CPA/CFG traits use this ref type instead. This allows many types to pass ops by reference which should involve much less cloning/allocation in many workloads.

Author: toolCHAINZ

jingle/examples/stack_offset.rs

@@ -100,7 +100,6 @@ fn main() {
                 VarnodeValue::Entry(_) => " [stack: Entry (0)]".to_string(),
                 VarnodeValue::Offset(_, off) => format!(" [stack: {:+}]", off),
                 VarnodeValue::Const(c) => format!(" [stack: const 0x{:x}]", c),
-                VarnodeValue::Bottom => " [stack: bottom]".to_string(),
                 _ => " [stack: unknown]".to_string(),
             })
             .unwrap_or_default();
@@ -161,7 +160,6 @@ fn main() {
                 VarnodeValue::Entry(_) => " [stack: Entry (0)]".to_string(),
                 VarnodeValue::Offset(_, off) => format!(" [stack: {:+}]", off),
                 VarnodeValue::Const(c) => format!(" [stack: const 0x{:x}]", c),
-                VarnodeValue::Bottom => " [stack: bottom]".to_string(),
                 _ => " [stack: unknown]".to_string(),
             })
             .unwrap_or_default();

jingle/examples/unwind.rs

@@ -0,0 +1,79 @@
+#![allow(unused)]
+
+use jingle::analysis::cpa::RunnableConfigurableProgramAnalysis;
+use jingle::analysis::cpa::reducer::CfgReducer;
+use jingle::analysis::cpa::residue::Residue;
+use jingle::analysis::cpa::state::LocationState;
+use jingle::analysis::direct_location::{CallBehavior, DirectLocationAnalysis};
+use jingle::analysis::unwinding::BoundedBackEdgeVisitAnalysis;
+use jingle::analysis::unwinding2::UnwindExt;
+use jingle::analysis::{Analysis, RunnableAnalysis};
+use jingle::modeling::machine::cpu::concrete::ConcretePcodeAddress;
+use jingle_sleigh::context::image::gimli::load_with_gimli;
+use petgraph::dot::Dot;
+use std::{env, fs};
+
+/// Addresses of various test functions in the example binary.
+const FUNC_LINE: u64 = 0x100000460;
+const FUNC_BRANCH: u64 = 0x100000480;
+const FUNC_SWITCH: u64 = 0x1000004a0;
+const FUNC_LOOP: u64 = 0x100000548;
+const FUNC_NESTED: u64 = 0x100000588;
+const FUNC_GOTO: u64 = 0x100000610;
+
+fn main() {
+    // Initialize tracing for debug output
+    tracing_subscriber::fmt()
+        .with_max_level(tracing::Level::INFO)
+        .with_target(false)
+        .with_thread_ids(false)
+        .with_line_number(true)
+        .init();
+
+    tracing::info!("Starting unwinding analysis with back-edge visit counting");
+
+    // Load binary via gimli-backed image context
+    let bin_path = env::home_dir()
+        .unwrap()
+        .join("Documents/test_funcs/build/example");
+    let loaded = load_with_gimli(bin_path, "/Applications/ghidra").unwrap();
+
+    tracing::info!("Binary loaded successfully");
+
+    // Run unwinding analysis - back-edges are computed internally
+    tracing::info!("Running unwinding analysis with bounded back-edge visit counting");
+
+    let location_analysis = DirectLocationAnalysis::new(CallBehavior::Branch).unwind(5);
+
+    // Wrap with CfgReducer
+    let mut analysis_with_cfg = location_analysis.with_residue(CfgReducer::new());
+
+    // Run the unwinding analysis
+    let cfg = analysis_with_cfg.run(&loaded, ConcretePcodeAddress::from(FUNC_NESTED));
+
+    // Print results
+    println!("\nUnwinding Analysis Results:");
+    println!("===========================\n");
+
+    println!("CFG nodes (unwound states): {}", cfg.nodes().count());
+
+    let mut locations: Vec<_> = cfg.nodes().filter_map(|n| n.get_location()).collect();
+    locations.sort();
+    locations.dedup();
+
+    println!("Unique program locations: {}", locations.len());
+    for loc in &locations {
+        let count = cfg
+            .nodes()
+            .filter(|n| n.get_location() == Some(*loc))
+            .count();
+        println!("  0x{:x} (visited {} times)", loc, count);
+    }
+    fs::write("dot.dot", format!("{:x}", Dot::new(cfg.graph())));
+    println!(
+        "\nTotal CFG nodes with unwinding: {}",
+        cfg.graph().node_count()
+    );
+
+    tracing::info!("Analysis complete");
+}

jingle/src/analysis/back_edge/mod.rs

@@ -1,10 +1,9 @@
 use crate::analysis::Analysis;
 use crate::analysis::cpa::lattice::JoinSemiLattice;
 use crate::analysis::cpa::lattice::pcode::PcodeAddressLattice;
-use crate::analysis::cpa::residue::EmptyResidue;
+use crate::analysis::cpa::residue::Residue;
 use crate::analysis::cpa::state::{AbstractState, LocationState, MergeOutcome, Successor};
 use crate::analysis::cpa::{ConfigurableProgramAnalysis, IntoState};
-use crate::analysis::pcode_store::PcodeStore;
 use crate::modeling::machine::cpu::concrete::ConcretePcodeAddress;
 use jingle_sleigh::PcodeOperation;
 use std::borrow::Borrow;
@@ -123,7 +122,10 @@ impl AbstractState for BackEdgeState {
 }
 
 impl LocationState for BackEdgeState {
-    fn get_operation<T: PcodeStore>(&self, t: &T) -> Option<PcodeOperation> {
+    fn get_operation<'a, T: crate::analysis::pcode_store::PcodeStore + ?Sized>(
+        &'a self,
+        t: &'a T,
+    ) -> Option<crate::analysis::pcode_store::PcodeOpRef<'a>> {
         self.location.get_operation(t)
     }
 
@@ -132,32 +134,90 @@ impl LocationState for BackEdgeState {
     }
 }
 
-pub struct BackEdgeCPA {
-    pub back_edges: Vec<(PcodeAddressLattice, PcodeAddressLattice)>,
+/// A reducer that identifies back-edges during the analysis.
+///
+/// A back-edge is an edge from a state to a previously visited state in its path.
+/// This reducer tracks all visited edges and identifies when a transition creates
+/// a back-edge by checking if the destination location appears in the source state's
+/// visited path.
+pub struct BackEdgeReducer {
+    /// All visited edges (from_location, to_location)
+    visited_edges: Vec<(ConcretePcodeAddress, ConcretePcodeAddress)>,
+    /// Identified back-edges
+    back_edges: BackEdges,
 }
 
-impl Default for BackEdgeCPA {
-    fn default() -> Self {
-        Self::new()
+impl BackEdgeReducer {
+    pub fn new() -> Self {
+        Self {
+            visited_edges: Vec::new(),
+            back_edges: BackEdges::default(),
+        }
     }
-}
 
-impl BackEdgeCPA {
-    pub fn new() -> Self {
+    pub fn new_with_capacity(cap: usize) -> Self {
         Self {
-            back_edges: Vec::new(),
+            visited_edges: Vec::with_capacity(cap),
+            back_edges: BackEdges::default(),
         }
     }
+}
+
+impl Default for BackEdgeReducer {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Residue<BackEdgeState> for BackEdgeReducer {
+    type Output = BackEdges;
 
-    /// Extract the computed back edges into a BackEdges structure
-    pub fn get_back_edges(&self) -> BackEdges {
-        let mut b = BackEdges::default();
-        for (from, to) in &self.back_edges {
-            if let (PcodeAddressLattice::Const(from), PcodeAddressLattice::Const(to)) = (from, to) {
-                b.add(*from, *to);
+    /// Track a state transition and identify if it's a back-edge.
+    ///
+    /// A back-edge occurs when we transition from a state to a destination
+    /// that appears in the source state's visited path.
+    fn new_state(
+        &mut self,
+        state: &BackEdgeState,
+        dest_state: &BackEdgeState,
+        _op: &Option<crate::analysis::pcode_store::PcodeOpRef<'_>>,
+    ) {
+        // Extract concrete addresses from both states
+        if let (Some(from_addr), Some(to_addr)) = (state.get_location(), dest_state.get_location())
+        {
+            // Record this edge
+            if !self.visited_edges.contains(&(from_addr, to_addr)) {
+                self.visited_edges.push((from_addr, to_addr));
+            }
+
+            // Check if this is a back-edge:
+            // The destination is a back-edge if it appears in the source state's visited path
+            if state.path_visits.contains(&dest_state.location) {
+                self.back_edges.add(from_addr, to_addr);
             }
         }
-        b
+    }
+
+    fn new() -> Self {
+        Self::new()
+    }
+
+    fn finalize(self) -> Self::Output {
+        self.back_edges
+    }
+}
+
+pub struct BackEdgeCPA;
+
+impl Default for BackEdgeCPA {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl BackEdgeCPA {
+    pub fn new() -> Self {
+        Self
     }
 
     /// Inherent constructor for the analysis initial state.
@@ -174,20 +234,7 @@ impl BackEdgeCPA {
 
 impl ConfigurableProgramAnalysis for BackEdgeCPA {
     type State = BackEdgeState;
-    type Reducer = EmptyResidue<Self::State>;
-
-    fn residue(
-        &mut self,
-        old_state: &Self::State,
-        new_state: &Self::State,
-        _op: &Option<PcodeOperation>,
-    ) {
-        if old_state.path_visits.contains(&new_state.location) {
-            // Clone the locations since `old_state` and `new_state` are borrowed here.
-            self.back_edges
-                .push((old_state.location.clone(), new_state.location.clone()))
-        }
-    }
+    type Reducer = BackEdgeReducer;
 }
 
 impl Analysis for BackEdgeCPA {}

jingle/src/analysis/cfg/mod.rs

@@ -9,14 +9,19 @@ use petgraph::visit::EdgeRef;
 use std::borrow::Borrow;
 use std::cell::RefCell;
 use std::collections::{HashMap, HashSet};
-use std::fmt::{Formatter, LowerHex};
+use std::fmt::{Display, Formatter, LowerHex};
 use std::rc::Rc;
 
 pub(crate) mod model;
 
 #[derive(Debug, Default, Copy, Clone, Hash)]
 pub struct EmptyEdge;
 
+impl Display for EmptyEdge {
+    fn fmt(&self, _f: &mut Formatter<'_>) -> std::fmt::Result {
+        Ok(())
+    }
+}
 impl LowerHex for EmptyEdge {
     fn fmt(&self, _: &mut Formatter<'_>) -> std::fmt::Result {
         Ok(())
@@ -277,9 +282,13 @@ impl<N: CfgState, D: ModelTransition<N::Model>> PcodeCfg<N, D> {
 }
 
 impl PcodeStore for PcodeCfg<ConcretePcodeAddress, PcodeOperation> {
-    fn get_pcode_op_at<T: Borrow<ConcretePcodeAddress>>(&self, addr: T) -> Option<PcodeOperation> {
+    fn get_pcode_op_at<'a, T: Borrow<ConcretePcodeAddress>>(
+        &'a self,
+        addr: T,
+    ) -> Option<crate::analysis::pcode_store::PcodeOpRef<'a>> {
         let addr = *addr.borrow();
-        self.get_op_at(addr).cloned()
+        self.get_op_at(addr)
+            .map(crate::analysis::pcode_store::PcodeOpRef::from)
     }
 }
 

jingle/src/analysis/cfg/model.rs

@@ -1,4 +1,5 @@
 use crate::JingleError;
+use crate::analysis::compound::CompoundState;
 use crate::analysis::cpa::lattice::flat::FlatLattice;
 use crate::analysis::cpa::state::StateDisplay;
 use crate::modeling::machine::MachineState;
@@ -139,7 +140,7 @@ impl<'a, S: StateDisplay> std::fmt::Display for StateDisplayWrapper<'a, S> {
         self.0.fmt_state(f)
     }
 }
-impl<A: CfgState, B: StateDisplay + Clone + Debug + Hash + Eq> CfgState for (A, B) {
+impl<A: CfgState, B: StateDisplay + Clone + Debug + Hash + Eq> CfgState for CompoundState<A, B> {
     type Model = A::Model;
 
     fn new_const(&self, i: &SleighArchInfo) -> Self::Model {
@@ -156,59 +157,3 @@ impl<A: CfgState, B: StateDisplay + Clone + Debug + Hash + Eq> CfgState for (A,
         self.0.location()
     }
 }
-
-impl<
-    A: CfgState,
-    B: StateDisplay + Clone + Debug + Hash + Eq,
-    C: StateDisplay + Clone + Debug + Hash + Eq,
-> CfgState for (A, B, C)
-{
-    type Model = A::Model;
-
-    fn new_const(&self, i: &SleighArchInfo) -> Self::Model {
-        self.0.new_const(i)
-    }
-
-    fn model_id(&self) -> String {
-        // Include display outputs from the second and third elements.
-        format!(
-            "{}_{}_{}",
-            self.0.model_id(),
-            StateDisplayWrapper(&self.1),
-            StateDisplayWrapper(&self.2)
-        )
-    }
-
-    fn location(&self) -> Option<ConcretePcodeAddress> {
-        self.0.location()
-    }
-}
-
-impl<
-    A: CfgState,
-    B: StateDisplay + Clone + Debug + Hash + Eq,
-    C: StateDisplay + Clone + Debug + Hash + Eq,
-    D: StateDisplay + Clone + Debug + Hash + Eq,
-> CfgState for (A, B, C, D)
-{
-    type Model = A::Model;
-
-    fn new_const(&self, i: &SleighArchInfo) -> Self::Model {
-        self.0.new_const(i)
-    }
-
-    fn model_id(&self) -> String {
-        // Include display outputs from elements 2, 3 and 4.
-        format!(
-            "{}_{}_{}_{}",
-            self.0.model_id(),
-            StateDisplayWrapper(&self.1),
-            StateDisplayWrapper(&self.2),
-            StateDisplayWrapper(&self.3)
-        )
-    }
-
-    fn location(&self) -> Option<ConcretePcodeAddress> {
-        self.0.location()
-    }
-}