Python APIs

Common functions

async interfaces.common_functions.test_functions.test_configure(dut: SimHandle, timeout_cycles=1000000, clk=25, timeout_precision=0.2, num_error=3, start_up=True) → Caravel_env[source]

Configure caravel power, clock, and reset and setup the timeout watchdog then return object of caravel environment.

Parameters:

dut (SimHandle) – dut handle
timeout_cycles (int) – Number of cycles before reporting timeout and exit the test default = 1000000 cycles
clk (int) – The clock period to be used in the design in 'ns' default 12.5 'ns'
timeout_precision (int) – Precision of logging how many cycle left until the timeout default is 0.2 meaning if time is 100 cycle every 20 cycles there would be a warning message for timeout
num_error (int) – Maximum number of errors reported before terminate the test
start_up (bool) – start up the test connecting power and reset

Returns:

Object of type Caravel_env (caravel environment)

Caravel Environment

class interfaces.caravel.Caravel_env(dut: SimHandleBase)[source]

Verification environment for caraval - provide APIs for monitoring and driving caravel GPIOs, power pins, clock and reset pins :param SimHandle dut: dut handle

async reset()[source]: Reset caravel

async disable_csb()[source]: Set the SPI CSB signal high to disable housekeeping SPI transmission pin E8 mprj[3]

async release_csb()[source]: Set the SPI CSB signal high impedance

async enable_csb()[source]: Set the SPI CSB signal low to enable housekeeping SPI transmission pin E8 mprj[3]

monitor_gpio(h_bit, l_bit=None) → BinaryValue[source]

monitor GPIOs output value

Parameters:

h_bit (int or tuple(int, int)) – highest GPIO number of the tuple of (high GPIO, low GPIO)
l_bit – lowest GPIO to monitor number

Raises:

exception – If h_bit is lower than l_bit

Returns:

cocotb.binary.BinaryValue

Example:

monitor_gpio(7) #get output value of GPIO 7 (GPIOs[7])
monitor_gpio(7,0) # get output value from GPIO 7 to 0 (GPIOs[7:0])
monitor_gpio((7,0)) #get output value from GPIO 7 to 0 (GPIOs[7:0])

monitor_mgmt_gpio() → str[source]

monitor management GPIO output

Returns:: return the value of management GPIO in string format possible values "0" "1" "X" "Z"

monitor_discontinuous_gpios(arr: list) → str[source]

monitor discontinuous GPIOs output value

Parameters:: arr (list(ints) or tuple(ints)) – highest GPIO number of the tuple of (high GPIO, low GPIO)
Returns:: str

Example:

monitor_discontinuous_gpios([3,2,5]]) #return the value at 3,1,5 in str, str[0] = gpio[5], str[-1]=gpio[3]

async wait_mgmt_gpio(data: int) → None[source]

wait for specific management GPIO value

Parameters:: data (int or str) – data to wait for possible inputs "0" "1" 0 1

drive_gpio_in(bits, data) → None[source]

drive input GPIOs with specific data

Parameters:

bits (int or tuple(int, int)) – GPIOs to drive
data (int) – data to drive the GPIOs with

Example:

drive_gpio_in(7,0x1) # drive GPIO 7 with 1 (GPIOs[7]=1)
drive_gpio_in((31,0),0xFFFFFFFF) # drive GPIO 31 to 0 with ones (GPIOs[31:0]=32'hFFFFFFFF)

release_gpio(bits)[source]: release driving the value of mprj bits :param bits: GPIOs to drive :type bits: int or tuple(int, int)

drive_mgmt_gpio(data)[source]

drive GPIO management with specific data

Parameters:: data (int) – data to drive the GPIOs with

setup_clock(period, unit='ns') → Clock[source]

Configure caravel clock and start it

Parameters:

period (int) – clock period
unit (str) – One of 'step', 'fs', 'ps', 'ns', 'us', 'ms', 'sec'.When unit is 'step',the timestep is determined by the simulator.

Returns:

Object of type Caravel_env (caravel environment)

get_clock_obj() → Clock[source]: return the used clock object of cocotb.clock.Clock used mostly to get info about simulation time or clock period info

get_clock_period() → int[source]: return the used clock period in ns

SPI Environment

class interfaces.SPI.SPI(caravelEnv: Caravel_env, clk_period=None, spi_pins={'CSB': 3, 'SCK': 4, 'SDI': 1, 'SDO': 2})[source]

The interface is acting as an spi master. It communicates mainly with the slave inside the housekeeping

Parameters:

caravelEnv (Caravel_env) – The Caravel environment object to use.
clk_period (float or None) – The clock period in microseconds, or None to use the default (3 times the Caravel clock period).
spi_pins (dict[str, int]) – The SPI pins to use, as a dictionary with keys “CSB”, “SCK”, “SDO”, and “SDI”.

async disable_csb()[source]

Disables the housekeeping SPI transmission by driving the CSB line high.

Note: The function waits for 2 clock cycles before disabling to ensure that the previous writing command has been applied. It then drives the CSB line high and kills the SPI clock.Finally, the function waits for some time to ensure that the disable has taken effect.

async enable_csb()[source]

Enable the chip select bar (CSB) pin for SPI transmission.

Note: This method drives the CSB pin low and sets up the SPI clock. It also waits for some time after disabling the CSB pin for the changes to take effect.

async write_reg_spi(address, data, disable_csb: bool = True)[source]

Writes a register over SPI using the housekeeping SPI bus.

Parameters:

address (int) – The address of the register to write.
data (int) – The value to write to the register.
disable_csb (bool) – Whether to disable the chip select line after the write is complete. Defaults to True.

Returns:

None

async read_reg_spi(address, disable_csb: bool = True)[source]

Reads a byte from a register at the given address over the housekeeping SPI interface.

Parameters:

address (int) – The address of the register to read from.
disable_csb (bool) – Whether to disable the chip select line after reading the byte. Defaults to True.

Returns:

int: The byte read from the register.

async read_write_reg_spi(address, data, disable_csb: bool = True)[source]

Writes to and reads from a register at the given SPI address using the housekeeping SPI.

Parameters:

address (int) – The address of the register to write to/read from.
data (int) – The data to write to the register.
disable_csb (bool) – Whether to disable the chip select line after the operation. Defaults to True.

Returns:

int: The data read from the register.

Examples:

>>> result = await read_write_reg_spi(0x14, 0xAB)
>>> print(hex(result))
0x42
>>> result = await read_write_reg_spi(0x14, 0xD7)
>>> print(hex(result))
0xAB

async write_reg_spi_nbytes(address, data, n_bytes, disable_csb: bool = True)[source]

Writes to n_bytes bytes starting from the register at address over the housekeeping SPI.

Parameters:

address (int) – The address of the register to write.
data (list(int)) – The data to be written to the register.
n_bytes (int) – The number of bytes to be written.
disable_csb (bool) – Whether to disable chip select after write. Defaults to True.

Returns:

None

async read_reg_spi_nbytes(address, n_bytes, disable_csb: bool = True)[source]

Read n_bytes bytes starting from the register at address over the housekeeping SPI.

Parameters:

address (int) – The address of the register to read.
n_bytes (int) – The number of bytes to read.
disable_csb (bool) – Whether to disable chip select after reading. Defaults to True.

Returns:

A list with n_bytes integers, where each integer is a byte read from the register.

async read_write_reg_nbytes(address, data_in, n_bytes, disable_csb: bool = True)[source]

Read and write n_bytes bytes starting from the register at address over the housekeeping SPI.

Parameters:

address (int) – The address of the register to read.
data (list(int)) – The data to be written to the register.
n_bytes (int) – The number of bytes to read.
disable_csb (bool) – Whether to disable chip select after reading. Defaults to True.

Returns:

A list with n_bytes integers, where each integer is a byte read from the register.

async reg_spi_user_pass_thru(send_data: list, read_byte_num: int = 0, disable_csb: bool = True)[source]

Sends SPI data to a housekeeping SPI using user pass-thru command.

Parameters:

send_data (list) – A list of data to be sent includeing the commands and addresses.
read_byte_num (int) – expected number of bytes to be read defaults to 0.
disable_csb (bool) – Whether to disable CSB after the transaction defaults to True.

Returns:

A list of read data if read_byte_num is not 0.

async reg_spi_mgmt_pass_thru_read(address: int, read_byte_num: int = 1, disable_csb: bool = True)[source]

Sends SPI read data command to a housekeeping SPI using managment pass-thru command.

Parameters:

address (int) – The address of the register to read.
read_byte_num (int) – expected number of bytes to be read defaults to 1.
disable_csb (bool) – Whether to disable CSB after the transaction defaults to True.

async reg_spi_op(command, address, disable_csb: bool = True)[source]

Perform a register SPI operation.

Parameters:

command (int) – The SPI command byte.
address (int) – The SPI address byte.
disable_csb (bool) – Whether to disable the chip select line after the operation. Defaults to True.

Returns:

None

class SPI_COMMAND(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

enum class representing SPI command bytes.

members:

NO_OP:: A command byte representing a no-op operation.
WRITE_STREAM:: A command byte representing a write stream operation.
READ_STREAM:: A command byte representing a read stream operation.
WRITE_READ:: A command byte representing a write-and-read operation.
USER_PASS_THRU:: A command byte representing a user pass-through operation.
MGMT_PATH_THRU:: A command byte representing a management path pass-through operation.

UART Environment

class interfaces.UART.UART(caravelEnv: Caravel_env, uart_pins={'rx': 5, 'tx': 6})[source]

UART Verification environment to provide APIs to communicate with caravel UART through caravel gpios

Parameters:: caravelEnv (Caravel_env) – caravel environment

async get_line()[source]

Read line sent through UART (msg is sent by the software)

Line is a bunch of ASCII sybmols ended by linefeed ‘\n’

async get_int() → int[source]: read int sent by firmware API uart_put_int

async get_char()[source]

Read character sent through UART (character is sent by the software)

Character is a 8 bit ASCII symbol

async uart_send_char(char)[source]

Send character to UART (character is sent to the software)

Character is a 8 bit ASCII symbol

async uart_send_line(line)[source]

Send line to UART (msg is sent to the software)

Line is a bunch of ASCII symbols ended by linefeed ‘\n’