Scalable Scatter-Gather DMA Intel® FPGA IP User Guide

Download PDF
ID 823097
Date 4/07/2025
Public
Document Table of Contents
Document Table of Contents x
1. Terms and Acronyms 2. Introduction 3. Functional Description 4. Interfaces 5. HAL Driver for DMA SoC Mode  6. Parameters 7. Registers 8. Document Revision History for the Scalable Scatter-Gather DMA Intel® FPGA IP User Guide
2. Introduction x
2.1. Device Family Support 2.2. Release Information 2.3. Resource Utilization
3. Functional Description x
3.1. DMA PCIe* Mode 3.2. DMA SoC Mode 3.3. Device Port 3.4. Prefetcher Engine 3.5. DMA Arbiter 3.6. DMA Router 3.7. CSRUnit 3.8. Descriptor Handling 3.9. Interrupts 3.10. Reset Initialization Flows 3.11. Transaction Flow
3.1. DMA PCIe* Mode x
3.1.1. Submodules
3.1.1. Submodules x
3.1.1.1. PCIe* TLP Constructor 3.1.1.2. PCIe* TLP ID Generation 3.1.1.3. PCIe TX Credit Controller 3.1.1.4. PCIe* TX Scheduler 3.1.1.5. PCIe TLP Completer 3.1.1.6. PCIe RX Router 3.1.1.7. PCIe* MSI-X Controller 3.1.1.8. PCIe BAR0 3.1.1.9. PCIe Bursting Manager (BAM) 3.1.1.10. Completion Timeout Parser 3.1.1.11. Control Shadow Parser
3.2. DMA SoC Mode x
3.2.1. Interrupt Controller 3.2.2. Host AXI-4 Agent 3.2.3. Host CSR AXI-4 Lite Agent
3.3. Device Port x
3.3.1. ST Source Agent/ST Sink Agent/MM Agent 3.3.2. Descriptor Engine 3.3.3. Agent Controller 3.3.4. Constructor 3.3.5. Responder 3.3.6. Width Adaptation FIFO
3.8. Descriptor Handling x
3.8.1. Link Descriptor 3.8.2. Data Descriptor 3.8.3. Responder Descriptor 3.8.4. Descriptor Chain 3.8.5. Aligned and Unaligned Transfer Support
3.8.2. Data Descriptor x
3.8.2.1. Data Descriptor - H2D Streaming Transfer 3.8.2.2. Data Descriptor - D2H Streaming Transfer 3.8.2.3. Data Descriptor - H2D Memory Transfer
3.8.3. Responder Descriptor x
3.8.3.1. Responder Descriptor - H2D Streaming Transfer 3.8.3.2. Responder Descriptor - D2H Streaming Transfer 3.8.3.3. Responder Descriptor - H2D Memory Transfer
3.8.4. Descriptor Chain x
3.8.4.1. Descriptor Fetch and Status Update Mechanism
3.11. Transaction Flow x
3.11.1. General DMA Operation Flow 3.11.2. Host to Device (H2D) Flow 3.11.3. Device to Host (D2H) Flow 3.11.4. Soft Reset Handshake Flow
4. Interfaces x
4.1. Port List 4.2. DMA PCIe* Mode Interfaces 4.3. DMA SoC Mode Interfaces 4.4. Device Port Interfaces 4.5. Resets 4.6. Clocks
4.2. DMA PCIe* Mode Interfaces x
4.2.1. Application Packet Receive Interface 4.2.2. Application Packet Transmit Interface 4.2.3. Control Shadow Interface 4.2.4. Transmit Flow Control Credit Interface 4.2.5. Completion Timeout Interface 4.2.6. PCIe* Miscellaneous Signals 4.2.7. Control and Status Register Responder Manager Interface 4.2.8. Bursting Manager Interface
4.3. DMA SoC Mode Interfaces x
4.3.1. Host AXI-4 Memory Map Manager Interface 4.3.2. Host AXI-4 Lite CSR Memory Map Subordinate Interface 4.3.3. Interrupt Interface
4.4. Device Port Interfaces x
4.4.1. Device to Host <PORT#> AXI-ST Subordinate Interface 4.4.2. Device to Host <PORT#> Avalon-ST Sink Interface 4.4.3. Host to Device <PORT#> AXI-ST Manager Interface 4.4.4. Host to Device <PORT#> Avalon-ST Source Interface 4.4.5. Host to Device <PORT#> AXI-4 Manager Interface
5. HAL Driver for DMA SoC Mode  x
5.1. Descriptor Indexing  5.2. HAL Public API 
5.1. Descriptor Indexing  x
5.1.1. Data Descriptors  5.1.2. Responders 
5.2. HAL Public API  x
5.2.1. Software Features 5.2.2. intel_ssgdma.c  5.2.3. intel_ssgdma_global.c 5.2.4. intel_ssgdma_device_port.c  5.2.5. intel_ssgdma_descriptor.c 
6. Parameters x
6.1. DMA Settings 6.2. Device Port Settings 6.3. DMA PCIe Mode Settings 6.4. DMA SoC Mode Settings 6.5. Example Design
6.2. Device Port Settings x
6.2.1. H2D MM 6.2.2. H2D ST 6.2.3. D2H ST
7. Registers x
7.1. Global CSR 7.2. MSI-X Memory Space 7.3. Device Port Control Register
1. Terms and Acronyms
2. Introduction
3. Functional Description
4. Interfaces
5. HAL Driver for DMA SoC Mode 
6. Parameters
7. Registers
8. Document Revision History for the Scalable Scatter-Gather DMA Intel® FPGA IP User Guide

5. HAL Driver for DMA SoC Mode 

This section describes the HAL driver for the DMA SoC mode. SSGDMA IP is equipped with AXI-4/4- LITE interfaces which is intended to pair with the HPS / Nios® V processor.  

Note: This driver is not supported for the Nios® II processor.
Note: For DMA only mode, the host writes the descriptor directly to the SSGDMA controller. You need to create your own custom Prefetcher logic and driver for DMA Only mode.

The driver only returns a negative value as an error if the error is due to software or can be detected with HW-CSR. An error while reading/writing registers (IORD or IOWR) or due to wrong configuration of Device_Interface_Control/Device_Interface_Control (Data descriptor) is not be considered. 

The driver does not allocate or manage memory for the data buffers. You should do this in the application. 

The driver allocates contiguous memory for data and responder descriptor blocks. After allocation, the same function initializes the data descriptor with format and index. The link descriptor is also chained with the next address. Besides that, the responder table also is filled. (For more information, refer to intel_ssgdma_setup_device_port). If you decide to do non-contiguous memory allocation, then the driver needs to be modified manually. 

You may set different descriptor and responder blocks and should not “skip” the data descriptor, (for example, setting valid in control to 0). This is to ensure, that the driver gets the correct responder.  If these are violated, you need to modify the driver to get the correct responder. For more information, refer to the Descriptor Indexing section. 

There are no memory management for HAL OS. Ensure that the memory management for HAL OS has sufficient heap memory for dynamic memory allocation. For example, if the design has three device ports and each device port has two blocks of descriptors, and responders are enabled:
  • Required minimum heap size: 49KB
  • sizeof(intel_ssgdma_device_port) = 40 bytes
  • Descriptor per block = 128, size of one descriptor = 32 bytes
  • Two descriptor blocks = 2 x 128 x 32 = 8192 bytes
  • If responder is enabled, memory for descriptor together with responder is equal to 8192 x 2 = 16384 bytes.
  • Bytes required per port = 16384 + 40 = 16424 bytes. If three ports are used, 3 x 16424 = 49KB.

If heap and stack shares the same memory, ensure that at least 100KB is free. Ensure that you increase the memory of the design to meet the minimal 100KB of free memory space or else this causes unrecoverable memory allocation error.

The condition of Descriptor buffer full or empty is indicated by the last slot in the circular descriptor. The last slot of the circular descriptor is “sacrificed” to distinguish empty and full condition.
Figure 19. Buffer Full
Figure 20. Buffer Empty
Figure 21. Buffer Full in the middle of Descriptor

Section Content
Descriptor Indexing 
HAL Public API 

Related Information
Level Two Title