librelane 2.4.0.dev2__py3-none-any.whl → 2.4.7__py3-none-any.whl

librelane/flows/flow.py

@@ -375,7 +375,7 @@ class Flow(ABC):
         self.progress_bar = FlowProgressBar(self.name)
 
     @classmethod
-    def get_help_md(Self) -> str:  # pragma: no cover
+    def get_help_md(Self, myst_anchors: bool = False) -> str:  # pragma: no cover
         """
         :returns: rendered Markdown help for this Flow
         """
@@ -383,10 +383,12 @@ class Flow(ABC):
         if Self.__doc__:
             doc_string = textwrap.dedent(Self.__doc__)
 
+        flow_anchor = f"(flow-{slugify(Self.__name__, lower=True)})="
+
         result = (
             textwrap.dedent(
                 f"""\
-                (flow-{slugify(Self.__name__, lower=True)})=
+                {flow_anchor * myst_anchors}
                 ### {Self.__name__}
 
                 ```{{eval-rst}}
@@ -413,35 +415,53 @@ class Flow(ABC):
         flow_config_vars = Self.config_vars
 
         if len(flow_config_vars):
+            config_var_anchors = f"({slugify(Self.__name__, lower=True)}-config-vars)="
             result += textwrap.dedent(
                 f"""
-                ({slugify(Self.__name__, lower=True)}-config-vars)=
-
+                {config_var_anchors * myst_anchors}
                 #### Flow-specific Configuration Variables
-
-                | Variable Name | Type | Description | Default | Units |
-                | - | - | - | - | - |
                 """
             )
-            for var in flow_config_vars:
-                units = var.units or ""
-                pdk_superscript = "<sup>PDK</sup>" if var.pdk else ""
-                result += f"| `{var.name}`{{#{var._get_docs_identifier(Self.__name__)}}}{pdk_superscript} | {var.type_repr_md()} | {var.desc_repr_md()} | `{var.default}` | {units} |\n"
+            result += Variable._render_table_md(
+                flow_config_vars,
+                myst_anchor_owner_id=Self.__name__ if myst_anchors else None,
+            )
             result += "\n"
 
         if len(Self.Steps):
             result += "#### Included Steps\n"
             for step in Self.Steps:
-                if hasattr(step, "long_name"):
-                    name = step.long_name
-                elif hasattr(step, "name"):
-                    name = step.name
+                imp_id = step.get_implementation_id()
+                if myst_anchors:
+                    result += f"* [`{step.id}`](./step_config_vars.md#step-{slugify(imp_id, lower=True)})\n"
                 else:
-                    name = step.id
-                result += f"* [`{step.id}`](./step_config_vars.md#{slugify(name)})\n"
+                    variant_str = ""
+                    if imp_id != step.id:
+                        variant_str = f" (implementation: `{imp_id}`)"
+                    result += f"* `{step.id}`{variant_str}\n"
 
         return result
 
+    @classmethod
+    def display_help(Self):  # pragma: no cover
+        """
+        Displays Markdown help for a given flow.
+
+        If in an IPython environment, it's rendered using ``IPython.display``.
+        Otherwise, it's rendered using ``rich.markdown``.
+        """
+        try:
+            get_ipython()  # type: ignore
+
+            import IPython.display
+
+            IPython.display.display(IPython.display.Markdown(Self.get_help_md()))
+        except NameError:
+            from ..logging import console
+            from rich.markdown import Markdown
+
+            console.log(Markdown(Self.get_help_md()))
+
     def get_all_config_variables(self) -> List[Variable]:
         """
         :returns: All configuration variables for this Flow, including
@@ -510,8 +530,11 @@ class Flow(ABC):
 
         :param with_initial_state: An optional initial state object to use.
             If not provided:
+
             * If resuming a previous run, the latest ``state_out.json`` (by filesystem modification date)
+
             * If not, an empty state object is created.
+
         :param tag: A name for this invocation of the flow. If not provided,
             one based on a date string will be created.
 
@@ -796,7 +819,6 @@ class Flow(ABC):
             DesignFormat.POWERED_NETLIST: (os.path.join("verilog", "gl"), "v"),
             DesignFormat.DEF: ("def", "def"),
             DesignFormat.LEF: ("lef", "lef"),
-            DesignFormat.SDF: (os.path.join("sdf", "multicorner"), "sdf"),
             DesignFormat.SPEF: (os.path.join("spef", "multicorner"), "spef"),
             DesignFormat.LIB: (os.path.join("lib", "multicorner"), "lib"),
             DesignFormat.GDS: ("gds", "gds"),
@@ -855,38 +877,67 @@ class Flow(ABC):
                         file_path, os.path.join(to_dir, file), follow_symlinks=True
                     )
 
-        signoff_folder = os.path.join(
-            path, "signoff", self.config["DESIGN_NAME"], "librelane-signoff"
-        )
-        mkdirp(signoff_folder)
+        def find_one(pattern):
+            result = glob.glob(pattern)
+            if len(result) == 0:
+                return None
+            return result[0]
 
-        # resolved.json
+        signoff_dir = os.path.join(path, "signoff", self.config["DESIGN_NAME"])
+        openlane_signoff_dir = os.path.join(signoff_dir, "openlane-signoff")
+        mkdirp(openlane_signoff_dir)
+
+        ## resolved.json
         shutil.copyfile(
             self.config_resolved_path,
-            os.path.join(signoff_folder, "resolved.json"),
+            os.path.join(openlane_signoff_dir, "resolved.json"),
             follow_symlinks=True,
         )
 
-        # Logs
-        mkdirp(signoff_folder)
-        copy_dir_contents(self.run_dir, signoff_folder, "*.log")
+        ## metrics
+        with open(os.path.join(signoff_dir, "metrics.csv"), "w", encoding="utf8") as f:
+            last_state.metrics_to_csv(f)
+
+        ## flow logs
+        mkdirp(openlane_signoff_dir)
+        copy_dir_contents(self.run_dir, openlane_signoff_dir, "*.log")
 
-        # Step-specific
+        ### step-specific signoff logs and reports
         for step in self.step_objects:
             reports_dir = os.path.join(step.step_dir, "reports")
             step_imp_id = step.get_implementation_id()
+            if step_imp_id == "Magic.DRC":
+                if drc_rpt := find_one(os.path.join(reports_dir, "*.rpt")):
+                    shutil.copyfile(
+                        drc_rpt, os.path.join(openlane_signoff_dir, "drc.rpt")
+                    )
+                if drc_xml := find_one(os.path.join(reports_dir, "*.xml")):
+                    # Despite the name, this is the Magic DRC report simply
+                    # converted into a KLayout-compatible format. Confusing!
+                    drc_xml_out = os.path.join(openlane_signoff_dir, "drc.klayout.xml")
+                    with open(drc_xml, encoding="utf8") as i, open(
+                        drc_xml_out, "w", encoding="utf8"
+                    ) as o:
+                        o.write(
+                            "<!-- Despite the name, this is the Magic DRC report in KLayout format. -->\n"
+                        )
+                        shutil.copyfileobj(i, o)
+            if step_imp_id == "Netgen.LVS":
+                if lvs_rpt := find_one(os.path.join(reports_dir, "*.rpt")):
+                    shutil.copyfile(
+                        lvs_rpt, os.path.join(openlane_signoff_dir, "lvs.rpt")
+                    )
             if step_imp_id.endswith("DRC") or step_imp_id.endswith("LVS"):
-                if os.path.exists(reports_dir):
-                    copy_dir_contents(reports_dir, signoff_folder)
-            if step_imp_id.endswith("LVS"):
-                copy_dir_contents(step.step_dir, signoff_folder, "*.log")
+                copy_dir_contents(step.step_dir, openlane_signoff_dir, "*.log")
             if step_imp_id.endswith("CheckAntennas"):
                 if os.path.exists(reports_dir):
                     copy_dir_contents(
-                        reports_dir, signoff_folder, "antenna_summary.rpt"
+                        reports_dir, openlane_signoff_dir, "antenna_summary.rpt"
                     )
             if step_imp_id.endswith("STAPostPNR"):
-                timing_report_folder = os.path.join(signoff_folder, "timing-reports")
+                timing_report_folder = os.path.join(
+                    openlane_signoff_dir, "timing-reports"
+                )
                 mkdirp(timing_report_folder)
                 copy_dir_contents(step.step_dir, timing_report_folder, "*summary.rpt")
                 for dir in os.listdir(step.step_dir):
@@ -897,6 +948,18 @@ class Flow(ABC):
                     mkdirp(target)
                     copy_dir_contents(dir_path, target, "*.rpt")
 
+        # 3. SDF
+        #   (This one, as with many things in the Efabless format, is special)
+        if sdf := last_state[DesignFormat.SDF]:
+            assert isinstance(sdf, dict), "SDF is not a dictionary"
+            for corner, view in sdf.items():
+                assert isinstance(view, Path), "SDF state out returned multiple paths"
+                target_dir = os.path.join(signoff_dir, "sdf", corner)
+                mkdirp(target_dir)
+                shutil.copyfile(
+                    view, os.path.join(target_dir, f"{self.config['DESIGN_NAME']}.sdf")
+                )
+
     @deprecated(
         version="2.0.0a46",
         reason="Use .progress_bar.set_max_stage_count",
@@ -938,8 +1001,9 @@ class Flow(ABC):
         A factory singleton for Flows, allowing Flow types to be registered and then
         retrieved by name.
 
-        See https://en.wikipedia.org/wiki/Factory_(object-oriented_programming) for
-        a primer.
+        See
+        `Factory (object-oriented programming) on Wikipedia <https://en.wikipedia.org/wiki/Factory_(object-oriented_programming)>`_
+        for a primer.
         """
 
         __registry: ClassVar[Dict[str, Type[Flow]]] = {}

librelane/help/__main__.py

@@ -0,0 +1,39 @@
+# Copyright 2025 LibreLane Contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from ..common.cli import formatter_settings
+from ..flows import Flow
+from ..steps import Step
+from ..logging import console
+
+import cloup
+
+
+@cloup.command(formatter_settings=formatter_settings)
+@cloup.argument("step_or_flow")
+@cloup.pass_context
+def cli(ctx, step_or_flow):
+    """
+    Displays rich help for the step or flow in question.
+    """
+    if TargetFlow := Flow.factory.get(step_or_flow):
+        TargetFlow.display_help()
+    elif TargetStep := Step.factory.get(step_or_flow):
+        TargetStep.display_help()
+    else:
+        console.log(f"Unknown Flow or Step '{step_or_flow}'.")
+        ctx.exit(-1)
+
+
+if __name__ == "__main__":
+    cli()

librelane/scripts/magic/def/mag_gds.tcl

@@ -77,5 +77,3 @@ if { $::env(MAGIC_GDS_POLYGON_SUBCELLS) } {
 
 gds write $::env(SAVE_MAG_GDS)
 puts "\[INFO\] GDS Write Complete"
-
-exit 0

librelane/scripts/magic/drc.tcl

@@ -76,4 +76,3 @@ puts stdout "\[INFO\] Saving mag view with DRC errors ($mag_view)"
 # WARNING: changes the name of the cell; keep as last step
 save $mag_view
 puts stdout "\[INFO\] Saved"
-exit 0

librelane/scripts/magic/gds/extras_mag.tcl

@@ -43,5 +43,3 @@ if {  [info exist ::env(EXTRA_GDS_FILES)] } {
 		puts "\[INFO\] Saved mag view from $gds_file under $::env(STEP_DIR)"
 	}
 }
-
-exit 0

librelane/scripts/magic/gds/mag_with_pointers.tcl

@@ -29,4 +29,3 @@ set final_filepath $::env(signoff_tmpfiles)/gds_ptrs.mag
 file rename -force $::env(signoff_tmpfiles)/$::env(DESIGN_NAME).mag $final_filepath
 
 puts "\[INFO\] Wrote $final_filepath including GDS pointers."
-exit 0

librelane/scripts/magic/lef/extras_maglef.tcl

@@ -59,5 +59,3 @@ foreach design_name [cellname list allcells] {
 	puts $fp [join $new_mag_lines "\n"]
 	close $fp
 }
-
-exit 0

librelane/scripts/magic/lef/maglef.tcl

@@ -24,4 +24,3 @@ cellname filepath $::env(DESIGN_NAME).lef $::env(signoff_results)
 save
 
 puts "\[INFO\] DONE GENERATING MAGLEF VIEW"
-exit 0

librelane/scripts/magic/wrapper.tcl

@@ -17,3 +17,5 @@ if {[catch {source $::env(_MAGIC_SCRIPT)} err]} {
     puts "Error: $err"
     exit 1
 }
+
+exit 0

librelane/scripts/odbpy/defutil.py

@@ -21,7 +21,6 @@ from decimal import Decimal
 
 from reader import click_odb, click
 from typing import Tuple, List
-from exception_codes import METAL_LAYER_ERROR, FORMAT_ERROR, NOT_FOUND_ERROR
 
 
 @click.group()
@@ -249,13 +248,19 @@ def relocate_pins(db, input_lefs, template_def, permissive, copy_def_power=False
             pin_name = bterm.getName()
             pin_net_name = bterm.getNet().getName()
             pin_net = output_block.findNet(pin_net_name)
+            new_net_created = False
             if pin_net is None:
                 pin_net = odb.dbNet.create(output_block, pin_net_name, True)
                 pin_net.setSpecial()
                 pin_net.setSigType(bterm.getSigType())
-            pin_bterm = odb.dbBTerm.create(pin_net, pin_name)
-            pin_bterm.setSigType(bterm.getSigType())
-            output_bterms.append(pin_bterm)
+                new_net_created = True
+            pin_bterm = output_block.findBTerm(pin_name)
+            if pin_bterm is None:
+                pin_bterm = odb.dbBTerm.create(pin_net, pin_name)
+                pin_bterm.setSigType(bterm.getSigType())
+                output_bterms.append(pin_bterm)
+            elif new_net_created:
+                pin_bterm.connect(pin_net)
 
     grid_errors = False
     for output_bterm in output_bterms:
@@ -481,7 +486,7 @@ def parse_obstructions(obstructions) -> List[Tuple[str, List[int]]]:
                 f"[ERROR] Incorrectly formatted input {obs}.\n Format: layer llx lly urx ury, ...",
                 file=sys.stderr,
             )
-            sys.exit(FORMAT_ERROR)
+            sys.exit(1)
         else:
             layer = m.group("layer")
             bbox = [Decimal(x) for x in m.group("bbox").split()]
@@ -505,8 +510,8 @@ def add_obstructions(reader, input_lefs, obstructions):
         layer = obs[0]
         odb_layer = reader.tech.findLayer(layer)
         if odb_layer is None:
-            print(f"[ERROR] layer {layer} doesn't exist.", file=sys.stderr)
-            sys.exit(METAL_LAYER_ERROR)
+            print(f"[ERROR] Layer '{layer}' not found.", file=sys.stderr)
+            sys.exit(1)
         bbox = obs[1]
         dbu = reader.tech.getDbUnitsPerMicron()
         bbox = [int(x * dbu) for x in bbox]
@@ -550,8 +555,8 @@ def remove_obstructions(reader, input_lefs, obstructions):
         bbox = [int(x * dbu) for x in bbox]  # To dbus
         found = False
         if reader.tech.findLayer(layer) is None:
-            print(f"[ERROR] layer {layer} doesn't exist.", file=sys.stderr)
-            sys.exit(METAL_LAYER_ERROR)
+            print(f"[ERROR] Layer '{layer}' not found.", file=sys.stderr)
+            sys.exit(1)
         for odb_obstruction in existing_obstructions:
             odb_layer, odb_bbox, odb_obj = odb_obstruction
             if (odb_layer, odb_bbox) == (layer, bbox):
@@ -565,7 +570,7 @@ def remove_obstructions(reader, input_lefs, obstructions):
                 f"[ERROR] Obstruction on {layer} at {bbox} (DBU) not found.",
                 file=sys.stderr,
             )
-            sys.exit(NOT_FOUND_ERROR)
+            sys.exit(1)
 
 
 cli.add_command(remove_obstructions)

librelane/scripts/odbpy/eco_buffer.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+# Copyright 2025 Efabless Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import sys
+from reader import click_odb, click, odb
+import grt as GRT
+
+
+def average_location(instances):
+    locations = [instance.getLocation() for instance in instances]
+    x_sum = sum(loc[0] for loc in locations)
+    y_sum = sum(loc[1] for loc in locations)
+    return (x_sum // len(locations), y_sum // len(locations))
+
+
+@click.command()
+@click_odb
+def cli(reader):
+    grt = reader.design.getGlobalRouter()
+    dpl = reader.design.getOpendp()
+
+    insts_to_temporarily_lock_then_unlock_later = []
+    for inst in reader.block.getInsts():
+        if inst.getPlacementStatus() != "LOCKED":
+            insts_to_temporarily_lock_then_unlock_later.append(
+                (inst, inst.getPlacementStatus())
+            )
+            inst.setPlacementStatus("LOCKED")
+
+    reader._grt_setup(grt)
+
+    grt_inc = GRT.IncrementalGRoute(grt, reader.block)
+    i = 0
+
+    eco_buffers = reader.config["INSERT_ECO_BUFFERS"] or []
+    for target_info in eco_buffers:
+        target_name, target_pin = target_info["target"].split("/")
+        name_escaped = reader.escape_verilog_name(target_name)
+        buffer_master = target_info["buffer"]
+
+        master = reader.db.findMaster(buffer_master)
+        if master is None:
+            print(
+                f"[ERROR] Buffer type '{buffer_master}' not found.",
+                file=sys.stderr,
+            )
+            exit(-1)
+
+        target = reader.block.findInst(name_escaped)
+        if target is None:
+            print(f"[ERROR] Instance '{target_name}' not found.", file=sys.stderr)
+            exit(-1)
+
+        target_iterm = target.findITerm(target_pin)
+        if target_iterm is None:
+            print(
+                f"[ERROR] Pin '{target_pin}' not found for instance '{target_name}'.",
+                file=sys.stderr,
+            )
+            exit(-1)
+
+        net = target_iterm.getNet()
+        if net is None:
+            print(
+                f"[ERROR] Net not found on pin '{target_pin}' of instance '{target_name}'.",
+                file=sys.stderr,
+            )
+            exit(-1)
+
+        new_buf_name = f"eco_buffer_{i}"
+        new_net_name = f"eco_buffer_{i}_net"
+        while (
+            reader.block.findInst(new_buf_name) is not None
+            or reader.block.findNet(new_net_name) is not None
+        ):
+            i += 1
+            new_buf_name = f"eco_buffer_{i}"
+            new_net_name = f"eco_buffer_{i}_net"
+
+        # Prepare buffer cell, net
+        eco_buffer = odb.dbInst.create(reader.block, master, new_buf_name)
+        eco_net = odb.dbNet.create(reader.block, new_net_name)
+        buffer_iterms = eco_buffer.getITerms()
+        buffer_a = None
+        for iterm in buffer_iterms:
+            if iterm.isInputSignal():
+                buffer_a = iterm
+                break  # Exit loop once input is found
+        if buffer_a is None:
+            print(
+                f"[ERROR] Buffer {buffer_master} has no input signals.",
+                file=sys.stderr,
+            )
+            exit(-1)
+
+        buffer_x = None
+        for iterm in buffer_iterms:
+            if iterm.isOutputSignal():
+                buffer_x = iterm
+                break  # Exit loop once output is found
+        if buffer_x is None:
+            print(
+                f"[ERROR] Buffer {buffer_master} has no output signals.",
+                file=sys.stderr,
+            )
+            exit(-1)
+
+        location_instances = [target]
+        net_iterms = net.getITerms()
+        if target_iterm.getIoType() == "INPUT":
+            driver_iterms = [
+                iterm for iterm in net_iterms if iterm.getIoType() in ["OUTPUT"]
+            ]
+            drivers = [iterm.getInst() for iterm in driver_iterms]
+            location_instances.extend(drivers)
+
+            target_iterm.disconnect()
+            buffer_a.connect(net)
+            buffer_x.connect(eco_net)
+            target_iterm.connect(eco_net)
+        elif target_iterm.getIoType() == "OUTPUT":
+            sink_iterms = [
+                iterm for iterm in net_iterms if iterm.getIoType() in ["INPUT", "INOUT"]
+            ]
+            sinks = [iterm.getInst() for iterm in sink_iterms]
+            location_instances.extend(sinks)
+
+            target_iterm.disconnect()
+            target_iterm.connect(eco_net)
+            buffer_a.connect(eco_net)
+            buffer_x.connect(net)
+        else:
+            print(
+                f"[ERROR] {target_name}/{target_pin} is neither an INPUT or an OUTPUT and is unsupported by this script. To buffer an INOUT port, buffer its drivers instead.",
+                file=sys.stderr,
+            )
+            exit(-1)
+
+        if target_info.get("placement") is not None:
+            eco_x, eco_y = target_info["placement"]
+            eco_x = reader.block.micronsToDbu(float(eco_x))
+            eco_y = reader.block.micronsToDbu(float(eco_y))
+            eco_loc = (eco_x, eco_y)
+        else:
+            eco_loc = average_location(location_instances)
+
+        eco_buffer.setOrient("R0")
+        eco_buffer.setLocation(*eco_loc)
+        eco_buffer.setPlacementStatus("PLACED")
+        grt.addDirtyNet(net)
+        grt.addDirtyNet(eco_net)
+
+    site = reader.rows[0].getSite()
+    max_disp_x = int(
+        reader.design.micronToDBU(reader.config["PL_MAX_DISPLACEMENT_X"])
+        / site.getWidth()
+    )
+    max_disp_y = int(
+        reader.design.micronToDBU(reader.config["PL_MAX_DISPLACEMENT_Y"])
+        / site.getHeight()
+    )
+    dpl.detailedPlacement(max_disp_x, max_disp_y)
+
+    grt_inc.updateRoutes(True)
+
+    for inst, previous_status in insts_to_temporarily_lock_then_unlock_later:
+        inst.setPlacementStatus(previous_status)
+
+
+if __name__ == "__main__":
+    cli()