<h1>axivdma v5_0</h1><p>This is the Xilinx MVI AXI Video DMA device driver. The DMA engine transfers frames from the AXI Bus or to the AXI Bus. It is in the chain of video IPs, which process video frames.</p>
<li>Continuous transfers of video frames, AKA circular buffer mode</li>
<li>Continuous transfers of one specific video frame, AKA park mode</li>
<li>Optionally only transfer a certain amount of video frames</li>
<li>Optionally transfer unaligned frame buffers</li>
</ul>
<p>An AXI Video DMA engine can have one or two channels. If configured as two channels, then one of the channels reads data from memory, and the other channel writes to the memory.</p>
<p>For a full description of AXI Video DMA features, please see the hardware spec.</p>
<p>The driver composes of three parts: initialization, start a DMA transfer, and interrupt handling.</p>
<p><b> Driver Initialization </b></p>
<p>To initialize the driver, the caller needs to pass a configuration structure to the driver. This configuration structure contains information about the hardware build.</p>
<p>A caller can manually setup the configuration structure, or call XAxiVdma_LoopkupConfig().</p>
<p>The sequence of initialization of the driver is: 1. <aclass="el"href="xaxivdma_8h.html#ac1056bf89d30ac044aca72de431c6a3f">XAxiVdma_LookupConfig()</a> to get the configuration structure, or manually setup the structure. 2. <aclass="el"href="xaxivdma_8c.html#a8d11c9609cf957c560fb287af1433374">XAxiVdma_CfgInitialize()</a> to initialize the driver & device. 3. <aclass="el"href="xaxivdma_8c.html#af331929e09bf1454dc2835b6ecc4ff30">XAxiVdma_SetFrmStore()</a> to set the desired frame store number which is optional. 4. If interrupt is desired:</p>
<li>Set frame counter using <aclass="el"href="xaxivdma_8c.html#aabe404c2a5c1483bc95be749c7540ba4">XAxiVdma_SetFrameCounter()</a></li>
<li>Set call back functions for each channel. There are two types of call backfunctions: general and error</li>
<li>Enable interrupts that the user cares about</li>
</ul>
<p><b>Start a DMA Transaction </b></p>
<p>If you are using the driver API to start the transfer, then there are two ways to start a DMA transaction:</p>
<p>1. Invoke <aclass="el"href="xaxivdma_8c.html#a1dc126d885558e03cf06a4d9c05d5668">XAxiVdma_StartWriteFrame()</a> or <aclass="el"href="xaxivdma_8c.html#ab2646b6aeea2ff64c4b42319ffb49804">XAxiVdma_StartReadFrame()</a> to start a DMA operation, depending on the purpose of the transfer (Read or Write).</p>
<p>2. Or, call the phased functions as the following:</p>
<li>Do any processing or setting, but do not start the hardware, means do not set the RUN/STOP bit in the XAXIVDMA_CR_OFFSET register.</li>
<li>After any reset you need to do, write the head of your BD ring into the XAXIVDMA_CDESC_OFFSET register.</li>
<li>You can do other setup for the harware.</li>
<li>Start your hardware, by setting up the RUN/STOP bit in the XAXIVDMA_CR_OFFSET register.</li>
<li>You can do other setup for the hardware.</li>
<li>If you are done with all the setup, now write the tail of your BD ring to the XAXIVDMA_TDESC_OFFSET register to start the transfer.</li>
</ul>
<p>You can refer to <aclass="el"href="xaxivdma__channel_8c.html#a3b9c24a02c4b4f99d40820a647de811d">XAxiVdma_ChannelStartTransfer()</a> to see how this order is preserved there. The function is in <aclass="el"href="xaxivdma__channel_8c.html">xaxivdma_channel.c</a>.</p>
<p>Note a Read VDMA could work with one out of multiple write VDMA instances and vice versa. The PointNum in structure <aclass="el"href="struct_x_axi_vdma___dma_setup.html">XAxiVdma_DmaSetup</a> decides which VDMA instance this VDMA is working with.</p>
<p><b>Interrupt Handling </b></p>
<p>Each VDMA channel supports 2 kinds of interrupts:</p>
<ul>
<li>General Interrupt: An interrupt other than error interrupt.</li>
<li>Error Interrupt: An error just happened.</li>
</ul>
<p>The driver does the interrupt handling, and dispatch to the user application through callback functions that user has registered. If there are no registered callback functions, then a stub callback function is called.</p>
<p>Each channel has two interrupt callback functions. One for IOC and delay interrupt, or general interrupt; one for error interrupt.</p>
<p><b>Reset</b></p>
<p>Reset a DMA channel causes the channel enter the following state:</p>
<ul>
<li>Interrupts are disabled</li>
<li>Coalescing threshold is one</li>
<li>Delay counter is 0</li>
<li>RUN/STOP bit low</li>
<li>Halted bit high</li>
<li>XAXIVDMA_CDESC_OFFSET register has 0</li>
<li>XAXIVDMA_TDESC_OFFSET register has 0</li>
</ul>
<p>If there is an active transfer going on when reset (or stop) is issued to the hardware, the current transfer will gracefully finish. For a maximum transfer length of (0x1FFF * 0xFFFF) bytes, on a 100 MHz system, it can take as long as 1.34 seconds, assuming that the system responds to DMA engine's requests quickly.</p>
<p>To ensure that the hardware finishes the reset, please use <aclass="el"href="xaxivdma_8c.html#a3e01bd69f101126d5962f7078ee3e520">XAxiVdma_ResetNotDone()</a> to check for completion of the reset.</p>
<p>To start a transfer after a reset, the following actions are the minimal requirement before setting RUN/STOP bit high to avoid crashing the system:</p>
<ul>
<li>XAXIVDMA_CDESC_OFFSET register has a valid BD pointer, it should be the head of the BD ring.</li>
<li>XAXIVDMA_TDESC_OFFSET register has a valid BD pointer, it should be the tail of the BD ring.</li>
</ul>
<p>If you are using the driver API to start a transfer after a reset, then it should be fine.</p>
<p><b>Stop</b></p>
<p>Stop a channel using XAxiVDma_DmaStop() is similar to a reset, except the registers are kept intact.</p>
<p>To start a transfer after a stop:</p>
<ul>
<li>If there are error bits in the status register, then a reset is necessary. Please refer to the <b>Reset</b> section for more details on how to start a transfer after a reset.</li>
<li>If there are no error bits in the status register, then you can call <aclass="el"href="xaxivdma_8c.html#adf310ae3bd4c0ae9ebf3e445a2fbe444">XAxiVdma_DmaStart()</a> to start the transfer again. Note that the transfer always starts from the first video frame.</li>
</ul>
<p><b> Examples</b></p>
<p>We provide one example on how to use the AXI VDMA with AXI Video IPs. This example does not work by itself. To make it work, you must have two other Video IPs to connect to the VDMA. One of the Video IP does the write and the other does the read.</p>
<p><b>Cache Coherency</b></p>
<p>This driver does not handle any cache coherency for the data buffers. The application is responsible for handling cache coherency, if the cache is enabled.</p>
<p><b>Alignment</b></p>
<p>The VDMA supports any buffer alignment when DRE is enabled in the hardware configuration. It only supports word-aligned buffers otherwise. Note that "word" is defined by C_M_AXIS_MM2S_TDATA_WIDTH and C_S_AXIS_S2MM_TDATA_WIDTH for the read and write channel specifically.</p>
<p>If the horizonal frame size is not word-aligned, then DRE must be enabled in the hardware. Otherwise, undefined results happen.</p>
<p><b>Address Translation</b></p>
<p>Buffer addresses for transfers are physical addresses. If the system does not use MMU, then physical and virtual addresses are the same.</p>
<p><b>API Change from PLB Video DMA</b></p>
<p>We try to keep the API as consistent with the PLB Video DMA driver as possible. However, due to hardware differences, some of the PLB video DMA driver APIs are changed or removed. Two API functions are added to the AXI DMA driver.</p>
<p>For details on the API changes, please refer to <aclass="el"href="xaxivdma__porting__guide_8h.html">xaxivdma_porting_guide.h</a>.</p>
<li>Modified structures <aclass="el"href="struct_x_axi_vdma___config.html">XAxiVdma_Config</a> and <aclass="el"href="struct_x_axi_vdma.html">XAxiVdma</a> to
