Core

The HAL core is the C++ library at the heart of HAL. It holds the netlist and everything that operates on it, and it is what the GUI, the Python API, and every plugin are built on top of. If you write an analysis in HAL, you are writing against the core.

This section of the wiki describes the data model the core exposes. It is worth reading once in order, because almost everything you will do in HAL — visually or in Python — is expressed in terms of these few objects.

The data model

HAL's netlist model deliberately mirrors how hardware is actually built, so that what you learn about a design can be written back into the model:

Concept	What it is	Why you care
Netlist	The circuit as a whole; owns everything else	The root object. In Python it is simply the variable netlist
Gate	One instance of a standard cell	The nodes of the graph — the actual logic
Net	A wire connecting gate pins	The edges of the graph — the connectivity
Endpoint	The point where a net meets a specific pin of a specific gate	How you traverse: not just which gate, but through which pin
Module	A hierarchical container of gates	Where you record recovered structure — this is the register you found, this is the round function
Grouping	A flat, temporary set of gates, nets, and modules	Scratch space — mark things now, make sense of them later
Gate Library / Gate Type	The definition of the cells the netlist is built from	What makes the netlist mean something rather than just being a graph
Boolean Function	Symbolic representation of what logic computes	How you reason about behavior instead of just structure
Data Container	Arbitrary key-value data attached to gates, nets, and modules	Where parsed attributes (LUT init strings, generics) live, and where you can attach your own findings

Two structural rules explain most of the API:

The netlist owns everything. Gates, nets, modules, and groupings are always created and destroyed through the netlist (netlist.create_gate(...), netlist.delete_net(...)), never constructed directly. Every element carries an ID that is unique among elements of its kind, and holds a reference back to the netlist it belongs to.

Structure is something you add, not something you get. A netlist recovered from hardware arrives flat: every gate sits in the top module, no gate has a meaningful name, and no hierarchy exists. Modules and groupings are the two mechanisms for recording what you figure out — modules for structure you believe in, groupings for hypotheses you are still testing.

Two layers of functionality

The core deliberately keeps the netlist classes small. Anything that is a convenience, an algorithm, or an analysis lives outside of them:

• The netlist classes themselves (Netlist, Gate, Net, Module, ...) provide storage, connectivity, and traversal one step at a time.
• Decorators and netlist utilities wrap a netlist and add the higher-level operations: following paths through combinational logic, finding the next sequential gates, extracting the Boolean function of a whole subcircuit, safely rewiring gates.

If you find yourself writing a loop that walks the graph, check Decorators and Netlist Utilities first — the operation you need has likely already been implemented and tested.

Using the core

All of this functionality is available from both C++ and Python. The Python bindings cover nearly the entire core API and are what most users work with:

netlist.get_gates()                      # every gate in the design
netlist.get_gate_by_id(42)               # a specific gate
netlist.get_top_module().get_submodules()  # the module hierarchy

For a complete reference of every class and method, see the C++ API documentation and the Python API documentation. The pages in this section are not a replacement for that reference — they explain what the concepts are for and show the parts you will use most.

If you have not used HAL before, read Using HAL first for a hands-on introduction, then come back here.