HAL  v4.5.0-259-g577210b12
The Hardware Analyzer - a comprehensive reverse engineering and manipulation framework for gate-level netlists.
dot_export.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 
31 #include "hal_core/defines.h"
32 #include "hal_core/netlist/gate.h"
34 #include "hal_core/netlist/net.h"
35 #include "hal_core/utilities/log.h"
36 
37 #include <charconv>
38 #include <fstream>
39 #include <igraph/igraph.h>
40 #include <utility>
41 #include <vector>
42 
43 namespace hal::cte
44 {
45  namespace
46  {
47  const char *shape_of( const Gate *gate )
48  {
49  if( is_ff( gate ) )
50  {
51  return "box";
52  }
53  if( is_buffer( gate ) || is_inverter( gate ) || is_delay( gate ) )
54  {
55  // points in the direction of the signal, since the graph is laid out from top to bottom
56  return "invtriangle";
57  }
58  if( is_mux( gate ) )
59  {
60  return "diamond";
61  }
62  if( is_oscillator( gate ) || is_pll( gate ) )
63  {
64  return "cylinder";
65  }
66  return "hexagon";
67  }
68 
69  // quotes text as a DOT ID, e.g., names like a[3] or escaped Verilog identifiers
70  std::string quoted( const std::string &text )
71  {
72  std::string result = "\"";
73  for( const char character : text )
74  {
75  if( character == '"' || character == '\\' )
76  {
77  result += '\\';
78  }
79  result += character;
80  }
81  return result + "\"";
82  }
83 
84  // the shortest text that reads back as the same number, e.g., 100 or 12.5, independent of the locale
85  std::string number( const double value )
86  {
87  char text[32];
88  const auto [end, error] = std::to_chars( text, text + sizeof( text ), value );
89  return { text, end };
90  }
91  } // namespace
92 
94  const std::string &pathname,
95  const std::optional<std::string> &x_key,
96  const std::optional<std::string> &y_key )
97  {
98  if( x_key.has_value() != y_key.has_value() )
99  {
100  return ERR( "couldn't export clock tree to '" + pathname + "': give both coordinate keys or none" );
101  }
102 
103  std::ofstream dot_file( pathname );
104  if( !dot_file )
105  {
106  return ERR( "couldn't export clock tree to '" + pathname + "'" );
107  }
108 
109  dot_file << "digraph {\n"
110  << " comment=\"created by HAL plugin clock_tree_extractor\"\n"
111  << " node [color=black fontcolor=black]\n"
112  << " edge [color=black]\n";
113 
114  const igraph_t *graph = clock_tree.get_igraph();
115  const igraph_int_t vertex_count = igraph_vcount( graph );
116 
117  // the node ID of every vertex, reused for the edges
118  std::vector<std::string> node_ids( vertex_count );
119  u32 gates_without_coordinates = 0;
120 
121  for( igraph_int_t vertex = 0; vertex < vertex_count; vertex++ )
122  {
123  const auto object = clock_tree.get_ptr_from_vertex( vertex );
124  if( object.is_error() )
125  {
126  return ERR_APPEND( object.get_error(), "couldn't export clock tree to '" + pathname + "'" );
127  }
128  const auto [ptr, type] = object.get();
129 
130  if( type == NET )
131  {
132  // prefixed, since a numeric net name would otherwise merge with the gate of that ID
133  const Net *net = static_cast<const Net *>( ptr );
134  node_ids[vertex] = "net_" + std::to_string( net->get_id() );
135  dot_file << " " << node_ids[vertex] << " [label=" << quoted( net->get_name() ) << " shape=circle];\n";
136  continue;
137  }
138 
139  const Gate *gate = static_cast<const Gate *>( ptr );
140  node_ids[vertex] = std::to_string( gate->get_id() );
141  dot_file << " " << node_ids[vertex] << " [instance=" << quoted( gate->get_name() )
142  << " type=" << quoted( gate->get_type()->get_name() ) << " shape=" << shape_of( gate );
143 
144  // buffers, inverters and delays share the triangle, so the label tells them apart
145  if( is_inverter( gate ) )
146  {
147  dot_file << " label=\"¬ " << node_ids[vertex] << "\"";
148  }
149  else if( is_delay( gate ) )
150  {
151  dot_file << " label=\"Δ " << node_ids[vertex] << "\"";
152  }
153 
154  // coordinates from gate parameters can be negative, a location in HAL can't
155  std::optional<double> x;
156  std::optional<double> y;
157  if( x_key.has_value() )
158  {
159  x = read_parameter_coordinate( gate, *x_key );
160  y = read_parameter_coordinate( gate, *y_key );
161  }
162  else if( gate->has_location() )
163  {
164  x = gate->get_location_x();
165  y = gate->get_location_y();
166  }
167 
168  if( x.has_value() && y.has_value() )
169  {
170  dot_file << " x=" << number( *x ) << " y=" << number( *y );
171  }
172  else
173  {
174  gates_without_coordinates++;
175  }
176 
177  dot_file << "];\n";
178  }
179 
180  // every edge, also those that no root reaches, e.g., in a ring oscillator without an enable
181  const igraph_int_t edge_count = igraph_ecount( graph );
182  for( igraph_int_t edge = 0; edge < edge_count; edge++ )
183  {
184  igraph_int_t from;
185  igraph_int_t to;
186  igraph_edge( graph, edge, &from, &to ); // can't fail for an existing edge ID
187  dot_file << " " << node_ids[from] << " -> " << node_ids[to] << ";\n";
188  }
189 
190  dot_file << "}\n";
191  dot_file.close();
192  if( !dot_file )
193  {
194  return ERR( "couldn't write clock tree to '" + pathname + "'" );
195  }
196 
197  if( x_key.has_value() && gates_without_coordinates > 0 )
198  {
199  log_warning( "clock_tree_extractor",
200  "no valid coordinates in parameters '{}' and '{}' for {} gate(s)",
201  *x_key,
202  *y_key,
203  gates_without_coordinates );
204  }
205 
206  return OK( {} );
207  }
208 } // namespace hal::cte
Definition: gate.h:59
i32 get_location_x() const
Definition: gate.cpp:167
i32 get_location_y() const
Definition: gate.cpp:172
GateType * get_type() const
Definition: gate.cpp:162
const std::string & get_name() const
Definition: gate.cpp:142
bool has_location() const
Definition: gate.cpp:182
u32 get_id() const
Definition: gate.cpp:132
const std::string & get_name() const
Definition: gate_type.cpp:64
Definition: net.h:58
const igraph_t * get_igraph() const
Definition: clock_tree.cpp:729
Result< std::pair< const void *, PtrType > > get_ptr_from_vertex(igraph_int_t vertex) const
Definition: clock_tree.cpp:631
uint32_t u32
Definition: defines.h:41
#define log_warning(channel,...)
Definition: log.h:76
#define ERR(message)
Definition: result.h:60
#define OK(...)
Definition: result.h:56
#define ERR_APPEND(prev_error, message)
Definition: result.h:64
S to(const T &str)
bool is_delay(const Gate *gate)
Definition: utils.cpp:63
bool is_mux(const Gate *gate)
Definition: utils.cpp:68
bool is_inverter(const Gate *gate)
Definition: utils.cpp:58
bool is_buffer(const Gate *gate)
Definition: utils.cpp:53
bool is_pll(const Gate *gate)
Definition: utils.cpp:78
std::optional< double > read_parameter_coordinate(const Gate *gate, const std::string &name)
Definition: utils.cpp:94
Result< std::monostate > export_dot(const ClockTree &clock_tree, const std::string &pathname, const std::optional< std::string > &x_key=std::nullopt, const std::optional< std::string > &y_key=std::nullopt)
Definition: dot_export.cpp:93
bool is_ff(const Gate *gate)
Definition: utils.cpp:43
bool is_oscillator(const Gate *gate)
Definition: utils.cpp:73
PinType type
Net * net