openlane.common
API¶
Common Utilities Module¶
A number of common utility functions and classes used throughout the codebase.
- class openlane.common.TclUtils¶
Bases:
object
A collection of useful Tcl utilities.
- static escape(s: str) str ¶
- Returns:
If the string can be parsed by Tcl as a single token, the string is returned verbatim.
Otherwise, the string is returned in double quotes, with any unsafe characters escaped with a backslash.
- Parameters:
s (str)
- Return type:
str
- static join(ss: Iterable[str]) str ¶
- Parameters:
ss (Iterable[str]) – Input list
- Returns:
The input list converted to a Tcl-compatible list where each element is either a single token or double-quoted (i.e. interpreted by Tcl as a single element.)
- Return type:
str
- openlane.common.parse_metric_modifiers(metric_name: str) Tuple[str, Mapping[str, str]] ¶
Parses a metric name into a base and modifiers as specified in the METRICS2.1 naming convention.
- Parameters:
metric_name (str) – The name of the metric as generated by a utility.
- Returns:
A tuple of the base part as a string, then the modifiers as a key-value mapping.
- Return type:
Tuple[str, Mapping[str, str]]
- openlane.common.aggregate_metrics(input: Mapping[str, Any], aggregator_by_metric: Mapping[str, Tuple[int | float | Decimal, Callable[[Iterable[int | float | Decimal]], int | float | Decimal]] | Metric] | None = None) Dict[str, Any] ¶
Takes a set of metrics generated according to the METRICS2.1 naming convention.
- Parameters:
input (Mapping[str, Any]) – A mapping of strings to values of metrics.
aggregator_by_metric (Mapping[str, Tuple[int | float | Decimal, Callable[[Iterable[int | float | Decimal]], int | float | Decimal]] | Metric] | None) – A mapping of metric names to either: - A tuple of the initial accumulator and reducer to aggregate the values from all modifier metrics - A
Metric
class
- Returns:
A tuple of the base part as a string, then the modifiers as a key-value mapping.
- Return type:
Dict[str, Any]
- class openlane.common.GenericDictEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)¶
Bases:
JSONEncoder
A JSON encoder for
GenericDict
objects. Also handles some types not necessarily handled by the default JSON encoder, i.e., UserString, os.PathLike, Decimals, etcetera.It is recommended to use
GenericDict.to_json()
unless you know what you’re doing.- default(o)¶
Implement this method in a subclass such that it returns a serializable object for
o
, or calls the base implementation (to raise aTypeError
).For example, to support arbitrary iterators, you could implement default like this:
def default(self, o): try: iterable = iter(o) except TypeError: pass else: return list(iterable) # Let the base class default method raise the TypeError return JSONEncoder.default(self, o)
- class openlane.common.GenericDict(copying: Mapping[KT, VT] | None = None, /, overrides: Mapping[KT, VT] | None = None)¶
Bases:
Mapping
[KT
,VT
]A dictionary with generic keys and values that is compatible with Python 3.8.
- Parameters:
copying (Mapping[KT, VT] | None) – A base Mapping object to copy values from.
overrides (Mapping[KT, VT] | None) – Another mapping object to override the value from copying with.
- pop(key: KT, /) VT ¶
- Parameters:
key (KT) – The key to pop the value for.
- Returns:
The value for key. Raises
IndexError
if the key does not exist. The key/value pair is then deleted from the dictionary.- Return type:
VT
- copy() T ¶
Convenience replacement for object.__class__(object), which would create a copy of the
GenericDict
object.- Returns:
The copy
- Parameters:
self (T)
- Return type:
T
- to_raw_dict() dict ¶
- Returns:
A copy of the underlying Python built-in
dict
for this class.- Return type:
dict
- get_encoder() Type[GenericDictEncoder] ¶
- Returns:
A JSON encoder handling GenericDict objects.
- Return type:
Type[GenericDictEncoder]
- keys()¶
- Returns:
A set-like object providing a view of the keys of the GenericDict object.
- values()¶
- Returns:
A set-like object providing a view of the values of the GenericDict object.
- items() ItemsView[KT, VT] ¶
- Returns:
A set-like object providing a view of the GenericDict object as (key, value) tuples.
- Return type:
ItemsView[KT, VT]
- dumps(**kwargs) str ¶
- Parameters:
kwargs – Passed to
json.dumps
.- Returns:
A JSON string representing the the GenericDict object.
- Return type:
str
- check(key: KT, /) Tuple[KT | None, VT | None] ¶
Checks if a key exists and returns a tuple in the form
(key, value)
.- Parameters:
key (KT) – The key in question
- Returns:
If the key does not exist, the value of
key
will beNone
and so willvalue
. If the key exists,key
will be the key being checked for existence andvalue
will be the value assigned to said key in the GenericDict object.Do note
None
is a valid value for some keys, so simply checking if the second elementis not None
is insufficient to check whether a key exists.- Return type:
Tuple[KT | None, VT | None]
- update(incoming: Mapping[KT, VT])¶
A convenience function to update multiple values in the GenericDict object at the same time. :param incoming: The values to update
- Parameters:
incoming (Mapping[KT, VT])
- update_reorder(incoming: Mapping[KT, VT])¶
A convenience function to update multiple values in the GenericDict object at the same time. Pre-existing keys are deleted first so the values in incoming are emplaced at the end of the dictionary.
- Parameters:
incoming (Mapping[KT, VT]) – The values to update
- class openlane.common.GenericImmutableDict(copying: Mapping[KT, VT] | None = None, /, *args, **kwargs)¶
Bases:
GenericDict
[KT
,VT
]- Parameters:
copying (Mapping[KT, VT] | None)
- openlane.common.copy_recursive(input, translator: ~typing.Callable = <function idem>)¶
Copies any arbitrarily-deep nested structure of Mappings and/or Sequences.
- Parameters:
input – The input nested structure
translator (Callable) –
Before an object is appended, this function will be called to process the value.
By default,
idem()
is called.
- Returns:
The copy.
All sequences will become built-in
list
(s) and all mappings will become built-indict
(s).
- openlane.common.idem(obj: T, *args, **kwargs) T ¶
- Returns:
the parameter
obj
unchanged. Useful for some lambdas.- Parameters:
obj (T)
- Return type:
T
- openlane.common.get_openlane_root() str ¶
Returns the root OpenLane folder, i.e., the folder containing the
__init__.py
.- Return type:
str
- openlane.common.get_opdks_rev() str ¶
Gets the Open_PDKs revision confirmed compatible with this version of OpenLane.
- Return type:
str
- openlane.common.slugify(value: str, lower: bool = False) str ¶
- Parameters:
value (str) – Input string
lower (bool)
- Returns:
The input string converted to lower case, with all characters except alphanumerics, underscores and hyphens removed, and spaces and dots converted into hyphens.
Leading and trailing whitespace is stripped.
- Return type:
str
- openlane.common.protected(method)¶
A decorator to indicate protected methods.
It dynamically adds a statement to the effect in the docstring as well as setting an attribute,
protected
, toTrue
, but has no other effects.- Parameters:
f – Method to mark as protected
- openlane.common.final(f)¶
A decorator to indicate final methods and final classes.
Use this decorator to indicate to type checkers that the decorated method cannot be overridden, and decorated class cannot be subclassed. For example:
class Base: @final def done(self) -> None: ... class Sub(Base): def done(self) -> None: # Error reported by type checker ... @final class Leaf: ... class Other(Leaf): # Error reported by type checker ...
There is no runtime checking of these properties.
- openlane.common.mkdirp(path: str | PathLike)¶
Attempts to create a directory and all of its parents.
Does not fail if the directory already exists, however, it does fail if it is unable to create any of the components and/or if the path already exists as a file.
- Parameters:
path (str | PathLike) – A filesystem path for the directory
- class openlane.common.zip_first(a: Iterable, b: Iterable, fillvalue: Any)¶
Bases:
object
Works like
zip_longest
if |a| > |b| andzip
if |a| <= |b|.- Parameters:
a (Iterable)
b (Iterable)
fillvalue (Any)
- openlane.common.format_elapsed_time(elapsed_seconds: SupportsFloat) str ¶
- Parameters:
elapsed_seconds (SupportsFloat) – Total time elapsed in seconds
- Returns:
A string in the format
{hours}:{minutes}:{seconds}:{milliseconds}
- Return type:
str
- class openlane.common.Filter(filters: Iterable[str])¶
Bases:
object
Encapsulates commonly used wildcard-based filtering functions into an object.
- Parameters:
filters (Iterable[str]) –
A list of a wildcards supporting the fnmatch spec.
The wildcards will be split into an “allow” and “deny” list based on whether the filter is prefixed with a
!
.
- get_matching_wildcards(input: str) Generator[str, Any, None] ¶
- Parameters:
input (str) – An input to match wildcards against.
- Returns:
An iterable object for all wildcards in the allow list accepting
input
, and all wildcards in the deny list rejectinginput
.- Return type:
Generator[str, Any, None]
- match(input: str) bool ¶
- Parameters:
input (str) – An input string to either accept or reject
- Returns:
A boolean indicating whether the input: * Has matched at least one wildcard in the allow list * Has matched exactly 0 inputs in the deny list
- Return type:
bool
- filter(inputs: Iterable[str]) Generator[str, Any, None] ¶
- Parameters:
inputs (Iterable[str]) – A series of inputs to filter according to the wildcards.
- Returns:
An iterable object of any values in
inputs
that: * Have matched at least one wildcard in the allow list * Have matched exactly 0 inputs in the deny list- Return type:
Generator[str, Any, None]
- openlane.common.get_latest_file(in_path: str | PathLike, filename: str) Path | None ¶
- Parameters:
in_path (str | PathLike) – A directory to search in
filename (str) – The final filename
- Returns:
The latest file matching the parameters, by modification time
- Return type:
Path | None
- openlane.common.process_list_file(from_file: str | PathLike) List[str] ¶
Convenience function to process text files in a
.gitignore
-style format, i.e., those where the lines may be:A list element
A comment prefixed with
#
Blank
- Parameters:
from_file (str | PathLike) – The input text file.
- Returns:
A list of the strings listed in the file, ignoring lines prefixed with a
#
and empty lines.- Return type:
List[str]
- class openlane.common.Path(seq)¶
Bases:
UserString
,PathLike
A Path type for OpenLane configuration variables.
Basically just a string.
- exists() bool ¶
A convenience method calling
os.path.exists()
- Return type:
bool
- validate(message_on_err: str = '')¶
Raises an error if the path does not exist.
- Parameters:
message_on_err (str)
- class openlane.common.ScopedFile(*, contents='')¶
Bases:
Path
Creates a temporary file that remains valid while this variable is in scope, and is deleted upon deconstruction.
The object itself is a string pointing to that file path.
- Parameters:
contents – The contents of the temporary file to create.
- class openlane.common.Toolbox(tmp_dir: str)¶
Bases:
object
An assisting object shared by a Flow and all its constituent Steps.
The toolbox may create artifacts that are cached to avoid constant re-creation between steps.
- Parameters:
tmp_dir (str)
- aggregate_metrics(input: Dict[str, Any], aggregator_by_metric: Dict[str, Tuple[Any, Callable[[Iterable], Any]]]) Dict[str, Any] ¶
Deprecated since version 2.0.0b1: Use ‘aggregate_metrics’ from ‘openlane.common’
- Parameters:
input (Dict[str, Any])
aggregator_by_metric (Dict[str, Tuple[Any, Callable[[Iterable], Any]]])
- Return type:
Dict[str, Any]
- filter_views(config: Mapping[str, Any], views_by_corner: Mapping[str, Path | Iterable[Path]], timing_corner: str | None = None) List[Path] ¶
Given a mapping from (wildcards of) corner names to views, this function enumerates all views matching either the default timing corner or an explicitly-provided override.
- Parameters:
config (Mapping[str, Any]) – The configuration. Used solely to extract the default corner.
views_by_corner (Mapping[str, Path | Iterable[Path]]) – The mapping from (wild cards) of corner names to views.
corner – An explicit override for the default corner. Must be a fully qualified IPVT corner.
timing_corner (str | None)
- Returns:
The created list
- Return type:
List[Path]
- get_macro_views(config: Mapping[str, Any], view: DesignFormat, timing_corner: str | None = None, unless_exist: None | DesignFormat | Sequence[DesignFormat] = None) List[Path] ¶
For
Config
objects (or similar Mappings) that have Macro information, this function gets all Macro views matching a certainDesignFormat
for either the default timing corner or an explicitly-provided override.- Parameters:
config (Mapping[str, Any]) – The configuration.
view (DesignFormat) – The design format to return views of.
timing_corner (str | None) – An explicit override for the default corner set by the configuration.
corner – An explicit override for the default corner. Must be a fully qualified IPVT corner.
unless_exist (None | DesignFormat | Sequence[DesignFormat]) –
If a Macro also has a view for these
DesignFormat
s, do not return a result for the requestedDesignFormat
.Useful for if you want to return say, Netlists if reliable LIB files do not exist.
- Returns:
A list of the Macro views matched by the process described above.
- Return type:
List[Path]
- get_timing_files_categorized(config: Mapping[str, Any], timing_corner: str | None = None, prioritize_nl: bool = False) Tuple[str, List[Path], List[Path], List[Tuple[str, Path]]] ¶
Returns the lib files for a given configuration and timing corner.
- Parameters:
config (Mapping[str, Any]) – A configuration object or a similar mapping.
timing_corner (str | None) –
A fully qualified IPVT corner to get SCL libs for.
If not specified, the value for
DEFAULT_CORNER
from the SCL will be used.prioritize_nl (bool) –
Do not return lib files for macros that have gate-Level Netlists and SPEF views.
If set to
false
, only lib files are returned.
- Returns:
A tuple of: * The name of the timing corner * A list of lib files * A list of netlists * A list of tuples of instances and SPEFs
- Return type:
- get_timing_files(config: Mapping[str, Any], timing_corner: str | None = None, prioritize_nl: bool = False) Tuple[str, List[str]] ¶
Returns the lib files for a given configuration and timing corner.
- Parameters:
config (Mapping[str, Any]) – A configuration object or a similar mapping.
timing_corner (str | None) –
A fully qualified IPVT corner to get SCL libs for.
If not specified, the value for
DEFAULT_CORNER
from the SCL will be used.prioritize_nl (bool) –
Do not return lib files for macros that have gate-Level Netlists and SPEF views.
If set to
false
, only lib files are returned.
- Returns:
A tuple of:
The name of the timing corner
A heterogeneous list of files composed of: Lib files are returned as-is, Netlists are returned as-is, and SPEF files are returned in the format
{instance_name}@{spef_path}
.
It is left up to the step or tool to process this list as they see fit.
- Return type:
Tuple[str, List[str]]
- remove_cells_from_lib(input_lib_files: FrozenSet[str], excluded_cells: FrozenSet[str]) List[str] ¶
Creates a new lib file with some cells removed.
This function is memoized, i.e., results are cached for a specific set of inputs.
- Parameters:
input_lib_files (FrozenSet[str]) – A frozenset of input lib files.
excluded_cells (FrozenSet[str]) – A frozenset of wildcards of cells to remove from the files.
- Returns:
A path to the lib file with the removed cells.
- Return type:
List[str]
- get_lib_voltage(input_lib: str) Decimal | None ¶
Extract the voltage from the default operating conditions of a liberty file.
Returns
None
if and only if thedefault_operating_conditions
key does not exist and the number of operating conditions enumerated is not exactly 1 (one).- Parameters:
input_lib (str) – The lib file in question
- Returns:
The voltage in question
- Return type:
Decimal | None
- class openlane.common.DRC(module: str, violations: Dict[str, Violation])¶
Bases:
object
A primitive database representing DRC violations generated by a design.
- Parameters:
module (str)
violations (Dict[str, Violation])
- classmethod from_magic(report: TextIOWrapper) Tuple[DRC, int] ¶
Parses a report generated by Magic into a DRC object.
- Parameters:
report (TextIOWrapper) – A text input stream containing the report in question. You can pass the result of
open("drc.rpt")
, for example.- Returns:
A tuple of the DRC object and an int representing the number of DRC violations.
- Return type:
Tuple[DRC, int]
- dumps()¶
- Returns:
The DRC object as a JSON string.
- to_klayout_xml(out: BufferedIOBase)¶
Converts the DRC object to a KLayout-compatible XML database.
- Parameters:
out (BufferedIOBase) – A binary output stream to the target XML file. You can pass the result of
open("drc.xml", "wb")
, for example.
- class openlane.common.Violation(rules: List[Tuple[str, str]], description: str, bounding_boxes: List[Tuple[decimal.Decimal, decimal.Decimal, decimal.Decimal, decimal.Decimal]] = <factory>)¶
Bases:
object
- Parameters:
rules (List[Tuple[str, str]])
description (str)
bounding_boxes (List[Tuple[Decimal, Decimal, Decimal, Decimal]])
- openlane.common.get_tpe() ThreadPoolExecutor ¶
- Returns:
OpenLane’s global
ThreadPoolExecutor
. This is used to run steps, so do not use them inside steps to avoid a deadlock.- Return type:
ThreadPoolExecutor
- openlane.common.set_tpe(tpe: ThreadPoolExecutor)¶
Allows replacing OpenLane’s global
ThreadPoolExecutor
with a customized one.It will be used inside steps, so use different TPEs inside steps to avoid a deadlock.
- Parameters:
tpe (ThreadPoolExecutor) – The replacement ThreadPoolExecutor
- class openlane.common.RingBuffer(t: Type[VT], max: int)¶
Bases:
Iterable
[VT
]A generic ring (circular) buffer that automatically pops the element at the head when full, and emplaces a new element in its place.
- Parameters:
t (Type[VT])
max (int)
Submodule |
Short Description |
---|---|
Metrics Module |