Streaming DMA Accelerator Functional Unit User Guide: Intel FPGA Programmable Acceleration Card D5005

ID 683424
Date 11/04/2019

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:

This driver supports the following functions:
API Description

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)
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)
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/