docs: Include the DMA SG documentation

Signed-off-by: Ionut Podgoreanu <ionut.podgoreanu@analog.com>
main
Ionut Podgoreanu 2023-10-31 00:16:58 +02:00 committed by podgori
parent 2687bbc02e
commit b3c58abcdc
3 changed files with 241 additions and 30 deletions

View File

@ -1,4 +1,5 @@
<svg width="585" height="245" preserveAspectRatio="xMidYMid slice" version="1.1" viewBox="0 0 585 245" xmlns="http://www.w3.org/2000/svg">
<?xml version="1.0" encoding="UTF-8"?>
<svg width="585" height="250" preserveAspectRatio="xMidYMid slice" version="1.1" viewBox="0 0 585 250" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<defs>
<marker id="h" overflow="visible" orient="auto">
<path transform="scale(.4)" d="m5.77 0-8.65 5v-10z" fill-rule="evenodd" stroke="#000" stroke-width="1pt"/>
@ -58,9 +59,22 @@
<stop stop-color="#fce94f" offset="0"/>
<stop stop-color="#729fcf" offset="1"/>
</linearGradient>
<marker id="i-9" overflow="visible" orient="auto">
<path transform="scale(.4)" d="m5.77 0-8.65 5v-10z" fill-rule="evenodd" stroke="#000" stroke-width="1pt"/>
</marker>
<marker id="e-2" overflow="visible" orient="auto">
<path transform="scale(.4)" d="m5.77 0-8.65 5v-10z" fill-rule="evenodd" stroke="#000" stroke-width="1pt"/>
</marker>
<linearGradient id="linearGradient59824" x1="58.883" x2="77.454" y1="89.272" y2="89.272" gradientUnits="userSpaceOnUse">
<stop stop-color="#008080" offset="0"/>
<stop stop-color="#008080" stop-opacity="0" offset="1"/>
</linearGradient>
<marker id="a-0" overflow="visible" orient="auto">
<path transform="scale(-.2)" d="m5.77 0-8.65 5v-10z" fill-rule="evenodd" stroke="#000" stroke-width="1pt"/>
</marker>
</defs>
<g transform="matrix(4 0 0 4 -117.17 -304.15)">
<rect x="54.052" y="76.302" width="97.349" height="53.988" fill="#d3d7cf" fill-rule="evenodd" stroke="#000" stroke-width=".52917"/>
<g transform="matrix(4,0,0,4,-117.17,-304.15)">
<rect x="54.052" y="76.302" width="97.349" height="56.488" fill="#d3d7cf" fill-rule="evenodd" stroke="#000" stroke-width=".52917"/>
<rect x="120.14" y="118.32" width="28.324" height="8.6862" fill="#fcaf3e" fill-rule="evenodd" stroke="#000" stroke-width=".52917"/>
<g transform="translate(-.53474 -.4009)">
<rect x="88.624" y="82.623" width="28.999" height="12.428" fill="url(#o)" fill-rule="evenodd" stroke="#000" stroke-width=".52917"/>
@ -68,9 +82,9 @@
</g>
<g font-family="'Liberation Sans'" font-size="2.6458px" letter-spacing="0px" stroke-width=".26458px" word-spacing="0px">
<text x="126.37469" y="123.3473" style="line-height:125%" xml:space="preserve"><tspan x="126.37469" y="123.3473" stroke-width=".26458px">Register Map</tspan></text>
<text x="119.46967" y="135.42929" style="line-height:125%" xml:space="preserve"><tspan x="119.46967" y="135.42929" stroke-width=".26458px">S_AXI</tspan></text>
<text x="129.22504" y="135.49905" style="line-height:125%" xml:space="preserve"><tspan x="129.22504" y="135.49905" stroke-width=".26458px">s_axi_aclk</tspan></text>
<text x="144.32582" y="135.49905" style="line-height:125%" xml:space="preserve"><tspan x="144.32582" y="135.49905" stroke-width=".26458px">irq</tspan></text>
<text x="119.46967" y="138.00647" style="line-height:125%" xml:space="preserve"><tspan x="119.46967" y="138.00647" stroke-width=".26458px">S_AXI</tspan></text>
<text x="129.22504" y="137.99905" style="line-height:125%" xml:space="preserve"><tspan x="129.22504" y="137.99905" stroke-width=".26458px">s_axi_aclk</tspan></text>
<text x="144.32582" y="137.99905" style="line-height:125%" xml:space="preserve"><tspan x="144.32582" y="137.99905" stroke-width=".26458px">irq</tspan></text>
</g>
<g transform="translate(-2.3947 -.19646)">
<rect x="92.956" y="118.52" width="22.985" height="8.6862" fill="#ad7fa8" fill-rule="evenodd" stroke="#000" stroke-width=".52917"/>
@ -90,12 +104,14 @@
<path d="m117.73 88.436h7.0159" marker-end="url(#g)"/>
<path d="m146.6 91.838h7.0159" marker-end="url(#f)"/>
<path d="m49.178 92.405h7.0159" marker-end="url(#e)"/>
<path d="m49.178 126.67h7.0159" marker-end="url(#e-2)"/>
</g>
<path d="m122.86 128.82v3.1851" marker-end="url(#p)" marker-start="url(#r)" stroke-width=".79375"/>
<path d="m122.86 128.82v5.6851" marker-end="url(#p)" marker-start="url(#r)" stroke-width=".79375"/>
<g stroke-width=".79375">
<path d="m135.05 132.81v-4.154" marker-end="url(#c)" stroke-linecap="square"/>
<path d="m145.92 128.22v4.2876" marker-end="url(#b)" stroke-linecap="square"/>
<path d="m135.05 134.81v-6.154" marker-end="url(#c)" stroke-linecap="square"/>
<path d="m145.92 128.22v6.2876" marker-end="url(#b)" stroke-linecap="square"/>
<path d="m115.81 122.66h3.0711" marker-start="url(#a)"/>
<path d="m87.961 122.87h-9.0342" marker-start="url(#a-0)"/>
</g>
</g>
<text x="156.62027" y="89.125519" fill="#000000" font-family="'Liberation Sans'" font-size="2.6458px" letter-spacing="0px" stroke-width=".26458px" word-spacing="0px" style="line-height:125%" xml:space="preserve"><tspan x="156.62027" y="89.125519">AXI-MM /</tspan><tspan x="156.62027" y="92.432816">AXI-Streaming /</tspan><tspan x="156.62027" y="95.74012">FIFO</tspan></text>
@ -121,5 +137,12 @@
<text x="41.117294" y="85.428101" fill="#000000" font-family="'Liberation Sans'" font-size="2.6458px" letter-spacing="0px" stroke-width=".26458px" word-spacing="0px" style="line-height:125%" xml:space="preserve"><tspan x="41.117294" y="85.428101" stroke-width=".26458px">src_clk</tspan></text>
<path d="m155.32 84.042h-7.0159" fill="none" marker-end="url(#h)" stroke="#000" stroke-width=".52917"/>
<text x="155.82919" y="84.861137" fill="#000000" font-family="'Liberation Sans'" font-size="2.6458px" letter-spacing="0px" stroke-width=".26458px" word-spacing="0px" style="line-height:125%" xml:space="preserve"><tspan x="155.82919" y="84.861137" stroke-width=".26458px">dest_clk</tspan></text>
<g transform="translate(-.00024899 33.433)">
<rect x="59.148" y="80.92" width="18.041" height="16.704" fill="url(#linearGradient59824)" fill-rule="evenodd" stroke="#000" stroke-width=".52917"/>
<text transform="translate(.00024899 -33.433)" x="68.10511" y="120.30859" fill="#000000" font-family="'Liberation Sans'" font-size="2.6458px" letter-spacing="0px" stroke-width=".26458px" text-anchor="middle" word-spacing="0px" style="font-variant-caps:normal;font-variant-east-asian:normal;font-variant-ligatures:normal;font-variant-numeric:normal;line-height:125%" xml:space="preserve"><tspan x="68.10511" y="120.30859">Scatter-</tspan><tspan x="68.10511" y="123.61584">Gather</tspan><tspan x="68.10511" y="126.9231">Interface</tspan></text>
</g>
<path d="m49.947 118.89h7.0159" fill="none" marker-end="url(#i-9)" stroke="#000" stroke-width=".52917"/>
<text x="41.867359" y="119.68142" fill="#000000" font-family="'Liberation Sans'" font-size="2.6458px" letter-spacing="0px" stroke-width=".26458px" word-spacing="0px" style="line-height:125%" xml:space="preserve"><tspan x="41.867359" y="119.68142" stroke-width=".26458px">sg_clk</tspan></text>
<text x="38.796375" y="127.43142" fill="#000000" font-family="'Liberation Sans'" font-size="2.6458px" letter-spacing="0px" stroke-width=".26458px" word-spacing="0px" style="line-height:125%" xml:space="preserve"><tspan x="38.796375" y="127.43142">AXI-MM</tspan></text>
</g>
</svg>

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 14 KiB

View File

@ -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.

View File

@ -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
############################################################################################