create netlist traversal decorator

include/hal_core/netlist/decorators/netlist_traversal_decorator.h

@@ -0,0 +1,139 @@
+// MIT License
+//
+// Copyright (c) 2019 Ruhr University Bochum, Chair for Embedded Security. All Rights reserved.
+// Copyright (c) 2019 Marc Fyrbiak, Sebastian Wallat, Max Hoffmann ("ORIGINAL AUTHORS"). All rights reserved.
+// Copyright (c) 2021 Max Planck Institute for Security and Privacy. All Rights reserved.
+// Copyright (c) 2021 Jörn Langheinrich, Julian Speith, Nils Albartus, René Walendy, Simon Klix ("ORIGINAL AUTHORS"). All Rights reserved.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+#pragma once
+
+#include "hal_core/defines.h"
+#include "hal_core/netlist/netlist.h"
+#include "hal_core/utilities/result.h"
+
+namespace hal
+{
+    /**
+     * A netlist decorator that provides functionality to traverse the associated netlist without making any modifications.
+     *
+     * @ingroup decorators
+     */
+    class NETLIST_API NetlistTraversalDecorator
+    {
+    public:
+        /**
+         * Construct new NetlistTraversalDecorator object.
+         * 
+         * @param[in] netlist - The netlist to operate on.
+         */
+        NetlistTraversalDecorator(const Netlist& netlist);
+
+        /**
+         * Starting from the given net, 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) 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.
+         * 
+         * @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] 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.
+         * @returns The next gates fulfilling the target gate filter condition.
+         */
+        Result<std::set<Gate*>> get_next_matching_gates(const Net* net,
+                                                        bool successors,
+                                                        const std::function<bool(const Gate*)>& target_gate_filter,
+                                                        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) 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) 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.
+         * 
+         * @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] 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.
+         * @returns The next gates fulfilling the target gate filter condition.
+         */
+        Result<std::set<Gate*>> get_next_matching_gates(const Gate* gate,
+                                                        bool successors,
+                                                        const std::function<bool(const Gate*)>& target_gate_filter,
+                                                        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) 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`.
+         * Continues traversal independent of whatever `target_gate_filter` evaluates to.
+         * Stop traversal if (1) the `exit_endpoint_filter` evaluates to `false` on a fan-in/out endpoint (i.e., when exiting the current gate during traversal) or (2) the `entry_endpoint_filter` evaluates to `false` on a successor/predecessor endpoint (i.e., when entering the next gate during traversal).
+         * The target_gate_filter may be omitted in which case all traversed gates will be returned.
+         * Both `entry_endpoint_filter` and the `exit_endpoint_filter` may be omitted as well.
+         * 
+         * @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] 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.
+         * @returns The next gates fulfilling the target gate filter condition.
+         */
+        Result<std::set<Gate*>> get_next_matching_gates_until(const Net* net,
+                                                              bool successors,
+                                                              const std::function<bool(const Gate*)>& target_gate_filter                                 = nullptr,
+                                                              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) 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`.
+         * Stop traversal if (1) the `exit_endpoint_filter` evaluates to `false` on a fan-in/out endpoint (i.e., when exiting the current gate during traversal) or (2) the `entry_endpoint_filter` evaluates to `false` on a successor/predecessor endpoint (i.e., when entering the next gate during traversal).
+         * The target_gate_filter may be omitted in which case all traversed gates will be returned.
+         * Both `entry_endpoint_filter` and the `exit_endpoint_filter` may be omitted as well.
+         * 
+         * @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] 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.
+         * @returns The next gates fulfilling the target gate filter condition.
+         */
+        Result<std::set<Gate*>> get_next_matching_gates_until(const Gate* gate,
+                                                              bool successors,
+                                                              const std::function<bool(const Gate*)>& target_gate_filter                                 = nullptr,
+                                                              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) const;
+
+        // TODO implement get_next_sequential_gates (get all sequential successors of the current gate by traversing other gates)
+
+        // TODO implement get_next_combinational_gates (get all combinational successor gates until sequential (non-combinational) gates are hit)
+
+        // TODO implement get_sequential_successor_map (iteratively call get_next_sequential_gates on all sequential gates and create a map)
+
+        // TODO move get_path and get_shortest_path here
+
+        // TODO move get_gate_chain and get_complex_gate_chain here
+
+    private:
+        const Netlist& m_netlist;
+    };
+}    // namespace hal

include/hal_core/python_bindings/python_bindings.h

@@ -33,8 +33,9 @@
 #include "hal_core/netlist/boolean_function/types.h"
 #include "hal_core/netlist/decorators/boolean_function_decorator.h"
 #include "hal_core/netlist/decorators/boolean_function_net_decorator.h"
-#include "hal_core/netlist/decorators/subgraph_netlist_decorator.h"
 #include "hal_core/netlist/decorators/netlist_modification_decorator.h"
+#include "hal_core/netlist/decorators/netlist_traversal_decorator.h"
+#include "hal_core/netlist/decorators/subgraph_netlist_decorator.h"
 #include "hal_core/netlist/gate.h"
 #include "hal_core/netlist/gate_library/enums/async_set_reset_behavior.h"
 #include "hal_core/netlist/gate_library/gate_library.h"
@@ -319,6 +320,13 @@ namespace hal
      */
     void netlist_modification_decorator_init(py::module& m);
 
+    /**
+     * Initializes Python bindings for the HAL netlist traversal decorator in a python module.
+     *
+     * @param[in] m - the python module
+     */
+    void netlist_traversal_decorator_init(py::module& m);
+
     /**
      * Initializes Python bindings for the HAL LogManager in a python module.
      *