Using the AXI DMA in Vivado

In a previous tutorial I went through how to use the AXI DMA Engine in EDK, now I’ll show you how to use the AXI DMA in Vivado. We’ll create the hardware design in Vivado, then write a software application in the Xilinx SDK and test it on the MicroZed board (source code is shared on Github for the MicroZed and the ZedBoard, see links at the bottom).

What is DMA?

DMA stands for Direct Memory Access and a DMA engine allows you to transfer data from one part of your system to another. The simplest usage of a DMA would be to transfer data from one part of the memory to another, however a DMA engine can be used to transfer data from any data producer (eg. an ADC) to a memory, or from a memory to any data consumer (eg. a DAC).

Tutorial overview

In this design, we’ll use the DMA to transfer data from memory to an IP block and back to the memory. In principle, the IP block could be any kind of data producer/consumer such as an ADC/DAC FMC, but in this tutorial we will use a simple FIFO to create a loopback. After, you’ll be able to break the loop and insert whatever custom IP you like.

Image may be NSFW.
Clik here to view.The block diagram above illustrates the design that we’ll create. The processor and DDR memory controller are contained within the Zynq PS. The AXI DMA and AXI Data FIFO are implemented in the Zynq PL. The AXI-lite bus allows the processor to communicate with the AXI DMA to setup, initiate and monitor data transfers. The AXI_MM2S and AXI_S2MM are memory-mapped AXI4 buses and provide the DMA access to the DDR memory. The AXIS_MM2S and AXIS_S2MM are AXI4-streaming buses, which source and sink a continuous stream of data, without addresses.

Notes:

• MM2S stands for Memory-Mapped to Streaming, whereas S2MM stands for Streaming to Memory-Mapped.
• When Scatter-Gather is used, there is an extra AXI bus between the DMA and the memory controller. It was left out of the diagram for simplicity.

Requirements

Before following this tutorial, you will need to do the following:

• Vivado 2014.2
• MicroZed
• Platform Cable USB II (or equivalent JTAG programmer)

 Start from the base project

We’ll start this tutorial with the base system project for the MicroZed that you can access here:

Base system project for the MicroZed

Add the AXI DMA

1. Open the base project in Vivado.
2. In the Flow Navigator, click ‘Open Block Design’.Image may be NSFW.
   Clik here to view.
3. The block diagram should open and you should only have the Zynq PS in the design.
4. Click the ‘Add IP’ icon and double click ‘AXI Direct Memory Access’ from the catalog.Image may be NSFW.
   Clik here to view.

Connect the Memory-mapped AXI buses

1. The DMA block should appear and designer assistance should be available. Click the ‘Run Connection Automation’ link and select ‘/axi_dma_0/S_AXI_LITE’ from the drop-down menu.Image may be NSFW.
   Clik here to view.
2. Click ‘OK’ in the window that appears. Vivado will connect the AXI-lite bus of the DMA to the General Purpose AXI Interconnect of the PS.Image may be NSFW.
   Clik here to view.
3. Your block diagram should now look like this :Image may be NSFW.
   Clik here to view.
4. Now we need to connect AXI buses M_AXI_SG, M_AXI_MM2S and M_AXI_S2MM of the DMA to a high performance AXI slave interface on the PS. Our PS doesn’t seem to have a high-performance AXI slave interface, so we need to change the Zynq configuration to enable one. Double click on the Zynq block.Image may be NSFW.
   Clik here to view.
5. Select ‘PS-PL Configuration’, open the ‘HP Slave AXI Interface’ branch and tick the ‘S AXI HP0 interface’ to enable it. Then click OK.Image may be NSFW.
   Clik here to view.
6. The high-performance AXI slave ports should now be visible in the block diagram, and designer assistance should be available. Click the ‘Run Connection Automation’ link and select ‘/processing_system7_0/S_AXI_HP0’ from the drop-down menu.Image may be NSFW.
   Clik here to view.
7. In the window that appears, make sure that Vivado intends to connect it to the DMA and click OK.Image may be NSFW.
   Clik here to view.
8. Designer assistance should again be available, click the ‘Run Connection Automation’ link and select ‘/axi_dma_0/M_AXI_SG’ from the drop-down menu.Image may be NSFW.
   Clik here to view.
9. In the window that appears, click OK.Image may be NSFW.
   Clik here to view.
10. Designer assistance should still be available, click the ‘Run Connection Automation’ link and select ‘/axi_dma_0/M_AXI_S2MM’ from the drop-down menu.Image may be NSFW.
    Clik here to view.
11. In the window that appears, click OK.Image may be NSFW.
    Clik here to view.

Now all the memory-mapped AXI buses are connected to the DMA. Now we only have to connect the AXI streaming buses to our loopback FIFO and connect the DMA interrupts.

Add the FIFO

1. Click the ‘Add IP’ icon and double click ‘AXI4-Stream Data FIFO’ from the catalog.Image may be NSFW.
   Clik here to view.
2. The FIFO should be visible in the block diagram. Now we must connect the AXI-streaming buses to those of the DMA. Click the ‘S_AXIS’ port on the FIFO and connect it to the ‘M_AXIS_MM2S’ port of the DMA.Image may be NSFW.
   Clik here to view.
3. Then connect the ‘M_AXIS’ port on the FIFO and connect it to the ‘S_AXIS_S2MM’ port of the DMA.Image may be NSFW.
   Clik here to view.
4. Now we must connect the FIFO clock and reset. Click the ‘s_axis_aresetn’ port of the FIFO and connect it to the ‘axi_resetn’ port of the DMA.Image may be NSFW.
   Clik here to view.
5. Click the ‘s_axis_aclk’ port of the FIFO and connect it to the ‘s_axi_lite_aclk’ port of the DMA.Image may be NSFW.
   Clik here to view.

Remove the AXI-Streaming status and control ports of the DMA

In our design, we won’t need the AXI-Streaming status and control ports which are used to transmit extra information alongside the data stream. You might use them if you were connecting to the AXI Ethernet core or a custom IP that made use of them.

1. In the block diagram, double click the AXI DMA block.
2. Un-tick the ‘Enable Control / Status Stream’ option and click OK.Image may be NSFW.
   Clik here to view.

Connect the DMA interrupts to the PS

Our software application will test the DMA in polling mode, but to be able to use it in interrupt mode, we need to connect the interrupts ‘mm2s_introut’ and ‘s2mm_introut’ to the Zynq PS.

1. First we have to enable interrupts from the PL. Double click the Zynq block and select the Interrupts tab.Image may be NSFW.
   Clik here to view.
2. Tick ‘Fabric Interrupts’ and ‘IRQ_F2P[15 :0]’ to enable them, and click OK.
3. Click the ‘Add IP’ icon and double-click ‘Concat’ from the catalog.Image may be NSFW.
   Clik here to view.
4. Connect the ‘dout’ port of the Concat to the ‘IRQ_F2P’ port of the Zynq PS.Image may be NSFW.
   Clik here to view.
5. Connect the ‘mm2s_introut’ port of the DMA to the ‘In0’ port of the Concat.Image may be NSFW.
   Clik here to view.
6. Connect the ‘s2mm_introut’ port of the DMA to the ‘In1’ port of the Concat.Image may be NSFW.
   Clik here to view.

Validate and build the design

1. From the menu select Tools->Validate Design.Image may be NSFW.
   Clik here to view.
2. You should get this message saying that validation was successful.Image may be NSFW.
   Clik here to view.
3. We can clean up the block diagram by clicking the Regenerate Layout icon.Image may be NSFW.
   Clik here to view.
4. Our block diagram now looks like this :Image may be NSFW.
   Clik here to view.
5. In the Flow Navigator, click ‘Generate Bitstream’.Image may be NSFW.
   Clik here to view.

Export the hardware design to SDK

Once the bitstream has been generated, we can export our design to SDK where we can develop the software application that will setup a DMA transfer, wait for completion and then verify the loopback.

1. In Vivado, from the File menu, select “Export->Export hardware”.Image may be NSFW.
   Clik here to view.
2. In the window that appears, tick “Include bitstream” and click “OK”.Image may be NSFW.
   Clik here to view.
3. Again from the File menu, select “Launch SDK”.Image may be NSFW.
   Clik here to view.
4. In the window that appears, use the following settings and click “OK”.Image may be NSFW.
   Clik here to view.

At this point, the SDK loads and a hardware platform specification will be created for your design. You should be able to see the hardware specification in the Project Explorer of SDK as shown in the image below.

Image may be NSFW.
Clik here to view.

We are now ready to create the software application.

Create a Software application

At this point, your SDK window should look somewhat like this:

Image may be NSFW.
Clik here to view.

To make things easy for us, we’ll use the template for the hello world application and then modify it to test the AXI DMA.

1. From the File menu, select New->Application Project.Image may be NSFW.
   Clik here to view.
2. In the first page of the New Project wizard, choose a name for the application. I’ve chosen “hello_world”. Click “Next”.Image may be NSFW.
   Clik here to view.
3. On the templates page, select the “Hello World” template and click “Finish”.Image may be NSFW.
   Clik here to view.
4. The SDK will generate a new application which you should find in the Project Explorer as in the image below.Image may be NSFW.
   Clik here to view.

The “hello_world” folder contains the Hello World software application, which we will modify to test our AXI DMA.

Modify the Software Application

We need to modify the hello world software application to test our DMA.

1. From the Project Explorer, open the “hello_world/src” folder. Open the “helloworld.c” source file.
2. Replace all the code in this file with the code that you will find on Github here: https://github.com/fpgadeveloper/microzed-axi-dma/blob/master/SDK/hello_world/src/helloworld.c
3. Save and close the file. The application should build automatically.

C:\Xilinx\14.7\ISE_DS\EDK\sw\XilinxProcessorIPLib\drivers\axidma_v7_02_a\examples\xaxidma_example_sg_poll.c

Test the design on the hardware

To test the design, we are using the MicroZed board from Avnet. Make the following setup before continuing:

1. On the MicroZed, set the JP1, JP2 and JP3 jumpers all to the 1-2 position.Image may be NSFW.
   Clik here to view.
2. Connect the USB-UART (J2) to a USB port of your PC.
3. Connect a Platform Cable USB II programmer (or similar device) to the JTAG connector. Connect the programmer to a USB port of your PC.Image may be NSFW.
   Clik here to view.

Now you need to open up a terminal program on your PC and set it up to receive the test messages. I use Miniterm because I’m a Python fan, but you could use any other terminal program such as Putty. Use the following settings:

• Comport – check your device manager to find out what comport the MicroZed popped up as. In my case, it was COM12 as shown below.Image may be NSFW.
  Clik here to view.
• Baud rate: 115200bps
• Data: 8 bits
• Parity: None
• Stop bits: 1

Now that your PC is ready to receive the test messages, we are ready to send our bitstream and software application to the hardware.

1. In the SDK, from the menu, select Xilinx Tools->Program FPGA.Image may be NSFW.
   Clik here to view.
2. In the Program FPGA window, we select the hardware platform to program. We have only one hardware platform, so click “Program”.Image may be NSFW.
   Clik here to view.
3. The bitstream will be loaded onto the Zynq and we are ready to load the software application. Select the “hello_world” folder in the Project Explorer, then from the menu, select Run->Run.Image may be NSFW.
   Clik here to view.
4. In the Run As window, select “Launch on Hardware (GDB)” and click “OK”.Image may be NSFW.
   Clik here to view.
5. The application will be loaded on the Zynq PS and it will be executed. Look out for the results in your terminal window!Image may be NSFW.
   Clik here to view.

Source code

The TCL build script and source code for this project is shared on Github at the following links:

• For the MicroZed: https://github.com/fpgadeveloper/microzed-axi-dma
• For the ZedBoard: https://github.com/fpgadeveloper/zedboard-axi-dma

For instructions on rebuilding the project from sources, read my post on version control for Vivado projects.