Module

A module is a functional unit comprising gates and their connected nets. Modules allow for hierarchization of the netlist and can be nested into each other, thus creating different levels of abstraction from the original netlist. Per design, modules only really contain gates and not nets. An important distinction between gates and modules is that a net does not end at the module boundaries but actually crosses them. The module comes with a set of functions to obtain all nets that are connected to gates within that module. By default, all gates of a netlist are contained in a single module called the "top_module" if no hierarchy is defined within the netlist file. Each module comes with a unique ID and a name. Additionally, a type may be assigned to a module if desired.

Module Information and Management

A module can be created by calling create_module on the current netlist. When creating a new module, the user always needs to specify its parent module. In the example below, we simply use the "top_module" as a parent module. The ID cannot be changed by the user and may only be read by calling the get_id function from Python. Read and write access to the name is provided by the get_name and set_name functions respectively. Similarly, the module's type can be accessed using get_type and set_type. The get_top_module function can be executed on the netlist and returns the top module of the current netlist. Some example Python code is given below:

m = netlist.create_module("example_module", netlist.get_top_module())   # create a new module within the top module
print(m.get_name())                                                     # print the name of the module
print(m.get_type())                                                     # print the type of the module
print(m.get_id())                                                       # print the ID of the module

To retrieve a module from the netlist that corresponds to a known ID, the get_module_by_id command can be executed on the netlist. Furthermore, a module may be deleted using delete_module as shown below. When deleting a module, all gates assigned to that module are handed over to its parent module.

m = netlist.get_module_by_id(3)   # get the module with ID 3 from the netlist
netlist.delete_module(m)          # delete the module

In addition, a module can also be part of a grouping itself. While details on how to assign a grouping can be found here, the easiest way to retrieve the current grouping of a module is given by the get_grouping function.

m = netlist.get_module_by_id(3)   # get the module with ID 3
grouping = m.get_grouping()       # get the current grouping of the module

Managing Gates, Parent-, and Submodules

Gates can be added to a module by calling assign_gate and removed by using remove_gate. Furthermore, the user can check whether a gate or module is part of a module by resorting to contains_gate and contains_module. Finally, a list of contained gates and submodules is returned by the functions get_gates and get_submodules. A short example is given below:

m = netlist.create_module("example_module", netlist.get_top_module())   # create a new module within the top module
m.assign_gate(netlist.get_gate_by_id(1))                                # assign gate with ID 1 to module
m.contains_gate(netlist.get_gate_by_id(4))                              # return 'false'
gates = m.get_gates()                                                   # return a list containing only the gate with ID 1
m.remove_gate(gates[0])                                                 # remove gate with ID 1 from module

A module's parent module can be obtained using get_parent_module. For the top module, this will return None. Furthermore, the gates of a module may also be accessed by ID using get_gate_by_id.

top = netlist.get_top_module()                     # get the top module of the netlist
m = netlist.create_module("example_module", top)   # create a new submodule of the top module 
m.get_parent_module()                              # return the top module
top.get_parent_module()                            # return None
top.get_gate_by_id(4)                              # get gate with ID 4 from top module if present within the module

Managing Nets

The nets within a module are dynamically classified depending on the gates contained within the module. Nets can either be inputs, outputs, or internal to the module. However, a net may fall into multiple of these categories at the same time. Input nets are all those nets that are either a global input to the netlist or have one of its sources outside of the module. Similarly, output nets either represent a global output or have at least one destination outside of the module. Internal nets do have at least one source and one destination within the module. Hence, a net with sources and destinations both inside and outside of the module is regarded as input, output, and internal. To access those nets, the functions get_input_nets, get_output_nets, and get_internal_nets each returning a list of nets are provided.

input_nets = m.get_input_nets()         # get all input nets of the module
internal_nets = m.get_internal_nets()   # get all internal nets of the module

Additional functions to operate on the port names of a module are available, though will not be discussed in detail here. For additional information on these, refer to the Python API documentation.