Skip to content

Commit 8736b9f

Browse files
SJulianSSJulianS
committed
create netlist traversal decorator
1 parent 2018d81 commit 8736b9f

File tree

5 files changed

+560
-1
lines changed

5 files changed

+560
-1
lines changed

‎include/hal_core/netlist/decorators/netlist_traversal_decorator.h

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
// MIT License
2+
//
3+
// Copyright (c) 2019 Ruhr University Bochum, Chair for Embedded Security. All Rights reserved.
4+
// Copyright (c) 2019 Marc Fyrbiak, Sebastian Wallat, Max Hoffmann ("ORIGINAL AUTHORS"). All rights reserved.
5+
// Copyright (c) 2021 Max Planck Institute for Security and Privacy. All Rights reserved.
6+
// Copyright (c) 2021 Jörn Langheinrich, Julian Speith, Nils Albartus, René Walendy, Simon Klix ("ORIGINAL AUTHORS"). All Rights reserved.
7+
//
8+
// Permission is hereby granted, free of charge, to any person obtaining a copy
9+
// of this software and associated documentation files (the "Software"), to deal
10+
// in the Software without restriction, including without limitation the rights
11+
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12+
// copies of the Software, and to permit persons to whom the Software is
13+
// furnished to do so, subject to the following conditions:
14+
//
15+
// The above copyright notice and this permission notice shall be included in all
16+
// copies or substantial portions of the Software.
17+
//
18+
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19+
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20+
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21+
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22+
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23+
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24+
// SOFTWARE.
25+
26+
#pragma once
27+
28+
#include "hal_core/defines.h"
29+
#include "hal_core/netlist/netlist.h"
30+
#include "hal_core/utilities/result.h"
31+
32+
namespace hal
33+
{
34+
/**
35+
* A netlist decorator that provides functionality to traverse the associated netlist without making any modifications.
36+
*
37+
* @ingroup decorators
38+
*/
39+
class NETLIST_API NetlistTraversalDecorator
40+
{
41+
public:
42+
/**
43+
* Construct new NetlistTraversalDecorator object.
44+
*
45+
* @param[in] netlist - The netlist to operate on.
46+
*/
47+
NetlistTraversalDecorator(const Netlist& netlist);
48+
49+
/**
50+
* Starting from the given net, traverse the netlist and return only the successor/predecessor gates for which the `target_gate_filter` evaluates to `true`.
51+
* Traverse over gates that do not meet the `target_gate_filter` condition.
52+
* 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).
53+
* Both the `entry_endpoint_filter` and the `exit_endpoint_filter` may be omitted.
54+
*
55+
* @param[in] net - Start net.
56+
* @param[in] successors - Set `true` to get successors, set `false` to get predecessors.
57+
* @param[in] target_gate_filter - Filter condition that must be met for the target gates.
58+
* @param[in] exit_endpoint_filter - Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
59+
* @param[in] entry_endpoint_filter - Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.
60+
* @returns The next gates fulfilling the target gate filter condition.
61+
*/
62+
Result<std::set<Gate*>> get_next_matching_gates(const Net* net,
63+
bool successors,
64+
const std::function<bool(const Gate*)>& target_gate_filter,
65+
const std::function<bool(const Endpoint*, const u32 current_depth)>& exit_endpoint_filter = nullptr,
66+
const std::function<bool(const Endpoint*, const u32 current_depth)>& entry_endpoint_filter = nullptr) const;
67+
68+
/**
69+
* Starting from the given gate, traverse the netlist and return only the successor/predecessor gates for which the `target_gate_filter` evaluates to `true`.
70+
* Traverse over gates that do not meet the `target_gate_filter` condition.
71+
* 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).
72+
* Both the `entry_endpoint_filter` and the `exit_endpoint_filter` may be omitted.
73+
*
74+
* @param[in] gate - Start gate.
75+
* @param[in] successors - Set `true` to get successors, set `false` to get predecessors.
76+
* @param[in] target_gate_filter - Filter condition that must be met for the target gates.
77+
* @param[in] exit_endpoint_filter - Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
78+
* @param[in] entry_endpoint_filter - Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.
79+
* @returns The next gates fulfilling the target gate filter condition.
80+
*/
81+
Result<std::set<Gate*>> get_next_matching_gates(const Gate* gate,
82+
bool successors,
83+
const std::function<bool(const Gate*)>& target_gate_filter,
84+
const std::function<bool(const Endpoint*, const u32 current_depth)>& exit_endpoint_filter = nullptr,
85+
const std::function<bool(const Endpoint*, const u32 current_depth)>& entry_endpoint_filter = nullptr) const;
86+
87+
/**
88+
* Starting from the given net, traverse the netlist and return only the successor/predecessor gates for which the `target_gate_filter` evaluates to `true`.
89+
* Continues traversal independent of whatever `target_gate_filter` evaluates to.
90+
* 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).
91+
* The target_gate_filter may be omitted in which case all traversed gates will be returned.
92+
* Both `entry_endpoint_filter` and the `exit_endpoint_filter` may be omitted as well.
93+
*
94+
* @param[in] net - Start net.
95+
* @param[in] successors - Set `true` to get successors, set `false` to get predecessors.
96+
* @param[in] target_gate_filter - Filter condition that must be met for the target gates.
97+
* @param[in] exit_endpoint_filter - Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
98+
* @param[in] entry_endpoint_filter - Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.
99+
* @returns The next gates fulfilling the target gate filter condition.
100+
*/
101+
Result<std::set<Gate*>> get_next_matching_gates_until(const Net* net,
102+
bool successors,
103+
const std::function<bool(const Gate*)>& target_gate_filter = nullptr,
104+
const std::function<bool(const Endpoint*, const u32 current_depth)>& exit_endpoint_filter = nullptr,
105+
const std::function<bool(const Endpoint*, const u32 current_depth)>& entry_endpoint_filter = nullptr) const;
106+
107+
/**
108+
* Starting from the given gate, traverse the netlist and return only the successor/predecessor gates for which the `target_gate_filter` evaluates to `true`.
109+
* 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).
110+
* The target_gate_filter may be omitted in which case all traversed gates will be returned.
111+
* Both `entry_endpoint_filter` and the `exit_endpoint_filter` may be omitted as well.
112+
*
113+
* @param[in] gate - Start gate.
114+
* @param[in] successors - Set `true` to get successors, set `false` to get predecessors.
115+
* @param[in] target_gate_filter - Filter condition that must be met for the target gates.
116+
* @param[in] exit_endpoint_filter - Filter condition that determines whether to stop traversal on a fan-in/out endpoint.
117+
* @param[in] entry_endpoint_filter - Filter condition that determines whether to stop traversal on a successor/predecessor endpoint.
118+
* @returns The next gates fulfilling the target gate filter condition.
119+
*/
120+
Result<std::set<Gate*>> get_next_matching_gates_until(const Gate* gate,
121+
bool successors,
122+
const std::function<bool(const Gate*)>& target_gate_filter = nullptr,
123+
const std::function<bool(const Endpoint*, const u32 current_depth)>& exit_endpoint_filter = nullptr,
124+
const std::function<bool(const Endpoint*, const u32 current_depth)>& entry_endpoint_filter = nullptr) const;
125+
126+
// TODO implement get_next_sequential_gates (get all sequential successors of the current gate by traversing other gates)
127+
128+
// TODO implement get_next_combinational_gates (get all combinational successor gates until sequential (non-combinational) gates are hit)
129+
130+
// TODO implement get_sequential_successor_map (iteratively call get_next_sequential_gates on all sequential gates and create a map)
131+
132+
// TODO move get_path and get_shortest_path here
133+
134+
// TODO move get_gate_chain and get_complex_gate_chain here
135+
136+
private:
137+
const Netlist& m_netlist;
138+
};
139+
} // namespace hal

‎include/hal_core/python_bindings/python_bindings.h

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,9 @@
3333
#include "hal_core/netlist/boolean_function/types.h"
3434
#include "hal_core/netlist/decorators/boolean_function_decorator.h"
3535
#include "hal_core/netlist/decorators/boolean_function_net_decorator.h"
36-
#include "hal_core/netlist/decorators/subgraph_netlist_decorator.h"
3736
#include "hal_core/netlist/decorators/netlist_modification_decorator.h"
37+
#include "hal_core/netlist/decorators/netlist_traversal_decorator.h"
38+
#include "hal_core/netlist/decorators/subgraph_netlist_decorator.h"
3839
#include "hal_core/netlist/gate.h"
3940
#include "hal_core/netlist/gate_library/enums/async_set_reset_behavior.h"
4041
#include "hal_core/netlist/gate_library/gate_library.h"
@@ -319,6 +320,13 @@ namespace hal
319320
*/
320321
void netlist_modification_decorator_init(py::module& m);
321322

323+
/**
324+
* Initializes Python bindings for the HAL netlist traversal decorator in a python module.
325+
*
326+
* @param[in] m - the python module
327+
*/
328+
void netlist_traversal_decorator_init(py::module& m);
329+
322330
/**
323331
* Initializes Python bindings for the HAL LogManager in a python module.
324332
*

0 commit comments

Comments
 (0)