Add comb depth analysis (#5)

* add comb depth analysis

* small api change

* add some panic docs

* fix issue

* fix the docs a bit

* make ex compile

Author: matth2k

src/bin/main.rs

@@ -51,7 +51,7 @@ fn simple_example() -> Netlist<Gate> {
 
 fn harder_example() -> Netlist<Gate> {
     let netlist = Netlist::new("harder_example".to_string());
-    let bitwidth = 8;
+    let bitwidth = 9;
 
     // Add the the inputs
     let a_vec = netlist.insert_input_escaped_logic_bus("a".to_string(), bitwidth);
@@ -94,6 +94,20 @@ fn harder_example() -> Netlist<Gate> {
 fn main() {
     let netlist = harder_example();
     print!("{}", netlist);
+
+    let logic_levels = netlist
+        .get_analysis::<circuit::graph::SimpleCombDepth<_>>()
+        .unwrap();
+    println!("Logic levels: {}", logic_levels.get_max_depth());
+    for n in netlist.objects() {
+        for n in n.nets() {
+            println!(
+                "{}: {}",
+                n.get_identifier(),
+                logic_levels.get_comb_depth(&n).unwrap()
+            );
+        }
+    }
     // let fo = netlist
     //     .get_analysis::<circuit::graph::FanOutTable<_>>()
     //     .unwrap();
@@ -106,16 +120,10 @@ fn main() {
     // for inst in netlist.objects() {
     //     println!("{}", inst);
     // }
-    let pg = netlist
-        .get_analysis::<circuit::graph::MultiDiGraph<_>>()
-        .unwrap();
-    let graph = pg.get_graph();
-    for c in graph.edge_references() {
-        let w = c.weight();
-        if let circuit::graph::Edge::Connection(c) = w {
-            c.src().get_net_mut().set_identifier("lolled".into());
-        }
-    }
+    // let pg = netlist
+    //     .get_analysis::<circuit::graph::MultiDiGraph<_>>()
+    //     .unwrap();
+    // let graph = pg.get_graph();
     // println!("{}", petgraph::dot::Dot::with_config(&graph, &[]));
 }
 

src/graph.rs

@@ -7,6 +7,7 @@
 use crate::circuit::{Instantiable, Net};
 #[cfg(feature = "graph")]
 use crate::netlist::Connection;
+use crate::netlist::iter::DFSIterator;
 use crate::netlist::{NetRef, Netlist};
 #[cfg(feature = "graph")]
 use petgraph::graph::DiGraph;
@@ -81,6 +82,78 @@ where
     }
 }
 
+/// An simple example to analyze the logic levels of a netlist.
+/// This analysis checks for cycles, but it doesn't check for registers.
+pub struct SimpleCombDepth<'a, I: Instantiable> {
+    // A reference to the underlying netlist
+    _netlist: &'a Netlist<I>,
+    // Maps a net to its logic level as a DAG
+    comb_depth: HashMap<Net, usize>,
+    /// The maximum depth of the circuit
+    max_depth: usize,
+}
+
+impl<I> SimpleCombDepth<'_, I>
+where
+    I: Instantiable,
+{
+    /// Returns the logic level of a net in the circuit.
+    pub fn get_comb_depth(&self, net: &Net) -> Option<usize> {
+        self.comb_depth.get(net).cloned()
+    }
+
+    /// Returns the maximum logic level of the circuit.
+    pub fn get_max_depth(&self) -> usize {
+        self.max_depth
+    }
+}
+
+impl<'a, I> Analysis<'a, I> for SimpleCombDepth<'a, I>
+where
+    I: Instantiable,
+{
+    fn build(netlist: &'a Netlist<I>) -> Result<Self, String> {
+        let mut comb_depth: HashMap<Net, usize> = HashMap::new();
+
+        let mut nodes = Vec::new();
+        for (driven, _) in netlist.outputs() {
+            let mut dfs = DFSIterator::new(netlist, driven.unwrap());
+            while let Some(n) = dfs.next() {
+                if dfs.check_cycles() {
+                    return Err("Cycle detected in the netlist".to_string());
+                }
+                nodes.push(n);
+            }
+        }
+        nodes.reverse();
+
+        for node in nodes {
+            if node.is_an_input() {
+                comb_depth.insert(node.as_net().clone(), 0);
+            } else {
+                // TODO(matth2k): get_driver_net() relies on a weak reference. Rewrite without it.
+                let max_depth: usize = (0..node.get_num_input_ports())
+                    .filter_map(|i| netlist.get_driver_net(node.clone(), i))
+                    .filter_map(|n| comb_depth.get(&n))
+                    .max()
+                    .cloned()
+                    .unwrap_or(usize::MAX);
+                for net in node.nets() {
+                    comb_depth.insert(net, max_depth + 1);
+                }
+            }
+        }
+
+        let max_depth = comb_depth.values().max().cloned().unwrap_or(0);
+
+        Ok(SimpleCombDepth {
+            _netlist: netlist,
+            comb_depth,
+            max_depth,
+        })
+    }
+}
+
 /// An enum to provide pseudo-nodes for any misc user-programmable behavior.
 #[cfg(feature = "graph")]
 #[derive(Debug, Clone)]

src/netlist.rs

@@ -315,6 +315,10 @@ where
     }
 
     /// Get driving net using the weak reference
+    ///
+    /// # Panics
+    ///
+    /// Panics if the reference to the netlist is lost.
     fn get_driver_net(&self, index: usize) -> Option<Net> {
         let operand = &self.operands[index];
         match operand {
@@ -387,12 +391,18 @@ where
     }
 
     /// Returns a borrow to the [Net] at this circuit node.
+    ///
+    /// # Panics
+    ///
     /// Panics if the circuit node has multiple outputs.
     pub fn as_net(&self) -> Ref<Net> {
         Ref::map(self.netref.borrow(), |f| f.as_net())
     }
 
     /// Returns a mutable borrow to the [Net] at this circuit node.
+    ///
+    /// # Panics
+    ///
     /// Panics if the circuit node has multiple outputs.
     pub fn as_net_mut(&self) -> RefMut<Net> {
         RefMut::map(self.netref.borrow_mut(), |f| f.as_net_mut())
@@ -422,12 +432,18 @@ where
     }
 
     /// Returns the name of the net at this circuit node.
+    ///
+    /// # Panics
+    ///
     /// Panics if the circuit node has multiple outputs.
     pub fn get_identifier(&self) -> Identifier {
         self.as_net().get_identifier().clone()
     }
 
     /// Changes the identifier of the net at this circuit node.
+    ///
+    /// # Panics
+    ///
     /// Panics if the circuit node has multiple outputs.
     pub fn set_identifier(&self, identifier: Identifier) {
         self.as_net_mut().set_identifier(identifier)
@@ -465,7 +481,10 @@ where
     }
 
     /// Updates the name of the instance, if the circuit node is an instance.
-    /// Panics if the circuit node is not an instance.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the circuit node is a principal input.
     pub fn set_instance_name(&self, name: Identifier) {
         match self.netref.borrow_mut().get_mut() {
             Object::Instance(_, inst_name, _) => *inst_name = name,
@@ -474,7 +493,12 @@ where
     }
 
     /// Exposes this circuit node as a top-level output in the netlist.
-    /// Panics if cell is a multi-output circuit node. Errors if circuit node is a principal input.
+    /// Returns an error if the circuit node is a principal input.
+    ///
+    /// # Panics
+    ///
+    /// Panics if cell is a multi-output circuit node.
+    /// Panics if the reference to the netlist is lost.
     pub fn expose_as_output(self) -> Result<Self, String> {
         let netlist = self
             .netref
@@ -487,6 +511,11 @@ where
     }
 
     /// Exposes this circuit node as a top-level output in the netlist with a specific port name.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the cell is a multi-output circuit node.
+    /// Panics if the reference to the netlist is lost.
     pub fn expose_with_name(self, name: String) -> Self {
         let netlist = self
             .netref
@@ -500,6 +529,9 @@ where
 
     /// Exposes the `net` driven by this circuit node as a top-level output.
     /// Errors if `net` is not driven by this circuit node.
+    ///
+    /// # Panics
+    /// Panics if the reference to the netlist is lost.
     pub fn expose_net(&self, net: &Net) -> Result<(), String> {
         let netlist = self
             .netref
@@ -522,12 +554,20 @@ where
     }
 
     /// Returns the net that drives the `index`th input
+    ///
+    /// # Panics
+    ///
+    /// Panics if the reference to the netlist is lost.
     pub fn get_driver_net(&self, index: usize) -> Option<Net> {
         self.netref.borrow().get_driver_net(index)
     }
 
     /// Returns a request to mutably borrow the operand net
     /// This requires another borrow in the form of [MutBorrowReq]
+    ///
+    /// # Panics
+    ///
+    /// Panics if the reference to the netlist is lost.
     pub fn req_driver_net(&self, index: usize) -> Option<MutBorrowReq<I>> {
         let net = self.get_driver_net(index)?;
         let operand = self.get_driver(index).unwrap();
@@ -599,6 +639,9 @@ where
     }
 
     /// Returns `true` if this circuit node drives a top-level output.
+    ///
+    /// # Panics
+    /// Panics if the weak reference to the netlist is lost.
     pub fn drives_an_top_output(&self) -> bool {
         let netlist = self
             .netref
@@ -620,6 +663,10 @@ where
     }
 
     /// Deletes the uses of this circuit node from the netlist.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the reference to the netlist is lost.
     pub fn delete_uses(self) -> Result<Object<I>, String> {
         let netlist = self
             .netref
@@ -631,7 +678,11 @@ where
     }
 
     /// Replaces the uses of this circuit node in the netlist with another circuit node.
+    ///
+    /// # Panics
+    ///
     /// Panics if either `self` or `other` is a multi-output circuit node.
+    /// Panics if the weak reference to the netlist is lost.
     pub fn replace_uses_with(self, other: &Self) -> Result<Object<I>, String> {
         let netlist = self
             .netref
@@ -1053,6 +1104,21 @@ where
         Ok(NetRef::wrap(owned_object))
     }
 
+    /// Returns the driving net at input position `index` for `netref`
+    ///
+    /// # Panics
+    ///
+    /// Panics if `index` is out of bounds
+    pub fn get_driver_net(&self, netref: NetRef<I>, index: usize) -> Option<Net> {
+        let op = netref.unwrap().borrow().operands[index].clone()?;
+        Some(
+            self.index_weak(&op.root())
+                .borrow()
+                .get_net(op.secondary())
+                .clone(),
+        )
+    }
+
     /// Set an added object as a top-level output.
     /// Panics if `net`` is a multi-output node.
     pub fn expose_net_with_name(&self, net: DrivenNet<I>, name: String) -> DrivenNet<I> {
@@ -1513,10 +1579,28 @@ pub mod iter {
     }
 
     /// A depth-first iterator over the circuit nodes in a netlist
+    /// # Examples
+    ///
+    /// ```
+    /// use circuit::netlist::iter::DFSIterator;
+    /// use circuit::netlist::GateNetlist;
+    ///
+    /// let netlist = GateNetlist::new("example".to_string());
+    /// netlist.insert_input("input1".into());
+    /// let mut nodes = Vec::new();
+    /// let mut dfs = DFSIterator::new(&netlist, netlist.last().unwrap());
+    /// while let Some(n) = dfs.next() {
+    ///     if dfs.check_cycles() {
+    ///         panic!("Cycle detected in the netlist");
+    ///     }
+    ///     nodes.push(n);
+    /// }
+    /// ```
     pub struct DFSIterator<'a, I: Instantiable> {
         netlist: &'a Netlist<I>,
         stack: Vec<NetRef<I>>,
         visited: HashSet<usize>,
+        cycles: bool,
     }
 
     impl<'a, I> DFSIterator<'a, I>
@@ -1529,7 +1613,33 @@ pub mod iter {
                 netlist,
                 stack: vec![from],
                 visited: HashSet::new(),
+                cycles: false,
+            }
+        }
+    }
+
+    impl<I> DFSIterator<'_, I>
+    where
+        I: Instantiable,
+    {
+        /// Check if the DFS traversal has encountered a cycle yet.
+        pub fn check_cycles(&self) -> bool {
+            self.cycles
+        }
+
+        /// Consumes the iterator to detect cycles in the netlist.
+        pub fn detect_cycles(mut self) -> bool {
+            if self.cycles {
+                return true;
             }
+
+            while let Some(_) = self.next() {
+                if self.cycles {
+                    return true;
+                }
+            }
+
+            self.cycles
         }
     }
 
@@ -1544,6 +1654,7 @@ pub mod iter {
                 let uw = item.clone().unwrap();
                 let index = uw.borrow().get_index();
                 if !self.visited.insert(index) {
+                    self.cycles = true;
                     return self.next();
                 }
                 let operands = &uw.borrow().operands;