Tool Organization¶
This page describes the general high level overview of the design structure. You’ll find low level details in the comments and the source code.
Overview¶
Omnibus has a simple CLI interface specified in main.py.
The main file is interconnect.py, which provides InterconnectBuilder that takes optional frontend and backend as arguments.
To provide illusion of a single Interconnect object with swappable frontend and backend, these arguments specify parents of Interconnect, which in turn make the class inherit all their methods.
This design provides an easy way to add a new frontend or backend - add a new file with a proper interface and specify it as an argument to InterconnectBuilder.
Internal processing is implemented directly in the Interconnect class, as there is never a reason to swap it.
Frontends¶
All frontends are put in frontends/ and must have Frontend the class.
They must populate the internal list of components.
They may add new members to Interconnect.
In particular, they are allowed, and even expected, to add new methods.
YAML¶
Argument name: “yaml”.
This fronted reads the specification from a YAML file specified as an argument and populates the internal representation with error checking.
It is done with a single read_yaml(filename) call.
No other methods are exposed.
Internal Processing¶
The process() method is implemented as shorthand for all the steps described below.
All paths from sources to destinations are found and encoded as crossbar configuration.
These paths are then picked depending on the address map needs; the rest are discarded.
Paths are coalesced into minimal representations for each crossbar - consecutive addresses are grouped together.
Parameters are propagated from each port that has them to all neighbors, but not over barriers. This process is repeated until there is nothing more to propagate.
ID widths are found, increasing width on each crossbar.
New components are inserted on each connection that has two different parameters on its end ports.
Backends¶
All backends are put in backends/ and must have the Backend class.
They read the internal list of components and create an appropriate output.
Generally, they should expose a simple generate(outdir) interface, but they are allowed to use different one.
A backend can accept specification parameters of its own, in default and in connections.
It declares them in three places:
parse_defaultandparse_connections: parameter name to parse function, set in its__init__.Interconnectadds the common parameters to them, and frontends warn about parameters found in neither.SCHEMA_EXTENSION: file name of a JSON Schema fragment next to the backend, orNone. Properties under its$defs/defaultextenddefault, those under$defs/connectionextend connection parameters. The YAML frontend validates specifications againstfrontend/spec.schema.ymlwith the fragment of the selected backend.port_connection_params: connection parameters that internal processing copies onto the port each connection starts at, for components that read them from ports.
See topwrap_pulpplatform and its topwrap_pulpplatform.schema.yml for an example.
Graphviz¶
Argument name: “graphviz”.
This backend converts an internal representation into a graphviz graph.
It generates a single .gv file and can be configured to display it in browser.
It allows for coloring according to some parameters.
This backend’s primary purpose is debugging and visualization.
Topwrap Pulp Platform¶
Argument name: “topwrap_pulpplatform”.
This backend converts an internal representation into a Topwrap file and SystemVerilog wrappers.
It expects Pulp Platform modules for operation.
It requires external commands to be executed to produce a proper output.
Verilator files are also provided to the set list of files and remove unnecessary warnings.
New components can be added to it by:
creating a new component class deriving from
MappedComponent, which:
forwards constructor arguments to
MappedComponentsand specifies theipname,creates the
generate_verilog(self, outdir)method which creates verilog wrappers/modules,creates
generate_hierarchy(self, ports, params), which populates Topwrap’s hierarchy - ports and parameters.
populating the registry in
map_components.possibly adjusting the choice procedure in
map_components.
In short:
It goes through all components that were generated in the internal processing stage, and using some choice function, they are mapped to Verilog components with the help of
registry.Verilog files are generated.
Verilator filelist and waivers are generated.
Topwrap hierarchy is generated.