Netlist Utilities

The netlist utilities are a collection of free functions that operate on a netlist. They live in the hal_py.NetlistUtils submodule and, unlike the decorators, are called directly without instantiating anything.

from hal_py import NetlistUtils

This module is being phased out. Netlist utilities predate HAL's decorators, and their functionality is progressively moving there: netlist traversal to the NetlistTraversalDecorator, Boolean function extraction and subgraph copying to the SubgraphNetlistDecorator, and netlist modification to the NetlistModificationDecorator. Cleanup passes have moved to the netlist preprocessing plugin. Prefer those for new code — only the functions documented below remain the recommended way to do their respective job.

Every function of this module is now deprecated or moved. Calling one from Python logs a warning naming its replacement, once per function. The sections below say where each went; the module itself will be removed in a future version.

Path and connectivity

get_path (deprecated)

Deprecated. Despite the name it never returned a path: it returns every gate of the cone, over every branch of a fan-out, stopping at gates whose gate type carries one of the given properties. Use NetlistTraversalDecorator.get_gates with the negated condition, which says exactly that, see Decorators:

trav = hal_py.NetlistTraversalDecorator(netlist)
stop = {hal_py.GateTypeProperty.ff, hal_py.GateTypeProperty.ram}
reached = trav.get_gates(gate, hal_py.TraversalDirection.forward,
                         lambda g: not any(g.get_type().has_property(p) for p in stop),
                         hal_py.TraversalStop.at_mismatch)

For repeated calls over many gates, create a traversal cache instead of passing a dict around.

get_shortest_path (deprecated)

Deprecated. All three shapes — gate to gate, gate to module, module to module — now live on NetlistTraversalDecorator.get_shortest_path, which additionally accepts endpoint filters, so a path can be forbidden from running through clock or reset logic. See Decorators.

It remains the fastest way to answer "is there any connection between these two parts of the design at all?" — the question you ask, for example, when checking whether a key register can influence an output it should never reach, as in the Crypto Trojan example.

get_nets_at_pins (deprecated)

Deprecated without a replacement, because it never needed one — it is a per-pin lookup that Gate already provides:

nets = [gate.get_fan_in_net(p) if p.direction == hal_py.PinDirection.input else gate.get_fan_out_net(p)
        for p in pins]

Structure detection

get_gate_chain and get_complex_gate_chain (moved)

Moved to the NetlistTraversalDecorator, where the rest of the traversal lives — see Decorators. The functionality is unchanged.

get_common_inputs (moved)

Moved to the NetlistTraversalDecorator, unchanged in behaviour — see Decorators.

get_ff_dependency_matrix (deprecated)

Deprecated. Use boolean_influence.get_ff_dependency_matrix from the Boolean influence plugin, which computes the same matrix and can additionally weight each dependency by how strongly one flip-flop influences the other:

from hal_plugins import boolean_influence
mapping, matrix = boolean_influence.get_ff_dependency_matrix(netlist, False)   # True to weight by influence

This is the representation that register-grouping techniques such as dataflow analysis build on, and it is also the most convenient way to hand a netlist's register structure to external graph or clustering tools.

See also

• Decorators — netlist traversal, subgraph Boolean functions, and netlist modification
• Netlist Preprocessing — cleanup passes such as buffer removal and unused LUT input removal, which are worth running on a freshly imported netlist before any structural analysis