librelane 2.4.0__py3-none-any.whl

librelane/container.py

@@ -0,0 +1,285 @@
+# Copyright 2023 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.
+
+## This file is internal to LibreLane and is not part of the API.
+import os
+import re
+import uuid
+import shlex
+import pathlib
+import subprocess
+from typing import List, NoReturn, Sequence, Optional, Union, Tuple
+
+import httpx
+import semver
+
+from .common import mkdirp
+from .logging import err, info, warn
+from .env_info import ContainerInfo, OSInfo
+
+__file_dir__ = os.path.dirname(os.path.abspath(__file__))
+
+
+def permission_args(osinfo: OSInfo) -> List[str]:
+    if (
+        osinfo.kernel == "Linux"
+        and isinstance(osinfo.container_info, ContainerInfo)
+        and osinfo.container_info.engine == "docker"
+        and not osinfo.container_info.rootless
+    ):
+        uid = os.getuid()
+        gid = os.getgid()
+
+        return ["--user", f"{uid}:{gid}"]
+
+    return []
+
+
+def gui_args(osinfo: OSInfo) -> List[str]:
+    args = []
+    if osinfo.kernel == "Linux":
+        if os.environ.get("DISPLAY") is None:
+            warn(
+                "DISPLAY environment variable not set. GUI features will not be available."
+            )
+        else:
+            args += [
+                "-e",
+                f"DISPLAY={os.environ.get('DISPLAY')}",
+                "-v",
+                "/tmp/.X11-unix:/tmp/.X11-unix",
+                "-v",
+                f"{os.path.expanduser('~')}/.Xauthority:/.Xauthority",
+                "--network",
+                "host",
+                "--security-opt",
+                "seccomp=unconfined",
+            ]
+    return args
+
+
+def image_exists(ce_path: str, image: str) -> bool:
+    images = (
+        subprocess.check_output([ce_path, "images", image])
+        .decode("utf8")
+        .rstrip()
+        .split("\n")[1:]
+    )
+    return len(images) >= 1
+
+
+def remote_manifest_exists(image: str) -> bool:
+    registry = "docker.io"
+    image_elements = image.split("/", maxsplit=1)
+    if len(image_elements) > 1:
+        registry = image_elements[0]
+        image = image_elements[1]
+    elements = image.split(":")
+    repo = elements[0]
+    tag = "latest"
+    if len(elements) > 1:
+        tag = elements[1]
+
+    url = None
+    if registry == "docker.io":
+        url = f"https://registry.hub.docker.com/v2/repositories/{repo}/tags/{tag}"
+    elif registry == "ghcr.io":
+        url = f"https://ghcr.io/v2/{repo}/manifests/{tag}"
+    else:
+        err(f"Unknown registry '{registry}'.")
+        return False
+
+    try:
+        httpx.Client(follow_redirects=True).get(
+            url, headers={"Accept": "application/json"}
+        )
+    except httpx.NetworkError:
+        err("Couldn't connect to the internet to pull container images.")
+        return False
+    except httpx.HTTPStatusError as e:
+        err(
+            f"The image {image} was not found. This may be because the CI for this image is running- in which case, please try again later. (error: {e})"
+        )
+        return False
+    return True
+
+
+def ensure_image(ce_path: str, image: str) -> bool:
+    if image_exists(ce_path, image):
+        return True
+
+    try:
+        subprocess.check_call([ce_path, "pull", image])
+    except subprocess.CalledProcessError:
+        err(f"Failed to pull image '{image}' from the container registries.")
+        return False
+
+    return True
+
+
+dos_path_sep = re.compile(r"\\")
+
+
+def sanitize_path(path: Union[str, os.PathLike]) -> Tuple[str, str]:
+    """
+    :returns: A tuple of:
+        - The host path, processed ``abspath``
+        - The target path, on UNIX-like operating systems it's identical to the
+          host path, but on Windows, the path is translated to a valid UNIX path
+          as follows:
+          - Backslashes are converted into forward slashes
+          - The drive letter (e.g. C:) is converted to a root directory (e.g. /c)
+    """
+    path_str = str(path)
+    abspath = os.path.abspath(path_str)
+    mountable_path = abspath
+    if os.path.sep == "\\":
+        mountable_path = f"/{abspath[0]}" + dos_path_sep.sub("/", abspath)[2:]
+    return (abspath, mountable_path)
+
+
+def container_version_error(input: str, against: str) -> Optional[str]:
+    if input == "UNKNOWN":
+        return (
+            "Could not determine version for %s. You may encounter unexpected issues."
+        )
+    if semver.compare(input, against) < 0:
+        return f"Your %s version ({input}) is out of date. You may encounter unexpected issues."
+    return None
+
+
+def ubuntu_version_at_least(current: str, minimum: str) -> bool:
+    if current == "UNKNOWN":
+        return False
+    return tuple(map(int, current.split("."))) >= tuple(map(int, minimum.split(".")))
+
+
+def run_in_container(
+    image: str,
+    args: Sequence[str],
+    pdk_root: Optional[str] = None,
+    pdk: Optional[str] = None,
+    scl: Optional[str] = None,
+    other_mounts: Optional[Sequence[str]] = None,
+    tty: bool = False,
+) -> NoReturn:
+    # If imported at the top level, would interfere with Conda where Volare
+    # would not be installed.
+    import ciel
+
+    osinfo = OSInfo.get()
+    if not osinfo.supported:
+        warn(
+            f"Unsupported host operating system '{osinfo.kernel}'. You may encounter unexpected issues."
+        )
+
+    if not isinstance(osinfo.container_info, ContainerInfo):
+        raise FileNotFoundError("No compatible container engine found.")
+
+    ce_path = osinfo.container_info.path
+    assert ce_path is not None
+
+    engine_name = osinfo.container_info.engine.lower()
+    if engine_name == "docker":
+        if error := container_version_error(osinfo.container_info.version, "25.0.5"):
+            warn(error % engine_name)
+    elif engine_name == "podman":
+        if osinfo.distro.lower() == "ubuntu" and not ubuntu_version_at_least(
+            osinfo.distro_version, "24.04"
+        ):
+            warn(
+                "Versions of Podman for Ubuntu before Ubuntu 24.04 are generally pretty buggy. We recommend using Docker instead if possible."
+            )
+        elif error := container_version_error(osinfo.container_info.version, "4.1.0"):
+            warn(error % engine_name)
+    else:
+        warn(
+            f"Unsupported container engine referenced by '{osinfo.container_info.path}'. You may encounter unexpected issues."
+        )
+
+    if not ensure_image(ce_path, image):
+        raise ValueError(f"Failed to use image '{image}'.")
+
+    terminal_args = ["-i"]
+    if tty:
+        terminal_args.append("-t")
+
+    mount_args = []
+    from_home, to_home = sanitize_path(pathlib.Path.home())
+
+    mount_args += ["-v", f"{from_home}:{to_home}"]
+
+    from_pdk, to_pdk = sanitize_path(ciel.get_ciel_home(pdk_root))
+
+    try:
+        mkdirp(from_pdk)
+    except FileExistsError:
+        raise ValueError(f"Invalid PDK root: '{from_pdk}' is a file")
+
+    mount_args += [
+        "-v",
+        f"{from_pdk}:{to_pdk}",
+        "-e",
+        f"PDK_ROOT={to_pdk}",
+    ]
+
+    if pdk is not None:
+        mount_args += ["-e", f"PDK={pdk}"]
+
+    if scl is not None:
+        mount_args += [
+            "-e",
+            f"STD_CELL_LIBRARY={scl}",
+        ]
+
+    from_cwd, to_cwd = sanitize_path(os.getcwd())
+    if not from_cwd.startswith(from_home):
+        mount_args += ["-v", f"{from_cwd}:{to_cwd}"]
+    mount_args += ["-w", to_cwd]
+
+    if other_mounts is not None:
+        for mount in other_mounts:
+            if os.path.isdir(mount):
+                mount_from, mount_to = sanitize_path(mount)
+                mount_args += ["-v", f"{mount_from}:{mount_to}"]
+                mkdirp(mount_from)
+            else:
+                mount_args += ["-v", f"{mount}"]
+
+    container_id = str(uuid.uuid4())
+
+    if os.getenv("_MOUNT_HOST_LIBRELANE") == "1":
+        host_librelane_pythonpath = os.path.dirname(__file_dir__)
+        mount_args += ["-v", f"{host_librelane_pythonpath}:/host_librelane"]
+
+    cmd = (
+        [
+            ce_path,
+            "run",
+            "--rm",
+            "--name",
+            container_id,
+        ]
+        + terminal_args
+        + permission_args(osinfo)
+        + mount_args
+        + gui_args(osinfo)
+        + [image]
+        + list(args)
+    )
+
+    info("Running containerized command:")
+    print(shlex.join(cmd))
+
+    os.execlp(ce_path, *cmd)

librelane/env_info.py

@@ -0,0 +1,320 @@
+#!/usr/bin/env python3
+
+# Copyright 2021-2023 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.
+
+# Note: This file may be run with no dependencies installed as part of
+# environment surveys. Please ensure all code as compatible as possible
+# with ancient versions of Python.
+
+## This file is internal to LibreLane and is not part of the API.
+import os
+import re
+import sys
+import json
+import shutil
+import tempfile
+import platform
+import subprocess
+
+try:
+    from typing import Union, Optional, Dict, List  # noqa: F401
+except ImportError:
+    pass
+
+
+class StringRepresentable(object):
+    def __str__(self):
+        return str(self.__dict__)
+
+    def __repr__(self):
+        return str(self.__dict__)
+
+
+class ContainerInfo(StringRepresentable):
+    path = None  # type: Optional[str]
+    engine = "UNKNOWN"  # type: str
+    version = "UNKNOWN"  # type: str
+    conmon = False  # type: bool
+    rootless = False  # type : bool
+
+    def __init__(self):
+        self.engine = "UNKNOWN"
+        self.version = "UNKNOWN"
+        self.conmon = False
+        self.rootless = False
+        self.seccomp = False
+        self.selinux = False
+        self.apparmor = False
+
+    @staticmethod
+    def get():
+        # type: () -> Union[ContainerInfo, str]
+        cinfo = ContainerInfo()
+        # Here are the rules:
+        # 1. If LIBRELANE_CONTAINER_ENGINE exists, use that uncritically.
+        # 2. Else, if OPENLANE_CONTAINER_ENGINE exists, use that uncritically.
+        # 3. Else, if "docker" is in PATH, always use it.
+        # 4. Else, see if "podman" is in PATH, and use THAT.
+        # 5. If none exist, halt and return early.
+
+        container_engine = os.getenv(
+            "LIBRELANE_CONTAINER_ENGINE", os.getenv("OPENLANE_CONTAINER_ENGINE")
+        )
+        if container_engine is None or container_engine == "":
+            container_engine = shutil.which("docker")
+            if container_engine is None:
+                container_engine = shutil.which("podman")
+                if container_engine is None:
+                    return "no compatible container engine found in PATH (tried docker, podman)"
+        try:
+            info_str = subprocess.check_output(
+                [container_engine, "info", "--format", "{{json .}}"]
+            ).decode("utf8")
+        except Exception as e:
+            return "failed to get container engine info: %s" % str(e)
+        cinfo.path = container_engine
+
+        try:
+            info = json.loads(info_str)
+        except Exception as e:
+            return "result from '%s info' was not valid JSON: %s" % (
+                container_engine,
+                str(e),
+            )
+
+        if (
+            info.get("Docker Root Dir") is not None
+            or info.get("DockerRootDir") is not None
+        ):
+            cinfo.engine = "docker"
+
+            # Get Version
+            try:
+                version_output = (
+                    subprocess.check_output([container_engine, "--version"])
+                    .decode("utf8")
+                    .strip()
+                )
+                cinfo.version = re.split(r"\s", version_output)[2].strip(",")
+            except Exception:
+                pass
+
+            security_options = info.get("SecurityOptions")
+            for option in security_options:
+                if "rootless" in option:
+                    cinfo.rootless = True
+        elif info.get("host") is not None:
+            host = info["host"]
+            conmon = host.get("conmon")
+            remote_socket = host.get("remoteSocket")
+            security = host.get("security")
+            if conmon is not None:
+                cinfo.conmon = True
+            if remote_socket is not None and "podman" in remote_socket["path"]:
+                cinfo.engine = "podman"
+                cinfo.version = info["version"]["Version"]
+            if security is not None:
+                cinfo.rootless = security.get("rootless", False)
+                cinfo.apparmor = security.get("apparmorEnabled", False)
+                cinfo.seccomp = security.get("seccompEnabled", False)
+                cinfo.selinux = security.get("selinuxEnabled", False)
+
+        return cinfo
+
+
+class NixInfo(StringRepresentable):
+    version_string = ""  # type: str
+    channels = None  # type: Optional[Dict[str, str]]
+    nix_command = False  # type: bool
+    flakes = False  # type: bool
+
+    def __init__(self) -> None:
+        self.version_string = ""
+        self.channels = None
+        self.nix_command = False
+        self.flakes = False
+
+    @staticmethod
+    def get():
+        # type: () -> Union[NixInfo, str]
+        ninfo = NixInfo()
+        if shutil.which("nix") is None:
+            return "nix not found in PATH"
+        try:
+            version_str = subprocess.check_output(["nix", "--version"], encoding="utf8")
+            ninfo.version_string = version_str.strip()
+        except Exception as e:
+            return "could not get nix version: %s" % str(e)
+
+        try:
+            channels = {}
+            channels_raw = subprocess.check_output(
+                ["nix-channel", "--list"], encoding="utf8"
+            )
+            for channel in channels_raw.splitlines():
+                name, url = channel.split(maxsplit=1)
+                channels[name] = url
+            ninfo.channels = channels
+        except Exception:
+            pass
+
+        with tempfile.TemporaryDirectory(prefix="librelane_env_report_") as d:
+            with open(os.path.join(d, "flake.nix"), "w") as f:
+                f.write("{}")
+            nix_command = subprocess.run(
+                ["nix", "eval"],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                cwd=d,
+                encoding="utf8",
+            )
+            nix_command_result = nix_command.stdout
+            if "'nix-command'" in nix_command_result:
+                pass
+            elif "'flakes'" in nix_command_result:
+                ninfo.nix_command = True
+            elif "lacks attribute" in nix_command_result:
+                ninfo.nix_command = True
+                ninfo.flakes = True
+            else:
+                print(
+                    "'nix flake' returned unexpected output: %s" % nix_command_result,
+                    file=sys.stderr,
+                )
+
+        return ninfo
+
+
+class OSInfo(StringRepresentable):
+    kernel = ""  # type: str
+    kernel_version = ""  # type: str
+    supported = False  # type: bool
+    distro = "UNKNOWN"  # type: str
+    distro_version = "UNKNOWN"  # type: str
+    python_version = ""  # type: str
+    python_path = []  # type: List[str]
+    container_info = None  # type: Union[ContainerInfo, str]
+    nix_info = None  # type: Union[NixInfo, str]
+
+    def __init__(self):
+        self.kernel = platform.system()
+        self.kernel_version = (
+            platform.release()
+        )  # Unintuitively enough, it's the kernel's release
+        self.supported = self.kernel in ["Darwin", "Linux"]
+        self.distro = "UNKNOWN"
+        self.distro_version = "UNKNOWN"
+        self.python_version = platform.python_version()
+        self.python_path = sys.path.copy()
+        self.tkinter = False
+        try:
+            import tkinter  # noqa: F401
+
+            self.tkinter = True
+        except ImportError:
+            pass
+        self.container_info = ""
+        self.nix_info = ""
+
+    @staticmethod
+    def get():
+        # type: () -> 'OSInfo'
+        osinfo = OSInfo()
+
+        if osinfo.kernel == "Windows":
+            osinfo.distro = "Windows"
+            osinfo.distro_version = platform.release()
+            osinfo.kernel_version = platform.version()
+
+        if osinfo.kernel == "Darwin":
+            osinfo.distro = "macOS"
+            osinfo.distro_version = platform.mac_ver()[0]
+            osinfo.kernel_version = platform.release()
+
+        if osinfo.kernel == "Linux":
+            os_release = ""
+            try:
+                os_release += open("/etc/lsb-release").read()
+            except FileNotFoundError:
+                pass
+            try:
+                os_release += open("/etc/os-release").read()
+            except FileNotFoundError:
+                pass
+
+            if os_release.strip() != "":
+                config = {}
+                for line in os_release.split("\n"):
+                    if line.strip() == "":
+                        continue
+                    if line.strip().startswith("#"):
+                        continue
+                    key, value = line.split("=")
+                    value = value.strip('"')
+
+                    config[key] = value
+
+                osinfo.distro = (
+                    config.get("ID") or config.get("DISTRIB_ID") or "UNKNOWN"
+                )
+                osinfo.distro_version = (
+                    config.get("VERSION_ID")
+                    or config.get("DISTRIB_RELEASE")
+                    or "UNKNOWN"
+                )
+
+        osinfo.container_info = ContainerInfo.get()
+        osinfo.nix_info = NixInfo.get()
+        return osinfo
+
+
+def env_info_cli():
+    def print_params(obj, indent=0):
+        if isinstance(obj, list):
+            for value in obj:
+                if isinstance(value, StringRepresentable) or isinstance(value, dict):
+                    print("%s- " % (" " * indent), end="")
+                    print_params(value, indent=indent + 2)
+                elif isinstance(value, list):
+                    if len(value) == 0:
+                        print("%s- []" % (" " * indent))
+                    else:
+                        print("%s- " % (" " * indent), end="")
+                        print_params(value, indent=indent + 2)
+                else:
+                    print("%s- %s" % (" " * indent, value))
+
+        else:
+            current = obj if isinstance(obj, dict) else obj.__dict__
+            for key in current:
+                value = current[key]
+                if isinstance(value, StringRepresentable) or isinstance(value, dict):
+                    print("%s%s:" % (" " * indent, key))
+                    print_params(value, indent=indent + 2)
+                elif isinstance(value, list):
+                    if len(value) == 0:
+                        print("%s%s: []" % (" " * indent, key))
+                    else:
+                        print("%s%s:" % (" " * indent, key))
+                        print_params(value, indent=indent + 2)
+                else:
+                    print("%s%s: %s" % (" " * indent, key, value))
+
+    info = OSInfo.get()
+    print_params(info)
+
+
+if __name__ == "__main__":
+    env_info_cli()

librelane/examples/spm/config.yaml

@@ -0,0 +1,33 @@
+# Basics
+DESIGN_NAME: spm
+VERILOG_FILES: dir::src/*.v
+CLOCK_PERIOD: 10
+CLOCK_PORT: clk
+PNR_SDC_FILE: dir::src/impl.sdc
+SIGNOFF_SDC_FILE: dir::src/signoff.sdc
+
+# PDN
+FP_PDN_VOFFSET: 5
+FP_PDN_HOFFSET: 5
+FP_PDN_VWIDTH: 2
+FP_PDN_HWIDTH: 2
+FP_PDN_VPITCH: 30
+FP_PDN_HPITCH: 30
+FP_PDN_SKIPTRIM: true
+
+# Pin Order
+FP_PIN_ORDER_CFG: dir::pin_order.cfg
+
+# Technology-Specific Configs
+pdk::sky130*:
+  FP_CORE_UTIL: 45
+  CLOCK_PERIOD: 10.0
+  scl::sky130_fd_sc_hs:
+    CLOCK_PERIOD: 8
+  scl::sky130_fd_sc_ls:
+    MAX_FANOUT_CONSTRAINT: 5
+pdk::gf180mcu*:
+  CLOCK_PERIOD: 24.0
+  FP_CORE_UTIL: 40
+  MAX_FANOUT_CONSTRAINT: 4
+  PL_TARGET_DENSITY: 0.5

librelane/examples/spm/pin_order.cfg

@@ -0,0 +1,14 @@
+#N
+@min_distance=0.1
+a.*
+
+#S
+$1
+rst
+
+#E
+clk
+
+#W
+y
+x