ZYNQ Userspace DMA: ZU_DMA

ZYNQ Userspace DMA (ZU_DMA for brevity) is a userspace DMA implementation to manage AXI DMA and transmit data to/from custom designs on ZYNQ FPGAs.

Getting Started

To get started and use ZU_DMA, you should first clone the udmabuf repository as a submodule to build the kernel driver

git submodule update --init --recursive

then move into the udmabuf directory and build udmabuf

cd udmabuf
make
cd ..

Finally, move into the lib_dmabuf directory to generate the static library (libdmabuf.a)

cd lib_dmabuf
make

or the dynamic library (libdmabuf.so)

make dynamic

Prerequisites and assumptions

We developed and tested ZU_DMA in the following environment:

PYNQ platform v2.1, with Ubuntu 16.04 LTS
gcc 5.3.1, available within PYNQ platform v2.1
make, also available within PYNQ platform v2.1
Doxygen for generating the documentation

ZU_DMA depends on udmabuf for getting userspace memory-coherent buffers for DMA transmission.

NOTE: ZU_DMA makes little assumptions on the underlying hardware and software (basically: Linux+Xilinx SoC+Xilinx DMA IP), therefore we are confident it can work on other platforms like Zedboard. Testers are welcome!

Running the tests

ZU_DMA comes with pre-defined tests for the PYNQ platform to check that things work out correctly. If you want to build all tests at once, then run

cd tests/host_src
make

Two examples of how to run single tests are shown in the following. More details are available in tests details.

DMA Passthrough

The DMA Passthrough test consists in a simple AXI Data FIFO connected to a single DMA, which just returns the data it receives. To run the passthrough test, first build it

cd tests/host_src
make test_passthrough

then flash the bitstream (the provided bitstreams are for PYNQ platform only!); here, we use the /dev/xdevcfg device to flash, which needs root permission

cd ..
sudo su
cat pynq_test_bitstreams/pynq_test_passthrough.bit > /dev/xdevcfg

and finally run the test (as sudo, since it requires inserting the udmabuf module)

cd host_src
./test_passthrough

2D Vector Sum

The 2D Vector Sum test consists in a custom HLS kernel that takes in input:

2 integer vectors V1 and V2 (as separate DMA streams) of equal length
the number of elements inside a vector
three constants a, b and c

and returns the vector sum V3 = a * V1 + b + V2 + c as output DMA stream.

This kernel has two DMA IPs and a custom AXI control interface to control its running status and to pass inputs, which is also controlled via host software. The steps to run it are similar to the previous test: first build it

cd tests/host_src
make test_2d_vec_sum

then flash the bitstream

cd ..
sudo su
cat pynq_test_bitstreams/pynq_test_2d_vec_sum.bit > /dev/xdevcfg

and finally run it

cd host_src
./test_2d_vec_sum

Authors

Alberto Scolari - Initial work

More authors are welcome!

License

This project is licensed under the Apache V2 License - see the LICENSE file for details

necst / zynq_userspace_dma