openlane.config
API¶
The Configuration Module¶
This modules includes various functions for importing and/or generating OpenLane configuration objects. Configuration objects are the primary input to a flow.
- class openlane.config.Instance(location: Tuple[Decimal, Decimal] | None, orientation: Orientation | None)¶
Bases:
object
Location information for an instance of a cell or macro.
- Parameters:
location (Tuple[Decimal, Decimal] | None) – The physical co-ordinates of the object’s origin. Leave empty for automatic placement.
orientation (Orientation | None) – The orientation of the object’s placement. ‘N’/’R0’ by default.
- class openlane.config.Macro(gds: ~typing.List[~openlane.common.types.Path], lef: ~typing.List[~openlane.common.types.Path], instances: ~typing.Dict[str, ~openlane.config.variable.Instance] = <factory>, vh: ~typing.List[~openlane.common.types.Path] = <factory>, nl: ~typing.List[~openlane.common.types.Path] = <factory>, pnl: ~typing.List[~openlane.common.types.Path] = <factory>, spef: ~typing.Dict[str, ~typing.List[~openlane.common.types.Path]] = <factory>, lib: ~typing.Dict[str, ~typing.List[~openlane.common.types.Path]] = <factory>, spice: ~typing.List[~openlane.common.types.Path] = <factory>, sdf: ~typing.Dict[str, ~typing.List[~openlane.common.types.Path]] = <factory>, json_h: ~openlane.common.types.Path | None = None)¶
Bases:
object
A data structure for storing definitions of Macros.
As it is typically stored in a dictionary in its superclass, the module name is not stored in any of these fields.
You will note most fields correspond to a
openlane.state.DesignFormat
entry IDs. This is not coincidental.- Parameters:
gds (List[Path]) – A list of GDSII files representing the design. At least one is required.
lef (List[Path]) – A list of LEF files representing the design. At least one is required.
instances (Dict[str, Instance]) –
A dictionary of
Instance
objects representing the instances of said macro.The keys for the dictionaries are the names of the instances.
nl (List[Path]) –
A list of netlists constituting the design.
The netlists must be valid Verilog netlists readable by tools such as OpenSTA.
Can be empty, however SPEF-based hierarchical static timing analysis will be unavailable.
spef (Dict[str, List[Path]]) –
A dictionary of parasitics annotations for the various netlists of the Macro.
The keys are wildcards for timing corners supported by a certain SPEF file.
Can be empty, however SPEF-based hierarchical static timing analysis will be unavailable.
lib (Dict[str, List[Path]]) –
A dictionary of timing library files.
The keys are wildcards for timing corners supported by a certain LIB file.
If both SPEF and LIB views are empty, the design may be black-boxed during STA.
spice (List[Path]) – A list of SPICE netlists constituting the design. May be useful in some flows.
sdf (Dict[str, List[Path]]) –
A dictionary of standard delay format files. May be useful in some flows.
The keys are wildcards for timing corners supported by a certain SPEF file.
json_h (Path | None) – A JSON file as generated by Yosys. Helpful in some flows.
vh (List[Path])
pnl (List[Path])
- class openlane.config.Variable(name: str, type: ~typing.Any, description: str, default: ~typing.Any | None = None, deprecated_names: ~typing.List[str | ~typing.Tuple[str, ~typing.Callable]] = <factory>, units: str | None = None, pdk: bool = False)¶
Bases:
object
An object encapsulating metadata on an OpenLane configuration variable, which is used to name, document and validate values supplied to
openlane.steps.Step
s oropenlane.flows.Flow
s.Values supplied for configuration variables are the primary interface by which users configure OpenLane flows.
- Parameters:
name (str) – A string name for the Variable. Because of backwards compatibility with OpenLane 1, the convention is
UPPER_SNAKE_CASE
.type (Any) –
A Python type object representing the variable.
Supported scalars:
int
decimal.Decimal
bool
str
Path
Supported products:
Union
(incl.Optional
)List
Tuple
Dict
Enum
Other:
dataclass
types composed of the above.
description (str) – A human-readable description of the variable. Used to generate help strings and documentation.
default (Any) –
A default value for the variable.
Optional variables have an implicit default value of
None
.deprecated_names (List[str | Tuple[str, Callable]]) –
A list of deprecated names for said variable.
An element of the list can alternative be a tuple of a name and a Callable used to perform a translation for when a renamed variable is also slightly modified.
units (str | None) – Used only in documentation: the unit corresponding to this object, i.e., µm, pF, etc. Can be any string, but for consistency, SI units must be represented in terms of their official symbols.
pdk (bool) –
Whether this variable is expected to be given a default value by a PDK or not.
If this is true, and the variable is not of an option type, a PDK must give this variable a default value in order to be marked compatible with a step.
If this is true and the variable is of an option type, a PDK may optionally provide a default value for this variable, however steps must presume it is
null
.If this is false, a PDK is not allowed to set a default value for this variable. In current versions of OpenLane, the value will be silently ignored, but warnings or errors may occur in future versions.
- property optional: bool¶
- Returns:
Whether a variable’s type is an Option type.
- property some: Any¶
- Returns:
The type of a variable presuming it is not None.
If a variable is not Optional, that is simply the type specified in the
type
attribute.
- type_repr_md(for_document: bool = False) str ¶
- Parameters:
for_document (bool) – Adds HTML line breaks between sum type separators for easier wrapping by web browsers/PDF renderers/what have you
- Returns:
A pretty Markdown string representation of the Variable’s type.
- Return type:
str
- desc_repr_md() str ¶
- Returns:
The description, but with newlines escaped for Markdown.
- Return type:
str
- class openlane.config.Meta(version: int = 1, flow: None | str | List[str] = None, substituting_steps: None | Dict[str, str | None] = None, step: str | None = None, openlane_version: None | str = '2.3.5')¶
Bases:
object
Constitutes metadata for a configuration object.
- Parameters:
version (int)
flow (None | str | List[str])
substituting_steps (None | Dict[str, str | None])
step (None | str)
openlane_version (None | str)
- class openlane.config.Config(*args, meta: Meta | None = None, **kwargs)¶
Bases:
GenericImmutableDict
[str
,Any
]A map from OpenLane configuration variable keys to their values.
It is recommended that you use
load()
to create new, validated configurations from dictionaries or files.- Parameters:
- copy(**overrides) Config ¶
Produces a shallow copy of the configuration object.
- Parameters:
overrides – A series of configuration overrides as key-value pairs. These values are NOT validated and you should not be overriding these haphazardly.
- Return type:
- to_raw_dict(include_meta: bool = True) Dict[str, Any] ¶
- Parameters:
include_meta (bool) – Whether to include the “meta” object or not
- Returns:
A raw dictionary representation including the
meta
object.- Return type:
Dict[str, Any]
- dumps(include_meta: bool = True, **kwargs) str ¶
- Parameters:
include_meta (bool) – Whether to include the
meta
object in the serialized string.kwargs – Passed to
json.dumps
.
- Returns:
A JSON string representing the the GenericDict object.
- Return type:
str
- copy_filtered(config_vars: Sequence[Variable], include_flow_variables: bool = True) Config ¶
Creates a new copy of the configuration object, but only with the configuration variables defined by the parameter.
- Parameters:
config_vars (Sequence[Variable]) – A list of configuration variables to include in the filtered copy.
include_flow_variables (bool) –
Whether to include the common flow variables in the copy or not.
This parameter is deprecated as of OpenLane 2.0.0b5 and should be set to
False
by callers.
- Returns:
The new copy
- Return type:
- with_increment(config_vars: Sequence[Variable], other_inputs: Mapping[str, Any], config_quiet: bool = False) Config ¶
Creates a new
Config
object by copying all values from the original in addition to any new variables (and removing any variables not in config_vars).Furthermore, inputs can be provided incrementally by passing the object
other_inputs
, which will also use these as overrides to the values in the baseConfig
object.All values, including those in the base
Config
object and inother_inputs
, will be re-validated.
- classmethod get_meta(config_in: str | PathLike | Mapping[str, Any], flow_override: str | None = None) Meta ¶
Returns the Meta object of a configuration dictionary or file.
- Parameters:
config_in (str | PathLike | Mapping[str, Any]) – A configuration object or file.
flow_override (str | None)
- Returns:
Either a Meta object, or if the file is invalid, None.
- Return type:
- classmethod interactive(DESIGN_NAME: str, PDK: str, STD_CELL_LIBRARY: str | None = None, PDK_ROOT: str | None = None, **kwargs) Config ¶
This constructs a partial configuration object that may be incrementally adjusted per-step, and activates OpenLane’s interactive mode.
The interactive mode is overall less rigid than the pure mode, adding various references to global objects to make the REPL or Notebook experience more pleasant, however, it is not as resilient as the pure mode and should not be used in production code.
- Parameters:
DESIGN_NAME (str) – The name of the design to be used.
PDK (str) – The name of the PDK.
STD_CELL_LIBRARY (str | None) –
The name of the standard cell library.
If not specified, the PDK’s default SCL will be used.
PDK_ROOT (str | None) –
Required if Volare is not installed.
If Volare is installed, this value can be used to optionally override Volare’s default.
kwargs –
Any overrides to PDK values and/or common flow default variables can be passed as keyword arguments to this function.
Useful examples are CLOCK_PORT, CLOCK_PERIOD, et cetera, which while not bound to a specific
Step
, affects most Steps’ behavior.
- Return type:
- classmethod load(config_in: str | PathLike | Mapping[str, Any] | Sequence[str | PathLike | Mapping[str, Any]], flow_config_vars: Sequence[Variable], *, config_override_strings: Sequence[str] | None = None, pdk: str | None = None, pdk_root: str | None = None, scl: str | None = None, design_dir: str | None = None, _load_pdk_configs: bool = True) Tuple[Config, str] ¶
Creates a new Config object based on a Tcl file, a JSON file, or a dictionary.
The returned config object is locked and cannot be modified.
- Parameters:
config_in (str | PathLike | Mapping[str, Any] | Sequence[str | PathLike | Mapping[str, Any]]) –
Either a file path to a JSON file or a Python Mapping object (such as
dict
) representing an unprocessed OpenLane configuration object.Tcl files are also supported, but are deprecated and will be removed in the future.
config_override_strings (Sequence[str] | None) – A list of “overrides” in the form of NAME=VALUE strings. These are primarily for running OpenLane from the command-line and strictly speaking should not be used in the API.
design_dir (str | None) –
The design directory for said configuration(s).
If not explicitly provided, the design directory will be the directory holding the last file in the list.
If no files are provided, this argument is required.
pdk (str | None) – A process design kit to use. Required unless specified via the “PDK” key in a configuration object.
pdk_root (str | None) –
Required if Volare is not installed.
If Volare is installed, this value can be used to optionally override Volare’s default.
scl (str | None) – A standard cell library to use. If not specified, the PDK’s default standard cell library will be used instead.
flow_config_vars (Sequence[Variable])
_load_pdk_configs (bool)
- Returns:
A tuple containing a Config object and the design directory.
- Return type:
Tuple[Config, str]
- exception openlane.config.InvalidConfig(config: str, warnings: List[str], errors: List[str], message: str | None = None, *args, **kwargs)¶
Bases:
ValueError
An error raised when a configuration under resolution is invalid.
- Parameters:
config (str) – A human-readable name for the particular configuration file causing this exception, i.e. whether it’s a PDK configuration file or a user configuration file.
warnings (List[str]) – A list of warnings generated during the loading of this configuration file.
errors (List[str]) – A list of errors generated during the loading of this configuration file.
args – Further arguments to be passed onto the constructor of
ValueError
.message (str | None) – An optional override for the Exception message.
kwargs – Further keyword arguments to be passed onto the constructor of
ValueError
.
- Return type:
None
- exception openlane.config.PassedDirectoryError(config: str | PathLike)¶
Bases:
ValueError
When a passed configuration file is in fact a directory.
- Parameters:
config (str | PathLike)
- Return type:
None
- exception openlane.config.UnknownExtensionError(config: str | PathLike)¶
Bases:
ValueError
When a passed configuration file has an unrecognized extension, i.e., not .json, .yml/.yaml or .tcl.
- Parameters:
config (str | PathLike)
- Return type:
None