Gate Library

The gate library is a container for all gate types that are available within a selected standard cell library. Commonly, such standard cell libraries are proprietary. HAL comes with a few selected libraries covering both FPGAs and ASIC standard cell libraries. However, the reverse engineer is free to add any library they desire by either using the supplemented gate library parsers or writing a new one for the desired gate library format.

The gate library is what makes a netlist analyzable. A netlist file merely states that some instance is of type LUT6 or INV_X1; without a library, HAL has no idea how many pins that cell has, which one is the clock, or what it computes. Everything beyond pure topology — Boolean functions, sequential behavior, simulation, LUT configuration handling — is read from here. This is why choosing the right gate library on import is the single most consequential decision when bringing a netlist into HAL, see Using HAL.

A netlist's gate library is fixed at creation and cannot be swapped afterwards. If you picked the wrong one, re-import the netlist.

Gate library information

In HAL, a gate library comprises a name, the path to its underlying file, and a collection of gate types. It can be constructed giving just the input path and a name using its constructor GateLibrary. Access to its name and path are provided by the get_name and get_path functions.

gl = GateLibrary("path/to/example_library.lib", "example_library")   # construct a new (empty) gate library
name = gl.get_name()   # get the name of the gate library
path = gl.get_path()   # get the path to the gate library file

The gate library of the currently loaded netlist is obtained from the netlist itself, which is what you will normally do:

gl = netlist.get_gate_library()

Managing gate types

It is currently not possible to create new gate types from within Python, but only via the C++ API. However, to operate on existing gate types, diverse functions are provided to the user. For example, contains_gate_type and contains_gate_type_by_name may be used to check whether a gate type is part of the gate library. While get_gate_type_by_name may be utilized to retrieve a gate type of the specified name from the gate library (if available), the function get_gate_types returns all gate types available in the gate library. The latter function additionally allows for a filter condition to be specified, in case the user wants to narrow down the result set.

gl.contains_gate_type(some_gt)                # returns True if some_gt exists within the gate library
gl.contains_gate_type_by_name("some_gt")      # returns True if a gate type with name "some_gt" exists within the library
gt = gl.get_gate_type_by_name("some_gt")      # returns gate type 'some_gt'
gate_types = gl.get_gate_types()              # get all gate types of that library

Note that get_gate_types returns every type the library defines, not the types actually used in your netlist — a full vendor library contains thousands of cells of which a given design uses a few dozen. To see what is really in your design, iterate over the netlist's gates instead:

from collections import Counter
used = Counter(g.get_type().get_name() for g in netlist.get_gates())

Browsing the library by gate type property is often more useful than browsing by name, since it works across technologies:

ff_types = gl.get_gate_types(lambda gt: gt.has_property(hal_py.GateTypeProperty.ff))

The GUI offers the same information interactively through the Gate Library Manager (main menu > Utilities).

VCC and GND gate types

Since the gate library keeps track of types that act as VCC or GND sources, the functions mark_vcc_gate_type and mark_gnd_gate_type may be used to declare a gate type to be such a VCC or GND type. Usually, these special gate types are automatically annotated after successful parsing of the gate library. However, manually manipulating the gate library may require additional gate types being marked accordingly. Additionally, using get_vcc_gate_types and get_gnd_gate_types, the user can retrieve a list of these special gate types. Each gate library needs to provide at least one VCC and one GND gate type. If no such type is present within the gate library file that is parsed by HAL, a new gate type fulfilling that purpose is created by HAL automatically.

vcc_types = gl.get_vcc_gate_types()   # gate types acting as constant '1' sources
gnd_types = gl.get_gnd_gate_types()   # gate types acting as constant '0' sources

Gate location data

If the netlist carries placement information, the gate library declares where in a gate's data container HAL should look for it. set_gate_location_data_category sets the data category and set_gate_location_data_identifiers the keys holding the x and y coordinates; get_gate_location_data_category reads the category back. Once configured, coordinates are available through Gate.get_location.

gl.set_gate_location_data_category("attribute")
gl.set_gate_location_data_identifiers("X_COORD", "Y_COORD")

Placement data is worth wiring up when available: gates belonging to the same word-level structure tend to be placed close together, which is an independent hint about logical grouping.

Includes

Gate library files may reference other files. add_include registers such a dependency and get_includes lists them. These are used by gate library writers when serializing a library back to disk, and rarely need to be touched directly.