From b3c58abcdcaf5f21b0ea4bf8121c296d5a39e84d Mon Sep 17 00:00:00 2001 From: Ionut Podgoreanu Date: Tue, 31 Oct 2023 00:16:58 +0200 Subject: [PATCH] docs: Include the DMA SG documentation Signed-off-by: Ionut Podgoreanu --- docs/library/axi_dmac/block_diagram.svg | 41 +++++-- docs/library/axi_dmac/index.rst | 138 ++++++++++++++++++++++-- docs/regmap/adi_regmap_dmac.txt | 92 +++++++++++++--- 3 files changed, 241 insertions(+), 30 deletions(-) diff --git a/docs/library/axi_dmac/block_diagram.svg b/docs/library/axi_dmac/block_diagram.svg index 5b024bd05..094f74732 100644 --- a/docs/library/axi_dmac/block_diagram.svg +++ b/docs/library/axi_dmac/block_diagram.svg @@ -1,4 +1,5 @@ - + + @@ -58,9 +59,22 @@ + + + + + + + + + + + + + - - + + @@ -68,9 +82,9 @@ Register Map - S_AXI - s_axi_aclk - irq + S_AXI + s_axi_aclk + irq @@ -90,12 +104,14 @@ + - + - - + + + AXI-MM /AXI-Streaming /FIFO @@ -121,5 +137,12 @@ src_clk dest_clk + + + Scatter-GatherInterface + + + sg_clk + AXI-MM diff --git a/docs/library/axi_dmac/index.rst b/docs/library/axi_dmac/index.rst index 0f8a261b0..d080a29cd 100644 --- a/docs/library/axi_dmac/index.rst +++ b/docs/library/axi_dmac/index.rst @@ -25,6 +25,7 @@ Features - Cyclic transfers - 2D transfers +- Scatter-Gather transfers Utilization -------------------------------------------------------------------------------- @@ -78,21 +79,31 @@ Configuration Parameters - Data path width of the source interface in bits. * - DMA_DATA_WIDTH_DEST - Data path width of the destination interface in bits. + * - DMA_DATA_WIDTH_SG + - Data path width of the scatter-gather interface in bits. * - DMA_LENGTH_WIDTH - Width of transfer length control register in bits. Limits length of the transfers to 2*\*\ ``DMA_LENGTH_WIDTH``. * - DMA_2D_TRANSFER - Enable support for 2D transfers. + * - DMA_SG_TRANSFER + - Enable support for scatter-gather transfers. * - ASYNC_CLK_REQ_SRC - Whether the request and source clock domains are asynchronous. * - ASYNC_CLK_SRC_DEST - Whether the source and destination clock domains are asynchronous. * - ASYNC_CLK_DEST_REQ - Whether the destination and request clock domains are asynchronous. + * - ASYNC_CLK_REQ_SG + - Whether the request and scatter-gather clock domains are asynchronous. + * - ASYNC_CLK_SRC_SG + - Whether the source and scatter-gather clock domains are asynchronous. + * - ASYNC_CLK_DEST_SG + - Whether the destination and scatter-gather clock domains are asynchronous. * - AXI_SLICE_DEST - - Whether to insert a extra register slice on the source data path. + - Whether to insert an extra register slice on the source data path. * - AXI_SLICE_SRC - - Whether to insert a extra register slice on the destination data path. + - Whether to insert an extra register slice on the destination data path. * - SYNC_TRANSFER_START - Enable the transfer start synchronization feature. * - CYCLIC @@ -100,7 +111,9 @@ Configuration Parameters * - DMA_AXI_PROTOCOL_SRC - AXI protocol version of the source interface (0 = AXI4, 1 = AXI3). * - DMA_AXI_PROTOCOL_DEST - - AXI protocol version of the destionation interface (0 = AXI4, 1 = AXI3). + - AXI protocol version of the destination interface (0 = AXI4, 1 = AXI3). + * - DMA_AXI_PROTOCOL_SG + - AXI protocol version of the scatter-gather interface (0 = AXI4, 1 = AXI3). * - DMA_TYPE_SRC - Interface type for the source interface (0 = AXI-MM, 1 = AXI-Streaming, 2 = ADI-FIFO). @@ -149,7 +162,7 @@ Interface - Reset for the ``m_src_axi`` interface. Only present when ``DMA_TYPE_SRC`` parameter is set to AXI-MM (0). * - m_src_axi - - + - Only present when ``DMA_TYPE_SRC`` parameter is set to AXI-MM (0). * - m_dest_axi_aclk - The ``m_src_axi`` interface is synchronous to this clock. Only present when ``DMA_TYPE_DEST`` parameter is set to AXI-MM (0). @@ -157,7 +170,15 @@ Interface - Reset for the ``m_dest_axi`` interface. Only present when ``DMA_TYPE_DEST`` parameter is set to AXI-MM (0). * - m_dest_axi - - + - Only present when ``DMA_TYPE_DEST`` parameter is set to AXI-MM (0). + * - m_sg_axi_aclk + - The ``m_sg_axi`` interface is synchronous to this clock. + Only present when ``DMA_SG_TRANSFER`` parameter is set. + * - m_sg_axi_aresetn + - Reset for the ``m_sg_axi`` interface. + Only present when ``DMA_SG_TRANSFER`` parameter is set. + * - m_sg_axi + - Only present when ``DMA_SG_TRANSFER`` parameter is set. * - s_axis_aclk - The ``s_axis`` interface is synchronous to this clock. Only present when ``DMA_TYPE_SRC`` parameter is set to AXI-Streaming @@ -539,6 +560,101 @@ cyclic transfer the DMA channel must be disabled. Any additional transfers that are submitted after the submission of a cyclic transfer (and before stopping the cyclic transfer) will never be executed. +Scatter-Gather Transfers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the ``DMA_SG_TRANSFER`` HDL synthesis configuration parameter is set the DMA +controller has support for scatter-gather transfers. + +The scatter-gather optional feature allows the DMA to access noncontiguous areas +of memory within a single transfer. + +The DMA can read from or write to different memory addresses in one transaction +by using a list of vectors called *descriptors*. Each descriptor provides the +starting address and the length of the current memory block to be accessed, as +well as the next address of the following descriptor to be processed. By chaining +these descriptors, the DMA can *gather* the data into a contiguous transfer from +the *scattered* memory data from multiple addresses. + +The scatter-gather has its own dedicated AXI3/4 memory mapped interface +``m_sg_axi`` through which it receives the descriptor data. + +Descriptor Structure +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The scatter-gather interface fetches the descriptor information from memory in +the following order: + +.. list-table:: + :header-rows: 1 + + * - Size + - Name + - Description + * - 32-bit + - flags + - | This field includes 2 control bits: + + * bit0: if set, the transfer will complete after this last descriptor is + processed and the DMA core will go back to idle state; if cleared, the + next DMA descriptor pointed to by ``next_sg_addr`` will be loaded. + * bit1: if set, an end-of-transfer interrupt will be raised after the + memory segment pointed to by this descriptor has been transferred. + * - 32-bit + - id + - This field corresponds to an identifier of the descriptor. + * - 64-bit + - dest_addr + - This field contains the destination address of the transfer. + * - 64-bit + - src_addr + - This field contains the source address of the transfer. + * - 64-bit + - next_sg_addr + - This field contains the address of the next descriptor. + * - 32-bit + - y_len + - This field contains the number of rows to transfer, minus one. + * - 32-bit + - x_len + - This field contains the number of bytes to transfer, minus one. + * - 32-bit + - src_stride + - This field contains the number of bytes between the start of one row and + the next row for the source address. + * - 32-bit + - dst_stride + - This field contains the number of bytes between the start of one row and + the next row for the destination address. + +The ``y_len``, ``src_stride`` and ``dst_stride`` fields are only useful for 2D +transfers and should be set to 0 if 2D transfers are not required. + +Transfer Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The scatter-gather transfers are enabled through the ``HWDESC`` bit from the +``CONTROL`` (``0x400``) register. Once this bit is set, cyclic transfers are +disabled, since the same cyclic behavior can be replicated using a descriptor +chain loop. + +To start a scatter-gather transfer, the address of the first DMA descriptor must +be written to the register pair [``SG_ADDRESS_HIGH`` (``0x4BC``), ``SG_ADDRESS`` +(``0x47C``)]. + +To end a scatter-gather transfer, the last descriptor of the transfer must have +the ``flags[0]`` bit set. + +The scatter-gather transfer is queued in a similar way to the simple transfers, +through the ``TRANSFER_SUBMIT``. Software should always poll this bit to be 0 +before setting it, otherwise the scatter-gather transfer will not be queued. + +The scatter-gather transfers support the generation of the same two types of +interrupt events as the simple transfers. However, the scatter-gather transfers +have the distinct advantage of generating fewer interrupts by treating the +chained descriptor transfers as a single transfer, thus improving the performance +of the application. + Transfer Start Synchronization ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -580,7 +696,7 @@ must hold: * ``MAX_BYTES_PER_BURST`` ≤ 4096; * ``MAX_BYTES_PER_BURST`` is power of 2; -* ``​SRC/​DEST_ADDRESS`` ​mod ``​MAX_BYTES_PER_BURST`` ​== 0 +* ``SRC/DEST_ADDRESS`` mod ``MAX_BYTES_PER_BURST`` == 0 * ``SRC/DEST_ADDRESS[11:0]`` + MIN(``X_LENGTH``\ +1,\ ``MAX_BYTES_PER_BURST``) ≤ 4096 Address Alignment @@ -617,6 +733,12 @@ bytes. Note that the address alignment requirement is not affected by this. The address still needs to be aligned to the width of the MM interface that it belongs to. +Scatter-Gather Datapath Width +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The scatter-gather dedicated interface ``m_sg_axi`` currently supports only +64-bit transfers. ``DMA_DATA_WIDTH_SG`` can only be set to 64. + Software Support -------------------------------------------------------------------------------- @@ -659,6 +781,6 @@ Glossary consecutive beats. * - partial transfer - Represents a transfer which is shorter than the programmed length that - is based on the X_LENGTH and Y_LENGTH registers. This can occur on AXIS - source interfaces when TLAST asserts earlier than the programmed + is based on the ``X_LENGTH`` and ``Y_LENGTH`` registers. This can occur + on AXIS source interfaces when TLAST asserts earlier than the programmed length. diff --git a/docs/regmap/adi_regmap_dmac.txt b/docs/regmap/adi_regmap_dmac.txt index b2263b955..b17b321a0 100644 --- a/docs/regmap/adi_regmap_dmac.txt +++ b/docs/regmap/adi_regmap_dmac.txt @@ -9,7 +9,7 @@ ENDTITLE REG 0x000 VERSION -Version of the peripheral. Follows semantic versioning. Current version 4.04.61. +Version of the peripheral. Follows semantic versioning. Current version 4.05.61. ENDREG FIELD @@ -19,7 +19,7 @@ RO ENDFIELD FIELD -[15:8] 0x03 +[15:8] 0x05 VERSION_MINOR RO ENDFIELD @@ -200,6 +200,15 @@ REG CONTROL ENDREG +FIELD +[2] 0x0 +HWDESC +RW +When set to 1 the scatter-gather transfers are enabled. + +Note, this field is only valid if the DMA channel has been configured with SG transfer support. +ENDFIELD + FIELD [1] 0x0 PAUSE @@ -242,7 +251,7 @@ TRANSFER_SUBMIT ENDREG FIELD -[0] 0x00 +[0] 0x0 TRANSFER_SUBMIT RW Writing a 1 to this register queues a new transfer. The bit transitions back to 0 once @@ -464,7 +473,7 @@ STATUS ENDREG FIELD -[31:0] 0x00 +[31:0] 0x00000000 RESERVED RO This register is reserved for future usage. Reading it will always return 0. @@ -479,7 +488,7 @@ CURRENT_DEST_ADDRESS ENDREG FIELD -[31:0] 0x00 +[31:0] 0x00000000 CURRENT_DEST_ADDRESS RO Address to which the next data sample is written to. @@ -496,7 +505,7 @@ CURRENT_SRC_ADDRESS ENDREG FIELD -[31:0] 0x00 +[31:0] 0x00000000 CURRENT_SRC_ADDRESS RO Address form which the next data sample is read. @@ -530,7 +539,7 @@ PARTIAL_TRANSFER_LENGTH ENDREG FIELD -[31:0] 0x000000 +[31:0] 0x00000000 PARTIAL_LENGTH RO Length of the partial transfer in bytes. Represents the number of bytes received @@ -558,6 +567,41 @@ ENDFIELD ############################################################################################ ############################################################################################ +REG +0x115 +DESCRIPTOR_ID +ENDREG + +FIELD +[31:0] 0x00000000 +DESCRIPTOR_ID +RO +ID of the descriptor that points to the current memory segment being transferred. +If HWDESC is set to 0, then this register returns 0. + +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x11f +SG_ADDRESS +ENDREG + +FIELD +[31:0] 0x00000000 +SG_ADDRESS +RW +This register contains the starting address of the scatter-gather transfer. The address needs +to be aligned to the bus width. + +This register is only valid if the DMA channel has been configured with SG transfer support. +ENDFIELD + +############################################################################################ +############################################################################################ + REG 0x124 DEST_ADDRESS_HIGH @@ -569,7 +613,8 @@ DEST_ADDRESS_HIGH RW This register contains the HIGH segment of the destination address of the transfer. -This register is only valid if the DMA_AXI_ADDR_WIDTH is bigger than 32 and if DMA channel has been configured for write to memory support. +This register is only valid if the DMA_AXI_ADDR_WIDTH is bigger than 32 and if DMA channel +has been configured for write to memory support. ENDFIELD ############################################################################################ @@ -586,7 +631,8 @@ SRC_ADDRESS_HIGH RW This register contains the HIGH segment of the source address of the transfer. -This register is only valid if the DMA_AXI_ADDR_WIDTH is bigger than 32 and if the DMA channel has been configured for read from memory support. +This register is only valid if the DMA_AXI_ADDR_WIDTH is bigger than 32 and if the DMA channel +has been configured for read from memory support. ENDFIELD ############################################################################################ @@ -598,12 +644,13 @@ CURRENT_DEST_ADDRESS_HIGH ENDREG FIELD -[31:0] 0x00 +[31:0] 0x00000000 CURRENT_DEST_ADDRESS_HIGH RO HIGH segment of the address to which the next data sample is written to. -This register is only valid if the DMA_AXI_ADDR_WIDTH is bigger than 32 and if the DMA channel has been configured for write to memory support. +This register is only valid if the DMA_AXI_ADDR_WIDTH is bigger than 32 and if the DMA channel +has been configured for write to memory support. ENDFIELD ############################################################################################ @@ -615,12 +662,31 @@ CURRENT_SRC_ADDRESS_HIGH ENDREG FIELD -[31:0] 0x00 +[31:0] 0x00000000 CURRENT_SRC_ADDRESS_HIGH RO HIGH segment of the address from which the next data sample is read. -This register is only valid if the DMA_AXI_ADDR_WIDTH is bigger than 32 and if the DMA channel has been configured for read from memory support. +This register is only valid if the DMA_AXI_ADDR_WIDTH is bigger than 32 and if the DMA channel +has been configured for read from memory support. +ENDFIELD + +############################################################################################ +############################################################################################ + +REG +0x12f +SG_ADDRESS_HIGH +ENDREG + +FIELD +[31:0] 0x00000000 +SG_ADDRESS_HIGH +RW +HIGH segment of the starting address of the scatter-gather transfer. + +This register is only valid if the DMA_AXI_ADDR_WIDTH is bigger than 32 and if the DMA channel +has been configured with SG transfer support. ENDFIELD ############################################################################################