docs: axi_dmac: Add framelock and autorun

Signed-off-by: Jorge Marques <[email protected]>

docs/library/axi_dmac/index.rst

@@ -25,6 +25,8 @@ Features
 - Cyclic transfers
 - 2D transfers
 - Scatter-Gather transfers
+- Framelock
+- AutoRun
 
 Utilization
 --------------------------------------------------------------------------------
@@ -481,6 +483,17 @@ from the internal buffer will be cleared/lost. In case of AXIS the DMAC will
 wait for data to be accepted if valid is high since it can't just de-assert
 valid without breaking the interface semantics
 
+AutoRun mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When the ``AUTORUN`` parameter is set the DMAC can initiate transfers without
+software intervention. Once the core comes out of reset, the core will operate
+on a transfer defined through the ``DMAC_DEF_*`` synthesis parameters.
+This is useful mostly in ``CYCLIC`` mode. In non cyclic mode, once the initial
+transfer is done the core will go to idle state and will wait for software
+interaction if that exists. In this mode the s_axi AXI configuration interface
+is optional.
+
 .. _axi_dmac interrupts:
 
 Interrupts
@@ -655,6 +668,42 @@ 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.
 
+External Synchronization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This feature allows external components to throttle the consumption of
+descriptors queued by the software. A transfer will start only after the
+assertion of the external sync signal for at least one clock cycle.
+
+The sync signal can be either in source or destination clock domain or both.
+This feature does not ensures fixed latency from the assertion of external sync
+signal and the availability of the data at the destination interface.
+
+Framelock Synchronization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This feature adds support for multiple 2D frame buffers which are used in a
+cyclic way. On the same set of buffers a second DMAC core can operate.
+The "Framelock" mechanism ensures no buffer is accessed by two DMACs in the same time.
+
+The core can operate in two modes:
+
+* Writer mode - available in s2mm configuration, the writer DMAC will always
+  skip the current in use readers buffer.
+* Reader mode - available in mm2s configuration, the reader DMAC will stay
+  behind the writers buffer by either repeating or skipping buffers according to
+  the speed relationship of the two cores.
+
+The writer and reader DMAC cores must be connected through the dedicated
+"framelock" interface. They must be programmed with similar settings regarding
+the buffers size, start address and stride through the ``FRAMELOCK_CONFIG`` and
+``FRAMELOCK_STRIDE`` registers.
+
+Notice that the reader DMA will start to read the frames only after the writer
+finished to store in the DDR at least ``FRAMELOCK_CONFIG_DISTANCE+1`` frames.
+This means that while the FRAMLOCK_CONFIG_DISTANCE+1 frames are written into the
+memory the reader DMA won’t output anything.
+
 Transfer Start Synchronization
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/regmap/adi_regmap_dmac.txt

@@ -84,31 +84,31 @@ INTERFACE_DESCRIPTION_1
 ENDREG
 
 FIELD
-[3:0] log2(''DMA_DATA_WIDTH_DEST''/8)
-BYTES_PER_BEAT_DEST_LOG2
+[31:27] ''MAX_NUM_FRAMES''
+MAX_NUM_FRAMES
 R
-Width of data bus on destination interface. Log2 of interface data widths in bytes.
+Max number of frames.
 ENDFIELD
 
 FIELD
-[5:4] ''DMA_TYPE_DEST''
-DMA_TYPE_DEST
+[26] ''DMA_2D_TLAST_MODE''
+DMA_2D_TLAST_MODE
 R
-Value of ''DMA_TYPE_DEST'' parameter.(0 - AXI MemoryMap, 1 -  AXI Stream, 2 - FIFO )
+TLAST behaviour for 2D transfer (0 - End of Frame; 1 - End of Line).
 ENDFIELD
 
 FIELD
-[11:8] log2(''DMA_DATA_WIDTH_SRC''/8)
-BYTES_PER_BEAT_SRC_LOG2
+[25] ''USE_EXT_SYNC''
+USE_EXT_SYNC
 R
-Width of data bus on source interface. Log2 of interface data widths in bytes.
+Use external sync.
 ENDFIELD
 
 FIELD
-[13:12] ''DMA_TYPE_SRC''
-DMA_TYPE_SRC
+[24] ''AUTORUN''
+AUTORUN
 R
-Value of ''DMA_TYPE_SRC'' parameter.(0 - AXI MemoryMap, 1 -  AXI Stream, 2 - FIFO )
+Run in the AUTORUN_* configuration.
 ENDFIELD
 
 FIELD
@@ -120,6 +120,34 @@ The starting address of the transfer must be aligned with ''MAX_BYTES_PER_BURST'
 the 4kB address boundary.
 ENDFIELD
 
+FIELD
+[13:12] ''DMA_TYPE_SRC''
+DMA_TYPE_SRC
+R
+Value of ''DMA_TYPE_SRC'' parameter.(0 - AXI MemoryMap, 1 -  AXI Stream, 2 - FIFO )
+ENDFIELD
+
+FIELD
+[11:8] log2(''DMA_DATA_WIDTH_SRC''/8)
+BYTES_PER_BEAT_SRC_LOG2
+R
+Width of data bus on source interface. Log2 of interface data widths in bytes.
+ENDFIELD
+
+FIELD
+[5:4] ''DMA_TYPE_DEST''
+DMA_TYPE_DEST
+R
+Value of ''DMA_TYPE_DEST'' parameter.(0 - AXI MemoryMap, 1 -  AXI Stream, 2 - FIFO )
+ENDFIELD
+
+FIELD
+[3:0] log2(''DMA_DATA_WIDTH_DEST''/8)
+BYTES_PER_BEAT_DEST_LOG2
+R
+Width of data bus on destination interface. Log2 of interface data widths in bytes.
+ENDFIELD
+
 ############################################################################################
 ############################################################################################
 
@@ -132,7 +160,7 @@ FIELD
 [0] ''CACHE_COHERENT''
 CACHE_COHERENT
 R
-Value of ''CACHE_COHERENT'' parameter.(0 - Disabled, 1 -  Enabled )
+Value of ''CACHE_COHERENT'' parameter. (0 - Disabled, 1 -  Enabled)
 ENDFIELD
 
 FIELD
@@ -193,7 +221,7 @@ FIELD
 TRANSFER_QUEUED
 RW1C
 This bit will be asserted if a transfer has been queued and it is possible to queue
-the next transfer. It can be masked out by setting the TRANSFER_QUEUED bit in the 
+the next transfer. It can be masked out by setting the TRANSFER_QUEUED bit in the
 IRQ_MASK register.
 ENDFIELD
 
@@ -298,29 +326,43 @@ FLAGS
 ENDREG
 
 FIELD
-[0] ''CYCLIC''
-CYCLIC
+[3] ''AUTORUN_FLAGS[3]''
+FRAMELOCK
 RW
-Setting this field to 1 puts the DMA transfer into cyclic mode. In cyclic mode
-the controller will re-start a transfer again once it has finished. In cyclic
-mode no end-of-transfer interrupts will be generated.
+Setting this field to 1 puts the DMA transfer into framelock mode.
+In framelock mode the data is hold to compensate frames rates mismatch between source and
+sink channels.
+Parameter ``FRAMELOCK`` must 1 to writing to this register to have an effect.
+If ``AUTORUN`` is unset, the default value of the field is 0x0.
 ENDFIELD
 
 FIELD
-[1] 0x00000001
+[2] ''AUTORUN_FLAGS[2]''
+PARTIAL_REPORTING_EN
+RW
+When setting this bit the length of partial transfers caused eventually by TLAST will be recorded.
+If ``AUTORUN`` is unset, the default value of the field is 0x0.
+ENDFIELD
+
+FIELD
+[1] ''AUTORUN_FLAGS[1]''
 TLAST
 RW
 When setting this bit for a MM to AXIS transfer the TLAST signal
 will be asserted during the last beat of the transfer.
 For AXIS to MM transfers the TLAST signal from the AXIS interface is monitored.
 After its occurrence all descriptors are ignored until this bit is set.
+If ``AUTORUN`` is unset, the default value of the field is 0x1.
 ENDFIELD
 
 FIELD
-[2] 0x00000000
-PARTIAL_REPORTING_EN
+[0] ''AUTORUN_FLAGS[0]''
+CYCLIC
 RW
-When setting this bit the length of partial transfers caused eventually by TLAST will be recorded.
+Setting this field to 1 puts the DMA transfer into cyclic mode. In cyclic mode
+the controller will re-start a transfer again once it has finished. In cyclic
+mode no end-of-transfer interrupts will be generated.
+If ``AUTORUN`` is unset, the default value of the field is ''CYCLIC''.
 ENDFIELD
 
 ############################################################################################
@@ -332,12 +374,13 @@ DEST_ADDRESS
 ENDREG
 
 FIELD
-[31:0] 0x00000000
+[31:0] ''AUTORUN_DEST_ADDR''
 DEST_ADDRESS
 RW
 This register contains the destination address of the transfer. The address needs to be aligned
 to the bus width.
 
+If ``AUTORUN`` is unset, the default value of the field is 0x00000000.
 This register is only valid if the DMA channel has been configured for write to memory support.
 ENDFIELD
 
@@ -350,12 +393,13 @@ SRC_ADDRESS
 ENDREG
 
 FIELD
-[31:0] 0x00000000
+[31:0] ''AUTORUN_SRC_ADDR''
 SRC_ADDRESS
 RW
 This register contains the source address of the transfer. The address needs to be aligned
 to the bus width.
 
+If ``AUTORUN`` is unset, the default value of the field is 0x00000000.
 This register is only valid if the DMA channel has been configured for read from memory support.
 ENDFIELD
 
@@ -372,6 +416,7 @@ FIELD
 X_LENGTH
 RW
 Number of bytes to transfer - 1.
+If ``AUTORUN`` is set, the default value of the field is ''AUTORUN_FRAMELOCK_X_LENGTH''.
 ENDFIELD
 
 ############################################################################################
@@ -383,10 +428,11 @@ Y_LENGTH
 ENDREG
 
 FIELD
-[31:0] 0x00000000
+[31:0] ''AUTORUN_FRAMELOCK_Y_LENGTH''
 Y_LENGTH
 RW
 Number of rows to transfer - 1.
+If ``AUTORUN`` is unset, the default value of the field is 0x00000000.
 
 Note, this field is only valid if the DMA channel has been configured with 2D transfer support.
 ENDFIELD
@@ -400,12 +446,13 @@ DEST_STRIDE
 ENDREG
 
 FIELD
-[31:0] 0x00000000
+[31:0] ''AUTORUN_DEST_STRIDE''
 DEST_STRIDE
 RW
 The number of bytes between the start of one row and the next row for the
 destination address. Needs to be aligned to the bus width.
 
+If ``AUTORUN`` is unset, the default value of the field is 0x00000000.
 Note, this field is only valid if the DMA channel has been configured with 2D
 transfer support and write to memory support.
 ENDFIELD
@@ -419,12 +466,13 @@ SRC_STRIDE
 ENDREG
 
 FIELD
-[31:0] 0x00000000
+[31:0] ''AUTORUN_SRC_STRIDE''
 SRC_STRIDE
 RW
 The number of bytes between the start of one row and the next row for the source
 address. Needs to be aligned to the bus width.
 
+If ``AUTORUN`` is unset, the default value of the field is 0x00000000.
 Note, this field is only valid if the DMA channel has been configured with 2D
 transfer and read from memory support.
 ENDFIELD
@@ -611,6 +659,71 @@ ENDFIELD
 ############################################################################################
 ############################################################################################
 
+REG
+0x116
+FRAMELOCK_CONFIG
+Configure the Framelock feature.
+If ``AUTORUN`` is unset, the default value of all fields are 0x00000000.
+ENDREG
+
+FIELD
+[23:16] ''AUTORUN_FRAMELOCK_CONFIG[23:16]''
+DISTANCE
+RW
+Applicable only in output delay mode. Set the output delay in frames.
+Should be set in interval 0 to flock, FRAMENUM - 2.
+ENDFIELD
+
+FIELD
+[9] ''AUTORUN_FRAMELOCK_CONFIG[9]''
+WAIT_WRITER
+RW
+If WAIT_WRITER is unset, enable the generation of new request right away.
+In Simple Flock when WAIT_WRITER is set, the reader must wait until the writer completes a
+buffer. In Dynamic Flock just wait until the required number of buffers are filled, then
+enable the request generation regardless of the writer.
+ENDFIELD
+
+FIELD
+[8] ''AUTORUN_FRAMELOCK_CONFIG[8]''
+MODE
+RW
+Select operating mode of the framebuffer.
+(0 - Frame rate conversion mode (dynamic), 1 - Output delay mode (simple))
+ENDFIELD
+
+FIELD
+[7:0] ''AUTORUN_FRAMELOCK_CONFIG[7:0]''
+FRAMENUM
+RW
+The total number of video frame buffers.
+Related to MAX_NUM_FRAMES synthesis parameter.
+ENDFIELD
+
+############################################################################################
+############################################################################################
+
+REG
+0x117
+FRAMELOCK_STRIDE
+Configure the Framelock feature.
+ENDREG
+
+FIELD
+[31:0] ''AUTORUN_FRAMELOCK_STRIDE''
+STRIDE
+RW
+The number of bytes between the start of one row and the next row for the
+framelock.
+
+If ``AUTORUN`` is unset, the default value of the field is 0x00000000.
+Note, this field is only valid if the DMA channel has been configured with 2D
+transfer support, framelock support, and write to memory support.
+ENDFIELD
+
+############################################################################################
+############################################################################################
+
 REG
 0x11f
 SG_ADDRESS