sdfgen 0.9.0__cp312-cp312-musllinux_1_2_x86_64.whl

sdfgen/__init__.py

@@ -0,0 +1,3 @@
+from .module import SystemDescription, Sddf, DeviceTree, LionsOs
+
+__all__ = ['SystemDescription', 'Sddf', 'LionsOs', 'DeviceTree']

sdfgen/module.py

@@ -0,0 +1,683 @@
+from __future__ import annotations
+import ctypes
+import importlib.util
+from ctypes import (
+    cast, c_void_p, c_char_p, c_uint8, c_uint16, c_uint32, c_uint64, c_bool, POINTER, byref
+)
+from typing import Optional, List, Tuple
+from enum import IntEnum
+
+# TOOD: double check
+MapPermsType = c_uint32
+
+libsdfgen = ctypes.CDLL(importlib.util.find_spec("csdfgen").origin)
+
+libsdfgen.sdfgen_create.argtypes = [c_uint32, c_uint64]
+libsdfgen.sdfgen_create.restype = c_void_p
+
+libsdfgen.sdfgen_destroy.restype = None
+libsdfgen.sdfgen_destroy.argtypes = [c_void_p]
+
+libsdfgen.sdfgen_dtb_parse_from_bytes.restype = c_void_p
+libsdfgen.sdfgen_dtb_parse_from_bytes.argtypes = [c_char_p, c_uint32]
+
+libsdfgen.sdfgen_dtb_destroy.restype = None
+libsdfgen.sdfgen_dtb_destroy.argtypes = [c_void_p]
+
+libsdfgen.sdfgen_dtb_node.restype = c_void_p
+libsdfgen.sdfgen_dtb_node.argtypes = [c_void_p, c_char_p]
+
+libsdfgen.sdfgen_add_pd.restype = None
+libsdfgen.sdfgen_add_pd.argtypes = [c_void_p, c_void_p]
+libsdfgen.sdfgen_add_mr.restype = None
+libsdfgen.sdfgen_add_mr.argtypes = [c_void_p, c_void_p]
+libsdfgen.sdfgen_add_channel.restype = None
+libsdfgen.sdfgen_add_channel.argtypes = [c_void_p, c_void_p]
+
+libsdfgen.sdfgen_pd_set_priority.restype = None
+libsdfgen.sdfgen_pd_set_priority.argtypes = [c_void_p, c_uint8]
+libsdfgen.sdfgen_pd_set_budget.restype = None
+libsdfgen.sdfgen_pd_set_budget.argtypes = [c_void_p, c_uint32]
+libsdfgen.sdfgen_pd_set_period.restype = None
+libsdfgen.sdfgen_pd_set_period.argtypes = [c_void_p, c_uint32]
+libsdfgen.sdfgen_pd_set_stack_size.restype = None
+libsdfgen.sdfgen_pd_set_stack_size.argtypes = [c_void_p, c_uint32]
+
+libsdfgen.sdfgen_to_xml.restype = c_char_p
+libsdfgen.sdfgen_to_xml.argtypes = [c_void_p]
+
+libsdfgen.sdfgen_channel_create.restype = c_void_p
+libsdfgen.sdfgen_channel_create.argtypes = [c_void_p, c_void_p]
+libsdfgen.sdfgen_channel_destroy.restype = None
+libsdfgen.sdfgen_channel_destroy.argtypes = [c_void_p]
+libsdfgen.sdfgen_channel_get_pd_a_id.restype = c_uint8
+libsdfgen.sdfgen_channel_get_pd_a_id.argtypes = [c_void_p]
+libsdfgen.sdfgen_channel_get_pd_b_id.restype = c_uint8
+libsdfgen.sdfgen_channel_get_pd_b_id.argtypes = [c_void_p]
+
+libsdfgen.sdfgen_map_create.restype = c_void_p
+libsdfgen.sdfgen_map_create.argtypes = [c_void_p, c_uint64, MapPermsType, c_bool]
+libsdfgen.sdfgen_map_destroy.restype = None
+libsdfgen.sdfgen_map_destroy.argtypes = [c_void_p]
+
+libsdfgen.sdfgen_mr_create.restype = c_void_p
+libsdfgen.sdfgen_mr_create.argtypes = [c_char_p, c_uint64]
+libsdfgen.sdfgen_mr_create_physical.restype = c_void_p
+libsdfgen.sdfgen_mr_create_physical.argtypes = [c_char_p, c_uint64, c_uint64]
+libsdfgen.sdfgen_mr_destroy.restype = None
+libsdfgen.sdfgen_mr_destroy.argtypes = [c_void_p]
+
+libsdfgen.sdfgen_vm_create.restype = c_void_p
+libsdfgen.sdfgen_vm_create.argtypes = [c_char_p, POINTER(c_void_p), c_uint32]
+libsdfgen.sdfgen_vm_destroy.restype = None
+libsdfgen.sdfgen_vm_destroy.argtypes = [c_void_p]
+
+libsdfgen.sdfgen_vm_add_map.restype = None
+libsdfgen.sdfgen_vm_add_map.argtypes = [c_void_p, c_void_p]
+
+libsdfgen.sdfgen_vm_vcpu_create.restype = c_void_p
+libsdfgen.sdfgen_vm_vcpu_create.argtypes = [c_uint8, c_uint16]
+libsdfgen.sdfgen_vm_vcpu_destroy.restype = None
+libsdfgen.sdfgen_vm_vcpu_destroy.argtypes = [c_void_p]
+
+libsdfgen.sdfgen_pd_create.restype = c_void_p
+libsdfgen.sdfgen_pd_create.argtypes = [c_char_p, c_char_p]
+libsdfgen.sdfgen_pd_destroy.restype = None
+libsdfgen.sdfgen_pd_destroy.argtypes = [c_void_p]
+
+libsdfgen.sdfgen_pd_add_child.restype = c_uint8
+libsdfgen.sdfgen_pd_add_child.argtypes = [c_void_p, c_void_p, POINTER(c_uint8)]
+libsdfgen.sdfgen_pd_add_map.restype = None
+libsdfgen.sdfgen_pd_add_map.argtypes = [c_void_p, c_void_p]
+
+libsdfgen.sdfgen_sddf_timer.restype = c_void_p
+libsdfgen.sdfgen_sddf_timer.argtypes = [c_void_p, c_void_p, c_void_p]
+libsdfgen.sdfgen_sddf_timer_destroy.restype = None
+libsdfgen.sdfgen_sddf_timer_destroy.argtypes = [c_void_p]
+
+libsdfgen.sdfgen_sddf_timer_add_client.restype = None
+libsdfgen.sdfgen_sddf_timer_add_client.argtypes = [c_void_p, c_void_p]
+
+libsdfgen.sdfgen_sddf_timer_connect.restype = c_bool
+libsdfgen.sdfgen_sddf_timer_connect.argtypes = [c_void_p]
+libsdfgen.sdfgen_sddf_timer_serialise_config.restype = c_bool
+libsdfgen.sdfgen_sddf_timer_serialise_config.argtypes = [c_void_p, c_char_p]
+
+libsdfgen.sdfgen_sddf_i2c.restype = c_void_p
+libsdfgen.sdfgen_sddf_i2c.argtypes = [c_void_p, c_void_p, c_void_p, c_void_p]
+libsdfgen.sdfgen_sddf_i2c_destroy.restype = None
+libsdfgen.sdfgen_sddf_i2c_destroy.argtypes = [c_void_p]
+
+libsdfgen.sdfgen_sddf_i2c_add_client.restype = None
+libsdfgen.sdfgen_sddf_i2c_add_client.argtypes = [c_void_p, c_void_p]
+
+libsdfgen.sdfgen_sddf_i2c_connect.restype = c_bool
+libsdfgen.sdfgen_sddf_i2c_connect.argtypes = [c_void_p]
+libsdfgen.sdfgen_sddf_i2c_serialise_config.restype = c_bool
+libsdfgen.sdfgen_sddf_i2c_serialise_config.argtypes = [c_void_p, c_char_p]
+
+libsdfgen.sdfgen_sddf_block.restype = c_void_p
+libsdfgen.sdfgen_sddf_block.argtypes = [c_void_p, c_void_p, c_void_p, c_void_p]
+libsdfgen.sdfgen_sddf_block_destroy.restype = None
+libsdfgen.sdfgen_sddf_block_destroy.argtypes = [c_void_p]
+
+libsdfgen.sdfgen_sddf_block_add_client.restype = None
+libsdfgen.sdfgen_sddf_block_add_client.argtypes = [c_void_p, c_void_p, c_uint32]
+
+libsdfgen.sdfgen_sddf_block_connect.restype = c_bool
+libsdfgen.sdfgen_sddf_block_connect.argtypes = [c_void_p]
+
+libsdfgen.sdfgen_sddf_block_serialise_config.restype = c_bool
+libsdfgen.sdfgen_sddf_block_serialise_config.argtypes = [c_void_p, c_char_p]
+
+libsdfgen.sdfgen_sddf_serial.restype = c_void_p
+libsdfgen.sdfgen_sddf_serial.argtypes = [c_void_p, c_void_p, c_void_p, c_void_p, c_void_p]
+libsdfgen.sdfgen_sddf_serial_destroy.restype = None
+libsdfgen.sdfgen_sddf_serial_destroy.argtypes = [c_void_p]
+
+libsdfgen.sdfgen_sddf_serial_add_client.restype = None
+libsdfgen.sdfgen_sddf_serial_add_client.argtypes = [c_void_p, c_void_p]
+
+libsdfgen.sdfgen_sddf_serial_connect.restype = c_bool
+libsdfgen.sdfgen_sddf_serial_connect.argtypes = [c_void_p]
+
+libsdfgen.sdfgen_sddf_serial_serialise_config.restype = c_bool
+libsdfgen.sdfgen_sddf_serial_serialise_config.argtypes = [c_void_p, c_char_p]
+
+libsdfgen.sdfgen_sddf_net.restype = c_void_p
+libsdfgen.sdfgen_sddf_net.argtypes = [c_void_p, c_void_p, c_void_p, c_void_p, c_void_p]
+libsdfgen.sdfgen_sddf_net_destroy.restype = None
+libsdfgen.sdfgen_sddf_net_destroy.argtypes = [c_void_p]
+
+libsdfgen.sdfgen_sddf_net_add_client_with_copier.restype = c_bool
+libsdfgen.sdfgen_sddf_net_add_client_with_copier.argtypes = [
+    c_void_p,
+    c_void_p,
+    c_void_p,
+    c_char_p
+]
+
+libsdfgen.sdfgen_sddf_net_connect.restype = c_bool
+libsdfgen.sdfgen_sddf_net_connect.argtypes = [c_void_p]
+
+libsdfgen.sdfgen_sddf_net_serialise_config.restype = c_bool
+libsdfgen.sdfgen_sddf_net_serialise_config.argtypes = [c_void_p, c_char_p]
+
+libsdfgen.sdfgen_lionsos_fs_fat.restype = None
+libsdfgen.sdfgen_lionsos_fs_fat.argtypes = [c_void_p, c_void_p, c_void_p]
+libsdfgen.sdfgen_lionsos_fs_fat_connect.restype = c_bool
+libsdfgen.sdfgen_lionsos_fs_fat_connect.argtypes = [c_void_p]
+libsdfgen.sdfgen_lionsos_fs_nfs.restype = None
+libsdfgen.sdfgen_lionsos_fs_nfs.argtypes = [c_void_p, c_void_p, c_void_p, c_void_p, c_void_p]
+libsdfgen.sdfgen_lionsos_fs_nfs_connect.restype = c_bool
+libsdfgen.sdfgen_lionsos_fs_nfs_connect.argtypes = [c_void_p]
+
+
+class DeviceTree:
+    """
+    This class exists to allow other layers to be generic to boards or architectures
+    by letting the user talk about hardware via the Device Tree.
+    """
+    _obj: c_void_p
+    _bytes: bytes
+
+    def __init__(self, data: bytes):
+        """
+        Parse a Device Tree Blob (.dtb) and use it to get nodes
+        for generating sDDF device classes or other components.
+        """
+        # Data is stored explicitly so it is not freed in GC.
+        # The DTB parser assumes the memory does not go away.
+        self._bytes = data
+        self._obj = libsdfgen.sdfgen_dtb_parse_from_bytes(c_char_p(data), len(data))
+        assert self._obj is not None
+
+    def __del__(self):
+        libsdfgen.sdfgen_dtb_destroy(self._obj)
+
+    class Node:
+        # TODO: does having a node increase the ref count for the
+        # device tree
+        def __init__(self, device_tree: DeviceTree, node: str):
+            c_node = c_char_p(node.encode("utf-8"))
+            self._obj = libsdfgen.sdfgen_dtb_node(device_tree._obj, c_node)
+
+            if self._obj is None:
+                raise Exception(f"could not find DTB node '{node}'")
+
+    def node(self, name: str) -> DeviceTree.Node:
+        """
+        Given a parsed DeviceTree, find the specific node based on the node names.
+        Child nodes can be referenced by separating the parent and child node name
+        by '/'.
+
+        Example:
+
+        .. code-block:: python
+
+            dtb = DeviceTree(dtb_bytes)
+            dtb.node("soc/timer@13050000")
+
+        would be used to access the timer device on a Device Tree that looked like:
+
+        .. code-block::
+
+            soc {
+                timer@13050000 {
+                    ...
+                };
+            };
+        """
+        return DeviceTree.Node(self, name)
+
+
+class SystemDescription:
+    """
+    Class for describing a Microkit system. Manages all Microkit resources such as
+    Protection Domains, Memory Regions, Channels, etc.
+    """
+
+    _obj: c_void_p
+    # We need to hold references to the PDs in case they get GC'd.
+    # TODO: is this really necessary?
+    _pds: List[ProtectionDomain]
+
+    class Arch(IntEnum):
+        """Target architecture. Used to resolve architecture specific features or attributes."""
+        # Important that this aligns with sdfgen_arch_t in the C bindings.
+        AARCH32 = 0,
+        AARCH64 = 1,
+        RISCV32 = 2,
+        RISCV64 = 3,
+        X86 = 4,
+        X86_64 = 5,
+
+    class ProtectionDomain:
+        name: str
+        _obj: c_void_p
+        # We need to hold references to the PDs in case they get GC'd.
+        _child_pds: List[SystemDescription.ProtectionDomain]
+
+        def __init__(
+            self,
+            name: str,
+            program_image: str,
+            priority: Optional[int] = None,
+            budget: Optional[int] = None,
+            period: Optional[int] = None,
+            stack_size: Optional[int] = None
+        ) -> None:
+            # TODO: don't do this, users might expect to be able to mutate name which
+            # is not the case
+            self.name = name
+            c_name = c_char_p(name.encode("utf-8"))
+            c_program_image = c_char_p(program_image.encode("utf-8"))
+            self._obj = libsdfgen.sdfgen_pd_create(c_name, c_program_image)
+            self._child_pds = []
+            if priority is not None:
+                libsdfgen.sdfgen_pd_set_priority(self._obj, priority)
+            if budget is not None:
+                libsdfgen.sdfgen_pd_set_budget(self._obj, budget)
+            if period is not None:
+                libsdfgen.sdfgen_pd_set_period(self._obj, period)
+            if stack_size is not None:
+                libsdfgen.sdfgen_pd_set_stack_size(self._obj, stack_size)
+
+        def add_child_pd(self, child_pd: SystemDescription.ProtectionDomain, child_id=None) -> int:
+            """
+            Returns allocated ID for the child.
+            """
+            c_child_id = byref(c_uint8(child_id)) if child_id else None
+
+            returned_id = libsdfgen.sdfgen_pd_add_child(self._obj, child_pd._obj, c_child_id)
+            if returned_id is None:
+                raise Exception("Could not allocate child PD ID")
+
+            self._child_pds.append(child_pd)
+
+            return returned_id
+
+        def add_map(self, map: SystemDescription.Map):
+            libsdfgen.sdfgen_pd_add_map(self._obj, map._obj)
+
+        def set_virtual_machine(self, vm: SystemDescription.VirtualMachine):
+            ret = libsdfgen.sdfgen_pd_set_virtual_machine(self._obj, vm._obj)
+            if not ret:
+                # TODO: improve error message
+                raise Exception("ProtectionDomain already has VirtualMachine")
+
+        def __del__(self):
+            libsdfgen.sdfgen_pd_destroy(self._obj)
+
+    class VirtualMachine:
+        _obj: c_void_p
+
+        class VirtualCpu:
+            def __init__(self, *, id: int, cpu: Optional[int] = 0):
+                # TODO: error checking
+                self._obj = libsdfgen.sdfgen_vm_vcpu_create(id, cpu)
+
+        def __init__(self, name: str, vcpus: List[VirtualCpu]):
+            vcpus_tuple: Tuple[c_void_p] = tuple([vcpu._obj for vcpu in vcpus])
+            c_vcpus = (c_void_p * len(vcpus))(vcpus_tuple)
+            self._obj = libsdfgen.sdfgen_vm_create(name, cast(c_vcpus, POINTER(c_void_p)))
+
+        def add_map(self, map: SystemDescription.Map):
+            libsdfgen.sdfgen_vm_add_map(self._obj, map._obj)
+
+    class Map:
+        _obj: c_void_p
+
+        class Perms:
+            def __init__(self, *, r: bool = False, w: bool = False, x: bool = False):
+                self.read = r
+                self.write = w
+                self.execute = x
+
+            def _to_c_bindings(self) -> int:
+                c_perms = 0
+                if self.read:
+                    c_perms |= 0b001
+                if self.write:
+                    c_perms |= 0b010
+                if self.execute:
+                    c_perms |= 0b100
+
+                return c_perms
+
+        def __init__(
+            self,
+            mr: SystemDescription.MemoryRegion,
+            vaddr: int,
+            perms: Perms,
+            *,
+            cached: bool = True,
+        ) -> None:
+            self._obj = libsdfgen.sdfgen_map_create(mr._obj, vaddr, perms._to_c_bindings(), cached)
+
+    class MemoryRegion:
+        _obj: c_void_p
+
+        # TODO: handle more options
+        def __init__(
+            self,
+            name: str,
+            size: int,
+            *,
+            paddr: Optional[int] = None
+        ) -> None:
+            c_name = c_char_p(name.encode("utf-8"))
+            if paddr:
+                self._obj = libsdfgen.sdfgen_mr_create_physical(c_name, size, paddr)
+            else:
+                self._obj = libsdfgen.sdfgen_mr_create(c_name, size)
+
+        def __del__(self):
+            libsdfgen.sdfgen_mr_destroy(self._obj)
+
+    class Channel:
+        _obj: c_void_p
+
+        # TODO: handle options
+        def __init__(
+            self,
+            a: SystemDescription.ProtectionDomain,
+            b: SystemDescription.ProtectionDomain,
+            *,
+            pp_a=False,
+            pp_b=False,
+            notify_a=True,
+            notify_b=True
+        ) -> None:
+            self._obj = libsdfgen.sdfgen_channel_create(a._obj, b._obj)
+
+        @property
+        def pd_a_id(self) -> int:
+            return libsdfgen.sdfgen_channel_get_pd_a_id(self._obj)
+
+        @property
+        def pd_b_id(self) -> int:
+            return libsdfgen.sdfgen_channel_get_pd_b_id(self._obj)
+
+        def __del__(self):
+            libsdfgen.sdfgen_channel_destroy(self._obj)
+
+    def __init__(self, arch: Arch, paddr_top: int) -> None:
+        """
+        Create a System Description
+        """
+        self._obj = libsdfgen.sdfgen_create(arch.value, paddr_top)
+        self._pds = []
+
+    def __del__(self):
+        libsdfgen.sdfgen_destroy(self._obj)
+
+    def add_pd(self, pd: ProtectionDomain):
+        self._pds.append(pd)
+        libsdfgen.sdfgen_add_pd(self._obj, pd._obj)
+
+    def add_mr(self, mr: MemoryRegion):
+        libsdfgen.sdfgen_add_mr(self._obj, mr._obj)
+
+    def add_channel(self, ch: Channel):
+        libsdfgen.sdfgen_add_channel(self._obj, ch._obj)
+
+    def xml(self) -> str:
+        """
+        Generate the XML view of the System Description Format for consumption by the Microkit.
+        """
+        return libsdfgen.sdfgen_to_xml(self._obj).decode("utf-8")
+
+
+class Sddf:
+    """
+    Class for creating I/O systems based on the seL4 Device Driver Framework (sDDF).
+
+    There is a Python class for each device class (e.g Block, Network). They all follow
+    the pattern of being initialised, then having clients added, and then being connected
+    before the final SDF is generated.
+    """
+    def __init__(self, path: str):
+        """
+        :param path: str to the root of the sDDF source code.
+        """
+        ret = libsdfgen.sdfgen_sddf_init(c_char_p(path.encode("utf-8")))
+        if not ret:
+            # TODO: report more information
+            raise Exception("sDDF failed to initialise")
+
+    def __del__(self):
+        # TODO
+        pass
+
+    class Serial:
+        _obj: c_void_p
+
+        def __init__(
+            self,
+            sdf: SystemDescription,
+            device: Optional[DeviceTree.Node],
+            driver: SystemDescription.ProtectionDomain,
+            virt_tx: SystemDescription.ProtectionDomain,
+            *,
+            virt_rx: Optional[SystemDescription.ProtectionDomain] = None
+        ) -> None:
+            if device is None:
+                device_obj = None
+            else:
+                device_obj = device._obj
+
+            if virt_rx is None:
+                virt_rx_obj = None
+            else:
+                virt_rx_obj = virt_rx._obj
+
+            self._obj = libsdfgen.sdfgen_sddf_serial(
+                sdf._obj, device_obj, driver._obj, virt_tx._obj, virt_rx_obj
+            )
+
+        def add_client(self, client: SystemDescription.ProtectionDomain):
+            """Add a new client connection to the serial system."""
+            libsdfgen.sdfgen_sddf_serial_add_client(self._obj, client._obj)
+
+        def connect(self) -> bool:
+            """
+            Construct and all resources to the associated SystemDescription,
+            returns whether successful.
+
+            Must have all clients and options set before calling.
+
+            Cannot be called more than once.
+            """
+            return libsdfgen.sdfgen_sddf_serial_connect(self._obj)
+
+        def serialise_config(self, output_dir: str) -> bool:
+            c_output_dir = c_char_p(output_dir.encode("utf-8"))
+            return libsdfgen.sdfgen_sddf_serial_serialise_config(self._obj, c_output_dir)
+
+        def __del__(self):
+            libsdfgen.sdfgen_sddf_serial_destroy(self._obj)
+
+    class I2c:
+        _obj: c_void_p
+
+        def __init__(
+            self,
+            sdf: SystemDescription,
+            device: Optional[DeviceTree.Node],
+            driver: SystemDescription.ProtectionDomain,
+            virt: SystemDescription.ProtectionDomain
+        ) -> None:
+            if device is None:
+                device_obj = None
+            else:
+                device_obj = device._obj
+
+            self._obj = libsdfgen.sdfgen_sddf_i2c(sdf._obj, device_obj, driver._obj, virt._obj)
+
+        def add_client(self, client: SystemDescription.ProtectionDomain):
+            libsdfgen.sdfgen_sddf_i2c_add_client(self._obj, client._obj)
+
+        def connect(self) -> bool:
+            return libsdfgen.sdfgen_sddf_i2c_connect(self._obj)
+
+        def serialise_config(self, output_dir: str) -> bool:
+            c_output_dir = c_char_p(output_dir.encode("utf-8"))
+            return libsdfgen.sdfgen_sddf_i2c_serialise_config(self._obj, c_output_dir)
+
+        def __del__(self):
+            libsdfgen.sdfgen_sddf_i2c_destroy(self._obj)
+
+    class Block:
+        _obj: c_void_p
+
+        def __init__(
+            self,
+            sdf: SystemDescription,
+            device: Optional[DeviceTree.Node],
+            driver: SystemDescription.ProtectionDomain,
+            virt: SystemDescription.ProtectionDomain
+        ) -> None:
+            if device is None:
+                device_obj = None
+            else:
+                device_obj = device._obj
+
+            self._obj = libsdfgen.sdfgen_sddf_block(sdf._obj, device_obj, driver._obj, virt._obj)
+
+        def add_client(self, client: SystemDescription.ProtectionDomain, *, partition: int):
+            libsdfgen.sdfgen_sddf_block_add_client(self._obj, client._obj, partition)
+
+        def connect(self) -> bool:
+            return libsdfgen.sdfgen_sddf_block_connect(self._obj)
+
+        def serialise_config(self, output_dir: str) -> bool:
+            c_output_dir = c_char_p(output_dir.encode("utf-8"))
+            return libsdfgen.sdfgen_sddf_block_serialise_config(self._obj, c_output_dir)
+
+        def __del__(self):
+            libsdfgen.sdfgen_sddf_block_destroy(self._obj)
+
+    class Network:
+        _obj: c_void_p
+
+        def __init__(
+            self,
+            sdf: SystemDescription,
+            device: Optional[DeviceTree.Node],
+            driver: SystemDescription.ProtectionDomain,
+            virt_tx: SystemDescription.ProtectionDomain,
+            virt_rx: SystemDescription.ProtectionDomain
+        ) -> None:
+            if device is None:
+                device_obj = None
+            else:
+                device_obj = device._obj
+
+            self._obj = libsdfgen.sdfgen_sddf_net(
+                sdf._obj, device_obj, driver._obj, virt_tx._obj, virt_rx._obj
+            )
+
+        def add_client_with_copier(
+            self,
+            client: SystemDescription.ProtectionDomain,
+            copier: SystemDescription.ProtectionDomain,
+            *,
+            mac_addr: Optional[str] = None
+        ) -> None:
+            """
+            Add a client connected to a copier component for RX traffic.
+
+            :param copier: must be unique to this client, cannot be used with any other client.
+            :param mac_addr: must be unique to the Network system.
+            """
+            if mac_addr is not None and len(mac_addr) != 17:
+                raise Exception(f"invalid MAC address length for client '{client.name}', {mac_addr}")
+
+            c_mac_addr = c_char_p(0)
+            if mac_addr is not None:
+                c_mac_addr = c_char_p(mac_addr.encode("utf-8"))
+            ret = libsdfgen.sdfgen_sddf_net_add_client_with_copier(
+                self._obj, client._obj, copier._obj, c_mac_addr
+            )
+            if ret == 0:
+                return
+            elif ret == 1:
+                raise Exception(f"duplicate MAC address given '{mac_addr}'")
+            elif ret == 2:
+                raise Exception(f"duplicate client given '{client}'")
+            elif ret == 3:
+                raise Exception(f"duplicate copier given '{copier}'")
+            else:
+                raise Exception("internal error")
+
+        def connect(self) -> bool:
+            return libsdfgen.sdfgen_sddf_net_connect(self._obj)
+
+        def serialise_config(self, output_dir: str) -> bool:
+            c_output_dir = c_char_p(output_dir.encode("utf-8"))
+            return libsdfgen.sdfgen_sddf_net_serialise_config(self._obj, c_output_dir)
+
+        def __del__(self):
+            libsdfgen.sdfgen_sddf_net_destroy(self._obj)
+
+    class Timer:
+        _obj: c_void_p
+
+        def __init__(
+            self,
+            sdf: SystemDescription,
+            device: Optional[DeviceTree.Node],
+            driver: SystemDescription.ProtectionDomain
+        ) -> None:
+            if device is None:
+                device_obj = None
+            else:
+                device_obj = device._obj
+
+            self._obj: c_void_p = libsdfgen.sdfgen_sddf_timer(sdf._obj, device_obj, driver._obj)
+
+        def add_client(self, client: SystemDescription.ProtectionDomain):
+            libsdfgen.sdfgen_sddf_timer_add_client(self._obj, client._obj)
+
+        def connect(self) -> bool:
+            return libsdfgen.sdfgen_sddf_timer_connect(self._obj)
+
+        def serialise_config(self, output_dir: str) -> bool:
+            c_output_dir = c_char_p(output_dir.encode("utf-8"))
+            return libsdfgen.sdfgen_sddf_timer_serialise_config(self._obj, c_output_dir)
+
+        def __del__(self):
+            libsdfgen.sdfgen_sddf_timer_destroy(self._obj)
+
+class LionsOs:
+    class FileSystem:
+        class Fat:
+            _obj: c_void_p
+
+            def __init__(
+                self,
+                sdf: SystemDescription,
+                fs: SystemDescription.ProtectionDomain,
+                client: SystemDescription.ProtectionDomain
+            ):
+                self._obj = libsdfgen.sdfgen_lionsos_fs_fat(sdf._obj, fs._obj, client._obj)
+
+            def connect(self) -> bool:
+                return libsdfgen.sdfgen_lionsos_fs_fat_connect(self._obj)
+
+        class Nfs:
+            _obj: c_void_p
+
+            def __init__(
+                self,
+                sdf: SystemDescription,
+                fs: SystemDescription.ProtectionDomain,
+                client: SystemDescription.ProtectionDomain,
+                net: Sddf.Network,
+                net_copier: SystemDescription.ProtectionDomain
+            ):
+                self._obj = libsdfgen.sdfgen_lionsos_fs_nfs(sdf._obj, fs._obj, client._obj, net._obj, net_copier._obj)
+
+            def connect(self) -> bool:
+                return libsdfgen.sdfgen_lionsos_fs_fat_connect(self._obj)

sdfgen-0.9.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.1
+Name: sdfgen
+Version: 0.9.0
+Summary: Automating the creation of Microkit System Description Files (SDF)
+Home-page: https://github.com/au-ts/microkit_sdf_gen
+Description-Content-Type: text/markdown
+
+# Higher-level tooling for constructing seL4 Microkit systems
+
+This repository currently holds various programs to help with automating the
+process of creating seL4 Microkit systems.
+
+> [!IMPORTANT]
+> This project is experimental, we are using it internally to get it into a
+> usable state for the public. For development this work exists in a separate repository,
+> but that may change once it has matured (e.g by being apart of the official Microkit
+> repository).
+
+## Problem
+
+In order to remain simple, the seL4 Microkit (intentionally) does not provide one-size-fits-all
+abstractions for creating systems where the information about the design of the system flows into
+the actual code of the system.
+
+A concrete example of this might be say some code that needs to know how many clients it needs to
+serve. This obviously depends on the system designer, and could easily be something that changes
+for different configurations of the same system. The Microkit SDF offers no way to pass down this
+kind of information. For the example described, an easy 'solution' would be to pass some kind of
+compile-time parameter (e.g a #define in C) for the number of clients. However imagine now you
+have the same system with two configurations, with two clients and one with three, this requires
+two separate SDF files even though they are very similar systems and the code remains identical
+expect for the compile-time parameter. This problem ultimately hampers experimentation.
+
+Another 'problem' with SDF is that is verbose and descriptive. I say 'problem' as the verbosity of it
+makes it an ideal source of truth for the design of the system and hides minimal information as to the
+capability distribution and access policy of a system. But the negative of this is that it does not scale
+well, even small changes to a large SDF file are difficult to make and ensure are correct.
+
+## Solution(s)
+
+* Allow for users to easily auto-generate SDF programmatically using a tool called `sdfgen`.
+* Create a graphical user-interface to visually display and produce/maintain the design of a Microkit system.
+  This graphical user-interface will sort of act as a 'frontend' for the `sdfgen` tool.
+
+Both of these solutions are very much in a work-in-progress state.
+
+## Developing
+
+All the tooling is currently written in [Zig](https://ziglang.org/download/) with bindings
+for other languages available.
+
+### Dependencies
+
+There are two dependencies:
+
+* Zig (`0.14.0-dev.2079+ba2d00663` or higher)
+  * See https://ziglang.org/download/, until 0.14.0 is released we rely on a master version of Zig.
+    Once 0.14.0 is released (most likely in a couple of months) we can pin to that release.
+* Device Tree Compiler (dtc)
+
+### Tests
+
+To test the Zig and C bindings, you can run:
+```sh
+zig build test
+```
+
+### Zig bindings
+
+The source code for the sdfgen tooling is written in Zig, and so we simply expose a module called
+`sdf` in `build.zig`.
+
+To build and run an example of the Zig bindings being used run:
+```sh
+zig build zig_example -- --example webserver --board qemu_virt_aarch64
+```
+
+The source code is in `examples/examples.zig`.
+
+To see all the options run:
+```sh
+zig build zig_example -- --help
+```
+
+### C bindings
+
+```sh
+zig build c
+```
+
+The library will be at `zig-out/lib/csdfgen`.
+
+The source code for the bindings is in `src/c/`.
+
+To run an example C program that uses the bindings, run:
+```sh
+zig build c_example
+```
+
+The source code for the example is in `examples/examples.c`.
+
+### Python bindings
+
+The Python package is supported for versions 3.9 to 3.13.
+Linux (x86-64) and macOS (Intel/Apple Silicon) are supported. Windows is *not* supported.
+
+The Python bindings are all in Python itself, and do direct FFI to the C bindings via
+[ctypes](https://docs.python.org/3/library/ctypes.html).
+
+#### Building the package
+
+To build a usable Python package run the following:
+```sh
+python3 -m venv venv
+./venv/bin/python3 -m pip install .
+```
+
+Now you should be able to import and use the bindings:
+```sh
+./venv/bin/python3
+>>> import sdfgen
+>>> help(sdfgen)
+```
+
+#### Publishing Python packages
+
+Binary releases of the Python package (known as 'wheels' in the Python universe) are published to
+[PyPI](https://pypi.org/project/microkit_sdfgen/).
+
+Unlike most Python packages, ours is a bit more complicated because:
+1. We depend on an external C library.
+2. We are building that external C library via Zig and not a regular C compiler.
+
+These have some consequences, mainly that the regular `setup.py` has a custom
+`build_extension` function that calls out to Zig. It calls out to `zig build c`
+using the correct output library name/path that the Python packaging
+wants to use.
+
+This means that you *must* use Zig to build the Python package from source.
+
+##### Supported versions
+
+We try to support all versions of Python people would want to use, within reason.
+
+Right now, that means CPython 3.9 is the lowest version available. If there is a
+missing Python package target (OS, architecture, or version), please open an issue.
+
+##### CI
+
+For the CI, we use [cibuildwheel](https://cibuildwheel.pypa.io/) to automate the process of building
+for various architectures/operating systems.
+
+The CI runs on every commit and produces GitHub action artefacts that contain all the wheels (`*.whl`).
+
+For any new tags to the repository, the CI also uploads a new version of the package to PyPI automatically.
+Note that each tag should have a new version in the `VERSION` file at the root of the source. See
+[scripts/README.md](scripts/README.md) for doing this.
+
+The publishing job works by authenticating the repository's GitHub workflow with the package on PyPI, there
+are no tokens etc stored on GitHub.

sdfgen-0.9.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+csdfgen.cpython-312-x86_64-linux-musl.so,sha256=Vva1vY4-RvPsr9wNA9AyzUKZmynnDo-0B4kLJ1yemYQ,3847008
+sdfgen/module.py,sha256=0DK9UsggaL7dqP-16bh1q-2LJsU-AOzn-bpdVkQg9-I,24807
+sdfgen/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sdfgen/__init__.py,sha256=qFoYMCiM89s1BduC2hWsDRa3kGhvmJcxJsaHMWLhf1g,131
+sdfgen-0.9.0.dist-info/METADATA,sha256=TvnwfHvf1WYJ0yjYMrhdJc0LXEOAOTz7aJQxSpK-ajM,5913
+sdfgen-0.9.0.dist-info/RECORD,,
+sdfgen-0.9.0.dist-info/top_level.txt,sha256=M3gUW9vTMij10peQKgv1Qs0jZkdsk_PG0REFxuv6jNY,15
+sdfgen-0.9.0.dist-info/WHEEL,sha256=BwYrisTu1yp8WloXcEi-3Rmdx-uar3nqcuXFSFGpP_Q,112

sdfgen-0.9.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.1.0)
+Root-Is-Purelib: false
+Tag: cp312-cp312-musllinux_1_2_x86_64
+

sdfgen-0.9.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+csdfgen
+sdfgen