simbricks-enso-sys-py 0.6.0__tar.gz

simbricks_enso_sys_py-0.6.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: simbricks-enso-sys-py
+Version: 0.6.0
+Summary: Ensō NIC System integration into SimBricks
+Author: Team SimBricks
+Author-email: team@simbricks.io
+Requires-Python: >=3.12
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Dist: simbricks-imagebuild-packer (>=0.6.0)
+Requires-Dist: simbricks-orchestration (>=0.6.0)
+Requires-Dist: simbricks-utils (>=0.6.0)
+Project-URL: Homepage, https://www.simbricks.io/

simbricks_enso_sys_py-0.6.0/pyproject.toml

@@ -0,0 +1,50 @@
+# MIT License
+#
+# Copyright (c) 2026 SimBricks
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+[tool.black]
+line-length = 100
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "simbricks-enso-sys-py"
+version = "0.6.0"
+description = "Ensō NIC System integration into SimBricks"
+authors  = [
+  "Team SimBricks <team@simbricks.io>"
+]
+homepage = "https://www.simbricks.io/"
+packages = [
+  { include = "simbricks" }
+]
+# Guest install script, shipped as package data.
+include = [
+  { path = "simbricks/components/enso/system/data/*", format = ["sdist", "wheel"] }
+]
+
+[tool.poetry.dependencies]
+python = ">=3.12"
+simbricks-orchestration = ">=0.6.0"
+simbricks-utils = ">=0.6.0"
+simbricks-imagebuild-packer = ">=0.6.0"

simbricks_enso_sys_py-0.6.0/simbricks/components/enso/system/__init__.py

@@ -0,0 +1,33 @@
+# Copyright 2026 Max Planck Institute for Software Systems,
+# National University of Singapore, Carnegie Mellon University,
+# and SimBricks UG (haftungsbeschränkt)
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+from .enso import EnsoEchoServer, EnsoGen, EnsoLinuxHost, EnsoNIC
+from .image import enso_image
+
+__all__ = [
+    "EnsoNIC",
+    "EnsoLinuxHost",
+    "EnsoEchoServer",
+    "EnsoGen",
+    "enso_image",
+]

simbricks_enso_sys_py-0.6.0/simbricks/components/enso/system/data/install-enso.sh

@@ -0,0 +1,63 @@
+#!/bin/bash -eux
+#
+# Installs Ensō into a guest image. Run by enso_image() (see ../image.py) as
+# the single packer layer inside the booted base image. Do not run it on your
+# workstation: it apt-installs packages, writes to /lib/modules and installs
+# into /usr/local.
+#
+# enso_image() exports ENSO_REPO / ENSO_BRANCH / ENSO_DIR ahead of the defaults
+# below; `make guest-install` runs it with the defaults.
+#
+# Because packer boots the very image the driver will be loaded into, `uname -r`
+# here is already the right kernel, so Ensō's own setup.sh does the whole job:
+# dependencies, hugepages, the kernel module, and the meson build of the
+# userspace with the buffer sizes the behavioral model expects.
+#
+# The one thing added afterwards is putting the module where modprobe can find
+# it; setup.sh leaves it in Ensō's build tree, which would force every
+# simulation run to rebuild it. EnsoLinuxHost only modprobes.
+set -eux
+export DEBIAN_FRONTEND=noninteractive
+
+ENSO_REPO="${ENSO_REPO:-https://github.com/crossroadsfpga/enso}"
+ENSO_BRANCH="${ENSO_BRANCH:-simbricks-24.04}"
+
+# Must match EnsoLinuxHost.enso_parent_dir / .enso_name.
+ENSO_DIR="${ENSO_DIR:-/root/enso}"
+
+KVER=$(uname -r)
+
+# The kernel headers come with the image's kernel, whether that is a distro one
+# or a custom SimBricks build installed from a .deb. Do not apt-install them:
+# there is no linux-headers package to fetch for a custom kernel.
+if [ ! -d "/lib/modules/$KVER/build" ]; then
+    echo "no kernel build tree at /lib/modules/$KVER/build -- the image needs" >&2
+    echo "the headers matching its kernel to build the Ensō driver." >&2
+    exit 1
+fi
+
+# Only what Ensō's setup.sh does not install itself. sudo, because its scripts
+# and scripts/ensogen.sh use it and the base image may not have it.
+apt-get -y update
+apt-get -y install build-essential git ca-certificates sudo \
+    libnuma-dev rsync bc libelf-dev kmod pkg-config
+
+git clone "$ENSO_REPO" "$ENSO_DIR"
+cd "$ENSO_DIR"
+git checkout "$ENSO_BRANCH"
+
+# Installs dependencies, reserves hugepages, builds and loads the kernel module,
+# then meson-builds and installs the userspace. --no-quartus skips the FPGA
+# toolchain check; it still fetches the bitstream, which we never program.
+./setup.sh --no-quartus
+
+# setup.sh leaves the module in the build tree, so make it modprobe-able.
+install -Dm644 "$ENSO_DIR/software/kernel/linux/intel_fpga_pcie_drv.ko" \
+    "/lib/modules/$KVER/extra/intel_fpga_pcie_drv.ko"
+depmod -a "$KVER"
+
+# ensogen.sh resolves its binaries through $ENSO_DIR/build, so leave the tree in
+# place. Check that what the application classes invoke actually exists.
+test -x "$ENSO_DIR/build/software/examples/echo"
+test -x "$ENSO_DIR/build/software/examples/ensogen"
+test -x "$ENSO_DIR/build/scripts/get_pcap_pkt_size"

simbricks_enso_sys_py-0.6.0/simbricks/components/enso/system/enso.py

@@ -0,0 +1,231 @@
+# Copyright 2026 Max Planck Institute for Software Systems,
+# National University of Singapore, Carnegie Mellon University,
+# and SimBricks UG (haftungsbeschränkt)
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+from __future__ import annotations
+
+import typing as tp
+
+import typing_extensions as tpe
+
+from simbricks.orchestration.system import base as sys_base
+from simbricks.orchestration.system import nic
+from simbricks.orchestration.system.host import app
+from simbricks.orchestration.system.host import base as sys_host
+from simbricks.utils import base as utils_base
+
+if tp.TYPE_CHECKING:
+    from simbricks.orchestration.instantiation import base as inst_base
+
+
+class EnsoNIC(nic.SimplePCIeNIC):
+    """
+    The Ensō NIC.
+    """
+
+    def __init__(self, s: sys_base.System) -> None:
+        super().__init__(s)
+
+
+class EnsoLinuxHost(sys_host.LinuxHost):
+    """
+    A Linux host set up to drive an :class:`EnsoNIC`.
+
+    On top of a plain Linux host this reserves hugepages, mounts ``hugetlbfs``
+    and loads Ensō's kernel driver. The Ensō checkout itself is expected to be
+    in the disk image, put there by :func:`.image.enso_image`.
+    """
+
+    def __init__(self, s: sys_base.System) -> None:
+        super().__init__(s)
+        # Ensō reserves several GiB of hugepages, so give the guest headroom.
+        self.memory: int = 16 * 1024
+        self.cores: int = 2
+
+        self.enso_parent_dir: str = "/root"
+        self.enso_name: str = "enso"
+
+        self.nr_hugepages: int = 4096
+
+        # Ensō's kernel driver, built into the image by install-enso.sh and
+        # installed under /lib/modules/<kver>/extra, so it is modprobe'd by
+        # name.
+        self.enso_kmod: str = "intel_fpga_pcie_drv"
+        self.enso_dev_node: str = "/dev/intel_fpga_pcie_drv"
+
+    @property
+    def enso_dir(self) -> str:
+        return f"{self.enso_parent_dir}/{self.enso_name}"
+
+    def prepare_pre_cp(self, inst: inst_base.Instantiation) -> list[str]:
+        return [
+            "mount -t proc proc /proc",
+            "mount -t sysfs sysfs /sys",
+        ] + super().prepare_pre_cp(inst)
+
+    def prepare_post_cp(self, inst: inst_base.Instantiation) -> list[str]:
+        # NOTE: LinuxHost.prepare_post_cp is bypassed on purpose. It walks every
+        # PCIeHostInterface whose peer is an EthSimpleNIC/SimplePCIeNIC and
+        # emits
+        #     assert com._ip is not None
+        #     ip link set dev ethN up
+        #     ip addr add {com._ip}/24 dev ethN
+        # An EnsoNIC is a SimplePCIeNIC but exposes no kernel netdev.
+        cmds = sys_host.BaseLinuxHost.prepare_post_cp(self, inst)
+        cmds += self._hugepage_cmds()
+        cmds += self._enso_driver_cmds()
+        return cmds
+
+    def _hugepage_cmds(self) -> list[str]:
+        """Equivalent of the hugepage section of Ensō's scripts/sw_setup.sh."""
+        return [
+            "mkdir -p /mnt/huge",
+            'mount | grep -q " /mnt/huge " || mount -t hugetlbfs hugetlbfs /mnt/huge',
+            f"echo {self.nr_hugepages} > "
+            "/sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages",
+        ]
+
+    def _enso_driver_cmds(self) -> list[str]:
+        """Load Ensō's kernel driver and make sure its device node exists.
+
+        Replaces the driver loop of LinuxHost.prepare_post_cp, which we skip
+        (see prepare_post_cp).
+        """
+        cmds: list[str] = []
+        for driver in self.drivers:
+            if driver[0] == "/":
+                cmds.append(f"insmod {driver}")
+            else:
+                cmds.append(f"modprobe {driver}")
+
+        node = self.enso_dev_node
+        cmds += [
+            "modprobe uio",
+            f"modprobe {self.enso_kmod}",
+            f"test -e {node} || mknod {node} c "
+            f'$(grep -w {self.enso_kmod} /proc/devices | cut -f1 -d" ") 0',
+            f"chmod 666 {node}",
+        ]
+        return cmds
+
+    def toJSON(self) -> dict:
+        json_obj = super().toJSON()
+        json_obj["enso_parent_dir"] = self.enso_parent_dir
+        json_obj["enso_name"] = self.enso_name
+        json_obj["nr_hugepages"] = self.nr_hugepages
+        json_obj["enso_kmod"] = self.enso_kmod
+        json_obj["enso_dev_node"] = self.enso_dev_node
+        return json_obj
+
+    @classmethod
+    def fromJSON(cls, system: sys_base.System, json_obj: dict) -> tpe.Self:
+        instance = super().fromJSON(system, json_obj)
+        instance.enso_parent_dir = utils_base.get_json_attr_top(json_obj, "enso_parent_dir")
+        instance.enso_name = utils_base.get_json_attr_top(json_obj, "enso_name")
+        instance.nr_hugepages = int(utils_base.get_json_attr_top(json_obj, "nr_hugepages"))
+        instance.enso_kmod = utils_base.get_json_attr_top(json_obj, "enso_kmod")
+        instance.enso_dev_node = utils_base.get_json_attr_top(json_obj, "enso_dev_node")
+        return instance
+
+
+class EnsoEchoServer(app.BaseLinuxApplication):
+    """
+    Ensō's bundled echo example, ``build/software/examples/echo``.
+    """
+
+    def __init__(self, h: EnsoLinuxHost) -> None:
+        utils_base.has_expected_type(h, EnsoLinuxHost)
+        super().__init__(h)
+        self.threads: int = 1
+        self.queues: int = 2
+        self.cycles: int = 0
+
+    def run_cmds(self, inst: inst_base.Instantiation) -> list[str]:
+        host = self.host
+        assert isinstance(host, EnsoLinuxHost)
+        return [
+            f"cd {host.enso_dir}",
+            f"./build/software/examples/echo {self.threads} {self.queues} {self.cycles}",
+        ]
+
+    def toJSON(self) -> dict:
+        json_obj = super().toJSON()
+        json_obj["threads"] = self.threads
+        json_obj["queues"] = self.queues
+        json_obj["cycles"] = self.cycles
+        return json_obj
+
+    @classmethod
+    def fromJSON(cls, system: sys_base.System, json_obj: dict) -> tpe.Self:
+        instance = super().fromJSON(system, json_obj)
+        instance.threads = int(utils_base.get_json_attr_top(json_obj, "threads"))
+        instance.queues = int(utils_base.get_json_attr_top(json_obj, "queues"))
+        instance.cycles = int(utils_base.get_json_attr_top(json_obj, "cycles"))
+        return instance
+
+
+class EnsoGen(app.BaseLinuxApplication):
+    """
+    Ensō's traffic generator, ``scripts/ensogen.sh``.
+    """
+
+    def __init__(self, h: EnsoLinuxHost) -> None:
+        utils_base.has_expected_type(h, EnsoLinuxHost)
+        super().__init__(h)
+        # None selects Ensō's bundled sample capture, relative to enso_dir.
+        self.pcap: str | None = None
+        self.count: int = 10
+        self.rate: int = 100  # Gbps
+        self.pcie_addr: str | None = None
+
+    def run_cmds(self, inst: inst_base.Instantiation) -> list[str]:
+        host = self.host
+        assert isinstance(host, EnsoLinuxHost)
+        pcap = self.pcap
+        if pcap is None:
+            pcap = f"{host.enso_dir}/scripts/sample_pcaps/2_64_1_2.pcap"
+        cmd = f"./scripts/ensogen.sh {pcap} {self.rate} --count {self.count}"
+        if self.pcie_addr is not None:
+            cmd += f" --pcie-addr {self.pcie_addr}"
+        return [
+            f"cd {host.enso_dir}",
+            f"sleep 5",
+            cmd,
+            f"sleep 5",
+        ]
+
+    def toJSON(self) -> dict:
+        json_obj = super().toJSON()
+        json_obj["pcap"] = self.pcap
+        json_obj["count"] = self.count
+        json_obj["rate"] = self.rate
+        json_obj["pcie_addr"] = self.pcie_addr
+        return json_obj
+
+    @classmethod
+    def fromJSON(cls, system: sys_base.System, json_obj: dict) -> tpe.Self:
+        instance = super().fromJSON(system, json_obj)
+        instance.pcap = utils_base.get_json_attr_top_or_none(json_obj, "pcap")
+        instance.count = int(utils_base.get_json_attr_top(json_obj, "count"))
+        instance.rate = int(utils_base.get_json_attr_top(json_obj, "rate"))
+        instance.pcie_addr = utils_base.get_json_attr_top_or_none(json_obj, "pcie_addr")
+        return instance

simbricks_enso_sys_py-0.6.0/simbricks/components/enso/system/image.py

@@ -0,0 +1,89 @@
+# Copyright 2026 Max Planck Institute for Software Systems,
+# National University of Singapore, Carnegie Mellon University,
+# and SimBricks UG (haftungsbeschränkt)
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+# CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+# TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+"""The Ensō guest image: the SimBricks base image with Ensō installed into it.
+
+    from simbricks.components.enso.system import enso_image
+
+    host.add_disk(enso_image(system))
+"""
+
+from __future__ import annotations
+
+import pathlib
+import shlex
+import typing as tp
+
+from simbricks.imagebuild.packer.image import PackerImage
+from simbricks.orchestration.system import disk_images
+
+if tp.TYPE_CHECKING:
+    from simbricks.orchestration.system import base as sys_base
+
+_DATA = pathlib.Path(__file__).parent / "data"
+
+ENSO_REPO = "https://github.com/crossroadsfpga/enso"
+ENSO_BRANCH = "simbricks-24.04"
+ENSO_DIR = "/root/enso"
+DISK_SIZE = "16G"
+BUILD_MEM_SIZE = "16G"
+BUILD_CPUS = 4
+
+
+def _script(name: str, env: dict[str, str]) -> str:
+    """The packaged script @name with @env exported after its shebang."""
+    lines = (_DATA / name).read_text().splitlines(keepends=True)
+    exports = "".join(f"export {k}={shlex.quote(v)}\n" for k, v in sorted(env.items()))
+    return lines[0] + exports + "".join(lines[1:])
+
+
+def enso_image(
+    system: sys_base.System,
+    enso_repo: str = ENSO_REPO,
+    enso_branch: str = ENSO_BRANCH,
+    enso_dir: str = ENSO_DIR,
+) -> PackerImage:
+    """The SimBricks ``base`` image with Ensō installed into it.
+
+    Built with packer on the runner while the simulation is prepared; cached
+    across runs with ``simbricks-run --image-cache-dir``.
+
+    @enso_repo, @enso_branch and @enso_dir are exported into the install script
+    and are part of the image's content hash. @enso_dir has to match the
+    EnsoLinuxHost this image is attached to.
+
+    The result is an ordinary PackerImage; ``cleanup``, ``accelerator`` etc.
+    can be set on it.
+    """
+    image = PackerImage(system, disk_images.DistroDiskImage(system, "base"))
+    image.disk_size = DISK_SIZE
+    image.mem_size = BUILD_MEM_SIZE
+    image.cpus = BUILD_CPUS
+    image.run_script_str(
+        "install-enso.sh",
+        _script(
+            "install-enso.sh",
+            {"ENSO_REPO": enso_repo, "ENSO_BRANCH": enso_branch, "ENSO_DIR": enso_dir},
+        ),
+    )
+    return image