cocotbext-umi 0.0.2__py3-none-any.whl

cocotbext/umi/__init__.py

@@ -0,0 +1,7 @@
+# Version number
+__version__ = "0.0.2"
+
+# Sub-modules
+from . import sumi, tumi
+
+__all__ = ["sumi", "tumi"]

cocotbext/umi/drivers/sumi_driver.py

@@ -0,0 +1,92 @@
+from typing import Any
+
+from cocotb.types import LogicArray
+from cocotb.triggers import RisingEdge
+from cocotb.handle import SimHandleBase
+
+from cocotb_bus.drivers import ValidatedBusDriver
+
+from cocotbext.umi.sumi import SumiTransaction
+
+
+class SumiDriver(ValidatedBusDriver):
+
+    _signals = [
+        "valid",
+        "cmd",
+        "dstaddr",
+        "srcaddr",
+        "data",
+        "ready"
+    ]
+
+    _optional_signals = []
+
+    def __init__(
+        self,
+        entity: SimHandleBase,
+        name: str,
+        clock: SimHandleBase,
+        *,
+        config={},
+        **kwargs: Any
+    ):
+        ValidatedBusDriver.__init__(self, entity, name, clock, **kwargs)
+
+        self.clock = clock
+        self.bus.valid.value = 0
+
+        self.addr_width = len(self.bus.dstaddr)
+        self.data_width = len(self.bus.data)
+
+    def get_bus_width(self) -> int:
+        return self.data_width
+
+    def get_addr_width(self) -> int:
+        return self.addr_width
+
+    async def _driver_send(self, transaction: SumiTransaction, sync: bool = True) -> None:
+        """Implementation for BusDriver.
+        Args:
+            transaction: The transaction to send.
+            sync: Synchronize the transfer by waiting for a rising edge.
+        """
+
+        clk_re = RisingEdge(self.clock)
+
+        if sync:
+            await clk_re
+
+        # Insert a gap where valid is low
+        if not self.on:
+            self.bus.valid.value = 0
+            for _ in range(self.off):
+                await clk_re
+
+            # Grab the next set of on/off values
+            self._next_valids()
+
+        # Consume a valid cycle
+        if self.on is not True and self.on:
+            self.on -= 1
+
+        def ready() -> bool:
+            return bool(self.bus.ready.value)
+
+        bus_size = len(self.bus.data)//8
+
+        while True:
+            self.bus.valid.value = 1
+            self.bus.cmd.value = int(transaction.cmd)
+            self.bus.data.value = LogicArray.from_bytes(
+                value=transaction.data + bytearray([0]*(bus_size - len(transaction.data))),
+                range=len(self.bus.data),
+                byteorder="little"
+            )
+            self.bus.dstaddr.value = int(transaction.da)
+            self.bus.srcaddr.value = int(transaction.sa)
+            await clk_re
+            if ready():
+                break
+
+        self.bus.valid.value = 0

cocotbext/umi/models/umi_memory_device.py

@@ -0,0 +1,123 @@
+from cocotbext.umi.sumi import SumiCmd, SumiCmdType, SumiTransaction
+from cocotbext.umi.tumi import TumiTransaction
+from cocotbext.umi.drivers.sumi_driver import SumiDriver
+from cocotbext.umi.monitors.sumi_monitor import SumiMonitor
+
+
+class UmiMemoryDevice:
+    """
+    Virtual memory device that responds to UMI read/write requests.
+
+    Uses a SumiMonitor to receive requests and a SumiDriver to send responses.
+    """
+
+    def __init__(
+        self,
+        monitor: SumiMonitor,
+        driver: SumiDriver,
+        log=None
+    ):
+        self.monitor = monitor
+        self.driver = driver
+        self.log = log
+        self.memory: dict[int, int] = {}
+
+        self.dw = self.driver.get_bus_width()
+        self.aw = self.driver.get_addr_width()
+
+        self.monitor.add_callback(self._on_transaction)
+
+    def _on_transaction(self, transaction: SumiTransaction):
+        """Callback invoked when the monitor receives a transaction."""
+        cmd_type = int(transaction.cmd.cmd_type)
+
+        if cmd_type == SumiCmdType.UMI_REQ_WRITE:
+            self._handle_write(transaction, send_response=True)
+        elif cmd_type == SumiCmdType.UMI_REQ_POSTED:
+            self._handle_write(transaction, send_response=False)
+        elif cmd_type == SumiCmdType.UMI_REQ_READ:
+            self._handle_read(transaction)
+        else:
+            if self.log:
+                self.log.warning(f"Unhandled UMI command type: 0x{cmd_type:02x}")
+
+    def _handle_write(self, transaction: SumiTransaction, send_response: bool = True):
+        """Handle a write request by storing data and optionally sending response."""
+        dstaddr = int(transaction.da)
+        data = transaction.data
+        size = int(transaction.cmd.size)
+        length = int(transaction.cmd.len)
+        data_size = (length + 1) << size
+
+        if self.log:
+            self.log.info(
+                f"MEM WRITE: addr=0x{dstaddr:08x} size={data_size} "
+                f"data={data[:data_size].hex()}"
+            )
+
+        for i in range(data_size):
+            self.memory[dstaddr + i] = data[i]
+
+        if send_response:
+            resp_cmd = SumiCmd.from_fields(
+                cmd_type=SumiCmdType.UMI_RESP_WRITE,
+                size=0,
+                len=0,
+                eom=1
+            )
+            resp = SumiTransaction(
+                cmd=resp_cmd,
+                da=int(transaction.sa),
+                sa=int(transaction.da),
+                data=bytes([0]),
+                addr_width=transaction._addr_width
+            )
+            self.driver.append(resp)
+
+    def _handle_read(self, transaction: SumiTransaction):
+        """Handle a read request by returning data from memory."""
+        srcaddr = int(transaction.da)
+        size = int(transaction.cmd.size)
+        length = int(transaction.cmd.len)
+        data_size = (length + 1) << size
+
+        data = bytes(self.memory.get(srcaddr + i, 0) for i in range(data_size))
+
+        if self.log:
+            self.log.info(
+                f"MEM READ: addr=0x{srcaddr:08x} size={data_size} "
+                f"data={data.hex()}"
+            )
+
+        resp_cmd = SumiCmd.from_fields(
+            cmd_type=SumiCmdType.UMI_RESP_READ,
+            size=size,
+            len=length,
+            eom=1
+        )
+
+        tumi_trans = TumiTransaction(
+            cmd=resp_cmd,
+            da=int(transaction.sa),
+            sa=int(transaction.da),
+            data=data
+        )
+        for sumi_trans in tumi_trans.to_sumi(data_bus_size=self.dw//8, addr_width=self.aw):
+            self.driver.append(sumi_trans)
+
+    def read(self, address: int, length: int = 1) -> bytes:
+        """Read bytes from virtual memory directly."""
+        return bytes(self.memory.get(address + i, 0) for i in range(length))
+
+    def write(self, address: int, data: bytes):
+        """Write bytes to virtual memory directly (for test setup)."""
+        for i, byte in enumerate(data):
+            self.memory[address + i] = byte
+
+    def dump_memory(self) -> list[tuple[int, int]]:
+        """Return a sorted list of (address, value) tuples."""
+        return sorted(self.memory.items())
+
+    def clear(self):
+        """Clear all memory contents."""
+        self.memory.clear()

cocotbext/umi/monitors/sumi_monitor.py

@@ -0,0 +1,68 @@
+from cocotb.types import LogicArray
+from cocotb.triggers import RisingEdge
+
+from cocotb_bus.monitors import BusMonitor
+
+from cocotbext.umi.sumi import SumiCmd, SumiTransaction
+
+
+class SumiMonitor(BusMonitor):
+
+    _signals = [
+        "valid",
+        "cmd",
+        "dstaddr",
+        "srcaddr",
+        "data",
+        "ready"
+    ]
+    _optional_signals = []
+
+    def __init__(self, entity, name, clock, **kwargs):
+        BusMonitor.__init__(self, entity, name, clock, **kwargs)
+        self.addr_width = len(self.bus.dstaddr)
+        self.data_width = len(self.bus.data)
+
+    def get_bus_width(self) -> int:
+        return self.data_width
+
+    def get_addr_width(self) -> int:
+        return self.addr_width
+
+    async def _monitor_recv(self):
+        clk_re = RisingEdge(self.clock)
+
+        def valid_handshake() -> bool:
+            return bool(self.bus.valid.value) and bool(self.bus.ready.value)
+
+        while True:
+            await clk_re
+
+            if self.in_reset:
+                continue
+
+            if valid_handshake():
+                sumi_cmd: SumiCmd = SumiCmd.from_int(int(self.bus.cmd.value))
+
+                # Only slice data if the command type carries data
+                if sumi_cmd.has_data():
+                    data: LogicArray = self.bus.data.value
+                    # Limit slice to actual data size, but don't exceed bus width
+                    data_bits = min(
+                        (((int(sumi_cmd.len) + 1) << int(sumi_cmd.size)) * 8),
+                        self.data_width
+                    )
+                    data = data[data_bits - 1:0]
+                    data_bytes = data.to_bytes(byteorder="little") if data.is_resolvable else None
+                else:
+                    data_bytes = None
+
+                self._recv(SumiTransaction(
+                    cmd=sumi_cmd,
+                    da=int(self.bus.dstaddr.value) if self.bus.dstaddr.value.is_resolvable
+                    else None,
+                    sa=int(self.bus.srcaddr.value) if self.bus.srcaddr.value.is_resolvable
+                    else None,
+                    data=data_bytes,
+                    addr_width=self.addr_width
+                ))

cocotbext/umi/sumi.py

@@ -0,0 +1,335 @@
+from enum import IntEnum
+from typing import Optional
+import dataclasses
+import copy
+
+from cocotbext.umi.utils.bit_utils import BitField, BitVector
+from cocotbext.umi.utils.vrd_transaction import VRDTransaction
+
+
+class SumiCmdType(IntEnum):
+    """UMI Command Opcodes (CMD[4:0])"""
+    # Invalid transaction indicator
+    UMI_INVALID = 0x00
+
+    # Requests (host -> device)
+    UMI_REQ_READ = 0x01       # read/load
+    UMI_REQ_WRITE = 0x03      # write/store with ack
+    UMI_REQ_POSTED = 0x05     # posted write (no response)
+    UMI_REQ_RDMA = 0x07       # remote DMA command
+    UMI_REQ_ATOMIC = 0x09     # atomic read-modify-write
+    UMI_REQ_USER0 = 0x0B      # reserved for user
+    UMI_REQ_FUTURE0 = 0x0D    # reserved for future use
+    UMI_REQ_ERROR = 0x0F      # error message (SIZE=0x0)
+    UMI_REQ_LINK = 0x2F       # link ctrl (SIZE=0x1)
+
+    # Responses (device -> host)
+    UMI_RESP_READ = 0x02      # response to read request (with data)
+    UMI_RESP_WRITE = 0x04     # response (ack) from write request
+    UMI_RESP_USER0 = 0x06     # reserved for user (no data)
+    UMI_RESP_USER1 = 0x08     # reserved for user (with data)
+    UMI_RESP_FUTURE0 = 0x0A   # reserved for future use (no data)
+    UMI_RESP_FUTURE1 = 0x0C   # reserved for future use (with data)
+    UMI_RESP_LINK = 0x0E      # link ctrl response (SIZE=0x0)
+
+    @classmethod
+    def supports_streaming(cls, value):
+        """Check if the command type supports streaming (multiple data transfers)."""
+        return value in [
+            SumiCmdType.UMI_REQ_WRITE,
+            SumiCmdType.UMI_REQ_POSTED,
+            SumiCmdType.UMI_RESP_READ
+        ]
+
+    @classmethod
+    def is_request(cls, value):
+        """Check if the command is a request (host -> device)."""
+        return value in [
+            SumiCmdType.UMI_REQ_READ,
+            SumiCmdType.UMI_REQ_WRITE,
+            SumiCmdType.UMI_REQ_POSTED,
+            SumiCmdType.UMI_REQ_RDMA,
+            SumiCmdType.UMI_REQ_ATOMIC,
+            SumiCmdType.UMI_REQ_USER0,
+            SumiCmdType.UMI_REQ_FUTURE0,
+            SumiCmdType.UMI_REQ_ERROR,
+            SumiCmdType.UMI_REQ_LINK,
+        ]
+
+    @classmethod
+    def is_response(cls, value):
+        """Check if the command is a response (device -> host)."""
+        return value in [
+            SumiCmdType.UMI_RESP_READ,
+            SumiCmdType.UMI_RESP_WRITE,
+            SumiCmdType.UMI_RESP_USER0,
+            SumiCmdType.UMI_RESP_USER1,
+            SumiCmdType.UMI_RESP_FUTURE0,
+            SumiCmdType.UMI_RESP_FUTURE1,
+            SumiCmdType.UMI_RESP_LINK,
+        ]
+
+    @classmethod
+    def has_data(cls, value):
+        """Check if the command type carries data."""
+        return value in [
+            SumiCmdType.UMI_REQ_WRITE,
+            SumiCmdType.UMI_REQ_POSTED,
+            SumiCmdType.UMI_REQ_ATOMIC,
+            SumiCmdType.UMI_REQ_USER0,
+            SumiCmdType.UMI_REQ_FUTURE0,
+            SumiCmdType.UMI_RESP_READ,
+            SumiCmdType.UMI_RESP_USER1,
+            SumiCmdType.UMI_RESP_FUTURE1,
+        ]
+
+    @classmethod
+    def has_source_addr(cls, value):
+        """Check if the command type includes source address (SA)."""
+        return value in [
+            SumiCmdType.UMI_REQ_READ,
+            SumiCmdType.UMI_REQ_WRITE,
+            SumiCmdType.UMI_REQ_POSTED,
+            SumiCmdType.UMI_REQ_RDMA,
+            SumiCmdType.UMI_REQ_ATOMIC,
+            SumiCmdType.UMI_REQ_USER0,
+            SumiCmdType.UMI_REQ_FUTURE0,
+            SumiCmdType.UMI_REQ_ERROR,
+        ]
+
+
+class SumiAtomicType(IntEnum):
+    """Atomic Transaction Types (ATYPE[7:0]) - used in LEN field for REQ_ATOMIC"""
+    UMI_ATOMIC_ADD = 0x00
+    UMI_ATOMIC_AND = 0x01
+    UMI_ATOMIC_OR = 0x02
+    UMI_ATOMIC_XOR = 0x03
+    UMI_ATOMIC_MAX = 0x04
+    UMI_ATOMIC_MIN = 0x05
+    UMI_ATOMIC_MAXU = 0x06
+    UMI_ATOMIC_MINU = 0x07
+    UMI_ATOMIC_SWAP = 0x08
+
+
+class SumiErrorCode(IntEnum):
+    """Error Codes (ERR[1:0]) - used in U field for responses"""
+    UMI_ERR_OK = 0b00       # OK (no error)
+    UMI_ERR_EXOK = 0b01     # Successful exclusive access
+    UMI_ERR_DEVERR = 0b10   # Device error
+    UMI_ERR_NETERR = 0b11   # Network error
+
+
+class SumiProtMode(IntEnum):
+    """Protection Mode (PROT[1:0])"""
+    UMI_PROT_UNPRIVILEGED_SECURE = 0b00
+    UMI_PROT_PRIVILEGED_SECURE = 0b01
+    UMI_PROT_UNPRIVILEGED_NONSECURE = 0b10
+    UMI_PROT_PRIVILEGED_NONSECURE = 0b11
+
+
+class SumiSize(IntEnum):
+    """Transaction Word Size (SIZE[2:0]) - bytes per word = 2^SIZE"""
+    UMI_SIZE_1 = 0b000    # 1 byte
+    UMI_SIZE_2 = 0b001    # 2 bytes
+    UMI_SIZE_4 = 0b010    # 4 bytes
+    UMI_SIZE_8 = 0b011    # 8 bytes
+    UMI_SIZE_16 = 0b100   # 16 bytes
+    UMI_SIZE_32 = 0b101   # 32 bytes
+    UMI_SIZE_64 = 0b110   # 64 bytes
+    UMI_SIZE_128 = 0b111  # 128 bytes
+
+    def bytes_per_word(self) -> int:
+        """Return the number of bytes per word for this SIZE value."""
+        return 1 << self.value
+
+
+@dataclasses.dataclass
+class SumiCmd(BitVector):
+    """
+    UMI Command Header (32 bits)
+
+    Bit layout:
+        [4:0]   - opcode (cmd_type): Command opcode
+        [7:5]   - size: Word size (bytes = 2^SIZE)
+        [15:8]  - len: Word transfers per message (transfers = LEN+1)
+                  For REQ_ATOMIC, this field is ATYPE (atomic operation type)
+        [19:16] - qos: Quality of service
+        [21:20] - prot: Protection mode
+        [22]    - eom: End of message indicator
+        [23]    - eof: End of frame indicator
+        [24]    - ex: Exclusive access indicator
+        [26:25] - u: User bits (for requests) or ERR (for responses)
+        [31:27] - hostid: Host ID
+    """
+
+    # Bits [4:0] - Command opcode
+    cmd_type: BitField = dataclasses.field(
+        default_factory=lambda: BitField(value=0, width=5, offset=0)
+    )
+
+    # Bits [7:5] - Word size (bytes per word = 2^SIZE)
+    size: BitField = dataclasses.field(
+        default_factory=lambda: BitField(value=0, width=3, offset=5)
+    )
+
+    # Bits [15:8] - Transfer count (LEN+1 words) or ATYPE for atomics
+    len: BitField = dataclasses.field(
+        default_factory=lambda: BitField(value=0, width=8, offset=8)
+    )
+
+    # Bits [19:16] - Quality of service
+    qos: BitField = dataclasses.field(
+        default_factory=lambda: BitField(value=0, width=4, offset=16)
+    )
+
+    # Bits [21:20] - Protection mode
+    prot: BitField = dataclasses.field(
+        default_factory=lambda: BitField(value=0, width=2, offset=20)
+    )
+
+    # Bit [22] - End of message
+    eom: BitField = dataclasses.field(
+        default_factory=lambda: BitField(value=0, width=1, offset=22)
+    )
+
+    # Bit [23] - End of frame
+    eof: BitField = dataclasses.field(
+        default_factory=lambda: BitField(value=0, width=1, offset=23)
+    )
+
+    # Bit [24] - Exclusive access
+    ex: BitField = dataclasses.field(
+        default_factory=lambda: BitField(value=0, width=1, offset=24)
+    )
+
+    # Bits [26:25] - User bits (requests) or error code (responses)
+    u: BitField = dataclasses.field(
+        default_factory=lambda: BitField(value=0, width=2, offset=25)
+    )
+
+    # Bits [31:27] - Host ID
+    hostid: BitField = dataclasses.field(
+        default_factory=lambda: BitField(value=0, width=5, offset=27)
+    )
+
+    @property
+    def opcode(self) -> int:
+        """Alias for cmd_type field."""
+        return int(self.cmd_type)
+
+    @property
+    def atype(self) -> int:
+        """Get ATYPE field (alias for len, used in atomic operations)."""
+        return int(self.len)
+
+    @atype.setter
+    def atype(self, value: int):
+        """Set ATYPE field (alias for len, used in atomic operations)."""
+        self.len.from_int(value)
+
+    @property
+    def err(self) -> int:
+        """Get ERR field (alias for u, used in responses)."""
+        return int(self.u)
+
+    @err.setter
+    def err(self, value: int):
+        """Set ERR field (alias for u, used in responses)."""
+        self.u.from_int(value)
+
+    def bytes_per_word(self) -> int:
+        """Return the number of bytes per word based on SIZE field."""
+        return 1 << int(self.size)
+
+    def transfer_count(self) -> int:
+        """Return the number of word transfers (LEN+1)."""
+        return int(self.len) + 1
+
+    def total_bytes(self) -> int:
+        """Return the total number of bytes in the transaction."""
+        return self.bytes_per_word() * self.transfer_count()
+
+    def is_request(self) -> bool:
+        """Check if this command is a request."""
+        return SumiCmdType.is_request(int(self.cmd_type))
+
+    def is_response(self) -> bool:
+        """Check if this command is a response."""
+        return SumiCmdType.is_response(int(self.cmd_type))
+
+    def has_data(self) -> bool:
+        """Check if this command carries data."""
+        return SumiCmdType.has_data(int(self.cmd_type))
+
+    def has_source_addr(self) -> bool:
+        """Check if this command includes source address."""
+        return SumiCmdType.has_source_addr(int(self.cmd_type))
+
+    def __repr__(self):
+        return f"SumiCmd({super().__repr__()})"
+
+
+class SumiTransaction:
+
+    def __init__(
+        self,
+        cmd: SumiCmd,
+        da: Optional[int],
+        sa: Optional[int],
+        data: Optional[bytes],
+        addr_width: int = 64
+    ):
+        self.cmd = copy.deepcopy(cmd)
+        self.da = BitField(value=da, width=addr_width, offset=0)
+        self.sa = BitField(value=sa, width=addr_width, offset=0)
+        self.data = data
+        self._addr_width = addr_width
+
+    def header_to_bytes(self) -> bytes:
+        return (bytes(self.cmd)
+                + int.to_bytes(int(self.da), length=self._addr_width//8, byteorder='little')
+                + int.to_bytes(int(self.sa), length=self._addr_width//8, byteorder='little'))
+
+    def to_lumi(self, lumi_size, inc_header=True, override_last=None):
+        raw = self.data[:(int(self.cmd.len)+1 << int(self.cmd.size))]
+        if inc_header:
+            raw = self.header_to_bytes() + raw
+        # Break raw into LUMI bus sized chunks
+        chunks = [raw[i:i+lumi_size] for i in range(0, len(raw), lumi_size)]
+        # Zero pad last chunk
+        chunks[-1] = chunks[-1] + bytes([0] * (lumi_size - len(chunks[-1])))
+        vrd_transactions = []
+        for i, chunk in enumerate(chunks):
+            # Set last true for the last chunk
+            last = (i == len(chunks)-1)
+            # Allow user to override last (useful for simulating streaming mode)
+            if last and (override_last is not None):
+                last = override_last
+            # Convert data to a valid ready transaction type
+            vrd_transactions.append(VRDTransaction(
+                data=chunk,
+                last=last
+            ))
+        return vrd_transactions
+
+    def trunc_and_pad_zeros(self):
+        data_len = ((int(self.cmd.len)+1) << int(self.cmd.size))
+        self.data = bytes([0] * (len(self.data) - data_len)) + self.data[:data_len]
+
+    def __eq__(self, other):
+        if isinstance(other, SumiTransaction):
+            # For all command types CMD's must match
+            if int(self.cmd) == int(other.cmd):
+                # For RESP_WRITE only compare header fields DA
+                if int(self.cmd.cmd_type) == SumiCmdType.UMI_RESP_WRITE:
+                    return int(self.da) == int(other.da)
+                else:
+                    my_pkt = self.header_to_bytes() + self.data
+                    other_pkt = other.header_to_bytes() + other.data
+                    return my_pkt == other_pkt
+            return False
+        else:
+            return False
+
+    def __repr__(self):
+        return f"header = {self.header_to_bytes().hex()} data = {self.data.hex()} {self.cmd}"

cocotbext/umi/tumi.py

@@ -0,0 +1,55 @@
+from typing import List
+from cocotbext.umi.sumi import SumiCmd, SumiTransaction
+
+
+class TumiTransaction:
+
+    def __init__(
+        self,
+        cmd: SumiCmd,
+        da: int,
+        sa: int,
+        data: bytes
+    ):
+        self._cmd = cmd
+        self._data = data
+        self._da = da
+        self._sa = sa
+
+    def to_sumi(self, data_bus_size: int, addr_width: int = 64) -> List[SumiTransaction]:
+        sa = self._sa
+        da = self._da
+
+        sumi_size = 0
+
+        data_grouped = [
+            self._data[i:i+data_bus_size]
+            for i in range(0, len(self._data), data_bus_size)
+        ]
+
+        rtn = []
+        for idx, grouping in enumerate(data_grouped):
+            group_len = len(grouping)
+
+            for size in reversed(range(0, (1 << 3)-1)):
+                if group_len % (2**size) == 0:
+                    sumi_size = size
+                    break
+
+            group_len = int(group_len / (2**sumi_size))
+
+            self._cmd.size.from_int(sumi_size)
+            self._cmd.len.from_int(group_len-1)
+            self._cmd.eom.from_int(1 if idx == len(data_grouped)-1 else 0)
+
+            trans = SumiTransaction(
+                cmd=self._cmd,
+                da=da,
+                sa=sa,
+                data=grouping,
+                addr_width=addr_width
+            )
+            rtn.append(trans)
+            da += (int(self._cmd.len) + 1) << int(self._cmd.size)
+            sa += (int(self._cmd.len) + 1) << int(self._cmd.size)
+        return rtn