WIP: Adding SB APB master

Author: RiceShelley

switchboard/apb.py

@@ -0,0 +1,218 @@
+# Python interface for AXI-Lite reads and writes
+
+# Copyright (c) 2024 Zero ASIC Corporation
+# This code is licensed under Apache License 2.0 (see LICENSE for details)
+
+import numpy as np
+
+from math import floor, ceil, log2
+from numbers import Integral
+
+from _switchboard import PySbPacket, PySbTx, PySbRx
+
+
+class ApbTxRx:
+    def __init__(
+        self,
+        uri: str,
+        fresh: bool = True,
+        data_width: int = 32,
+        addr_width: int = 16,
+        prot: int = 0,
+        slv_err_expected: bool = False,
+        queue_suffix: str = '.q',
+        max_rate: float = -1
+    ):
+        """
+        Parameters
+        ----------
+        uri: str
+            Base name of for switchboard queues used to convey APB transactions.
+        fresh: bool, optional
+           If True (default), the queue specified by the uri parameter will get cleared
+           before executing the simulation.
+        data_width: int, optional
+            Width the write and read data buses, in bits.
+        addr_width: int, optional
+            Width the write and read address buses, in bits.
+        prot: int, optional
+            Default value of PROT to use for read and write transactions.  Can be
+            overridden on a transaction-by-transaction basis.
+        slv_err_expected: bool, optional
+            Default response to expect from reads and writes.
+            None means "don't check the response".
+            This default can be overridden on a transaction-by-transaction basis.
+        queue_suffix: str, optional
+            File extension/suffix to use when naming switchboard queues that carry
+            APB transactions.  For example, if set to ".queue", the write address
+            queue name will be "{uri}-aw.queue"
+        """
+
+        # check data types
+        assert isinstance(data_width, Integral), 'data_width must be an integer'
+        assert isinstance(addr_width, Integral), 'addr_width must be an integer'
+
+        # check that data width is a multiple of a byte
+        data_width_choices = [8, 16, 32, 64, 128, 256, 512, 1024]
+        assert data_width in data_width_choices, \
+            f'data_width must be in {data_width_choices}'
+
+        # check that data and address widths are supported
+        SBDW = 416
+        assert 0 < data_width <= floor(SBDW / (1 + (1 / 8))), 'data_width out of range'
+        assert 0 < addr_width <= SBDW - 3, 'addr_width out of range'
+
+        # save settings
+        self.data_width = data_width
+        self.addr_width = addr_width
+        self.default_prot = prot
+        self.default_slv_err_expected = slv_err_expected
+
+        # create the queues
+        self.apb_req = PySbTx(f'{uri}-apb-req{queue_suffix}', fresh=fresh, max_rate=max_rate)
+        self.apb_resp = PySbRx(f'{uri}-apb-resp{queue_suffix}', fresh=fresh, max_rate=max_rate)
+
+    @property
+    def strb_width(self):
+        return self.data_width // 8
+
+    def write(
+        self,
+        addr: Integral,
+        data,
+        prot: Integral = None,
+        slv_err_expected: bool = None
+    ):
+        """
+        Parameters
+        ----------
+        addr: int
+            Address to write to
+
+        data: np.uint8, np.uint16, np.uint32, np.uint64, or np.array
+            Data to write
+
+        prot: Integral
+            Value of PROT for this transaction.  Defaults to the value provided in the
+            ApbTxRx constructor if not provided, which in turn defaults to 0.
+
+        slv_err_expected: str, optional
+            Response to expect for this transaction.
+            None means, "don't check the response". Defaults to the
+            value provided in the ApbTxRx constructor if not provided, which in turn
+            defaults to False.
+
+        Returns
+        -------
+        bool
+            slv_err: True if SLVERR was received, False otherwise.
+        """
+
+        # set defaults
+
+        if prot is None:
+            prot = self.default_prot
+
+        if slv_err_expected is None:
+            slv_err_expected = self.default_resp_expected
+
+        # check/standardize data types
+
+        assert isinstance(addr, Integral), 'addr must be an integer'
+        addr = int(addr)
+
+        assert isinstance(prot, Integral), 'prot must be an integer'
+        prot = int(prot)
+
+        if isinstance(data, np.ndarray):
+            if data.ndim == 0:
+                write_data = np.atleast_1d(data)
+            elif data.ndim == 1:
+                write_data = data
+            else:
+                raise ValueError(f'Can only write 1D arrays (got ndim={data.ndim})')
+
+            if not np.issubdtype(write_data.dtype, np.integer):
+                raise ValueError('Can only write integer dtypes such as uint8, uint16, etc.'
+                    f'  (got dtype "{data.dtype}")')
+        elif isinstance(data, np.integer):
+            write_data = np.array(data, ndmin=1)
+        else:
+            raise TypeError(f"Unknown data type: {type(data)}")
+
+        write_data = write_data.view(np.uint8)
+        bytes_to_send = write_data.size
+
+        # range validation
+
+        assert 0 <= addr < (1 << self.addr_width), 'addr out of range'
+        assert addr + bytes_to_send <= (1 << self.addr_width), \
+            "transaction exceeds the address space."
+
+        assert 0 <= prot < (1 << 3), 'prot out of range'
+
+        # loop until all data is sent
+        # TODO: move to C++?
+
+        bytes_sent = 0
+
+        strb_bytes = (self.strb_width + 7) // 8
+        header_bytes = ceil((1 + 3 + self.strb_width) / 8.0)
+        data_bytes = self.data_width // 8
+        addr_bytes = self.addr_width // 8
+
+        addr_mask = (1 << self.addr_width) - 1
+        addr_mask >>= ceil(log2(data_bytes))
+        addr_mask <<= ceil(log2(data_bytes))
+
+        while bytes_sent < bytes_to_send:
+            # find the offset into the data bus for this cycle.  bytes below
+            # the offset will have write strobe de-asserted.
+            offset = addr % data_bytes
+
+            # determine how many bytes we're sending in this cycle
+            bytes_this_cycle = min(bytes_to_send - bytes_sent, data_bytes - offset)
+
+            # extract those bytes from the whole input data array, picking
+            # up where we left off from the last iteration
+            data_this_cycle = write_data[bytes_sent:bytes_sent + bytes_this_cycle]
+
+            # calculate strobe value based on the offset and number
+            # of bytes that we're writing.
+            strb = ((1 << bytes_this_cycle) - 1) << offset
+            header = 1
+            header = (header << 3) | prot
+            header = (header << self.strb_width) | strb
+            header = np.frombuffer(header, dtype=np.uint8)
+
+            addr_bytes = np.frombuffer(
+                (addr & addr_mask).to_bytes((self.addr_width + 7) // 8, 'little'),
+                dtype=np.uint8
+            )
+
+            pack = np.empty((header_bytes + addr_bytes + data_bytes,), dtype=np.uint8)
+            pack[0:data_bytes] = data_this_cycle
+            pack[data_bytes:data_bytes + addr_bytes] = addr_bytes
+            pack[data_bytes + addr_bytes:] = header
+            pack = PySbPacket(data=pack, flags=1, destination=0)
+            # Transmit request
+            self.apb_req.send(pack, True)
+
+            # wait for response
+            pack = self.apb_resp.recv(True)
+            pack = pack.data.tobytes()
+            pack = int.from_bytes(pack, 'little')
+
+            # decode the response
+            slv_err = bool(pack & 0b1)
+
+            # check the response if desired
+            if slv_err_expected is not None:
+                assert slv_err == slv_err_expected, f'Unexpected response: slv_err = {slv_err}'
+
+            # increment pointers
+            bytes_sent += bytes_this_cycle
+            addr += bytes_this_cycle
+
+        # return the last reponse
+        return slv_err

switchboard/verilog/common/switchboard.vh

@@ -156,6 +156,40 @@
         .valid(signal``_valid)                                                                     \
     )
 
+`define SB_APB_WIRES(signal, dw, aw)                                                               \
+    wire                  signal``_psel;                                                           \
+    wire                  signal``_penable;                                                        \
+    wire                  signal``_pwrite;                                                         \
+    wire [2:0]            signal``_pprot;                                                          \
+    wire [((aw)-1):0]     signal``_paddr;                                                          \
+    wire [((dw)/8)-1:0]   signal``_pstrb;                                                          \
+    wire [((dw)-1):0]     signal``_pwdata;                                                         \
+    wire [((dw)-1):0]     signal``_prdata;                                                         \
+    wire                  signal``_pready;                                                         \
+    wire                  signal``_pslverr
+
+`define SB_APB_M(signal, dw, aw, file, vldmode=1, rdymode=1, clk_signal=clk, rst_signal=1'b0)      \
+    sb_apb_m #(                                                                                    \
+        .DATA_WIDTH(dw),                                                                           \
+        .ADDR_WIDTH(aw),                                                                           \
+        .VALID_MODE_DEFAULT(vldmode),                                                              \
+        .READY_MODE_DEFAULT(rdymode),                                                              \
+        .FILE(file)                                                                                \
+    ) signal``_sb_inst (                                                                           \
+        .clk(clk_signal),                                                                          \
+        .reset(rst_signal),                                                                        \
+        .m_apb_psel(signal``_psel),                                                                \
+        .m_apb_penable(signal``_penable),                                                          \
+        .m_apb_pwrite(signal``_pwrite),                                                            \
+        .m_apb_pprot(signal``_pprot),                                                              \
+        .m_apb_paddr(signal``_paddr),                                                              \
+        .m_apb_pstrb(signal``_pstrb),                                                              \
+        .m_apb_pwdata(signal``_pwdata),                                                            \
+        .m_apb_prdata(signal``_prdata),                                                            \
+        .m_apb_pready(signal``_pready),                                                            \
+        .m_apb_pslverr(signal``_pslverr)                                                           \
+    )
+
 `define SB_AXIL_WIRES(signal, dw, aw)                                                              \
     wire [((aw)-1):0]     signal``_awaddr;                                                         \
     wire [2:0]            signal``_awprot;                                                         \