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.2.3. intel_ssgdma_global.c

Table 76.  intel_ssgdma_enable_prefetch_engine  

Prototype 

intel_ssgdma_return_e intel_ssgdma_enable_prefetch_engine(intel_ssgdma_dev *dev) 

Include 

<intel_ssgdma.h> 

Parameters 

dev - pointer to the SSGDMA device structure. 

Return 

E_INTEL_SSGDMA_OK                                  :  0   -> Success. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1   -> Invalid input device. 

Description 

Enable prefetcher engine. 

Table 77.  intel_ssgdma_prefetch_engine_is_enabled 

Prototype 

int intel_ssgdma_prefetch_engine_is_enabled(intel_ssgdma_dev *dev) 

Include 

<intel_ssgdma.h> 

Parameters 

dev - pointer to the SSGDMA device structure. 

Return 

INTEL_SSGDMA_NO        :  0 -> If disabled. 

INTEL_SSGDMA_YES       :  1 -> If enabled. 

INTEL_SSGDMA_ERROR : -1 -> Invalid input device. 

Description 

check if prefetcher engine is enabled. 

 
Table 78.  intel_ssgdma_reset_prefetch_engine 

Prototype 

intel_ssgdma_return_e intel_ssgdma_reset_prefetch_engine(intel_ssgdma_dev *dev) 

Include 

<intel_ssgdma.h> 

Parameters 

dev - pointer to the SSGDMA device structure. 

Return 

E_INTEL_SSGDMA_OK                                  :  0   -> Success. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1   -> Invalid input device. 

E_INTEL_SSGDMA_BUSY                              : -5  -> Previous prefetcher reset is not completed. Please enable prefetcher before next reset

Description 

Reset prefetcher engine. This function only sets the reset prefetcher 

engine bit. Please refer to intel_ssgdma_global_soft_pause and 

intel_ssgdma_global_soft_reset for the prefetcher soft reset flow. 

 
Table 79.  intel_ssgdma_watchdog_timer_set_state

Prototype 

int intel_ssgdma_watchdog_timer_set_state(intel_ssgdma_dev *dev, bool enable) 

Include 

<intel_ssgdma.h> 

Parameters 
  • dev      - pointer to the SSGDMA device structure
  • enable - 1 for enable or 0 for disable

Return 

E_INTEL_SSGDMA_OK                                  :  0  -> Success. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid input device. 

Description 

Enables/disable watchdog timer 

Table 80.  intel_ssgdma_set_writeback_delay  

Prototype 

intel_ssgdma_return_e intel_ssgdma_set_writeback_delay(intel_ssgdma_dev *dev, uint32_t delay) 

Include 

<intel_ssgdma.h> 

Parameters 
  • dev    - pointer to the SSGDMA device structure. 
  • delay - delay[2ns] (width: 20 bits). 

Return 

E_INTEL_SSGDMA_OK                                  :  0  -> Success. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid input device or delay > 20 bits 

Description 

Set writeback delay in WB_INTR_TIMEOUT register. Check if delay is within 20 bits. 

Table 81.  intel_ssgdma_set_watchdog_timeout  

Prototype 

intel_ssgdma_return_e intel_ssgdma_set_watchdog_timeout(intel_ssgdma_dev *dev, uint32_t timeout) 

Include 

<intel_ssgdma.h> 

Parameters 
  • dev - pointer to the SSGDMA device structure
  • timeout - timeout[2ns] (width: 20 bits)

Return 

E_INTEL_SSGDMA_OK                                  :  0  -> Success. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid input device or delay > 20 bits 

Description 

Set writeback delay in WATCHDOG_TIMEOUT register. Check if delay is within 20 bits. 

Table 82.  intel_ssgdma_sync_hw_sw_config

Prototype 

intel_ssgdma_return_e intel_ssgdma_sync_hw_sw_config(intel_ssgdma_dev *dev) 

Include 

<intel_ssgdma.h> 

Parameters 

dev - pointer to the SSGDMA device structure. 

Return 

E_INTEL_SSGDMA_OK                                   :  0 -> Success. 

E_INTEL_SSGDMA_INVALID_ARGUMENT  : -1 -> Invalid input device. 

E_INTEL_SSGDMA_HW_SW_MISMATCH   : -8 -> the generated sw configuration does not match with the hardware. 

Description 

Read from IP_PARAM1 register to check if the generated sw configuration 

matches with the hw. For NiosV system, this can be used to detect error, 

when the hw design in platform designer is modified, but the bsp for the 

software is not regenerated. If INTEL_SSGDMA_AUTO_CONF_SW is enabled, the 

driver automatically syncs the configuration. If disabled and 

configuration does not match; the driver blocks all attempts to setup port 

when calling intel_ssgdma_setup_device_port. 

Table 83.  intel_ssgdma_global_soft_pause 

Prototype 

intel_ssgdma_return_e intel_ssgdma_global_soft_pause(intel_ssgdma_dev *dev) 

Include 

<intel_ssgdma.h> 

Parameters 

dev - pointer to the SSGDMA device structure. 

Return 

E_INTEL_SSGDMA_OK                                  :  0  -> Success. All device port paused. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid input device. 

E_INTEL_SSGDMA_BUSY                              : -5  -> timeout for prefetcher reset. 

E_INTEL_SSGDMA_TIMEOUT                      : -6  -> timeout for device port paused 

Description 

This function pauses all dma transaction for the input device. 

The function blocks until the prefetcher engine is reset and all 

device ports are paused. If one of the ports failed to pause before timeout, 

this function stops the flow and return E_INTEL_SSGDMA_TIMEOUT. 

If blocking is not desired, refer to the flow in this function 

to implement their own function. 

Table 84.  intel_ssgdma_global_soft_reset

Prototype 

intel_ssgdma_return_e intel_ssgdma_global_soft_reset(intel_ssgdma_dev *dev, bool reuse_setup) 

Include 

<intel_ssgdma.h> 

Parameters 
  • dev - pointer to the SSGDMA device structure
  • reuse_setup - reuse previous setup

Return 

E_INTEL_SSGDMA_OK                                  :  0  -> Success. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid input device. 

E_INTEL_SSGDMA_BUSY                              : -5  -> Prefetcher running/port not paused. 

E_INTEL_SSGDMA_TIMEOUT                      : -6  -> timeout for device port reset. 

Description 

Before calling this function, prefetcher engine must not run and all device 

ports must be paused. You can pause the device by calling 

intel_ssgdma_global_soft_pause and ensure that E_INTEL_SSGDMA_OK is returned. 

This function resets all device ports. 

Function blocks until all device ports are reset. 

After reset csr of all device ports is reset to its initial value. 

If the input reuse_setup is set, you can call intel_ssgdma_global_resume to resume normal operation. If not, please call intel_ssgdma_setup_device_port to setup the port again before intel_ssgdma_global_resume.

Note: Soft pause is currently not supported for H2D_ST and H2D_MM ports.
Table 85.  intel_ssgdma_global_resume

Prototype 

intel_ssgdma_return_e intel_ssgdma_global_resume(intel_ssgdma_dev *dev, bool stop_on_error) 

Include 

<intel_ssgdma.h> 

Parameters 
  • dev                     - pointer to the SSGDMA device structure
  • stop_on_error  - stop resuming other ports, if the previous one has error

Return 

E_INTEL_SSGDMA_OK                                  :  0  -> All device ports are resumed. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid arguments. 

E_INTEL_SSGDMA_CANT_REUSE_SETUP  : -10 -> unable to resume as previous setup is released. Please call intel_ssgdma_setup_device_port, before resume.

E_INTEL_SSGDMA_NOT_ALL_RESUMED  : -13 -> stop_on_error = false and some ports failed to resume, because they are not setup. Please debug to check if this is intended. 

Description 

This function resumes all device port after paused or reset. 

Table 86.  intel_ssgdma_get_device_errors_flags  

Prototype 

intel_ssgdma_return_e intel_ssgdma_get_device_errors_flags( 

    intel_ssgdma_dev *dev, uint16_t *error_flag) 

Include 

<intel_ssgdma.h> 

Parameters 
  • dev - pointer to the SSGDMA device structure
  • error_flag  - pointer to return the device error flags

Return 

E_INTEL_SSGDMA_OK                                  :  0  -> Success. *error_flag is valid. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid input device. 

Description 

Get the value of device_errors_flags. 

These flags are set to indicate abnormal operation during interrupt. 

Table 87.  intel_ssgdma_clear_device_errors_flags 

Prototype 

intel_ssgdma_return_e intel_ssgdma_clear_device_errors_flags( 

    intel_ssgdma_dev *dev) 

Include 

<intel_ssgdma.h> 

Parameters 

dev - pointer to the SSGDMA device structure. 

Return 

E_INTEL_SSGDMA_OK                                  :  0  -> Success. Flags are cleared. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid input device. 

Description 

Clear the value of device_errors_flags. 

These flags are set to indicate abnormal operation during interrupt and 

needs to be cleared by the user. 

Level Two Title