Feature/hawkeye (#569)

* made is_X_in_netlist accept const pointers * create netlist traversal decorator * added RST file for pydoc * added new doxy group for decorators * added get_next_sequential_gates (untested) * fixed pybinds for get_next_sequential_gates * made forbidden_pins mandatory * fixed inf loop when using caching * added function to compute map from all sequential gates to their respective sequential successors * get next gates up to max depth * deprecated some netlist utils functions * function to get next combinational gates until other gates hit * API changes; let user specify whether to stop on a match/mismatch * fixed missing exit pin check * started writing some tests (yay) * added forbidden pins for combinational logic and fixed caching bugs * testing get_next_sequential_gates_map and get_next_combinational_gates * added get_next_matching_gates tests * added get_next_matching_gates_until_depth tests * get_next_matching_gates_until tests * initial HAWKEYE commit * added S-box database * started updating candidate search * removed cached versions * added caching to get_next_matching_gates * bindings for detection config * bindings for candidate * changed getter API * re-implemented candidate search * updated gate lib * added new GateTypeProperties and PinTypes * fixed igraph dependency * some fixes in unisim library * made GateType hashable in Python * removed cache due to the headache it caused (and surprisingly the slowdown) * more minor fixes * removed cache from tests * added optional filter to Net::get_num_of_X * allow creation of a graph with no edges and only a subset of the gates in the netlist * get gates from vertices as set * added deep copy function * fixed naming * improved candidate search * SCC-based candidate detection * isolate state logic * changed architecture * added function to unify FF outputs * gather remaining inputs and create netlist graph * added example script for testing * untested s-box identification * Update README.md * added Gauss elimination top remove linear dependent outputs * made get_graph const * added versions accepting sets * sbox detection (wip, not tested) * almost completed sbox extraction * some renaming, documentation and PyBinds * fixed segfault on copied graph * fixed filling candidate inputs and outputs * fixed missing pybind * fixed wrong nets in state inputs and outputs * fixed missing state logic gates * smallset_t implementation based on regular not-hardware-specific code added * fixed set intersection not working with std::vector * fixed missing one step during sbox search * fixed mapping gates through graph rather than subgraph * fixed wrong check on number of control signals * cleanup + some logging * fixed empty truth table * speedup (need to test on all circuits) * cleaned up logs * minor fixes * disregard output gates that only depend on other output gates * fix creating way too many sbox candidates * fix functional sbox analysis * added SBoxCandidate constructor * fixed whitespaces * fixing CI * trying to make CI compile again * disable hawkeye by default * continue bruteforce on macos CI --------- Co-authored-by: joern274 <[email protected]>
emsec · May 30, 2024 · 8f6c18d · 8f6c18d
1 parent 9f835fa
commit 8f6c18d
Show file tree

Hide file tree

Showing 44 changed files with 11,647 additions and 6,875 deletions.
diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 # Welcome to HAL! 
-[![Ubuntu 20.04](https://github.com/emsec/hal/actions/workflows/ubuntu20.04.yml/badge.svg)](https://github.com/emsec/hal/actions/workflows/ubuntu20.04.yml)  [![Ubuntu 22.04](https://github.com/emsec/hal/actions/workflows/ubuntu22.04.yml/badge.svg)](https://github.com/emsec/hal/actions/workflows/ubuntu22.04.yml)  [![macOS](https://github.com/emsec/hal/actions/workflows/macOS.yml/badge.svg)](https://github.com/emsec/hal/actions/workflows/macOS.yml) [![Deploy Documentation](https://github.com/emsec/hal/actions/workflows/releaseDoc.yml/badge.svg)](https://github.com/emsec/hal/actions/workflows/releaseDoc.yml) [![Doc: C++](https://img.shields.io/badge/doc-c%2B%2B-orange)](https://emsec.github.io/hal/doc/) [![Doc: Python](https://img.shields.io/badge/doc-python-red)](https://emsec.github.io/hal/pydoc/)
+[![Ubuntu 22.04](https://github.com/emsec/hal/actions/workflows/ubuntu22.04.yml/badge.svg)](https://github.com/emsec/hal/actions/workflows/ubuntu22.04.yml)  [![Ubuntu 24.04](https://github.com/emsec/hal/actions/workflows/ubuntu24.04.yml/badge.svg)](https://github.com/emsec/hal/actions/workflows/ubuntu24.04.yml)  [![macOS](https://github.com/emsec/hal/actions/workflows/macOS.yml/badge.svg)](https://github.com/emsec/hal/actions/workflows/macOS.yml) [![Deploy Documentation](https://github.com/emsec/hal/actions/workflows/releaseDoc.yml/badge.svg)](https://github.com/emsec/hal/actions/workflows/releaseDoc.yml) [![Doc: C++](https://img.shields.io/badge/doc-c%2B%2B-orange)](https://emsec.github.io/hal/doc/) [![Doc: Python](https://img.shields.io/badge/doc-python-red)](https://emsec.github.io/hal/pydoc/)
 
 
 HAL \[/hel/\] is a comprehensive netlist reverse engineering and manipulation framework.

diff --git a/include/hal_core/netlist/decorators/netlist_traversal_decorator.h b/include/hal_core/netlist/decorators/netlist_traversal_decorator.h
@@ -51,49 +51,42 @@ namespace hal
          * Traverse over gates that do not meet the `target_gate_filter` condition.
          * Stop traversal if (1) `continue_on_match` is `false` the `target_gate_filter` evaluates to `true`, (2) the `exit_endpoint_filter` evaluates to `false` on a fan-in/out endpoint (i.e., when exiting the current gate during traversal), or (3) the `entry_endpoint_filter` evaluates to `false` on a successor/predecessor endpoint (i.e., when entering the next gate during traversal).
          * Both the `entry_endpoint_filter` and the `exit_endpoint_filter` may be omitted.
-         * Provide a cache to speed up traversal when calling this function multiple times on the same netlist using the same forbidden pins.
-         * Do not use a cache if the filter functions operate on the `current_depth`.
          * 
          * @param[in] net - Start net.
          * @param[in] successors - Set `true` to get successors, set `false` to get predecessors.
          * @param[in] target_gate_filter - Filter condition that must be met for the target gates.
          * @param[in] continue_on_match - Set `true` to continue even if `target_gate_filter` evaluated to `true`, `false` otherwise. Defaults to `false`.
          * @param[in] exit_endpoint_filter - Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
          * @param[in] entry_endpoint_filter - Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.
-         * @param[inout] cache - An optional cache that can be used for better performance on repeated calls. Defaults to a `nullptr`.
          * @returns The next gates fulfilling the target gate filter condition on success, an error otherwise.
          */
         Result<std::set<Gate*>> get_next_matching_gates(const Net* net,
                                                         bool successors,
                                                         const std::function<bool(const Gate*)>& target_gate_filter,
                                                         bool continue_on_match                                                                     = false,
                                                         const std::function<bool(const Endpoint*, const u32 current_depth)>& exit_endpoint_filter  = nullptr,
-                                                        const std::function<bool(const Endpoint*, const u32 current_depth)>& entry_endpoint_filter = nullptr,
-                                                        std::unordered_map<const Net*, std::set<Gate*>>* cache                                     = nullptr) const;
+                                                        const std::function<bool(const Endpoint*, const u32 current_depth)>& entry_endpoint_filter = nullptr) const;
 
         /**
          * Starting from the given gate, traverse the netlist and return only the successor/predecessor gates for which the `target_gate_filter` evaluates to `true`.
          * Traverse over gates that do not meet the `target_gate_filter` condition.
          * Stop traversal if (1) `continue_on_match` is `false` the `target_gate_filter` evaluates to `true`, (2) the `exit_endpoint_filter` evaluates to `false` on a fan-in/out endpoint (i.e., when exiting the current gate during traversal), or (3) the `entry_endpoint_filter` evaluates to `false` on a successor/predecessor endpoint (i.e., when entering the next gate during traversal).
          * Both the `entry_endpoint_filter` and the `exit_endpoint_filter` may be omitted.
-         * Do not use a cache if the filter functions operate on the `current_depth`.
          * 
          * @param[in] gate - Start gate.
          * @param[in] successors - Set `true` to get successors, set `false` to get predecessors.
          * @param[in] target_gate_filter - Filter condition that must be met for the target gates.
          * @param[in] continue_on_match - Set `true` to continue even if `target_gate_filter` evaluated to `true`, `false` otherwise. Defaults to `false`.
          * @param[in] exit_endpoint_filter - Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
          * @param[in] entry_endpoint_filter - Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.
-         * @param[inout] cache - An optional cache that can be used for better performance on repeated calls. Defaults to a `nullptr`.
          * @returns The next gates fulfilling the target gate filter condition on success, an error otherwise.
          */
         Result<std::set<Gate*>> get_next_matching_gates(const Gate* gate,
                                                         bool successors,
                                                         const std::function<bool(const Gate*)>& target_gate_filter,
                                                         bool continue_on_match                                                                     = false,
                                                         const std::function<bool(const Endpoint*, const u32 current_depth)>& exit_endpoint_filter  = nullptr,
-                                                        const std::function<bool(const Endpoint*, const u32 current_depth)>& entry_endpoint_filter = nullptr,
-                                                        std::unordered_map<const Net*, std::set<Gate*>>* cache                                     = nullptr) const;
+                                                        const std::function<bool(const Endpoint*, const u32 current_depth)>& entry_endpoint_filter = nullptr) const;
 
         /**
          * Starting from the given net, traverse the netlist and return only the successor/predecessor gates for which the `target_gate_filter` evaluates to `true`.

diff --git a/include/hal_core/netlist/gate_library/enums/gate_type_property.h b/include/hal_core/netlist/gate_library/enums/gate_type_property.h
@@ -32,34 +32,36 @@ namespace hal
      */
     enum class GateTypeProperty
     {
-        combinational, /**< Combinational gate type. **/
-        sequential,    /**< Sequential gate type. **/
-        tristate,      /**< Tristate gate type. **/
-        power,         /**< Power gate type. **/
-        ground,        /**< Ground gate type. **/
-        ff,            /**< Flip-flop gate type. **/
-        latch,         /**< Latch gate type. **/
-        ram,           /**< RAM gate type. **/
-        io,            /**< IO gate type. **/
-        dsp,           /**< DSP gate type. **/
-        pll,           /**< PLL gate type. **/
-        oscillator,    /**< Oscillator gate type. **/
-        scan,          /**< Scan gate type. **/
-        c_buffer,      /**< Buffer gate type. **/
-        c_inverter,    /**< Inverter gate type. **/
-        c_and,         /**< AND gate type. **/
-        c_nand,        /**< NAND gate type. **/
-        c_or,          /**< OR gate type. **/
-        c_nor,         /**< NOR gate type. **/
-        c_xor,         /**< XOR gate type. **/
-        c_xnor,        /**< XNOR gate type. **/
-        c_aoi,         /**< AOI gate type. **/
-        c_oai,         /**< OAI gate type. **/
-        c_mux,         /**< MUX gate type. **/
-        c_carry,       /**< Carry gate type. **/
-        c_half_adder,  /**< Half adder gate type. **/
-        c_full_adder,  /**< Full adder gate type. **/
-        c_lut          /**< LUT gate type. **/
+        combinational,  /**< Combinational gate type. **/
+        sequential,     /**< Sequential gate type. **/
+        tristate,       /**< Tristate gate type. **/
+        power,          /**< Power gate type. **/
+        ground,         /**< Ground gate type. **/
+        ff,             /**< Flip-flop gate type. **/
+        latch,          /**< Latch gate type. **/
+        ram,            /**< RAM gate type. **/
+        fifo,           /**< FIFO gate type. **/
+        shift_register, /**< Shift register gate type. **/
+        io,             /**< IO gate type. **/
+        dsp,            /**< DSP gate type. **/
+        pll,            /**< PLL gate type. **/
+        oscillator,     /**< Oscillator gate type. **/
+        scan,           /**< Scan gate type. **/
+        c_buffer,       /**< Buffer gate type. **/
+        c_inverter,     /**< Inverter gate type. **/
+        c_and,          /**< AND gate type. **/
+        c_nand,         /**< NAND gate type. **/
+        c_or,           /**< OR gate type. **/
+        c_nor,          /**< NOR gate type. **/
+        c_xor,          /**< XOR gate type. **/
+        c_xnor,         /**< XNOR gate type. **/
+        c_aoi,          /**< AOI gate type. **/
+        c_oai,          /**< OAI gate type. **/
+        c_mux,          /**< MUX gate type. **/
+        c_carry,        /**< Carry gate type. **/
+        c_half_adder,   /**< Half adder gate type. **/
+        c_full_adder,   /**< Full adder gate type. **/
+        c_lut           /**< LUT gate type. **/
     };
 
     template<>

diff --git a/include/hal_core/netlist/gate_library/enums/pin_type.h b/include/hal_core/netlist/gate_library/enums/pin_type.h
@@ -34,22 +34,27 @@ namespace hal
      */
     enum class PinType
     {
-        none,      /**< Default pin. **/
-        power,     /**< Power pin. **/
-        ground,    /**< Ground pin. **/
-        lut,       /**< Pin that generates output from LUT initialization string. **/
-        state,     /**< Pin that generates output from internal state. **/
-        neg_state, /**< Pin that generates output from negated internal state. **/
-        clock,     /**< Clock pin. **/
-        enable,    /**< Enable pin. **/
-        set,       /**< Set/preset pin. **/
-        reset,     /**< Reset/clear pin. **/
-        data,      /**< Data pin. **/
-        address,   /**< Address pin. **/
-        io_pad,    /**< IO pad pin. **/
-        select,    /**< Select pin. **/
-        carry,     /**< Carry pin. **/
-        sum        /**< Sum pin. **/
+        none,            /**< Default pin. **/
+        power,           /**< Power pin. **/
+        ground,          /**< Ground pin. **/
+        lut,             /**< Pin that generates output from LUT initialization string. **/
+        state,           /**< Pin that generates output from internal state. **/
+        neg_state,       /**< Pin that generates output from negated internal state. **/
+        clock,           /**< Clock pin. **/
+        enable,          /**< Enable pin. **/
+        set,             /**< Set/preset pin. **/
+        reset,           /**< Reset/clear pin. **/
+        data,            /**< Data pin. **/
+        address,         /**< Address pin. **/
+        io_pad,          /**< IO pad pin. **/
+        select,          /**< Select pin. **/
+        carry,           /**< Carry pin. **/
+        sum,             /**< Sum pin. **/
+        status,          /**< Status pin.*/
+        error,           /**< Error pin.*/
+        error_detection, /**< Error detection pin.*/
+        done,            /**< Done pin.*/
+        control          /**< Control pin.*/
     };
 
     template<>

diff --git a/include/hal_core/netlist/gate_library/gate_type.h b/include/hal_core/netlist/gate_library/gate_type.h
@@ -50,6 +50,13 @@ namespace hal
     class NETLIST_API GateType
     {
     public:
+        /**
+         * Hash function for python binding.
+         *
+         * @return Pybind11 compatible hash.
+         */
+        ssize_t get_hash() const;
+
         /**
          * Get all components matching the filter condition (if provided) as a vector. 
          * Returns an empty vector if (i) the gate type does not contain any components or (ii) no component matches the filter condition.

diff --git a/include/hal_core/netlist/net.h b/include/hal_core/netlist/net.h
@@ -210,10 +210,12 @@ namespace hal
 
         /**
          * Get the number of sources of the net.
+         * The optional filter is evaluated on every candidate such that the result only contains those matching the specified condition.
          *
+         * @param[in] filter - An optional filter.
          * @returns The number of sources.
          */
-        u32 get_num_of_sources() const;
+        u32 get_num_of_sources(const std::function<bool(Endpoint* ep)>& filter = nullptr) const;
 
         /**
          * Get a vector of sources of the net.
@@ -318,10 +320,12 @@ namespace hal
 
         /**
          * Get the number of destinations of the net.
+         * The optional filter is evaluated on every candidate such that the result only contains those matching the specified condition.
          *
+         * @param[in] filter - An optional filter.
          * @returns The number of destinations.
          */
-        u32 get_num_of_destinations() const;
+        u32 get_num_of_destinations(const std::function<bool(Endpoint* ep)>& filter = nullptr) const;
 
         /**
          * Get a vector of destinations of the net.

diff --git a/plugins/.gitignore b/plugins/.gitignore
@@ -15,14 +15,16 @@
 !gui/**/*
 !gui_extension_demo*
 !gui_extension_demo/**/*
-!liberty_parser*
-!liberty_parser/**/*
-!netlist_preprocessing*
-!netlist_preprocessing/**/*
+!hawkeye*
+!hawkeye/**/*
 !hgl_parser*
 !hgl_parser/**/*
 !hgl_writer*
 !hgl_writer/**/*
+!liberty_parser*
+!liberty_parser/**/*
+!netlist_preprocessing*
+!netlist_preprocessing/**/*
 !python_shell*
 !python_shell/**/*
 !simulator