Streaming DMA Accelerator Functional Unit User Guide: Intel® Programmable Acceleration Card with Intel® Arria® 10 GX FPGA

Download PDF
ID 683840
Date 3/06/2020
Public
Document Table of Contents
Document Table of Contents x
1. About this Document 2. Streaming DMA AFU Description 3. Memory Map and Address Spaces 4. Software Programming Model 5. Running the AFU Example 6. Compiling the Accelerator Function (AF) 7. Simulating the AFU Example 8. Streaming DMA AFU User Guide Archives 9. Document Revision History for Streaming DMA Accelerator Functional Unit User Guide A. Enabling Hugepages
1. About this Document x
1.1. Intended Audience 1.2. Conventions 1.3. Acronyms 1.4. Acceleration Glossary
2. Streaming DMA AFU Description x
2.1. Hardware Subsystems 2.2. Streaming DMA Test System 2.3. Memory-to-Stream DMA BBB 2.4. Stream-to-Memory DMA BBB
3. Memory Map and Address Spaces x
3.1. Streaming DMA AFU Memory Map 3.2. Memory-to-Stream DMA BBB Memory Map 3.3. Stream-to-Memory DMA BBB Memory Map 3.4. Device Feature Header Linked-list
5. Running the AFU Example x
5.1. Optimization for Improved DMA Performance
1. About this Document
2. Streaming DMA AFU Description
3. Memory Map and Address Spaces
4. Software Programming Model
5. Running the AFU Example
6. Compiling the Accelerator Function (AF)
7. Simulating the AFU Example
8. Streaming DMA AFU User Guide Archives
9. Document Revision History for Streaming DMA Accelerator Functional Unit User Guide
A. Enabling Hugepages

4. Software Programming Model

The streaming DMA AFU includes a software driver that you can use in your own host application. The fpga_dma_st.c and fgpa_dma.h files located at the following location implement the software driver: 
$OPAE_PLATFORM_ROOT/hw/samples/streaming_dma_afu/sw

This driver supports the following functions:
API Description
fpgaCountDMAChannels

Scans the device feature chain for DMA BBBs and count all available channels.

fpgaDMAOpen Opens a handle to the DMA channel.
fpgaDMAClose Closes a handle to the DMA channel.
fpgaGetDMAChannelType Query DMA channel type.

Possible type of query channel is TX streaming (TX_ST) and RX streaming (RX_ST).

fpgaDMATransferInit Initializes an object that represents the DMA transfer.
fpgaDMATransferReset Resets the DMA transfer attribute object to default values.
fpgaDMATransferDestroy Destroys the DMA transfer attribute object.
fpgaDMATransferSetSrc Sets the source address of the transfer. This address must be 64 byte aligned.
fpgaDMATransferSetDst Sets the destination address of the transfer. This address must be 64 byte aligned.
fpgaDMATransferSetLen Sets the transfer lengths in bytes. For non-packet transfers, you must set the transfer length to a multiple of 64 bytes. For packet transfers, this is not a requirement.
fpgaDMATransferSetTransferType Sets the transfer type.
Legal values are:
  • HOST_MM_TO_FPGA_ST = TX (host to AFU streaming)
  • FPGA_ST_TO_HOST_MM = RX (AFU streaming to host)
fpgaDMATransferSetTxControl Sets TX control. This allows the driver to optionally generate in-band SOP and EOP in the data stream sent from the TX DMA.

TX control is only valid for HOST_MM_TO_FPGA_ST transfer.

Valid values are:
  • TX_NO_PACKET (No SOP, EOP, or empty value generated)
  • GENERATE_SOP_AND_EOP
  • GENERATE_SOP
  • GENERATE_EOP
fpgaDMATransferSetRxControl Sets RX control. This allows the driver to handle an unknown amount of receive data from the FPGA, When END_ON_EOP is set, the RX DMA ends the transfer when EOP arrives in the receive stream or when rx_count bytes have been received (whichever occurs first).

RX control is only valid for FPGA_ST_TO_HOST_MM transfer.

Valid values are:
  • RX_NO_PACKET (deterministic length transfer)
  • END_ON_EOP
fpgaDMATransferSetTransferCallback Registers callback for notification on asynchronous transfer completion. If you specify a callback, fpgaDMATransfer returns immediately (asynchronous transfer).

If you do not specify a callback, fpgaDMATransfer returns after the transfer is complete (synchronous/blocking transfer).

fpgaDMATransferGetBytesTransferred Returns the number of bytes transferred by an RX transfer request. The application uses this data when receiving packetized data (rx_control set to END_ON_EOP when transfer request was issued).
fpgaDMATransferCheckEopArrived Retrieves EOP status
Legal vales are:
  • 0: EOP did not arrive
  • 1: EOP arrived
fpgaDMATransferSetLast Indicates the last transfer so the DMA can start processing the prefetched transfers. The default value is 64 transfers in the pipeline before the DMA starts to work on the transfers.
fpgaDMATransfer Performs a DMA transfer.

For more information about the API, input, and output arguments, refer to the header file located at $OPAE_PLATFORM_ROOT/hw/samples/streaming_dma_afu/sw/fpga_dma.h

To know more about software driver use model, refer to the README file located at $OPAE_PLATFORM_ROOT/hw/samples/streaming_dma_afu/README.md

Level Two Title