switchboard.umi module

Classes:

UmiTxRx([tx_uri, rx_uri, srcaddr, posted, ...])

Functions:

addr_aligned(addr, align)

check_int_in_range(name, value[, min, max])

dtype2size(dtype)

nbytes2size(nbytes)

random_int_value(name, value, min, max[, align])

random_umi_packet([opcode, len, size, ...])

Generates a Random UMI packet.

size2dtype(size[, signed, float])

class switchboard.umi.UmiTxRx(tx_uri=None, rx_uri=None, srcaddr=0, posted=False, max_bytes=None, fresh=False, error=True, max_rate=-1)[source]

Bases: object

Parameters:

  • tx_uri (str, optional) – Name of the switchboard queue that write() and send() will send UMI packets to. Defaults to None, meaning “unused”.

  • rx_uri (str, optional) – Name of the switchboard queue that read() and recv() will receive UMI packets from. Defaults to None, meaning “unused”.

  • srcaddr (int, optional) – Default srcaddr to use for reads, ack’d writes, and atomics. Defaults to 0. Can also be provided as a dictionary with separate defaults for each type of transaction: srcaddr={‘read’: 0x1234, ‘write’: 0x2345, ‘atomic’: 0x3456}. When the defaults are provided with a dictionary, all keys are optional. Transactions that are not specified in the dictionary will default to a srcaddr of 0.

  • posted (bool, optional) – If True, default to using posted (i.e., non-ack’d) writes. This can be overridden on a transaction-by-transaction basis. Defaults to False.

  • max_bytes (int, optional) – Default maximum number of bytes to use in each UMI transaction. Can be overridden on a transaction-by-transaction basis. Defaults to 32 bytes.

  • fresh (bool, optional) – If True, the queue specified by the uri parameter will get cleared before executing the simulation.

  • error (bool, optional) – If True, error out upon receiving an unexpected UMI response.

  • max_rate (float)

atomic(addr, data, opcode, srcaddr=None, qos=0, prot=0, error=None)[source]
Parameters:

  • addr (int) – 64-bit address atomic operation will be applied to.

  • data (np.uint8, np.uint16, np.uint32, np.uint64) – must so that the size of the atomic operation can be determined.

  • opcode (str or switchboard.UmiAtomic value) – Supported string values are ‘add’, ‘and’, ‘or’, ‘xor’, ‘max’, ‘min’, ‘minu’, ‘maxu’, and ‘swap’ (case-insensitive).

  • srcaddr (int, optional) – The UMI source address used for the atomic transaction. This is sometimes needed to make sure the response get routed to the right place.

  • qos (int, optional) – 4-bit Quality of Service field used in the UMI command

  • prot (int, optional) – 2-bit Protection mode field used in the UMI command

  • error (bool, optional) – If True, error out upon receiving an unexpected UMI response.

Raises:

TypeError – If value is not a numpy integer datatype

Returns:

The value returned by this function is the original value at addr, immediately before the atomic operation is applied. The numpy dtype of the returned value will be the same as for “data”.

Return type:

np.uint8, np.uint16, np.uint32, np.uint64

gpio(iwidth=32, owidth=32, init=0, dstaddr=0, srcaddr=0, posted=False, max_bytes=32)[source]

Returns an object for communicating with umi_gpio modules.

Parameters:

  • iwidth (int) – Width of GPIO input (bits). Defaults to 32.

  • owidth (int) – Width of GPIO output (bits). Defaults to 32.

  • init (int) – Default value of GPIO output. Defaults to 0.

  • dstaddr (int) – Base address of the GPIO device. Defaults to 0.

  • srcaddr (int) – Source address to which responses should be routed. Defaults to 0.

  • posted (bool) – Whether writes should be sent as posted. Defaults to False.

  • max_bytes (int) – Maximum number of bytes in a single transaction to umi_gpio.

Returns:

UmiGpio object with .i (input) and .o (output) attributes

Return type:

UmiGpio

init_queues(tx_uri=None, rx_uri=None, fresh=False)[source]
Parameters:

  • tx_uri (str, optional) – Name of the switchboard queue that write() and send() will send UMI packets to. Defaults to None, meaning “unused”.

  • rx_uri (str, optional) – Name of the switchboard queue that read() and recv() will receive UMI packets from. Defaults to None, meaning “unused”.

  • fresh (bool, optional) – If True, the queue specified by the uri parameter will get cleared before executing the simulation.

read(addr, num_or_dtype, dtype=<class 'numpy.uint8'>, srcaddr=None, max_bytes=None, qos=0, prot=0, check_alignment=True, error=None)[source]
Parameters:

  • addr (int) – The 64-bit address 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.

  • srcaddr (int, optional) – The UMI source address used for the read transaction. This is sometimes needed to make sure that reads get routed to the right place.

  • max_bytes (int, optional) – Indicates the maximum number of bytes that can be used for any individual UMI transaction. If not specified, this defaults to the value of max_bytes provided in the UmiTxRx constructor, which in turn defaults to 32.

  • qos (int, optional) – 4-bit Quality of Service field used in the UMI command

  • prot (int, optional) – 2-bit Protection mode field used in the UMI command

  • error (bool, optional) – If True, error out upon receiving an unexpected UMI response.

Returns:

An array of num_or_dtype bytes read from addr. The array will have the type specified by dtype or num_or_dtype

Return type:

numpy integer array

recv(blocking=True)[source]

Wait for and return a UMI packet if blocking=True, otherwise return a UMI packet if one can be read immediately, and None otherwise.

Parameters:

blocking (bool, optional) – If True, the function will wait until a UMI packet can be read. If False, a None type will be returned if no UMI packet can be read immediately.

Returns:

If blocking is True, a PyUmiPacket is always returned. If blocking is False, a PyUmiPacket object will be returned if one can be read immediately. Otherwise, a None type will be returned.

Return type:

PyUmiPacket

send(p, blocking=True)[source]

Sends (or tries to send if burst=False) a UMI transaction (PyUmiPacket) Returns True if the packet was sent successfully, else False.

Parameters:

  • p (PyUmiPacket) – The UMI packet that will be sent

  • blocking (bool, optional) – If True, the program will pause execution until a response to the write request is received.

Returns:

Returns true if the p was sent successfully

Return type:

bool

write(addr, data, srcaddr=None, max_bytes=None, posted=None, qos=0, prot=0, progressbar=False, check_alignment=True, error=None)[source]

Writes the provided data to the given 64-bit address.

Parameters:

  • addr (int) – 64-bit address that will be written to

  • data (np.uint8, np.uint16, np.uint32, np.uint64, or np.array) – Can be either a numpy integer type (e.g., np.uint32) or an numpy array of integer types (np.uint8, np.uin16, np.uint32, np.uint64, etc.). The data input may contain more than “max_bytes”, in which case the write will automatically be split into multiple transactions.

  • srcaddr (int, optional) – UMI source address used for the write transaction. This is sometimes needed to make the write response gets routed to the right place.

  • max_bytes (int, optional) – Indicates the maximum number of bytes that can be used for any individual UMI transaction. If not specified, this defaults to the value of max_bytes provided in the UmiTxRx constructor, which in turn defaults to 32.

  • posted (bool, optional) – If True, a write response will be received.

  • qos (int, optional) – 4-bit Quality of Service field in UMI Command

  • prot (int, optional) – 2-bit protection mode field in UMI command

  • progressbar (bool, optional) – If True, the number of packets written will be displayed via a progressbar in the terminal.

  • check_alignment (bool, optional) – If true, an exception will be raised if the addr parameter cannot be aligned based on the size of the data parameter

  • error (bool, optional) – If True, error out upon receiving an unexpected UMI response.

write_readback(addr, value, mask=None, srcaddr=None, dtype=None, posted=True, write_srcaddr=None, check_alignment=True, error=None)[source]

Writes the provided value to the given 64-bit address, and blocks until that value is read back from the provided address.

Parameters:

  • addr (int) – The destination address to write to and read from

  • value (int, np.uint8, np.uint16, np.uint32, or np.uint64) – The data written to addr

  • mask (int, optional) – argument (optional) allows the user to mask off some bits in the comparison of the data written vs. data read back. For example, if a user only cares that bit “5” is written to “1”, and does not care about the value of other bits read back, they could use mask=1<<5.

  • srcaddr (int, optional) – The UMI source address used for the read transaction. This is sometimes needed to make sure that reads get routed to the right place.

  • dtype (np.uint8, np.uint16, np.uint32, or np.uint64, optional) – If value is specified as plain integer, then dtype must be specified, indicating a particular numpy integer type. This is so that the size of the UMI transaction can be set appropriately.

  • posted (bool, optional) – By default, the write is performed as a posted write, however it is is possible to use an ack’d write by setting posted=False.

  • write_srcaddr (int, optional) – If `posted`=True, write_srcaddr specifies the srcaddr used for that transaction. If write_srcaddr is None, the default srcaddr for writes will be used.

  • check_alignment (bool, optional) – If true, an exception will be raised if the addr parameter cannot be aligned based on the size of the data parameter

  • error (bool, optional) – If True, error out upon receiving an unexpected UMI response.

Raises:

TypeError – If value is not an integer type, if mask is not an integer type

switchboard.umi.addr_aligned(addr, align)[source]
Parameters:

  • addr (Integral)

  • align (Integral)

Return type:

bool

switchboard.umi.check_int_in_range(name, value, min=None, max=None)[source]
switchboard.umi.dtype2size(dtype)[source]
Parameters:

dtype (dtype)

switchboard.umi.nbytes2size(nbytes)[source]
Parameters:

nbytes (Integral)

switchboard.umi.random_int_value(name, value, min, max, align=None)[source]
switchboard.umi.random_umi_packet(opcode=None, len=None, size=None, dstaddr=None, srcaddr=None, data=None, qos=0, prot=0, ex=0, atype=0, eom=1, eof=1, max_bytes=32)[source]

Generates a Random UMI packet. All parameters are optional. Parameters that are not explicitly specified will be assigned randomly.

For more information on the meanings of each parameter, reference the UMI specification

Parameters:

  • opcode (int, optional) – Command opcode

  • len (int, optional) – Word transfers per message. (len-1 words will be transferred per message)

  • size (int, optional) – Word size ((2^size)-1 bits per word)

  • dstaddr (int, optional) – 64-bit destination address used in the UMI packet

  • srcaddr (int, optional) – 64-bit source address used in the UMI packet

  • data (numpy integer array, optional) – Values used in the Data field for the UMI packet

  • qos (int, optional) – 4-bit Quality of Service field used in the UMI command

  • prot (int, optional) – 2-bit Protection mode field used in the UMI command

  • ex (int, optional) – 1-bit Exclusive access indicator in the UMI command

  • atype (int, optional) – 8-bit field specifying the type of atomic transaction used in the UMI command for an atomic operation

  • eom (int, optional) – 1-bit End of Message indicator in UMI command, used to track the transfer of the last word in a message

  • eof (int, optional) – 1-bit End of Frame bit in UMI command, used to indicate the last message in a sequence of related UMI transactions

  • max_bytes (int, optional) – The maximum number of bytes included in each UMI packet

switchboard.umi.size2dtype(size, signed=False, float=False)[source]
Parameters:

  • size (int)

  • signed (bool)

  • float (bool)