ipweave 0.1.0__py3-none-any.whl

ipweave/__init__.py

@@ -0,0 +1,28 @@
+# Extract version for this package from the environment package metadata. This used to be a lot
+# more difficult in earlier Python versions, and the `__version__` field is a legacy of that time.
+import importlib.metadata
+try:
+    __version__ = importlib.metadata.version(__package__)
+except importlib.metadata.PackageNotFoundError:
+    # No importlib metadata for this package. This shouldn't normally happen, but some people
+    # prefer not installing packages via pip at all. Although not recommended we still support it.
+    # A source checkout that was never installed. The literal is the fallback rather
+    # than the source of truth, so an installed distribution cannot disagree with itself -
+    # and the banner in every generated file quotes this, so "unknown" would end up
+    # stamped into a customer's RTL.
+    __version__ = "0.1.0"
+del importlib
+
+
+from .hdl import *
+
+# must be kept in sync with docs/reference.rst!
+__all__ = [
+    "Shape", "unsigned", "signed",
+    "Value", "Const", "C", "Mux", "Cat", "Array", "Signal", "ClockSignal", "ResetSignal",
+    "Format", "Print", "Assert",
+    "Module",
+    "ClockDomain",
+    "Elaboratable", "Fragment", "Instance",
+    "DomainRenamer", "ResetInserter", "EnableInserter",
+]

ipweave/_legacy_cli.py

@@ -0,0 +1,80 @@
+import argparse
+
+from .hdl._ir import Fragment
+from .emit import rtlil, cxxrtl, verilog
+from .sim import Simulator
+
+
+__all__ = ["main"]
+
+
+def main_parser(parser=None):
+    if parser is None:
+        parser = argparse.ArgumentParser()
+
+    p_action = parser.add_subparsers(dest="action")
+
+    p_generate = p_action.add_parser("generate",
+        help="generate RTLIL, Verilog or CXXRTL from the design")
+    p_generate.add_argument("-t", "--type", dest="generate_type",
+        metavar="LANGUAGE", choices=["il", "cc", "v"],
+        help="generate LANGUAGE (il for RTLIL, v for Verilog, cc for CXXRTL; default: file extension of FILE, if given)")
+    p_generate.add_argument("--no-src", dest="emit_src", default=True, action="store_false",
+        help="suppress generation of source location attributes")
+    p_generate.add_argument("generate_file",
+        metavar="FILE", type=str, nargs="?",
+        help="write generated code to FILE")
+
+    p_simulate = p_action.add_parser(
+        "simulate", help="simulate the design")
+    p_simulate.add_argument("-v", "--vcd-file",
+        metavar="VCD-FILE", type=str,
+        help="write execution trace to VCD-FILE")
+    p_simulate.add_argument("-w", "--gtkw-file",
+        metavar="GTKW-FILE", type=str,
+        help="write GTKWave configuration to GTKW-FILE")
+    p_simulate.add_argument("-p", "--period", dest="sync_period",
+        metavar="TIME", type=float, default=1e-6,
+        help="set 'sync' clock domain period to TIME (default: %(default)s)")
+    p_simulate.add_argument("-c", "--clocks", dest="sync_clocks",
+        metavar="COUNT", type=int, required=True,
+        help="simulate for COUNT 'sync' clock periods")
+
+    return parser
+
+
+def main_runner(parser, args, design, platform=None, name="top", ports=None):
+    if args.action == "generate":
+        generate_type = args.generate_type
+        if generate_type is None and args.generate_file:
+            if args.generate_file.endswith(".il"):
+                generate_type = "il"
+            if args.generate_file.endswith(".cc"):
+                generate_type = "cc"
+            if args.generate_file.endswith(".v"):
+                generate_type = "v"
+        if generate_type is None:
+            parser.error("Unable to auto-detect language, specify explicitly with -t/--type")
+        if generate_type == "il":
+            output = rtlil.convert(design, platform=platform, name=name, ports=ports, emit_src=args.emit_src)
+        if generate_type == "cc":
+            output = cxxrtl.convert(design, platform=platform, name=name, ports=ports, emit_src=args.emit_src)
+        if generate_type == "v":
+            output = verilog.convert(design, platform=platform, name=name, ports=ports, emit_src=args.emit_src)
+        if args.generate_file:
+            with open(args.generate_file, "w") as f:
+                f.write(output)
+        else:
+            print(output)
+
+    if args.action == "simulate":
+        fragment = Fragment.get(design, platform)
+        sim = Simulator(fragment)
+        sim.add_clock(args.sync_period)
+        with sim.write_vcd(vcd_file=args.vcd_file, gtkw_file=args.gtkw_file, traces=ports):
+            sim.run_until(args.sync_period * args.sync_clocks, run_passive=True)
+
+
+def main(*args, **kwargs):
+    parser = main_parser()
+    main_runner(parser, parser.parse_args(), *args, **kwargs)

ipweave/_loc.py

@@ -0,0 +1,46 @@
+"""Source locations, and why every diagnostic carries one.
+
+The language records a ``(filename, lineno)`` tuple on every value and statement it
+builds. That tuple is the difference between "assignment width mismatch" and "assignment
+width mismatch at counter.py:31", and the second is the only one anybody can act on.
+
+Copyright 2026 IPweave contributors. SPDX-License-Identifier: Apache-2.0
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+__all__ = ["Loc", "UNKNOWN", "loc_of"]
+
+
+@dataclass(frozen=True, slots=True)
+class Loc:
+    file: str
+    line: int
+
+    @property
+    def short(self) -> str:
+        if not self.file:
+            return "<unknown>"
+        return f"{Path(self.file).name}:{self.line}"
+
+    def __str__(self) -> str:
+        return self.short
+
+
+UNKNOWN = Loc("", 0)
+
+
+def loc_of(obj) -> Loc:
+    """The location recorded on a value, statement or fragment.
+
+    Returns :data:`UNKNOWN` rather than raising when there is none: a diagnostic with a
+    weak location is still worth printing, and a crash inside the error path replaces a
+    real problem with an unrelated one.
+    """
+    src = getattr(obj, "src_loc", None)
+    if isinstance(src, tuple) and len(src) == 2 and isinstance(src[1], int):
+        return Loc(src[0] or "", src[1])
+    return UNKNOWN

ipweave/_toolchain/__init__.py

@@ -0,0 +1,37 @@
+import os
+import shutil
+
+
+__all__ = ["ToolNotFound", "tool_env_var", "has_tool", "require_tool"]
+
+
+class ToolNotFound(Exception):
+    pass
+
+
+def tool_env_var(name):
+    return name.upper().replace("-", "_").replace("+", "X")
+
+
+def _get_tool(name):
+    return os.environ.get(tool_env_var(name), name)
+
+
+def has_tool(name):
+    return shutil.which(_get_tool(name)) is not None
+
+
+def require_tool(name):
+    env_var = tool_env_var(name)
+    path = _get_tool(name)
+    if shutil.which(path) is None:
+        if env_var in os.environ:
+            raise ToolNotFound("Could not find required tool {} in {} as "
+                               "specified via the {} environment variable".
+                               format(name, path, env_var))
+        else:
+            raise ToolNotFound("Could not find required tool {} in PATH. Place "
+                               "it directly in PATH or specify path explicitly "
+                               "via the {} environment variable".
+                               format(name, env_var))
+    return path

ipweave/_toolchain/yosys.py

@@ -0,0 +1,255 @@
+import os
+import sys
+import re
+import subprocess
+import warnings
+import pathlib
+import importlib.metadata
+import importlib.resources
+
+from . import has_tool, require_tool
+
+
+__all__ = ["YosysError", "YosysBinary", "find_yosys"]
+
+
+class YosysError(Exception):
+    pass
+
+
+class YosysWarning(Warning):
+    pass
+
+
+class YosysBinary:
+    @classmethod
+    def available(cls):
+        """Check for Yosys availability.
+
+        Returns
+        -------
+        available : bool
+            ``True`` if Yosys is installed, ``False`` otherwise. Installed binary may still not
+            be runnable, or might be too old to be useful.
+        """
+        raise NotImplementedError
+
+    @classmethod
+    def version(cls):
+        """Get Yosys version.
+
+        Returns
+        -------
+        ``None`` if version number could not be determined, or a 3-tuple ``(major, minor, distance)`` if it could.
+
+        major : int
+            Major version.
+        minor : int
+            Minor version.
+        distance : int
+            Distance to last tag per ``git describe``. May not be exact for system Yosys.
+        """
+        raise NotImplementedError
+
+    @classmethod
+    def data_dir(cls):
+        """Get Yosys data directory.
+
+        Returns
+        -------
+        data_dir : pathlib.Path
+            Yosys data directory (also known as "datdir").
+        """
+        raise NotImplementedError
+
+    @classmethod
+    def run(cls, args, stdin=""):
+        """Run Yosys process.
+
+        Parameters
+        ----------
+        args : list of str
+            Arguments, not including the program name.
+        stdin : str
+            Standard input.
+
+        Returns
+        -------
+        stdout : str
+            Standard output.
+
+        Exceptions
+        ----------
+        YosysError
+            Raised if Yosys returns a non-zero code. The exception message is the standard error
+            output.
+        """
+        raise NotImplementedError
+
+    @classmethod
+    def _process_result(cls, returncode, stdout, stderr, ignore_warnings, src_loc_at):
+        if returncode:
+            raise YosysError(stderr.strip())
+        if not ignore_warnings:
+            for match in re.finditer(r"(?ms:^Warning: (.+)\n$)", stderr):
+                message = match.group(1).replace("\n", " ")
+                warnings.warn(message, YosysWarning, stacklevel=3 + src_loc_at)
+        return stdout
+
+
+class _BuiltinYosys(YosysBinary):
+    YOSYS_PACKAGE = "amaranth_yosys"
+
+    @classmethod
+    def available(cls):
+        try:
+            importlib.metadata.version(cls.YOSYS_PACKAGE)
+            return True
+        except importlib.metadata.PackageNotFoundError:
+            return False
+
+    @classmethod
+    def version(cls):
+        version = importlib.metadata.version(cls.YOSYS_PACKAGE)
+        match = re.match(r"^(\d+)\.(\d+)\.(?:\d+)(?:\.(\d+))?(?:\.post(\d+))?", version)
+        return (int(match[1]), int(match[2]), int(match[3] or 0), int(match[4] or 0))
+
+    @classmethod
+    def data_dir(cls):
+        return importlib.resources.files(cls.YOSYS_PACKAGE) / "share"
+
+    @classmethod
+    def run(cls, args, stdin="", *, ignore_warnings=False, src_loc_at=0):
+        popen = subprocess.Popen([sys.executable, "-m", cls.YOSYS_PACKAGE, *args],
+            stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+            encoding="utf-8")
+        stdout, stderr = popen.communicate(stdin)
+        return cls._process_result(popen.returncode, stdout, stderr, ignore_warnings, src_loc_at)
+
+
+class _SystemYosys(YosysBinary):
+    YOSYS_BINARY = "yosys"
+
+    @classmethod
+    def available(cls):
+        return has_tool(cls.YOSYS_BINARY)
+
+    @classmethod
+    def version(cls):
+        version = cls.run(["-V"])
+        match = re.match(r"^Yosys (\d+)\.(\d+)(?:\+(\d+))?", version)
+        if match:
+            return (int(match[1]), int(match[2]), int(match[3] or 0))
+        else:
+            return None
+
+    @classmethod
+    def data_dir(cls):
+        popen = subprocess.Popen([require_tool(cls.YOSYS_BINARY) + "-config", "--datdir"],
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+            encoding="utf-8")
+        stdout, stderr = popen.communicate()
+        if popen.returncode:
+            raise YosysError(stderr.strip())
+        return pathlib.Path(stdout.strip())
+
+    @classmethod
+    def run(cls, args, stdin="", *, ignore_warnings=False, src_loc_at=0):
+        popen = subprocess.Popen([require_tool(cls.YOSYS_BINARY), *args],
+            stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+            encoding="utf-8")
+        stdout, stderr = popen.communicate(stdin)
+        # If Yosys is built with an evaluation version of Verific, then Verific license
+        # information is printed first. It consists of empty lines and lines starting with `--`,
+        # which are not normally a part of Yosys output, and can be fairly safely removed.
+        #
+        # This is not ideal, but Verific license conditions rule out any other solution.
+        stdout = re.sub(r"\A(-- .+\n|\n)*", "", stdout)
+        return cls._process_result(popen.returncode, stdout, stderr, ignore_warnings, src_loc_at)
+
+
+class _JavaScriptYosys(YosysBinary):
+    """
+    This toolchain proxy is compatible with Pyodide_. The JavaScript environment must include
+    the following function:
+
+    .. code::
+
+        runAmaranthYosys(args: string[], stdin: string): (exit_code: int, stdout: string, stderr: string);
+
+    .. _Pyodide: https://pyodide.org/
+    """
+
+    @classmethod
+    def available(cls):
+        try:
+            return hasattr(__import__("js"), "runAmaranthYosys")
+        except ImportError:
+            return False
+
+    @classmethod
+    def version(cls):
+        version = cls.run(["-V"])
+        match = re.match(r"^Yosys (\d+)\.(\d+)(?:\+(\d+))?", version)
+        if match:
+            return (int(match[1]), int(match[2]), int(match[3] or 0))
+        else:
+            return None
+
+    @classmethod
+    def data_dir(cls):
+        # Not yet clear how this could work in a design with Wasm components. Most likely,
+        # the component would have to export its filesystem wholesale, and this method would
+        # return some kind of non-filesystem path-like object.
+        raise NotImplementedError
+
+    @classmethod
+    def run(cls, args, stdin="", *, ignore_warnings=False, src_loc_at=0):
+        exit_code, stdout, stderr = __import__("js").runAmaranthYosys(args, stdin)
+        return cls._process_result(exit_code, stdout, stderr, ignore_warnings, src_loc_at)
+
+
+def find_yosys(requirement):
+    """Find an available Yosys executable of required version.
+
+    Parameters
+    ----------
+    requirement : function
+        Version check. Should return ``True`` if the version is acceptable, ``False`` otherwise.
+
+    Returns
+    -------
+    yosys_binary : subclass of YosysBinary
+        Proxy for running the requested version of Yosys.
+
+    Exceptions
+    ----------
+    YosysError
+        Raised if required Yosys version is not found.
+    """
+    proxies = []
+    _use_var = "IPWEAVE_USE_YOSYS" if "IPWEAVE_USE_YOSYS" in os.environ else "AMARANTH_USE_YOSYS"
+    clauses = os.environ.get(_use_var, "system,builtin").split(",")
+    for clause in clauses:
+        if clause == "builtin":
+            proxies.append(_BuiltinYosys)
+        elif clause == "system":
+            proxies.append(_SystemYosys)
+        elif clause == "javascript":
+            proxies.append(_JavaScriptYosys)
+        else:
+            raise YosysError(f"The {_use_var} environment variable contains "
+                             "an unrecognized clause {!r}"
+                             .format(clause))
+    for proxy in proxies:
+        if proxy.available():
+            version = proxy.version()
+            if version is not None and requirement(version):
+                return proxy
+    else:
+        if "AMARANTH_USE_YOSYS" in os.environ or "IPWEAVE_USE_YOSYS" in os.environ:
+            raise YosysError("Could not find an acceptable Yosys binary. Searched: {}"
+                             .format(", ".join(clauses)))
+        else:
+            raise YosysError("Could not find an acceptable Yosys binary. The `amaranth-yosys` PyPI "
+                             "package, if available for this platform, can be used as fallback")

ipweave/_tree.py

@@ -0,0 +1,59 @@
+"""Reductions written as balanced trees of named signals.
+
+A flat ``a | b | c | d | e | f | g | h`` is correct, and it emits as one line that grows
+with the operand count until ``IPW-E016`` reports it - which is the rule doing its job,
+because the fix belongs in the generator rather than in the printer's line wrapping.
+
+It is also worse RTL. A flat reduction leaves the association to synthesis, which will
+usually build a tree and is under no obligation to; a tree built here is *stated*, its
+depth is ``ceil(log2(n))`` by construction, and the intermediate names survive into the
+output where somebody debugging a timing path can see them.
+
+Copyright 2026 IPweave contributors. SPDX-License-Identifier: Apache-2.0
+"""
+
+from __future__ import annotations
+
+from ipweave import Signal
+
+__all__ = ["or_reduce", "and_reduce"]
+
+
+def _reduce(m, name: str, terms, combine, what: str):
+    level = list(terms)
+    if not level:
+        raise ValueError(f"{what} needs at least one term")
+    if len(level) == 1:
+        return level[0]
+
+    shape = level[0].shape()
+    stage = 0
+    while len(level) > 1:
+        nxt = []
+        for index in range(0, len(level), 2):
+            if index + 1 == len(level):
+                # An odd one out is carried to the next level rather than paired with an
+                # identity, which would add a level of logic to hide the asymmetry.
+                nxt.append(level[index])
+                continue
+            node = Signal(shape, name=f"{name}_l{stage}_{index // 2}")
+            m.d.comb += node.eq(combine(level[index], level[index + 1]))
+            nxt.append(node)
+        level = nxt
+        stage += 1
+    return level[0]
+
+
+def or_reduce(m, name: str, terms):
+    """Bitwise OR of ``terms``, as a balanced tree of named intermediates.
+
+    ``terms`` may be any width, as long as they agree; the tree is built at the shape of
+    the first one. One term is returned unchanged rather than wrapped in a signal that
+    does nothing.
+    """
+    return _reduce(m, name, terms, lambda a, b: a | b, "or_reduce")
+
+
+def and_reduce(m, name: str, terms):
+    """Bitwise AND of ``terms``, same shape and same reasoning as :func:`or_reduce`."""
+    return _reduce(m, name, terms, lambda a, b: a & b, "and_reduce")

ipweave/_unused.py

@@ -0,0 +1,47 @@
+import sys
+import warnings
+
+from ._utils import get_linter_option
+
+
+__all__ = ["UnusedMustUse", "MustUse"]
+
+
+class UnusedMustUse(Warning):
+    pass
+
+
+class MustUse:
+    _MustUse__silence = False
+    _MustUse__warning = UnusedMustUse
+
+    def __new__(cls, *args, src_loc_at=0, **kwargs):
+        frame = sys._getframe(1 + src_loc_at)
+        self = super().__new__(cls)
+        self._MustUse__used    = False
+        self._MustUse__context = dict(
+            filename=frame.f_code.co_filename,
+            lineno=frame.f_lineno,
+            source=self)
+        return self
+
+    def __del__(self):
+        if self._MustUse__silence:
+            return
+        if getattr(self._MustUse__warning, "_MustUse__silence", False):
+            return
+        if hasattr(self, "_MustUse__used") and not self._MustUse__used:
+            if get_linter_option(self._MustUse__context["filename"],
+                                 self._MustUse__warning.__qualname__, bool, True):
+                warnings.warn_explicit(
+                    f"{self!r} created but never used", self._MustUse__warning,
+                    **self._MustUse__context)
+
+
+_old_excepthook = sys.excepthook
+def _silence_elaboratable(type, value, traceback):
+    # Don't show anything if the interpreter crashed; that'd just obscure the exception
+    # traceback instead of helping.
+    MustUse._MustUse__silence = True
+    _old_excepthook(type, value, traceback)
+sys.excepthook = _silence_elaboratable

ipweave/_utils.py

@@ -0,0 +1,104 @@
+import contextlib
+import functools
+import warnings
+import linecache
+import operator
+import re
+from collections.abc import Iterable
+
+
+__all__ = ["to_binary", "flatten", "union", "final", "deprecated", "get_linter_options",
+           "get_linter_option"]
+
+
+def to_binary(n: int, width: int) -> str:
+    """Formats ``n`` as exactly ``width`` binary digits, including when ``width`` is 0"""
+    n = operator.index(n)
+    width = operator.index(width)
+    if n not in range(1 << width):
+        raise ValueError(f"{n} does not fit in {width} bits")
+    if width == 0:
+        return ""
+    return f"{n:0{width}b}"
+
+
+def flatten(i):
+    for e in i:
+        if isinstance(e, str) or not isinstance(e, Iterable):
+            yield e
+        else:
+            yield from flatten(e)
+
+
+def union(i, start=None):
+    r = start
+    for e in i:
+        if r is None:
+            r = e
+        else:
+            r |= e
+    return r
+
+
+def final(cls):
+    def init_subclass():
+        raise TypeError("Subclassing {}.{} is not supported"
+                        .format(cls.__module__, cls.__qualname__))
+    cls.__init_subclass__ = init_subclass
+    return cls
+
+
+def deprecated(message, stacklevel=2):
+    def decorator(f):
+        @functools.wraps(f)
+        def wrapper(*args, **kwargs):
+            warnings.warn(message, DeprecationWarning, stacklevel=stacklevel)
+            return f(*args, **kwargs)
+        return wrapper
+    return decorator
+
+
+def _ignore_deprecated(f=None):
+    if f is None:
+        @contextlib.contextmanager
+        def context_like():
+            with warnings.catch_warnings():
+                warnings.filterwarnings(action="ignore", category=DeprecationWarning)
+                yield
+        return context_like()
+    else:
+        @functools.wraps(f)
+        def decorator_like(*args, **kwargs):
+            with warnings.catch_warnings():
+                warnings.filterwarnings(action="ignore", category=DeprecationWarning)
+                return f(*args, **kwargs)
+        return decorator_like
+
+
+def get_linter_options(filename):
+    first_line = linecache.getline(filename, 1)
+    if first_line:
+        match = re.match(r"^#\s*(?:ipweave|amaranth):\s*((?:\w+=\w+\s*)(?:,\s*\w+=\w+\s*)*)\n$", first_line)
+        if match:
+            return dict(map(lambda s: s.strip().split("=", 2), match.group(1).split(",")))
+    return dict()
+
+
+def get_linter_option(filename, name, type, default):
+    options = get_linter_options(filename)
+    if name not in options:
+        return default
+
+    option = options[name]
+    if type is bool:
+        if option in ("1", "yes", "enable"):
+            return True
+        if option in ("0", "no", "disable"):
+            return False
+        return default
+    if type is int:
+        try:
+            return int(option, 0)
+        except ValueError:
+            return default
+    assert False