From bd328e27e97056c45bd3ad925c921ad0d3f86208 Mon Sep 17 00:00:00 2001 From: Robert Winkler Date: Wed, 18 Sep 2024 10:45:29 +0200 Subject: [PATCH] modules/zstd/memory: Add README describing the AXI interface Co-authored-by: Pawel Czarnecki Signed-off-by: Robert Winkler --- xls/modules/zstd/memory/README.md | 103 ++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 xls/modules/zstd/memory/README.md diff --git a/xls/modules/zstd/memory/README.md b/xls/modules/zstd/memory/README.md new file mode 100644 index 0000000000..1284ba79cb --- /dev/null +++ b/xls/modules/zstd/memory/README.md @@ -0,0 +1,103 @@ +# Memory + +This directory contains procs responsible for issuing read and write +transactions compatible with AXI subordinates. The AXI bus was selected +because it consists of five streams, which closely resemble the streams +to which XLS channels are translated. + +Although XLS channels do not fully conform to the AXI standard, with proper +I/O configuration, DSLX procs using XLS channels can successfully interface +and communicate with AXI4 peripherals. + +The signals used to form AXI channels are represented as individual fields +in dedicated structures. However, the XLS toolchain generates these fields +as a flattened bit array. As a result, the Verilog code produced from these +structures will not match the expected AXI bus signature. To interface with +other AXI peripherals, additional Verilog wrappers may be needed to split +the flattened bit vector into individual signals. + +# Data Structures + +As noted, the procs in this directory use channels with dedicated +structures to represent AXI bus signals in DSLX. For instance, the AXI read +interface comprises the AR channel, which is used to provide a read address, +and the length of data to read, as well as the R channel, which is used +to receive the read data. These channels are represented by the `AxiAr` and +`AxiR` structures in the `axi.x` file, which contains AXI4 bus definitions. +The structures use to represent AXI4 Stream interface can be found in +the `axi_st.x` file. + +# Main components + +The primary components of this directory are `MemReader` and `MemWriter`, +which facilitate issuing read and write transactions on the AXI bus. +They provide a convenient interface for the DSLX side of the design, +managing the complexities of AXI transactions. + +The `MemReader` includes several procs that can be used individually: + +- `AxiReader`: Handles the creation of AXI transactions, managing unaligned + addresses and issuing additional transactions when crossing the 4KB boundary + or when the read request is longer than maximum possible burst size on the AXI bus + +- `AxiStreamDownscaler`: An optional proc available in `MemReaderAdv`, + enabling DSLX designs to connect to a wider AXI bus. + +- `AxiStreamRemoveEmpty`: Removes empty data bits, identified by zeroed bits in + the `tkeep` and `tstr` signals of the AXI Stream. + +The `MemWriter` proc is organised in a similar manner, it consists of: + +- `AxiWriter`: Handles the creation of AXI write transactions, managing unaligned + addresses and issuing additional transactions when crossing the 4KB boundary, + or when the write request is longer than maximum possible burst size on the AXI bus + +- `AxiStreamAddEmpty`: Adds empty data bits in the stream of data to write. + It is used to shift the data in the stream to facilitate writes to unaligned + addresses. + +# Usage + +The list below shows the usage of the `MemReader` proc: + +1. Configure the base address for the read transactions, by sending the + properly filled `MemReaderCtrl` structure to the `ctrl_r` channel. + All the requests performed later will be relative to the provided base address. + +2. Send a `MemReaderReq` to the `req_in_r` channel, providing the information + about the relative offset from which to read the data, and the length + of data to read. + +3. Wait for the response on the `resp_s` channel. The received packet + consists of: + + - the `status` of the operation indicating if the read was successful + - `data` read from the bus + - `length` of the valid `data` in bytes + - `last` flag used for marking the last `packet` with data + +The list below shows the usage of the `MemWriter` proc: + +1. Configure the base address for the write transactions, by sending the + properly filled `MemWriterCtrl` structure to the `ctrl_r` channel. + All the requests performed later will be relative to the provided base address. + +2. Send a `MemWriterReq` to the `req_in_r` channel, providing the information + about the relative offset to which data should be sent, and length of the + transaction in bytes. + +3. Provide the data to write using the `MemWriterDataPacket` structure, which + should be send to `data_in_r` channel. The structure consists of + + - the actual `data` + - `length` of the `data` in bytes + - `last` flag used for marking the last `packet` with data. + +4. Wait for the response submitted on the `resp_s` channel, which indicates + if the write operation was successful or an error occurred. + +# Cocotb Simulation + +This directory also contains Verilog simulations of the created modules, +which test their interaction with RAM attached to the AXI bus. These Verilog +simulations provide insight into the design's latency and achievable throughput.