iobundle / iob-axis

AXI4-Stream

What is this repository for?

The IObundle AXISTREAM is a RISC-V-based Peripheral written in Verilog, which users can download for free, modify, simulate, and implement in FPGA or ASIC. This peripheral provides an AXI4-Stream interface for communication with external systems. It also provides a Direct Memory Access (DMA) interface using another AXI4-Stream interface.

This peripheral can be used as a verification tool of the OpenCryptoTester project.

This repository contains both the AXISTREAM_IN and AXISTREAM_OUT peripherals. The configuration and sources for these peripherals are located within the axistream_in and axistream_out folders, respectively.

Integrate in SoC

• Check out IOb-SoC-SUT

Usage

The main classes that describe these cores are located in the iob_axistream_in.py and iob_axistream_out.py Python modules. They contain a set of methods useful to set up and instantiate these cores.

The following steps describe the process of creating an AXISTREAMIN peripheral in an IOb-SoC-based system (the steps for the AXISTREAMOUT peripheral are similar):

1. Import the iob_axistream_in class
2. Run the iob_axistream_in.setup() method to copy the required sources of this module to the build directory.
3. Run the iob_axistream_in(...) method to create a Verilog instance of the AXISTREAMIN peripheral.
4. Use this core as a peripheral of an IOb-SoC-based system:
   1. Add the created instance to the peripherals list of the IOb-SoC-based system.
   2. Write the firmware to run in the system, including the iob-axistream-in.h C header and use its driver functions to control this core.

Example configuration

The iob_soc_sut.py script of the IOb-SoC-SUT system, uses the following lines of code to instantiate an AXISTREAMIN peripheral with the instance name AXISTREAMIN0:

# Import the iob_axistream_in class
from iob_axistream_in import iob_axistream_in

# Class of the SUT system
class iob_soc_sut(iob_soc):
  ...
  # Method that runs the setup process of the SUT system
  @classmethod
  def _post_setup(cls):
    ...
    # Setup the AXISTREAMIN module (Copies every file and dependency required to the build directory)
    iob_axistream_in.setup()
    ...
    # Create a Verilog instance of this module, named 'AXISTREAMIN0', and add it to the peripherals list of the system.
    cls.peripherals.append(
        iob_axistream_in(
            "AXISTREAMIN0", # Verilog instance name
            "SUT AXI input stream interface", # Instance description

            # Verilog parameters to pass to this instance.
            # In this example, we use a 32-bit TDATA signal.
            parameters={"TDATA_W": "32"},
        )
    )

Direct Memory Access (DMA)

This peripheral provides a DMA interface using AXI4-Stream. Is also contains the fifo_threshold port to be used as an interrupt for the CPU. This signal can be used to trigger data transfers via DMA.

• Check out IOb-DMA for more details.

The iob_soc_tester.py script of the IOb-SoC-SUT system, provides examples of AXISTREAM peripherals configured to use the DMA interface.

Brief description of C interface

The AXISTREAM cores store the values in an internal FIFO buffer, which can be accessed via software.

An example of some C code is given, with explanations:

For the AXISTREAMIN peripheral:

//Set AXISTREAMIN base address
axistream_in_init(int base_address);

//Get a 32-bit word from FIFO
uint32_t received_word = axistream_in_pop_word();

//Signal when FIFO empty
bool is_empty = axistream_in_empty();

//Returns if the last value of read from FIFO was the end of frame (by TLAST signal) and gets rstrb from that value
bool was_last = axistream_in_was_last(char *rstrb);

//Pulse soft reset
axistream_in_reset();

//Enable peripheral
axistream_in_enable();

//Disable the tready signal, preventing new transfers
axistream_in_disable();

//Get value from FIFO [can be used instead of axistream_in_pop_word() and axistream_in_was_last()]
//Returns true if this word was tlast, false otherwise
//Arguments:
//    byte_array: byte array to be filled with 4 bytes popped from FIFO word
//    n_valid_bytes: Number of valid bytes in this word (will always be 4 if tlast is not active)
bool is_last = axistream_in_pop(uint8_t *byte_array, uint8_t *n_valid_bytes);

//Set the FIFO threshold level
//If the FIFO level is equal or higher than the threshold, trigger an interrupt
axistream_in_set_fifo_threshold(uint32_t threshold);

//Get current FIFO level
uint32_t fifo_level = axistream_in_fifo_level();

For the AXISTREAMOUT peripheral:

//Set AXISTREAMOUT base address
//If the instance has tdata_w > 1 byte, don't use this function to initialize it. Use function: axistream_out_init_tdata_w()
axistream_out_init(int base_address);

//Set AXISTREAMOUT base address and tdata width
axistream_out_init_tdata_w(int base_address, int tdata_w);

//Free memory from initialized instances
axistream_out_free();

//Place value in FIFO, also place wstrb for a word with TLAST signal.
//If tlast_wstrb is zero then all bytes are valid and don't send TLAST signal
//tlast_wstrb has 1 up to 4 bits depending on the output width of the FIFO (width of TDATA signal). 
//If TDATA has 8 bits, then tlast_wstrb has 4 bits (1 for each valid byte of the last 32bit word in FIFO);
//If TDATA has 16 bits, then tlast_wstrb has 2 bits (1 for each valid 16-bit word of the last 32bit word in FIFO);
//If TDATA has 32 bits, then tlast_wstrb has 1 bit (in this case, 32 bits are always valid independently of tlast_wstrb, this bit only selects if we send TLAST signal)
axistream_out_push_word(uint32_t value, char tlast_wstrb);

//Place value in FIFO, also place wstrb for a word with TLAST signal. [can be used instead of axistream_out_push_word()]
//Arguments:
//    byte_array: bytes to insert in fifo
//    n_valid_bytes: number of valid bytes in value, should be multiple of tdata_w
//    is_tlast: if value contains tlast
axistream_out_push(uint8_t *byte_array, uint8_t n_valid_bytes, bool is_tlast);

//Signal when FIFO is full
bool full = axistream_out_full();

//pulse soft reset
axistream_out_reset();

//Enable peripheral
axistream_out_enable();

//Disable peripheral, preventing new transfers
axistream_out_disable();

//Set the FIFO threshold level
//If the FIFO level is equal or lower than the threshold, trigger an interrupt
axistream_out_set_fifo_threshold(uint32_t threshold);

//Get current FIFO level
uint32_t fifo_level = axistream_out_fifo_level();

Acknowledgement

The OpenCryptoTester project is funded through the NGI Assure Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 957073.

iob-axis's Issues

Multiple frames in AXISTREAM_IN axis_tlast bug

If multiple frames are processed originating multiple tlasts, then only the first tlast is registered in the TLAST_DETECTED register and the word counter, meaning the software must disable, restart and re-enable the axistream between frames, which may delete samples from the next frame from the FIFO if the disable isn't done fast enough after detecting the tlast