|
HAL
v4.5.0-124-g47ab54673
The Hardware Analyzer - a comprehensive reverse engineering and manipulation framework for gate-level netlists.
|
A directed graph corresponding to a netlist. More...
#include </home/runner/work/hal/hal/plugins/graph_algorithm/include/graph_algorithm/netlist_graph.h>

Public Types | |
| enum class | Direction { NONE , IN , OUT , ALL } |
| The direction of exploration within the graph. More... | |
Public Member Functions | |
| NetlistGraph (Netlist *nl, igraph_t &&graph, std::unordered_map< u32, Gate * > &&nodes_to_gates) | |
Construct a netlist graph from a netlist, an igraph graph object, and a map from graph nodes to HAL gates. More... | |
| ~NetlistGraph () | |
Default destructor for NetlistGraph. More... | |
| NetlistGraph (const NetlistGraph &)=delete | |
| NetlistGraph & | operator= (const NetlistGraph &)=delete |
| Result< std::unique_ptr< NetlistGraph > > | copy () const |
| Create a deep copy of the netlist graph. More... | |
| Netlist * | get_netlist () const |
| Get the netlist associated with the netlist graph. More... | |
| igraph_t * | get_graph () const |
| Get the graph object of the netlist graph. More... | |
| Result< std::vector< Gate * > > | get_gates_from_vertices (const std::vector< u32 > &vertices) const |
| Get the gates corresponding to the specified vertices. More... | |
| Result< std::vector< Gate * > > | get_gates_from_vertices (const std::set< u32 > &vertices) const |
| Get the gates corresponding to the specified vertices. More... | |
| Result< std::vector< Gate * > > | get_gates_from_vertices_igraph (const igraph_vector_int_t *vertices) const |
| Get the gates corresponding to the specified vertices. More... | |
| Result< std::set< Gate * > > | get_gates_set_from_vertices (const std::vector< u32 > &vertices) const |
| Get the gates corresponding to the specified vertices. More... | |
| Result< std::set< Gate * > > | get_gates_set_from_vertices (const std::set< u32 > &vertices) const |
| Get the gates corresponding to the specified vertices. More... | |
| Result< std::set< Gate * > > | get_gates_set_from_vertices_igraph (const igraph_vector_int_t *vertices) const |
| Get the gates corresponding to the specified vertices. More... | |
| Result< Gate * > | get_gate_from_vertex (const u32 vertex) const |
| Get the gate corresponding to the specified vertex. More... | |
| Result< std::vector< u32 > > | get_vertices_from_gates (const std::vector< Gate * > &gates) const |
| Get the vertices corresponding to the specified gates. More... | |
| Result< std::vector< u32 > > | get_vertices_from_gates (const std::set< Gate * > &gates) const |
| Get the vertices corresponding to the specified gates. More... | |
| Result< igraph_vector_int_t > | get_vertices_from_gates_igraph (const std::vector< Gate * > &gates) const |
| Get the vertices corresponding to the specified gates. More... | |
| Result< igraph_vector_int_t > | get_vertices_from_gates_igraph (const std::set< Gate * > &gates) const |
| Get the vertices corresponding to the specified gates. More... | |
| Result< u32 > | get_vertex_from_gate (Gate *g) const |
| Get the vertex corresponding to the specified gate. More... | |
| bool | is_shadow_vertex (const u32 vertex) const |
| Check whether the specified vertex is a shadow vertex. More... | |
| Result< std::vector< u32 > > | get_all_vertices_from_gate (Gate *g) const |
Get all vertices corresponding to the specified gate, i.e., its primary vertex and, if the gate was split by from_gates, its shadow vertex. More... | |
| u32 | get_num_vertices (bool only_connected=false) const |
| Get the number of vertices in the netlist graph. More... | |
| u32 | get_num_edges () const |
| Get the number of edges in the netlist graph. More... | |
| Result< std::vector< u32 > > | get_vertices (bool only_connected=false) const |
| Get the vertices in the netlist graph. More... | |
| Result< std::vector< std::pair< u32, u32 > > > | get_edges () const |
| Get the edges between vertices in the netlist graph. More... | |
| Result< std::vector< std::pair< Gate *, Gate * > > > | get_edges_in_netlist () const |
| Get the edges between gates in the netlist corresponding to the netlist graph. More... | |
| Result< std::monostate > | add_edges (const std::vector< std::pair< Gate *, Gate * >> &edges) |
| Add edges between the specified pairs of source and destination gates to the netlist graph. More... | |
| Result< std::monostate > | add_edges (const std::vector< std::pair< u32, u32 >> &edges) |
| Add edges between the specified pairs of source and destination vertices to the netlist graph. More... | |
| Result< std::monostate > | add_edges (const std::map< Gate *, std::set< Gate * >> &edges) |
| Add edges between the specified pairs of source and destination gates to the netlist graph. More... | |
| Result< std::monostate > | delete_edges (const std::vector< std::pair< Gate *, Gate * >> &edges) |
| Delete edges between the specified pairs of source and destination gates from the netlist graph. More... | |
| Result< std::monostate > | delete_edges (const std::vector< std::pair< u32, u32 >> &edges) |
| Delete edges between the specified pairs of source and destination vertices from the netlist graph. More... | |
| void | print () const |
| Print the edge list of the graph to stdout. More... | |
Static Public Member Functions | |
| static Result< std::unique_ptr< NetlistGraph > > | from_netlist (Netlist *nl, bool create_dummy_vertices=false, const std::function< bool(const Net *)> &filter=nullptr) |
| Create a directed graph from a netlist. More... | |
| static Result< std::unique_ptr< NetlistGraph > > | from_netlist_no_edges (Netlist *nl, const std::vector< Gate * > &gates={}) |
| Create an empty directed graph from a netlist. More... | |
| static Result< std::unique_ptr< NetlistGraph > > | from_gates (const std::vector< Gate * > &gates, const std::set< Gate * > &split_gates={}, const std::function< bool(const Net *)> &filter=nullptr) |
| Create a directed graph from a subset of the gates of a netlist. More... | |
A directed graph corresponding to a netlist.
This class holds all information on a netlist graph that corresponds to a gate-level netlist and provides functions to access and operate on it.
Definition at line 59 of file netlist_graph.h.
|
strong |
The direction of exploration within the graph.
Definition at line 66 of file netlist_graph.h.
| hal::graph_algorithm::NetlistGraph::NetlistGraph | ( | Netlist * | nl, |
| igraph_t && | graph, | ||
| std::unordered_map< u32, Gate * > && | nodes_to_gates | ||
| ) |
Construct a netlist graph from a netlist, an igraph graph object, and a map from graph nodes to HAL gates.
| [in] | nl | - The netlist. |
| [in] | graph | - The igrapg graph object. |
| [in] | nodes_to_gates | - A map from nodes to gates. |
Definition at line 17 of file netlist_graph.cpp.
| hal::graph_algorithm::NetlistGraph::~NetlistGraph | ( | ) |
Default destructor for NetlistGraph.
Definition at line 34 of file netlist_graph.cpp.
|
delete |
igraph_t is a plain C struct holding heap pointers, so the implicitly generated copy operations would bitwise-copy m_graph and leave two NetlistGraph objects aliasing the same graph internals – the destructor would then call igraph_destroy() on them twice, and the copy's m_graph_ptr would still point into the source object. Every factory hands out a std::unique_ptr<NetlistGraph>, so nothing is meant to copy a graph in the first place; deleting the copy operations makes that invariant explicit and enforced at compile time instead of relying on convention.
| Result< std::monostate > hal::graph_algorithm::NetlistGraph::add_edges | ( | const std::map< Gate *, std::set< Gate * >> & | edges | ) |
Add edges between the specified pairs of source and destination gates to the netlist graph.
The vertices must already exist in the graph.
| [in] | edges | - The edges to add as a map from source gate to its destination gates. |
Definition at line 897 of file netlist_graph.cpp.
References ERR, hal::Netlist::get_id(), and OK.
| Result< std::monostate > hal::graph_algorithm::NetlistGraph::add_edges | ( | const std::vector< std::pair< Gate *, Gate * >> & | edges | ) |
Add edges between the specified pairs of source and destination gates to the netlist graph.
The gates must already correspond to vertices in the graph.
| [in] | edges | - The edges to add as pairs of gates. |
Definition at line 817 of file netlist_graph.cpp.
References ERR, hal::Netlist::get_id(), and OK.
| Result< std::monostate > hal::graph_algorithm::NetlistGraph::add_edges | ( | const std::vector< std::pair< u32, u32 >> & | edges | ) |
Add edges between the specified pairs of source and destination vertices to the netlist graph.
The vertices must already exist in the graph.
| [in] | edges | - The edges to add as pairs of vertices. |
Definition at line 860 of file netlist_graph.cpp.
References ERR, hal::Netlist::get_id(), and OK.
| Result< std::unique_ptr< NetlistGraph > > hal::graph_algorithm::NetlistGraph::copy | ( | ) | const |
Create a deep copy of the netlist graph.
Definition at line 329 of file netlist_graph.cpp.
| Result< std::monostate > hal::graph_algorithm::NetlistGraph::delete_edges | ( | const std::vector< std::pair< Gate *, Gate * >> & | edges | ) |
Delete edges between the specified pairs of source and destination gates from the netlist graph.
| [in] | edges | - The edges to delete as pairs of gates. |
Definition at line 951 of file netlist_graph.cpp.
References ERR, hal::Netlist::get_id(), and OK.
| Result< std::monostate > hal::graph_algorithm::NetlistGraph::delete_edges | ( | const std::vector< std::pair< u32, u32 >> & | edges | ) |
Delete edges between the specified pairs of source and destination vertices from the netlist graph.
| [in] | edges | - The edges to delete as pairs of vertices. |
Definition at line 1007 of file netlist_graph.cpp.
References ERR, hal::Netlist::get_id(), and OK.
|
static |
Create a directed graph from a subset of the gates of a netlist.
Only the given gates become vertices and only nets between two of them become edges, so the graph is a closed world irrespective of what the gates are connected to elsewhere in the netlist.
Gates in split_gates are represented by two vertices instead of one: a primary vertex carrying only the outgoing edges of the gate and a shadow vertex carrying only its incoming edges. This breaks feedback through those gates, which makes a sequential loop such as the round function of a cipher acyclic without having to copy it into a netlist of its own. Both vertices resolve back to the same gate, so use is_shadow_vertex to tell the two roles apart. A shadow vertex is only created if the gate actually has incoming edges within the graph.
Vertices are numbered in the order of gates, so pass them in a deterministic order to obtain a reproducible graph.
| [in] | gates | - The gates to include in the graph. Must all belong to the same netlist. |
| [in] | split_gates | - The gates to represent by a primary and a shadow vertex. Gates that are not part of gates are ignored. Defaults to an empty set. |
| [in] | filter | - An optional filter that is evaluated on every net considered as an edge. Defaults to nullptr. |
Definition at line 44 of file netlist_graph.cpp.
Referenced by hal::hawkeye::CipherCandidate::build_round_function(), and hal::PYBIND11_PLUGIN().
|
static |
Create a directed graph from a netlist.
Optionally create dummy vertices at nets missing a source or destination. An optional filter can be applied to exclude undesired edges.
| [in] | nl | - The netlist. |
| [in] | create_dummy_vertices | - Set true to create dummy vertices, false otherwise. Defaults to false. |
| [in] | filter | - An optional filter that is evaluated on every net of the netlist. Defaults to nullptr. |
Definition at line 171 of file netlist_graph.cpp.
Referenced by hal::PYBIND11_PLUGIN().
|
static |
Create an empty directed graph from a netlist.
Vertices for all gates are created, but no edges are added.
| [in] | nl | - The netlist. |
| [in] | gates | - The gates to include in the graph. If omitted, all gates of the netlist will be included. |
Definition at line 298 of file netlist_graph.cpp.
Referenced by hal::hawkeye::CipherCandidate::detect(), and hal::PYBIND11_PLUGIN().
| Result< std::vector< u32 > > hal::graph_algorithm::NetlistGraph::get_all_vertices_from_gate | ( | Gate * | g | ) | const |
Get all vertices corresponding to the specified gate, i.e., its primary vertex and, if the gate was split by from_gates, its shadow vertex.
| [in] | g | - A gate. |
Definition at line 635 of file netlist_graph.cpp.
References ERR, hal::Gate::get_id(), hal::Gate::get_name(), and OK.
| Result< std::vector< std::pair< u32, u32 > > > hal::graph_algorithm::NetlistGraph::get_edges | ( | ) | const |
Get the edges between vertices in the netlist graph.
Definition at line 738 of file netlist_graph.cpp.
| Result< std::vector< std::pair< Gate *, Gate * > > > hal::graph_algorithm::NetlistGraph::get_edges_in_netlist | ( | ) | const |
Get the edges between gates in the netlist corresponding to the netlist graph.
Definition at line 766 of file netlist_graph.cpp.
References ERR, log_warning, and OK.
Get the gate corresponding to the specified vertex.
| [in] | vertex | - A vertex. |
Definition at line 501 of file netlist_graph.cpp.
References ERR, get_gates_from_vertices(), and OK.
| Result< std::vector< Gate * > > hal::graph_algorithm::NetlistGraph::get_gates_from_vertices | ( | const std::set< u32 > & | vertices | ) | const |
Get the gates corresponding to the specified vertices.
The result may contain nullptr for dummy vertices.
| [in] | vertices | - A set of vertices. |
Definition at line 379 of file netlist_graph.cpp.
References ERR, hal::Netlist::get_id(), log_warning, and OK.
| Result< std::vector< Gate * > > hal::graph_algorithm::NetlistGraph::get_gates_from_vertices | ( | const std::vector< u32 > & | vertices | ) | const |
Get the gates corresponding to the specified vertices.
The result may contain nullptr for dummy vertices.
| [in] | vertices | - A vector of vertices. |
Definition at line 356 of file netlist_graph.cpp.
References ERR, hal::Netlist::get_id(), log_warning, and OK.
Referenced by get_gate_from_vertex().
| Result< std::vector< Gate * > > hal::graph_algorithm::NetlistGraph::get_gates_from_vertices_igraph | ( | const igraph_vector_int_t * | vertices | ) | const |
Get the gates corresponding to the specified vertices.
The result may contain nullptr for dummy vertices.
| [in] | vertices | - An igraph vector of vertices. |
Definition at line 402 of file netlist_graph.cpp.
References ERR, hal::Netlist::get_id(), log_warning, and OK.
Referenced by hal::graph_algorithm::get_subgraph_igraph().
| Result< std::set< Gate * > > hal::graph_algorithm::NetlistGraph::get_gates_set_from_vertices | ( | const std::set< u32 > & | vertices | ) | const |
Get the gates corresponding to the specified vertices.
| [in] | vertices | - A set of vertices. |
Definition at line 451 of file netlist_graph.cpp.
References ERR, hal::Netlist::get_id(), log_warning, and OK.
| Result< std::set< Gate * > > hal::graph_algorithm::NetlistGraph::get_gates_set_from_vertices | ( | const std::vector< u32 > & | vertices | ) | const |
Get the gates corresponding to the specified vertices.
| [in] | vertices | - A vector of vertices. |
Definition at line 427 of file netlist_graph.cpp.
References ERR, hal::Netlist::get_id(), log_warning, and OK.
| Result< std::set< Gate * > > hal::graph_algorithm::NetlistGraph::get_gates_set_from_vertices_igraph | ( | const igraph_vector_int_t * | vertices | ) | const |
Get the gates corresponding to the specified vertices.
| [in] | vertices | - An igraph vector of vertices. |
Definition at line 475 of file netlist_graph.cpp.
References ERR, hal::Netlist::get_id(), log_warning, and OK.
| igraph_t * hal::graph_algorithm::NetlistGraph::get_graph | ( | ) | const |
Get the graph object of the netlist graph.
Definition at line 351 of file netlist_graph.cpp.
Referenced by hal::graph_algorithm::get_all_shortest_paths_igraph(), hal::graph_algorithm::get_connected_components(), hal::graph_algorithm::get_neighborhood_igraph(), hal::graph_algorithm::get_shortest_paths_igraph(), and hal::graph_algorithm::get_subgraph_igraph().
| Netlist * hal::graph_algorithm::NetlistGraph::get_netlist | ( | ) | const |
Get the netlist associated with the netlist graph.
Definition at line 346 of file netlist_graph.cpp.
Referenced by hal::graph_algorithm::get_subgraph_igraph(), and hal::PYBIND11_PLUGIN().
| u32 hal::graph_algorithm::NetlistGraph::get_num_edges | ( | ) | const |
Get the number of edges in the netlist graph.
Definition at line 687 of file netlist_graph.cpp.
Referenced by hal::PYBIND11_PLUGIN().
| u32 hal::graph_algorithm::NetlistGraph::get_num_vertices | ( | bool | only_connected = false | ) | const |
Get the number of vertices in the netlist graph.
| [in] | only_connected | - Set true to only count vertices connected to at least one edge, false otherwise. Defaults to false. |
Definition at line 654 of file netlist_graph.cpp.
Referenced by hal::PYBIND11_PLUGIN().
Get the vertex corresponding to the specified gate.
| [in] | g | - A gate. |
Definition at line 619 of file netlist_graph.cpp.
References ERR, get_vertices_from_gates(), and OK.
Referenced by hal::graph_algorithm::get_all_shortest_paths(), and hal::graph_algorithm::get_shortest_paths().
| Result< std::vector< u32 > > hal::graph_algorithm::NetlistGraph::get_vertices | ( | bool | only_connected = false | ) | const |
Get the vertices in the netlist graph.
| [in] | only_connected | - Set true to only return vertices connected to at least one edge, false otherwise. Defaults to false. |
Definition at line 692 of file netlist_graph.cpp.
| Result< std::vector< u32 > > hal::graph_algorithm::NetlistGraph::get_vertices_from_gates | ( | const std::set< Gate * > & | gates | ) | const |
Get the vertices corresponding to the specified gates.
| [in] | gates | - A set of gates. |
Definition at line 536 of file netlist_graph.cpp.
References ERR, hal::Netlist::get_id(), and OK.
| Result< std::vector< u32 > > hal::graph_algorithm::NetlistGraph::get_vertices_from_gates | ( | const std::vector< Gate * > & | gates | ) | const |
Get the vertices corresponding to the specified gates.
| [in] | gates | - A vector of gates. |
Definition at line 512 of file netlist_graph.cpp.
References ERR, hal::Netlist::get_id(), and OK.
Referenced by get_vertex_from_gate().
| Result< igraph_vector_int_t > hal::graph_algorithm::NetlistGraph::get_vertices_from_gates_igraph | ( | const std::set< Gate * > & | gates | ) | const |
Get the vertices corresponding to the specified gates.
| [in] | gates | - A set of gates. |
Definition at line 587 of file netlist_graph.cpp.
References ERR, hal::Netlist::get_id(), and OK.
| Result< igraph_vector_int_t > hal::graph_algorithm::NetlistGraph::get_vertices_from_gates_igraph | ( | const std::vector< Gate * > & | gates | ) | const |
Get the vertices corresponding to the specified gates.
| [in] | gates | - A vector of gates. |
Definition at line 558 of file netlist_graph.cpp.
References ERR, hal::Netlist::get_id(), and OK.
Referenced by hal::graph_algorithm::get_all_shortest_paths(), hal::graph_algorithm::get_neighborhood(), hal::graph_algorithm::get_shortest_paths(), and hal::graph_algorithm::get_subgraph().
| bool hal::graph_algorithm::NetlistGraph::is_shadow_vertex | ( | const u32 | vertex | ) | const |
Check whether the specified vertex is a shadow vertex.
A shadow vertex carries only the incoming edges of a gate that was split by from_gates, while the primary vertex of that gate carries only its outgoing edges. Both resolve to the same gate, so this is the only way to tell which of the two roles a vertex stands for.
| [in] | vertex | - A vertex. |
true if the vertex is a shadow vertex, false otherwise. Definition at line 630 of file netlist_graph.cpp.
Referenced by hal::PYBIND11_PLUGIN().
|
delete |
| void hal::graph_algorithm::NetlistGraph::print | ( | ) | const |
Print the edge list of the graph to stdout.
Definition at line 1055 of file netlist_graph.cpp.
Referenced by hal::PYBIND11_PLUGIN().