garageworks 0.2.0.dev299555241357__tar.gz

garageworks-0.2.0.dev299555241357/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: garageworks
+Version: 0.2.0.dev299555241357
+Requires-Python: >=3.9
+Requires-Dist: cocotb==1.9.2
+Requires-Dist: cocotb-bus==0.3.0
+Requires-Dist: cocotb-test==0.2.6
+Requires-Dist: cocotbext-axi==0.1.26
+Requires-Dist: libcst==1.8.6
+Requires-Dist: pytest==8.4.2

garageworks-0.2.0.dev299555241357/garageworks/__init__.py

@@ -0,0 +1 @@
+# garageworks/__init__.py

garageworks-0.2.0.dev299555241357/garageworks/bridge/__init__.py

@@ -0,0 +1 @@
+# garageworks/bridge/__init__.py

garageworks-0.2.0.dev299555241357/garageworks/bridge/aved_bridge.py

@@ -0,0 +1,85 @@
+# See LICENSE file for details.
+# written by Kaz Yoshii <kazutomo.yoshii@gmail.com>
+
+import os, sys, time
+from pathlib import Path
+import json
+from types import SimpleNamespace
+import logging
+
+import pyaved
+
+class AVED_Bridge:
+    is_fpga = True
+
+    def readAddrMap(self):
+        fn = os.getenv("PARAMFN")
+        if fn is None:
+            raise RuntimeError("Environment variable PARAMFN is not set")
+
+        with open(fn) as f:
+            data = json.load(f, object_hook=lambda d: SimpleNamespace(**d))
+
+        return data
+
+    def aved_write32(self, addr, v):
+        self.aved.write32(addr, v)
+
+    def aved_read32(self, addr):
+        v = self.aved.read32(addr)
+        return v
+
+    def __init__(self, base=0x1100000, dev="b1:00.0", logfn = "output.log"):
+        self.base = base
+
+        self.p = self.readAddrMap()
+
+        self.aved = pyaved.AVED()
+        self.aved.open(dev)
+
+        log_path = Path(logfn).resolve()
+        self.log = logging.getLogger("tblog")
+        self.log.setLevel(logging.INFO)
+        self.log.propagate = False
+        self.log.handlers.clear()
+        handler = logging.FileHandler(log_path, mode="w")
+        handler.setLevel(logging.INFO)
+        handler.setFormatter(logging.Formatter("%(message)s"))
+        self.log.addHandler(handler)
+
+        self.log.info("FPGA Simulation Environment Initialized!\n")
+
+    def writelog(self, txt):
+        print(txt, end='')
+        with open(self.outputfn, "a")  as f:
+            f.write(txt)
+
+    def checkOffset(self, offset, align=8):
+        assert (offset % align) == 0, f"offset should be aligned with {align} bytes : {offset}"
+
+    def writeWord(self, offset, data):
+        self.checkOffset(offset, align=4)
+        self.aved_write32(self.base + offset, data)
+
+    def readWord(self, offset):
+        self.checkOffset(offset, align=4)
+        return self.aved_read32(self.base + offset)
+
+    def expectWord(self, offset, ref, msg = ""):
+        v = self.readWord(offset)
+        assert v == ref, msg
+
+    def softReset(self, maxloopcnt = 1000):
+        cycles = self.p.reset_cycles
+        self.writeWord(self.p.soft_reset_rw, 1)
+        reset_done = 0
+        loopcnt = 0
+        while reset_done == 0:
+            reset_done = self.readWord(self.p.soft_reset_rw)
+            if loopcnt > maxloopcnt:
+                raise RuntimeError("Reached maxloopcnt. Something wrong")
+            loopcnt += 1
+        return loopcnt
+
+    def setup(self):
+        pass

garageworks-0.2.0.dev299555241357/garageworks/bridge/cocotb_bridge.py

@@ -0,0 +1,93 @@
+# See LICENSE file for details.
+# written by Kaz Yoshii <kazutomo.yoshii@gmail.com>
+
+import os, sys, random
+from pathlib import Path
+import json
+from types import SimpleNamespace
+import logging
+
+import cocotb_test.simulator, pytest
+import cocotb
+from cocotb.clock import Clock
+from cocotb.triggers import RisingEdge, Timer
+from cocotb.regression import TestFactory
+from cocotbext.axi import AxiLiteBus, AxiLiteMaster, AxiLiteRam, AxiResp
+import warnings
+warnings.filterwarnings("ignore", category=DeprecationWarning)
+
+class COCOTB_Bridge:
+    is_fpga = False
+
+    def readParams(self):
+        fn = os.getenv("PARAMFN")
+        if fn is None:
+            raise RuntimeError("Environment variable PARAMFN is not set")
+
+        with open(fn) as f:
+            data = json.load(f, object_hook=lambda d: SimpleNamespace(**d))
+
+        return data
+
+    async def setup(self):
+        cocotb.start_soon(Clock(self.dut.s_axi_aclk, 10, units="ns").start())
+
+        bus = AxiLiteBus.from_prefix(self.dut, "S_AXI")
+        self.axi_master = AxiLiteMaster(
+            bus,
+            self.dut.s_axi_aclk,        # lower-case clock
+            self.dut.s_axi_aresetn,     # lower-case reset
+            reset_active_level=0   # because aresetn is active-low
+        )
+        await self.reset_dut()
+
+    def __init__(self, dut, logfn = "output.log"):
+        self.dut = dut
+
+        self.p = self.readParams()
+
+        log_path = Path(logfn).resolve()
+        self.log = logging.getLogger("tblog")
+        self.log.setLevel(logging.INFO)
+        self.log.propagate = False
+        self.log.handlers.clear()
+        handler = logging.FileHandler(log_path, mode="w")
+        handler.setLevel(logging.INFO)
+        handler.setFormatter(logging.Formatter("%(message)s"))
+        self.log.addHandler(handler)
+
+        self.log.info("Cocotb Test Initialized!\n")
+
+    async def writeWord(self, addr, data):
+        b = bytearray(data.to_bytes(4, byteorder="little"))
+        await self.axi_master.write(addr, b)
+
+    async def readWord(self, addr):
+        b = await self.axi_master.read(addr, 4)
+        v = int.from_bytes(b, byteorder="little")
+        return v
+
+    async def expectWord(self, addr, ref, msg = ""):
+        v = await self.readWord(addr)
+        assert v == ref, msg
+
+    async def softReset(self, maxloopcnt = 1000):
+        cycles = self.p.reset_cycles
+        await self.writeWord(self.p.soft_reset_rw, 1)
+        reset_done = 0
+        loopcnt = 0
+        while reset_done == 0:
+            reset_done = await self.readWord(self.p.soft_reset_rw)
+            if loopcnt > maxloopcnt:
+                raise RuntimeError("Reached maxloopcnt. Something wrong")
+            loopcnt += 1
+        return loopcnt
+
+    # obsolute below
+    async def reset_dut(self, cycles=5):
+        self.dut.s_axi_aresetn.value = 0  # assert (active-low)
+        for _ in range(cycles):
+            await RisingEdge(self.dut.s_axi_aclk)
+            self.dut.s_axi_aresetn.value = 1  # deassert
+        for _ in range(2):
+            await RisingEdge(self.dut.s_axi_aclk)

garageworks-0.2.0.dev299555241357/garageworks/bridge/conv_cocotb_to_fpga.py

@@ -0,0 +1,426 @@
+#!/usr/bin/env python3
+"""
+Convert a set of AXI cocotb testbench files into FPGA testbench files.
+
+Usage:
+    python conv_cocotb_to_fpga.py tb_filter.py r2bridge.py subtest1.py
+
+Each input file `foo.py` is written as `fpga_foo.py` (default: same
+directory as input, or --outdir if given). Local imports between files
+in the same batch are rewritten to match (e.g. `from r2bridge import
+R2Bridge` -> `from fpga_r2bridge import R2Bridge`) so the converted
+files import each other correctly.
+
+To overwrite existing output files, use the --force option.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import libcst as cst
+import libcst.matchers as m
+
+
+def fpga_name(stem: str) -> str:
+    """Map a module/file stem to its converted-output equivalent name."""
+    return f"fpga_{stem}"
+
+
+class CocotbToFpgaTransformer(cst.CSTTransformer):
+    def __init__(
+        self,
+        fpga: str,
+        local_stems: frozenset[str] = frozenset(),
+        drop_setup: bool = True,
+    ):
+        self.sim = 'COCOTB'
+        self.fpga = fpga
+        self.local_stems = local_stems
+        self.drop_setup = drop_setup
+        self.generated_main = False
+        self._bridge_class_depth: list[bool] = []
+
+    def _module_name(self, node: cst.BaseExpression) -> str:
+        """Return dotted module name from LibCST Name/Attribute node."""
+        if isinstance(node, cst.Name):
+            return node.value
+        if isinstance(node, cst.Attribute):
+            left = self._module_name(node.value)
+            return f"{left}.{node.attr.value}"
+        return ""
+
+    # -------------------------
+    # Imports
+    # -------------------------
+    def leave_Import(
+        self,
+        original_node: cst.Import,
+        updated_node: cst.Import,
+    ) -> cst.Import | cst.RemovalSentinel:
+        kept = []
+        for alias in updated_node.names:
+            name = alias.name
+            # remove: import cocotb
+            if isinstance(name, cst.Name) and name.value == "cocotb":
+                continue
+            kept.append(alias.with_changes(comma=cst.MaybeSentinel.DEFAULT))
+        if not kept:
+            return cst.RemoveFromParent()
+        return updated_node.with_changes(names=kept)
+
+    def leave_ImportFrom(
+        self,
+        original_node: cst.ImportFrom,
+        updated_node: cst.ImportFrom,
+    ) -> cst.ImportFrom | cst.RemovalSentinel:
+        if updated_node.module is None:
+            return updated_node
+
+        module_code = self._module_name(updated_node.module)
+
+        # remove: from cocotb... import ...
+        if module_code == "cocotb" or module_code.startswith("cocotb."):
+            return cst.RemoveFromParent()
+
+        # e.g.,
+        #   from garageworks.bridge.cocotb_bridge import COCOTB_Bridge
+        # ->
+        #   from garageworks.bridge.aved_bridge import AVED_Bridge
+        if module_code == "garageworks.bridge.cocotb_bridge":
+            return updated_node.with_changes(
+                module=cst.Attribute(
+                    value=cst.Attribute(
+                        value=cst.Name("garageworks"),
+                        attr=cst.Name("bridge"),
+                    ),
+                    attr=cst.Name(f"{self.fpga.lower()}_bridge"),
+                ),
+                names=[
+                    cst.ImportAlias(
+                        name=cst.Name(f"{self.fpga}_Bridge"),
+                        comma=cst.MaybeSentinel.DEFAULT,
+                    )
+                ],
+            )
+
+        # Batch-local import rewrite, e.g.
+        #   from r2bridge import R2Bridge
+        # ->
+        #   from fpga_r2bridge import R2Bridge
+        # (also covers helper modules like subtest1.py)
+        if module_code in self.local_stems:
+            return updated_node.with_changes(
+                module=cst.Name(fpga_name(module_code)),
+            )
+
+        return updated_node
+
+    # -------------------------
+    # async / await conversion
+    # -------------------------
+    def leave_Await(
+        self,
+        original_node: cst.Await,
+        updated_node: cst.Await,
+    ) -> cst.BaseExpression:
+        # await rev.readWord(...)
+        # ->
+        # rev.readWord(...)
+        return updated_node.expression
+
+    # -------------------------
+    # Function conversion
+    # -------------------------
+    def leave_FunctionDef(
+        self,
+        original_node: cst.FunctionDef,
+        updated_node: cst.FunctionDef,
+    ) -> cst.FunctionDef:
+        decorators = []
+        is_cocotb_test = False
+        for dec in updated_node.decorators:
+            if self._is_cocotb_test_decorator(dec):
+                is_cocotb_test = True
+                continue
+            decorators.append(dec)
+
+        # async def -> def
+        new_node = updated_node.with_changes(
+            asynchronous=None,
+            decorators=decorators,
+        )
+
+        if is_cocotb_test:
+            self.generated_main = True
+            # async def sim_simple(dut):
+            # ->
+            # def main():
+            new_node = new_node.with_changes(
+                name=cst.Name("main"),
+                params=cst.Parameters(),
+            )
+
+        # Inside a *Bridge subclass, __init__(self, cocotb_dut) drops the
+        # cocotb_dut param, since the FPGA-side bridge takes none.
+        in_bridge_class = (
+            self._bridge_class_depth and self._bridge_class_depth[-1]
+        )
+        if in_bridge_class and updated_node.name.value == "__init__":
+            params = list(updated_node.params.params)
+            if len(params) >= 2:
+                # keep self and all params after cocotb_dut
+                new_params_list = [params[0]] + params[2:]
+                new_params = updated_node.params.with_changes(
+                    params = new_params_list
+                    )
+                new_node =  new_node.with_changes(params=new_params)
+
+        return new_node
+
+    def _is_cocotb_test_decorator(self, dec: cst.Decorator) -> bool:
+        expr = dec.decorator
+        # @cocotb.test
+        if m.matches(
+            expr,
+            m.Attribute(
+                value=m.Name("cocotb"),
+                attr=m.Name("test"),
+            ),
+        ):
+            return True
+        # @cocotb.test()
+        if m.matches(
+            expr,
+            m.Call(
+                func=m.Attribute(
+                    value=m.Name("cocotb"),
+                    attr=m.Name("test"),
+                )
+            ),
+        ):
+            return True
+        return False
+
+    # -------------------------
+    # Class definition: rebase project bridge classes
+    # e.g. class R2Bridge(COCOTB_Bridge): -> class R2Bridge(AVED_Bridge):
+    # -------------------------
+    def _is_bridge_base(self, base_value: cst.BaseExpression) -> bool:
+        name = self._module_name(base_value)
+        return name == "COCOTB_Bridge" or name.endswith("Bridge")
+
+    def visit_ClassDef(self, node: cst.ClassDef) -> None:
+        is_bridge_class = any(
+            self._is_bridge_base(base.value) for base in node.bases
+        )
+        self._bridge_class_depth.append(is_bridge_class)
+
+    def leave_ClassDef(
+        self,
+        original_node: cst.ClassDef,
+        updated_node: cst.ClassDef,
+    ) -> cst.ClassDef:
+        self._bridge_class_depth.pop()
+
+        new_bases = []
+        changed = False
+        for base in updated_node.bases:
+            if m.matches(base.value, m.Name("COCOTB_Bridge")):
+                new_bases.append(
+                    base.with_changes(value=cst.Name(f"{self.fpga}_Bridge"))
+                )
+                changed = True
+            else:
+                new_bases.append(base)
+        if changed:
+            return updated_node.with_changes(bases=new_bases)
+        return updated_node
+
+    # -------------------------
+    # Class replacement (generalized to any *Bridge subclass call)
+    # -------------------------
+    def leave_Call(
+        self,
+        original_node: cst.Call,
+        updated_node: cst.Call,
+    ) -> cst.Call:
+        def drop_cocotb_dut(args):
+            args = list(args)
+            if (
+                    args
+                    and args[0].keyword is None
+                    and isinstance(args[0].value, cst.Name)
+                    and args[0].value.value == "cocotb_dut"
+            ):
+                return args[1:]
+            return args
+
+        if isinstance(updated_node.func, cst.Name):
+            name = updated_node.func.value
+
+            # COCOTB_Bridge(cocotb_dut) -> AVED_Bridge()
+            if name == "COCOTB_Bridge":
+                return updated_node.with_changes(
+                    func=cst.Name(f"{self.fpga}_Bridge"),
+                    args=[],
+                )
+
+            # R2Bridge(cocotb_dut, ...) -> R2Bridge(...)
+            if name.endswith("Bridge") and name != f"{self.fpga}_Bridge":
+                return updated_node.with_changes(
+                    args=drop_cocotb_dut(updated_node.args)
+                )
+
+        # Inside a *Bridge subclass, super().__init__(cocotb_dut, ...) -> super().__init__(...)
+        in_bridge_class = (
+            self._bridge_class_depth and self._bridge_class_depth[-1]
+        )
+        if in_bridge_class and m.matches(
+            updated_node.func,
+            m.Attribute(
+                value=m.Call(func=m.Name("super")),
+                attr=m.Name("__init__"),
+            ),
+        ):
+            return updated_node.with_changes(
+                args=drop_cocotb_dut(updated_node.args)
+            )
+
+        return updated_node
+
+    # -------------------------
+    # Optional setup removal
+    # -------------------------
+    def leave_SimpleStatementLine(
+        self,
+        original_node: cst.SimpleStatementLine,
+        updated_node: cst.SimpleStatementLine,
+    ) -> cst.SimpleStatementLine | cst.RemovalSentinel:
+        if self.drop_setup and len(updated_node.body) == 1:
+            stmt = updated_node.body[0]
+            # Drop:
+            #   await rev.setup()
+            # After await-removal, this becomes:
+            #   rev.setup()
+            if m.matches(
+                stmt,
+                m.Expr(
+                    value=m.Call(
+                        func=m.Attribute(
+                            attr=m.Name("setup"),
+                        )
+                    )
+                ),
+            ):
+                return cst.RemoveFromParent()
+        return updated_node
+
+    # -------------------------
+    # Add main entry point
+    # -------------------------
+    def leave_Module(
+        self,
+        original_node: cst.Module,
+        updated_node: cst.Module,
+    ) -> cst.Module:
+        if not self.generated_main:
+            return updated_node
+
+        main_block = cst.parse_statement(
+            '''
+if __name__ == "__main__":
+    main()
+'''
+        )
+        return updated_node.with_changes(
+            body=list(updated_node.body) + [main_block]
+        )
+
+
+def convert_code(
+    source: str,
+    fpga: str,
+    local_stems: frozenset[str] = frozenset(),
+    drop_setup: bool = True,
+) -> str:
+    module = cst.parse_module(source)
+    transformed = module.visit(
+        CocotbToFpgaTransformer(
+            fpga=fpga,
+            local_stems=local_stems,
+            drop_setup=drop_setup,
+        )
+    )
+    return transformed.code
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Convert a batch of restricted cocotb testbench files "
+                     "to FPGA testbench files."
+    )
+    parser.add_argument(
+        "inputs",
+        nargs="+",
+        type=Path,
+        help="Input cocotb files, e.g. tb_filter.py r2bridge.py subtest1.py",
+    )
+    parser.add_argument(
+        "--outdir",
+        type=Path,
+        default=None,
+        help="Directory for converted output files "
+             "(default: same directory as each input file).",
+    )
+    parser.add_argument(
+        "--fpga",
+        default="AVED",
+        help="FPGA backend name (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--keep-setup",
+        action="store_true",
+        help="Keep setup() calls instead of removing them.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite output files if they already exist.",
+    )
+    args = parser.parse_args()
+
+    # Batch-wide set of local module stems, so local imports between
+    # files in this same invocation get rewritten consistently
+    # (e.g. "r2bridge", "subtest1").
+    local_stems = frozenset(p.stem for p in args.inputs)
+
+    # Resolve output paths up front and check for collisions before
+    # writing anything.
+    output_paths = []
+    for in_path in args.inputs:
+        outdir = args.outdir if args.outdir is not None else in_path.parent
+        out_path = outdir / f"{fpga_name(in_path.stem)}{in_path.suffix}"
+        if out_path.exists() and not args.force:
+            raise FileExistsError(
+                f"{out_path} already exists. Use --force to overwrite."
+            )
+        output_paths.append(out_path)
+
+    for in_path, out_path in zip(args.inputs, output_paths):
+        source = in_path.read_text()
+        converted = convert_code(
+            source=source,
+            fpga=args.fpga,
+            local_stems=local_stems,
+            drop_setup=False,
+#           drop_setup=not args.keep_setup,
+        )
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(converted)
+        print(f"{in_path} -> {out_path}")
+
+
+if __name__ == "__main__":
+    main()

garageworks-0.2.0.dev299555241357/garageworks/gwscript/__init__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+__all__ = ["main"]