A5E-DMA-Example¶

Overview¶

The DMA example works by demonstrating the following:

• The FPGA XorShift Data Generator generators a data pattern which is written into the HPS's DDR through the TX mSGDMA.
• The HPS verifies this data that is written to ensure that the expected data is received.
  • This demonstrates the data path from the FPGA to the HPS
• The HPS generates an xorshift data pattern which it writes into the HPS DDR
• The FPGA RX mSGMDA reads this data and passes it to the XorShift Data Checker to verify the expected data is received.
  • This demonstrates the data path from the HPS to the FPGA

┌──────────────────────────────┐         ┌────────────────────────┐
│  XorShift Data Generator     │         │       TX mSGDMA        │
│        (pattern source)      ├────────►│     (FPGA → HPS DDR)   │
└──────────────────────────────┘         └───────────┬────────────┘
                                                     │
                                                     │ AXI writes
                                                     ▼
        ┌────────────────────────────────────────────────────────┐
        │                          HPS DDR                       │
        │   (shared memory via FPGA–HPS interconnect bridge)     │
        └────────────────────────────────────────────────────────┘
                                                     │
                                                     │ AXI reads
                                                     ▼
┌──────────────────────────────┐         ┌───────────┴────────────┐
│  XorShift Data Checker       │◄────────┤       RX mSGDMA        │
│     (pattern verification)   │         │     (HPS DDR → FPGA)   │
└──────────────────────────────┘         └────────────────────────┘

Building the FPGA Design DMA Example¶

Compile the FPGA design¶

Refer to Building_fpga_253pro for building the FPGA design. Navigate into the mitysom-a5e-{mini}-ref-dma example project before compiling the design.

• Ensure to flash the resulting a5e.hps.jic onto the hardware
• Ensure to replace the a5e.core.rbf and boot.scr on the SD card

Generate the FPGA design headers¶

Still in the FPGA project directory, run the following to generate the header files that describe the FPGA design

make generate_headers

Compile the HPS software support¶

In order to compile the HPS software support, please download and install the toolchain and source this in your environment. The toolchain can be found along with the Prebuild SD card images or in the Files section of Redmine. Once installed, make sure to source the toolchain.

source /path/to/installed/toolchain/environment-setup-armv8-2a-mitysom-linux

Compile the Linux Kernel, DTS, and Modules¶

The Linux Kernel source is also needed to compile dts overlays and kernel modules. Also, since we are compiling a kernel module out of tree we need to compile the Linux kernel and install it onto the SD card so that the versions will match, therefore, checkout the Linux Kernel source and compile it. This can be done following the instructions found here: Linux_Kernel
Make sure to compile the kernel Image, dtbs and modules and install them onto the SD card following the instructions in the previous link

You can use the toolchain previously source to compile the kernel. Once the kernel is compiled, set the following environment variable to point to the source.

export KERNEL_SRC=/path/to/linux-socfpga

Compile the Kernel DTS Overlay¶

Navigate into the software/dma_example/kernel_dts directory of the FPGA project. Run the following to compile the dts overlay.

make

Copy the resulting dma_example.dtbo file into the /boot directory of the filesystem (ext partition) of the SD card

Compile the Kernel Module¶

Navigate into the software/dma_example/kernel_module directory of the FPGA project. Run the following to compile the kernel module.

make

Copy the resulting cl_msgdma.ko into the /root directory of the SD card (ext partition)

Compile the Userspace Application¶

Navigate into the software/dma_example/userspace? directory of the FPGA project. Run the following to compile the userspace application.

make

Copy the resulting dma_example binary into the /root directory of the SD card (ext partition)

Running the DMA Example¶

Boot into Linux¶

Boot the modified SD card and login at the Linux prompt (User: root)

Load the custom kernel module¶

insmod cl_msgdma.ko

Successful load should look like the following:

root@mity-a5e:~# insmod cl_msgdma.ko
[  180.513657] cl_msgdma: loading out-of-tree module taints kernel.
[  180.521379] cl-msgdma write_cl_msgdma: registered /dev/cl_msgdma_rx
[  180.527737] cl-msgdma write_cl_msgdma: CL mSGDMA driver probe success
[  180.535056] cl-msgdma read_cl_msgdma: registered /dev/cl_msgdma_tx
[  180.541309] cl-msgdma read_cl_msgdma: CL mSGDMA driver probe success

Run the userspace application¶

./dma_example

Successful execution of the dma_example binary should look like the following:

root@mity-a5e:~# ./dma_example
Allocating RX buffers
Allocating TX buffers
Queuing all RX buffers
Setting up XorShift generator
Starting the RX DMA Engine
Reading RX buffers
Read 20 buffers from DMA
Setting up XorShift checker
Starting the TX DMA Engine
Writing TX buffers
Wrote 20 buffers to DMA
Data TX check passed

The following script can be used to restart the example as the mSGMDAs can potentially FIFO data and hold onto buffers from the previous run which can cause incorrect data. Reloading the mSGDMA driver causes the mSGDMAs to reset and all of the buffers to be reallocated in a clean state. The script below can be ran to run the example again or simply reboot the unit and start again from Boot into Linux above.

#!/bin/bash

rmmod cl_msgdma.ko
echo 20010000.dma-controller > /sys/bus/platform/drivers/altera-msgdma/unbind
echo 20010040.dma-controller > /sys/bus/platform/drivers/altera-msgdma/unbind
echo 20010000.dma-controller > /sys/bus/platform/drivers/altera-msgdma/bind
echo 20010040.dma-controller > /sys/bus/platform/drivers/altera-msgdma/bind
insmod cl_msgdma.ko
./dma_example