Skip to content

AXI SystemVerilog synthesizable IP modules and verification infrastructure for high-performance on-chip communication

License

Notifications You must be signed in to change notification settings

pulp-platform/axi

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

AXI SystemVerilog Modules for High-Performance On-Chip Communication

CI status GitHub tag (latest SemVer) SHL-0.51 license

This repository provides modules to build on-chip communication networks adhering to the AXI4 or AXI4-Lite standards. For high-performance communication, we implement AXI4+ATOPs from AXI5. For lightweight communication, we implement AXI4-Lite. We aim to provide a complete end-to-end communication platform, including endpoints such as DMA engines and on-chip memory controllers.

Our design goals are:

  • Topology Independence: We provide elementary building blocks such as protocol multiplexers and demultiplexers that allow users to implement any network topology. We also provide commonly used interconnecting components such as a crossbar.
  • Modularity: We favor design by composition over design by configuration where possible. We strive to apply the Unix philosophy to hardware: make each module do one thing well. This means you will more often instantiate our modules back-to-back than change a parameter value to build more specialized networks.
  • Fit for Heterogeneous Networks: Our modules are parametrizable in terms of data width and transaction concurrency. This allows to create optimized networks for a wide range of performance (e.g., bandwidth, concurrency, timing), power, and area requirements. We provide modules such as data width converters and ID width converters that allow to join subnetworks with different properties, creating heterogeneous on-chip networks.
  • Full AXI Standard Compliance.
  • Compatibility with a wide range of (recent versions of) EDA tools and implementation in standardized synthesizable SystemVerilog.

The design and microarchitecture of the modules in this repository is described in this paper (preprint). If you use our work in your research, please cite it.

List of Modules

In addition to the documents linked in the following table, we are setting up documentation auto-generated from inline docstrings. (Replace master in that URL with a tag to get the documentation for a specific version.)

Name Description Doc
axi_atop_filter Filters atomic operations (ATOPs), i.e., write transactions that have a non-zero aw_atop value.
axi_burst_splitter Split AXI4 burst transfers into single-beat transactions.
axi_cdc AXI clock domain crossing based on a Gray FIFO implementation.
axi_cut Breaks all combinatorial paths between its input and output.
axi_delayer Synthesizable module which can (randomly) delays AXI channels.
axi_demux_simple Demux without spill registers. Doc
axi_demux Demultiplexes an AXI bus from one slave port to multiple master ports. Doc
axi_dw_converter A data width converter between AXI interfaces of any data width.
axi_dw_downsizer A data width converter between a wide AXI master and a narrower AXI slave.
axi_dw_upsizer A data width converter between a narrow AXI master and a wider AXI slave.
axi_err_slv Always responds with an AXI decode/slave error for transactions which are sent to it.
axi_fifo A Fifo for each AXI4 channel to buffer requests.
axi_from_mem This module acts like an SRAM and makes AXI4 requests downstream.
axi_id_prepend This module prepends/strips the MSB from the AXI IDs.
axi_id_remap Remap AXI IDs from wide IDs at the slave port to narrower IDs at the master port. Doc
axi_id_serialize Reduce AXI IDs by serializing transactions when necessary. Doc
axi_interleaved_xbar Interleaved version of the crossbar. This module is experimental; use at your own risk.
axi_intf This file defines the interfaces we support.
axi_isolate A module that can isolate downstream slaves from receiving new AXI4 transactions.
axi_iw_converter Convert between any two AXI ID widths. Doc
axi_join A connector that joins two AXI interfaces.
axi_lfsr AXI4-attached LFSR; read returns pseudo-random data, writes are compressed into a checksum.
axi_lite_demux Demultiplexes an AXI4-Lite bus from one slave port to multiple master ports. Doc
axi_lite_dw_converter A data width converter between two AXI-Lite busses [Doc][doc.axi_lite_dw_converter]
axi_lite_from_mem This module acts like an SRAM and makes AXI4-Lite requests downstream.
axi_lite_join A connector that joins two AXI-Lite interfaces.
axi_lite_lfsr AXI4-Lite-attached LFSR; read returns pseudo-random data, writes are compressed into a checksum.
axi_lite_mailbox A AXI4-Lite Mailbox with two slave ports and usage triggered irq. Doc
axi_lite_mux Multiplexes AXI4-Lite slave ports down to one master port. Doc
axi_lite_regs AXI4-Lite registers with optional read-only and protection features. Doc
axi_lite_to_apb AXI4-Lite to APB4 protocol converter.
axi_lite_to_axi AXI4-Lite to AXI4 protocol converter.
axi_lite_xbar Fully-connected AXI4-Lite crossbar with an arbitrary number of slave and master ports. Doc
axi_modify_address A connector that allows addresses of AXI requests to be changed.
axi_multicut AXI register which can be used to relax timing pressure on long AXI buses.
axi_mux Multiplexes the AXI4 slave ports down to one master port. Doc
axi_pkg Contains AXI definitions, common structs, and useful helper functions.
axi_rw_join Joins a read and a write slave into one single read / write master.
axi_rw_split Splits a single read / write slave into one read and one write master.
axi_serializer Serializes transactions with different IDs to the same ID.
axi_slave_compare Compares two slave devices.
axi_throttle Limits the maximum number of outstanding transfers sent to the downstream logic.
axi_test A set of testbench utilities for AXI interfaces.
axi_to_axi_lite AXI4 to AXI4-Lite protocol converter.
axi_to_mem AXI4 to memory protocol (req, gnt, rvalid) converter. Additional banked, interleaved, split variant.
axi_xbar Fully-connected AXI4+ATOP crossbar with an arbitrary number of slave and master ports. Doc
axi_xbar_unmuxed Demux side of fully-connected AXI4+ATOP crossbar with an arbitrary number of slave and master ports. Doc
axi_xp AXI Crosspoint (XP) with homomorphous slave and master ports.
axi_zero_mem AXI-attached /dev/zero. All reads will be zero, writes are absorbed.

Synthesizable Verification Modules

The following modules are meant to be used for verification purposes only but are synthesizable to be used in FPGA environments.

Name Description
axi_bus_compare Compares two buses of the same type (and in the same clock domain), returns events on mismatch.
axi_slave_compare Compares two slave devices of the same type (and in the same clock domain), returns events on mismatch.

Simulation-Only Modules

In addition to the modules above, which are available in synthesis and simulation, the following modules are available only in simulation. Those modules are widely used in our testbenches, but they are also suitable to build testbenches for AXI modules and systems outside this repository.

Name Description
axi_chan_compare Non-synthesizable module comparing two AXI channels of the same type
axi_chan_logger Logs the transactions of an AXI4(+ATOPs) port to files.
axi_driver Low-level driver for AXI4(+ATOPs) that can send and receive individual beats on any channel.
axi_dumper Dumps log to file to be interpreted by axi_dumper_interpret script for debugging purposes.
axi_file_master AXI4 master for file-based testbenches
axi_lite_driver Low-level driver for AXI4-Lite that can send and receive individual beats on any channel.
axi_lite_rand_master AXI4-Lite master component that issues random transactions within user-defined constraints.
axi_lite_rand_slave AXI4-Lite slave component that responds to transactions with constrainable random delays and data.
axi_rand_master AXI4(+ATOPs) master component that issues random transactions within user-defined constraints.
axi_rand_slave AXI4(+ATOPs) slave component that responds to transactions with constrainable random delays and data.
axi_scoreboard Scoreboard that models a memory that only gets changed by the monitored AXI4(+ATOPs) port.
axi_sim_mem Infinite memory with AXI4 slave port.

Atomic Operations

AXI4+ATOPs means the full AXI4 specification plus atomic operations (ATOPs) as defined in Section E1.1 of the AMBA 5 specification. This has the following implications for modules that do not implement ATOPs and systems that include such modules:

  • Masters that do not issue ATOPs must set aw_atop to '0.
  • Slaves that do not support ATOPs must specify this in their interface documentation and can ignore the aw_atop signal.
  • System designers are responsible for ensuring that
    1. slaves that do not support ATOPs are behind an axi_atop_filter if any master could issue an ATOP to such slaves and
    2. the aw_atop signal is well-defined at the input of any (non-AXI4-Lite) module in this repository.

Masters and slaves that do support ATOPs must adhere to Section E1.1 of the AMBA 5 specification. In particular:

  • ATOPs that have the aw_atop[axi_pkg::ATOP_R_RESP] bit set generate a write response (B channel) beat and at least one read response (R channel) beat. All modules for which the aw_atop[axi_pkg::ATOP_R_RESP] bit could be set at their master port must be able to handle both B and R beats (in any order and without requiring a simultaneous handshake) for each such ATOP request. All modules for which the aw_atop[axi_pkg::ATOP_R_RESP] bit could be set at their slave port must respond with the appropriate number of B and R beats for each such ATOP request.
  • ATOPs must not use the same AXI ID as any other transaction that is outstanding at the same time.

Which EDA Tools Are Supported?

Our code is written in standard SystemVerilog (IEEE 1800-2012, to be precise), so the more important question is: Which subset of SystemVerilog does your EDA tool support?

We aim to be compatible with a wide range of EDA tools. For this reason, we strive to use as simple language constructs as possible, especially for our synthesizable modules. We encourage contributions that further simplify our code to make it compatible with even more EDA tools. We also welcome contributions that work around problems that specific EDA tools may have with our code, as long as:

  • the EDA tool is reasonably widely used,
  • recent versions of the EDA tool are affected,
  • the workaround does not break functionality in other tools, and
  • the workaround does not significantly complicate code or add maintenance overhead.

In addition, we suggest to report issues with the SystemVerilog language support directly to the EDA vendor. Our code is fully open and can / should be shared with the EDA vendor as a testcase for any language problem encountered.

All code in each release and on the default branch is tested on a recent version of at least one industry-standard RTL simulator and synthesizer. You can examine the CI settings to find out which version of which tool we are running.