switchboard-hw 0.3.0__cp314-cp314-macosx_11_0_arm64.whl

switchboard/axil.py

@@ -0,0 +1,348 @@
+# 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 AxiLiteTxRx:
+    def __init__(
+        self,
+        uri: str,
+        fresh: bool = True,
+        data_width: int = 32,
+        addr_width: int = 16,
+        prot: int = 0,
+        resp_expected: str = 'OKAY',
+        queue_suffix: str = '.q',
+        max_rate: float = -1
+    ):
+        """
+        Parameters
+        ----------
+        uri: str
+            Base name of for switchboard queues used to convey AXI transactions.  Five
+            queues are used: write address (aw), write data (w), write response (b),
+            read address (ar), and read response (r).  If the base name provided is
+            "axil", the correponding queues will be "axil-aw.q", "axil-w.q", "axil-b.q",
+            "axil-ar.q" and "axil-r.q".  The suffix used can be changed via the
+            "queue_suffix" argument if needed.
+        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.
+        resp_expected: str, optional
+            Default response to expect from reads and writes.  Options are 'OKAY',
+            'EXOKAY', 'SLVERR', 'DECERR'.  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
+            AXI 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_resp_expected = resp_expected
+
+        # create the queues
+        self.aw = PySbTx(f'{uri}-aw{queue_suffix}', fresh=fresh, max_rate=max_rate)
+        self.w = PySbTx(f'{uri}-w{queue_suffix}', fresh=fresh, max_rate=max_rate)
+        self.b = PySbRx(f'{uri}-b{queue_suffix}', fresh=fresh, max_rate=max_rate)
+        self.ar = PySbTx(f'{uri}-ar{queue_suffix}', fresh=fresh, max_rate=max_rate)
+        self.r = PySbRx(f'{uri}-r{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,
+        resp_expected: str = 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
+            AxiLiteTxRx constructor if not provided, which in turn defaults to 0.
+
+        resp_expected: str, optional
+            Response to expect for this transaction.  Options are 'OKAY', 'EXOKAY', 'SLVERR',
+            'DECERR', and None.  None means, "don't check the response". Defaults to the
+            value provided in the AxiLiteTxRx constructor if not provided, which in turn
+            defaults to 'OKAY'
+
+        Returns
+        -------
+        str
+            String representation of the response code, which may be 'OKAY', 'EXOKAY',
+            'SLVERR', or 'DECERR'.
+        """
+
+        # set defaults
+
+        if prot is None:
+            prot = self.default_prot
+
+        if resp_expected is None:
+            resp_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
+
+        data_bytes = self.data_width // 8
+        strb_bytes = (self.strb_width + 7) // 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
+            strb = strb.to_bytes(strb_bytes, 'little')
+            strb = np.frombuffer(strb, dtype=np.uint8)
+
+            # transmit the write address
+            pack = (prot << self.addr_width) | (addr & addr_mask)
+            pack = pack.to_bytes((self.addr_width + 3 + 7) // 8, 'little')
+            pack = np.frombuffer(pack, dtype=np.uint8)
+            pack = PySbPacket(data=pack, flags=1, destination=0)
+            self.aw.send(pack, True)
+
+            # write data and strobe
+            pack = np.empty((data_bytes + strb_bytes,), dtype=np.uint8)
+            pack[offset:offset + bytes_this_cycle] = data_this_cycle
+            pack[data_bytes:data_bytes + strb_bytes] = strb
+            pack = PySbPacket(data=pack, flags=1, destination=0)
+            self.w.send(pack, True)
+
+            # wait for response
+            pack = self.b.recv(True)
+            pack = pack.data.tobytes()
+            pack = int.from_bytes(pack, 'little')
+
+            # decode the response
+            resp = decode_resp(pack & 0b11)
+
+            # check the response if desired
+            if resp_expected is not None:
+                assert resp.upper() == resp_expected.upper(), f'Unexpected response: {resp}'
+
+            # increment pointers
+            bytes_sent += bytes_this_cycle
+            addr += bytes_this_cycle
+
+        # return the last reponse
+        return resp
+
+    def read(
+        self,
+        addr: Integral,
+        num_or_dtype,
+        dtype=np.uint8,
+        prot: Integral = None,
+        resp_expected: str = None
+    ):
+        """
+        Parameters
+        ----------
+        addr: int
+            Address to read from
+
+        num_or_dtype: int or numpy integer datatype
+            If a plain int, `num_or_datatype` specifies the number of bytes to be read.
+            If a numpy integer datatype (np.uint8, np.uint16, etc.), num_or_datatype
+            specifies the data type to be returned.
+
+        dtype: numpy integer datatype, optional
+            If num_or_dtype is a plain integer, the value returned by this function
+            will be a numpy array of type "dtype".  On the other hand, if num_or_dtype
+            is a numpy datatype, the value returned will be a scalar of that datatype.
+
+        prot: Integral
+            Value of PROT for this transaction.  Defaults to the value provided in the
+            AxiLiteTxRx constructor if not provided, which in turn defaults to 0.
+
+        resp_expected: str, optional
+            Response to expect for this transaction.  Options are 'OKAY', 'EXOKAY', 'SLVERR',
+            'DECERR', and None.  None means, "don't check the response". Defaults to the
+            value provided in the AxiLiteTxRx constructor if not provided, which in turn
+            defaults to 'OKAY'
+
+        Returns
+        -------
+        int
+            Value read, as an arbitrary-size Python integer.
+        """
+
+        # set defaults
+
+        if prot is None:
+            prot = self.default_prot
+
+        if resp_expected is None:
+            resp_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(num_or_dtype, (type, np.dtype)):
+            bytes_to_read = np.dtype(num_or_dtype).itemsize
+        else:
+            bytes_to_read = num_or_dtype * np.dtype(dtype).itemsize
+
+        # range validation
+
+        assert 0 <= addr < (1 << self.addr_width), 'addr out of range'
+        assert addr + bytes_to_read <= (1 << self.addr_width), \
+            "transaction exceeds the address space."
+
+        assert 0 <= prot < (1 << 3), 'prot out of range'
+
+        # loop until all data is read
+        # TODO: move to C++?
+
+        bytes_read = 0
+        data_bytes = self.data_width // 8
+
+        addr_mask = (1 << self.addr_width) - 1
+        addr_mask >>= ceil(log2(data_bytes))
+        addr_mask <<= ceil(log2(data_bytes))
+
+        retval = np.empty((bytes_to_read,), dtype=np.uint8)
+
+        while bytes_read < bytes_to_read:
+            # find the offset into the data bus for this cycle
+            offset = addr % data_bytes
+
+            # determine what data we're reading this cycle
+            bytes_this_cycle = min(bytes_to_read - bytes_read, data_bytes - offset)
+
+            # transmit read address
+            pack = (prot << self.addr_width) | (addr & addr_mask)
+            pack = pack.to_bytes((self.addr_width + 3 + 7) // 8, 'little')
+            pack = np.frombuffer(pack, dtype=np.uint8)
+            pack = PySbPacket(data=pack, flags=1, destination=0)
+            self.ar.send(pack, True)
+
+            # wait for response
+            pack = self.r.recv(True)
+            data = pack.data[offset:offset + bytes_this_cycle]
+            resp = pack.data[data_bytes] & 0b11
+
+            # check the reponse
+            if resp_expected is not None:
+                resp = decode_resp(resp)
+                assert resp.upper() == resp_expected.upper(), f'Unexpected response: {resp}'
+
+            # add this data to the return value
+            retval[bytes_read:bytes_read + bytes_this_cycle] = data
+
+            # increment pointers
+            bytes_read += bytes_this_cycle
+            addr += bytes_this_cycle
+
+        if isinstance(num_or_dtype, (type, np.dtype)):
+            return retval.view(num_or_dtype)[0]
+        else:
+            return retval.view(dtype)
+
+
+def decode_resp(resp: Integral):
+    assert isinstance(resp, Integral), 'response code must be an integer'
+    assert 0 <= resp <= 3, 'response code out of range'
+
+    return ['OKAY', 'EXOKAY', 'SLVERR', 'DECERR'][resp]

switchboard/bitvector.py

@@ -0,0 +1,112 @@
+# Utilities for working with bit vectors using Verilog-style syntax, i.e. [MSB:LSB]
+
+# Copyright (c) 2024 Zero ASIC Corporation
+# This code is licensed under Apache License 2.0 (see LICENSE for details)
+
+import numpy as np
+
+
+class BitVector:
+    def __init__(self, value: int = 0):
+        self.value = int(value)
+
+    def __int__(self):
+        return int(self.value)
+
+    def __str__(self):
+        return f'0x{self.value:x}'
+
+    def __setitem__(self, key, value):
+        if isinstance(key, slice):
+            if (key.start is None) and (key.stop is None) and (key.step is None):
+                self.value = value
+                return
+            else:
+                msb, lsb = slice_to_msb_lsb(key.start, key.stop, key.step)
+        else:
+            msb, lsb = slice_to_msb_lsb(key, key)
+
+        # generate mask with the right width
+        mask = (1 << (msb - lsb + 1)) - 1
+
+        # clear bit field using the mask
+        new_value = self.value & (~(mask << lsb))
+
+        # set bit field
+        new_value |= (value & mask) << lsb
+
+        # set the new value (done here instead of through
+        # incremental updates, to prevent the value from
+        # being partially updated in case of an exception
+        self.value = new_value
+
+    def __getitem__(self, key):
+        if isinstance(key, slice):
+            if (key.start is None) and (key.stop is None) and (key.step is None):
+                return self.value
+            else:
+                msb, lsb = slice_to_msb_lsb(key.start, key.stop, key.step)
+        else:
+            msb, lsb = slice_to_msb_lsb(key, key)
+
+        # generate mask with the right width
+        mask = (1 << (msb - lsb + 1)) - 1
+
+        # extract the value
+        return (self.value >> lsb) & mask
+
+    def tobytes(self, n=None):
+        # convert to a numpy byte array.  if "n" is provided,
+        # pad result to be "n" bytes.  will error out if "n"
+        # is less than the number of bytes needed to represent
+        # the current value.
+
+        value = self.value
+        bytes = []
+
+        while value != 0:
+            bytes.append(value & 0xff)
+            value >>= 8
+
+        if n is not None:
+            if len(bytes) < n:
+                bytes += [0] * (n - len(bytes))
+            elif len(bytes) > n:
+                raise ValueError('Number of bytes needed to represent the current value'
+                    f' ({self.value}) is {len(bytes)}, but the argument n={n} is smaller.')
+
+        return np.array(bytes, dtype=np.uint8)
+
+    @staticmethod
+    def frombytes(arr):
+        value = 0
+
+        for i, elem in enumerate(arr):
+            if not (0 <= elem <= 255):
+                raise ValueError(f'Non-byte value detected at index {i}: {elem}')
+            value |= (int(elem) & 0xff) << (i * 8)
+
+        return BitVector(value)
+
+
+def slice_to_msb_lsb(start=None, stop=None, step=None):
+    # set defaults
+    if start is None:
+        start = 0
+    if stop is None:
+        stop = 0
+    if step is None:
+        step = 1
+
+    if step != 1:
+        raise ValueError('Only step=1 allowed for slice indexing.')
+
+    msb = start
+    lsb = stop
+
+    if msb < lsb:
+        raise ValueError('MSB must be greater than or equal to LSB')
+    if lsb < 0:
+        raise ValueError('Negative LSB is not allowed.')
+
+    return msb, lsb

switchboard/cmdline.py

@@ -0,0 +1,142 @@
+# Copyright (c) 2024 Zero ASIC Corporation
+# This code is licensed under Apache License 2.0 (see LICENSE for details)
+
+def get_cmdline_args(
+    tool: str = 'verilator',
+    trace: bool = True,
+    trace_type: str = 'vcd',
+    frequency: float = 100e6,
+    period: float = None,
+    max_rate: float = -1,
+    start_delay: float = None,
+    fast: bool = False,
+    single_netlist: bool = False,
+    threads: int = None,
+    extra_args: dict = None
+):
+    """
+    Sets up and runs a command-line option parser (argparse) using the arguments
+    provided as defaults.  The object returned is an argparse.Namespace object,
+    which is the same object type returned by ArgumentParser.parse_args()
+
+    This function is used in SbNetwork and SbDut.  It should generally be
+    called only once, at the top level of the simulation.
+
+    Parameters
+    ----------
+    tool: string, optional
+        Which tool to use to compile simulator.  Options are "verilator" or
+        "icarus".
+
+    trace: bool, optional
+        If true, a waveform dump file will be produced using the file type
+        specified by `trace_type`.
+
+    trace_type: str, optional
+        File type for the waveform dump file. Defaults to vcd.
+
+    frequency: float, optional
+        If provided, the default frequency of the clock generated in the testbench,
+        in seconds.
+
+    period: float, optional
+        If provided, the default period of the clock generated in the testbench,
+        in seconds.
+
+    max_rate: float, optional
+        If provided, the maximum real-world rate that the simulation is allowed to run
+        at, in Hz.  Can be useful to encourage time-sharing between many processes and
+        for performance modeling when latencies are large and/or variable.  A value of
+        "-1" means that the rate-limiting feature is disabled.
+
+    start_delay: float, optional
+        If provided, the real-world time to delay before the first clock tick in the
+        simulation.  Can be useful to make sure that programs start at approximately
+        the same time and to prevent simulations from stepping on each other's toes
+        when starting up.
+
+    fast: bool, optional
+        If True, the simulation binary will not be rebuilt if an existing one is found.
+        The setting here can be overridden when build() is called by setting its argument
+        with the same name.
+
+    extra_args: dict, optional
+        If provided and cmdline=True, a dictionary of additional command line arguments
+        to be made available.  The keys of the dictionary are the arguments ("-n", "--test",
+        etc.) and the values are themselves dictionaries that contain keyword arguments
+        accepted by argparse ("action": "store_true", "default": 42, etc.)
+    """
+
+    from argparse import ArgumentParser
+
+    parser = ArgumentParser()
+
+    if not trace:
+        parser.add_argument('--trace', action='store_true', help='Probe'
+            ' waveforms during simulation.')
+    else:
+        parser.add_argument('--no-trace', action='store_true', help='Do not'
+            ' probe waveforms during simulation.  This can improve build time'
+            ' and run time, but reduces visibility.')
+
+    parser.add_argument('--trace-type', type=str, choices=['vcd', 'fst'],
+        default=trace_type, help='File type for waveform probing.')
+
+    if not fast:
+        parser.add_argument('--fast', action='store_true', help='Do not build'
+            ' the simulator binary if it has already been built.')
+    else:
+        parser.add_argument('--rebuild', action='store_true', help='Build the'
+            ' simulator binary even if it has already been built.')
+
+    parser.add_argument('--tool', type=str, choices=['verilator', 'icarus'],
+        default=tool, help='Name of the simulator to use.')
+
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument('--period', type=float, default=period,
+        help='Period of the clk signal in seconds.  Automatically set if'
+        ' --frequency is provided.')
+    group.add_argument('--frequency', type=float, default=frequency,
+        help='Frequency of the clk signal in Hz.  Automatically set if'
+        ' --period is provided.')
+
+    parser.add_argument('--max-rate', type=float, default=max_rate,
+        help='Maximum real-world rate that the simulation is allowed to run at, in Hz.')
+
+    parser.add_argument('--start-delay', type=float, default=start_delay,
+        help='Delay before starting simulation, in seconds.  Can be useful to prevent'
+        ' simulations from stepping on each others toes when starting up.')
+
+    if not single_netlist:
+        parser.add_argument('--single-netlist', action='store_true', help='Run in single-netlist'
+            ' mode, where the network is constructed in Verilog and run in a single simulator.')
+    else:
+        parser.add_argument('--distributed', action='store_true', help='Run in distributed'
+            ' simulation mode, rather than single-netlist mode.')
+
+    parser.add_argument('--threads', type=int, default=threads,
+        help='Number of threads to use when running a simulation.')
+
+    if extra_args is not None:
+        for k, v in extra_args.items():
+            parser.add_argument(k, **v)
+
+    args, _ = parser.parse_known_args()
+
+    # standardize boolean flags
+
+    if trace:
+        args.trace = not args.no_trace
+        del args.no_trace
+
+    if fast:
+        args.fast = not args.rebuild
+        del args.rebuild
+
+    if single_netlist:
+        args.single_netlist = not args.distributed
+        del args.distributed
+
+    # return arguments
+
+    return args

switchboard/cpp/Makefile

@@ -0,0 +1,13 @@
+# Copyright (c) 2024 Zero ASIC Corporation
+# This code is licensed under Apache License 2.0 (see LICENSE for details)
+
+TARGETS = umidriver old_umidriver router old2new
+
+all: $(TARGETS)
+
+%: %.cc switchboard.hpp
+	g++ -std=c++11 -I. $< -o $@ $(CPP_LIBS)
+
+.PHONY: clean
+clean:
+	rm -f $(TARGETS)

switchboard/cpp/bitutil.h

@@ -0,0 +1,39 @@
+// Copyright (c) 2024 Zero ASIC Corporation
+// This code is licensed under Apache License 2.0 (see LICENSE for details)
+
+#ifndef __BITUTIL_H__
+#define __BITUTIL_H__
+
+#include <stddef.h>
+
+// highest_bit: determine the index of the most significant non-zero
+// bit in a number.
+
+static inline size_t highest_bit(size_t x) {
+    size_t retval = 0;
+    while ((x >>= 1) != 0) {
+        retval++;
+    }
+    return retval;
+}
+
+// lowest_bit: determine index of the least significant non-zero
+// bit in a number.
+
+static inline size_t lowest_bit(size_t x) {
+    if (x == 0) {
+        // if the input is zero, it is convenient to return a value
+        // that is larger than the return value for any non-zero
+        // input value, which is (sizeof(size_t)*8)-1.
+        return sizeof(size_t) * 8;
+    } else {
+        size_t retval = 0;
+        while ((x & 1) == 0) {
+            x >>= 1;
+            retval++;
+        }
+        return retval;
+    }
+}
+
+#endif // #ifndef __BITUTIL_H__