HAL  v4.5.0-283-g3f42a39fa
The Hardware Analyzer - a comprehensive reverse engineering and manipulation framework for gate-level netlists.
python_bindings.cpp
Go to the documentation of this file.
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 // Copyright (c) 2025-2026 Sascha Tommasone. All rights reserved.
8 //
9 // Permission is hereby granted, free of charge, to any person obtaining a copy
10 // of this software and associated documentation files (the "Software"), to deal
11 // in the Software without restriction, including without limitation the rights
12 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13 // copies of the Software, and to permit persons to whom the Software is
14 // furnished to do so, subject to the following conditions:
15 //
16 // The above copyright notice and this permission notice shall be included in all
17 // copies or substantial portions of the Software.
18 //
19 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
25 // SOFTWARE.
26 
28 
33 #include "gui/gui_globals.h"
35 
36 #include <pybind11/detail/internals.h>
37 #include <pybind11/pytypes.h>
38 #include <set>
39 #include <string>
40 
41 namespace py = pybind11;
42 
43 namespace hal
44 {
45 
46  // the name in PYBIND11_MODULE/PYBIND11_PLUGIN *MUST* match the filename of the output library (without extension),
47  // otherwise you will get "ImportError: dynamic module does not define module export function" when importing the
48  // module
49 
50 #ifdef PYBIND11_MODULE
51  PYBIND11_MODULE( clock_tree_viewer, m )
52  {
53  m.doc() = "A plugin to interactively view clock trees extracted by the clock_tree_extractor plugin.";
54 #else
55  PYBIND11_PLUGIN( clock_tree_viewer )
56  {
57  py::module m( "clock_tree_viewer",
58  "A plugin to interactively view clock trees extracted by the clock_tree_extractor plugin." );
59 #endif // ifdef PYBIND11_MODULE
60 
61  py::class_<ClockTreeViewerPlugin, RawPtrWrapper<ClockTreeViewerPlugin>, BasePluginInterface>
62  py_clock_tree_viewer_plugin(
63  m,
64  "ClockTreeViewerPlugin",
65  R"(This class provides an interface to integrate the clock tree viewer as a plugin within the HAL framework.)" );
66 
67  py_clock_tree_viewer_plugin.def_property_readonly( "name", &ClockTreeViewerPlugin::get_name, R"(
68  The name of the plugin.
69 
70  :type: str
71  )" );
72 
73  py_clock_tree_viewer_plugin.def( "get_name", &ClockTreeViewerPlugin::get_name, R"(
74  Get the name of the plugin.
75 
76  :returns: The name of the plugin.
77  :rtype: str
78  )" );
79 
80  py_clock_tree_viewer_plugin.def_property_readonly( "version", &ClockTreeViewerPlugin::get_version, R"(
81  The version of the plugin.
82 
83  :type: str
84  )" );
85 
86  py_clock_tree_viewer_plugin.def( "get_version", &ClockTreeViewerPlugin::get_version, R"(
87  Get the version of the plugin.
88 
89  :returns: The version of the plugin.
90  :rtype: str
91  )" );
92 
93  py_clock_tree_viewer_plugin.def_property_readonly( "description", &ClockTreeViewerPlugin::get_description, R"(
94  The description of the plugin.
95 
96  :type: str
97  )" );
98 
99  py_clock_tree_viewer_plugin.def( "get_description", &ClockTreeViewerPlugin::get_description, R"(
100  Get the description of the plugin.
101 
102  :returns: The description of the plugin.
103  :rtype: str
104  )" );
105 
106  py_clock_tree_viewer_plugin.def_property_readonly( "dependencies", &ClockTreeViewerPlugin::get_dependencies, R"(
107  A set of plugin names that this plugin depends on.
108 
109  :type: set[str]
110  )" );
111 
112  py_clock_tree_viewer_plugin.def( "get_dependencies", &ClockTreeViewerPlugin::get_dependencies, R"(
113  Get a set of plugin names that this plugin depends on.
114 
115  :returns: A set of plugin names that this plugin depends on.
116  :rtype: set[str]
117  )" );
118 
119  m.def(
120  "show_clock_tree",
121  []( const cte::ClockTree &clock_tree,
122  const std::optional<double> node_radius,
123  const std::optional<double> edge_width,
124  const std::optional<double> picture_margin,
125  const std::optional<double> pixels_per_unit,
126  const std::optional<std::string> &x_key,
127  const std::optional<std::string> &y_key ) -> bool {
128  // The viewer hands the work to the GUI thread and waits for it, which must not hold up a GUI thread that
129  // waits for the interpreter.
130  py::gil_scoped_release release;
131 
133  clock_tree,
134  ctv::StyleOverrides{ node_radius, edge_width, picture_margin, pixels_per_unit },
135  x_key,
136  y_key );
137  },
138  py::arg( "clock_tree" ),
139  py::arg( "node_radius" ) = py::none(),
140  py::arg( "edge_width" ) = py::none(),
141  py::arg( "picture_margin" ) = py::none(),
142  py::arg( "pixels_per_unit" ) = py::none(),
143  py::arg( "x_key" ) = ctv::DEFAULT_X_KEY,
144  py::arg( "y_key" ) = ctv::DEFAULT_Y_KEY,
145  R"(
146  Plot a clock tree in the clock tree viewer of the GUI.
147 
148  The coordinates of the gates are read from the gate parameters ``X`` and ``Y``, e.g., from Verilog instance parameters, unless the keys of other parameters are given. Pass ``None`` for both keys to draw the gates at their location in the layout instead. If no gate has coordinates, nothing is drawn and an error is shown. If only some gates have none, those are left out of the plot and a warning is shown. A clock tree of another netlist than the one that is open in the GUI is not drawn either, since its gates cannot be matched to the gates in HAL.
149 
150  The sizes and coordinate keys are kept: extracting a clock tree with the button in the toolbar of the viewer uses them again.
151 
152  The plot is in the colors of HAL's graph view. The background and the connections follow the theme. A gate has the color of the module it belongs to, the color of its grouping if it is in one, or the orange of a selected item if it is selected, and the plot follows all of them when they change.
153 
154  The sizes of the drawing follow from the coordinates, from the length of a typical connection in the clock tree. Provide any of them to choose it yourself. All lengths are in the unit of the coordinates.
155 
156  :param clock_tree_extractor.ClockTree clock_tree: The clock tree to plot.
157  :param float node_radius: The radius of the dot that represents a gate. Defaults to ``None``, which derives it from the coordinates.
158  :param float edge_width: The width of the lines that represent connections. Defaults to ``None``, which derives it from the coordinates.
159  :param float picture_margin: The empty border around the tree in a saved picture. Defaults to ``None``, which derives it from the coordinates.
160  :param float pixels_per_unit: The resolution of a saved picture. Defaults to ``None``, which derives it from the coordinates and lowers it for a large tree, so that a picture stays within 10000 pixels per side. A resolution given here is kept, and a picture that would exceed the limit is not saved.
161  :param str x_key: The name of the parameter that holds the x-coordinate, ``None`` to use the location. Defaults to ``"X"``.
162  :param str y_key: The name of the parameter that holds the y-coordinate, ``None`` to use the location. Defaults to ``"Y"``.
163  :returns: ``True`` if the clock tree is plotted, ``False`` otherwise.
164  :rtype: bool
165  )" );
166 
167  m.def(
168  "highlight_gates",
169  []( const std::vector<Gate *> &gates ) -> std::size_t {
170  // The gates are read here, with the interpreter locked: only their IDs are handed to the viewer.
171  std::vector<u32> gate_ids;
172  gate_ids.reserve( gates.size() );
173  for( const Gate *gate : gates )
174  {
175  if( gate == nullptr )
176  {
177  continue;
178  }
179 
180  // The ID of a gate of another netlist says nothing about the netlist that is open.
181  if( gNetlist != nullptr && gate->get_netlist() != gNetlist )
182  {
183  log_warning( "clock_tree_viewer",
184  "Gate with ID {} is not part of the netlist that is open, ignored.",
185  gate->get_id() );
186  continue;
187  }
188 
189  gate_ids.push_back( gate->get_id() );
190  }
191 
192  // The viewer hands the work to the GUI thread and waits for it, see show_clock_tree.
193  py::gil_scoped_release release;
194 
195  return ClockTreeViewer::highlightGates( gate_ids );
196  },
197  py::arg( "gates" ),
198  R"(
199  Highlight gates in the clock tree viewer of the GUI, instead of the ones that were highlighted before.
200 
201  A highlighted gate has the color of a selected item and a ring around it that is the same size on the screen at every zoom, so it can be found in a plot of the whole chip. Only gates that are plotted can be highlighted. Gates that are not part of the clock tree are ignored, and so are those of the clock tree that have no coordinates and are therefore not plotted. Nothing is selected in HAL by this.
202 
203  The gates that are selected in HAL are highlighted without any call to this function, e.g., after ``gui.select(gates)`` in the Python console of the GUI. The last of the two, a selection in HAL and a call to this function, decides which gates are highlighted.
204 
205  :param list[hal_py.Gate] gates: The gates to highlight. An empty list removes the highlight.
206  :returns: The number of gates that are highlighted, i.e., those of ``gates`` that are plotted. ``0`` if there is no clock tree viewer or no clock tree is plotted.
207  :rtype: int
208  )" );
209 
210 #ifndef PYBIND11_MODULE
211  return m.ptr();
212 #endif // PYBIND11_MODULE
213  }
214 } // namespace hal
static std::size_t highlightGates(const std::vector< u32 > &gateIds)
static bool setClockTree(const cte::ClockTree &tree, const ctv::StyleOverrides &overrides=ctv::StyleOverrides(), const std::optional< std::string > &x_key=ctv::DEFAULT_X_KEY, const std::optional< std::string > &y_key=ctv::DEFAULT_Y_KEY)
std::string get_name() const override
std::string get_description() const override
std::string get_version() const override
std::set< std::string > get_dependencies() const override
Definition: gate.h:59
#define log_warning(channel,...)
Definition: log.h:76
const Module * module(const Gate *g, const NodeBoxes &boxes)
const std::string DEFAULT_Y_KEY
const std::string DEFAULT_X_KEY
Definition: defines.h:45
PYBIND11_PLUGIN(hal_py)
Netlist * gNetlist
Definition: gui_globals.h:69