Architectural Overview¶

At its core level, LibreLane is an infrastructure in which Flows could be built out of multiple atomic execution units called Steps, and then run with a Configuration.

LibreLane is implemented as a Python module with the following architecture:

The module is accessible via Python scripts, Jupyter Notebooks and a (limited) command-line API.

The module consists of four submodules:

…with an assisting module named librelane.common.

States¶

A librelane.state.State is a snapshot of paths to the various different views of the design (e.g. Netlist, DEF, GDS, etc.) at any point in time.

Keys must be of the type librelane.state.DesignFormat and values must be either:

Of the type librelane.config.Path.
N-nested dictionaries with key values such that the leaves are of the type librelane.config.Path as well.

States also have another property: metrics. This attribute captures design metrics, which may be read and/or updated by any step.

Steps¶

Steps are the primary execution unit of LibreLane.

Each step takes two inputs: a Configuration Object and a State, and returns an output State.

Steps should align themselves to one principle:

The same step with the same input configuration and same input state must emit the same output.

In other words, for the same version of LibreLane, the output state is strictly a function of the input configuration and the input state.

This is applied as far as the functionality goes:

Steps do NOT modify files in-place. New files must be created in the step’s dedicated directory. If the tool does not support out-of-place modification, copy the files then modify the copies.
Steps do NOT modify the config_in. This is programmatically enforced.
Steps do NOT rely on external filesystem paths. If a path is not in the configuration or in the input state, it effectively does not exist to the Step.
- This applies the other way around as well: Steps do NOT create files outside of their step directory.
Steps do fix PRNG seeds for replicability. They can be exposed as a configuration variable.

More of these strictures may be programatically enforced by the infrastructure in the future.

Some aspects cannot be made entirely deterministic, such as timestamps in views, file paths and the like. These are acceptable breaks from this dogma.

The librelane.steps.Step class is an abstract base class from which all other steps inherit and is the implementation of this part of the LibreLane architecture.

Flows¶

Flows are scripts that incorporate multiple Steps to achieve a certain function.

The librelane.flows.Flow class is an abstract base class from which all other flows inherit.

Sequential Flows¶

A subclass of Flows, librelane.flows.SequentialFlow will, as the name implies, run its declared steps in sequence with the same configuration object and a consecutive states, i.e.

\[ State_{i} = Step_{i}(State_{i - 1}, Config)\]

So, for a flow of \(n\) steps, the final state, \(State_{n}\) will be the output of the entire flow.

The default flow of LibreLane when run from the command-line is a SequentialFlow named Classic, which is based off of OpenLane.

Configuration¶

Objects¶

Configuration objects are a thoroughly-validated dictionary of values assigned to various configuration variables throughout a flow.

A flow’s configuration variables in an aggregate of all its incorporate steps.

The configuration object supports Python’s basic scalars (except for float), Decimal, List and Dict, the latter two infinitely nestable. Steps are given this configuration object as an input.

Builder¶

The configuration builder takes a Flow and a raw configuration object as an input, which can be one more of:

A Python dictionary
A path to an existent JSON configuration file
A path to an existent YAML file
A path to an existent Tcl configuration file

and then validates this configuration, resolving paths, fixing types and other such tasks along the way, returning the librelane.config.Config class which is essentially a validated and immutable string dictionary.