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.2. intel_ssgdma.c 

Table 68.  intel_ssgdma_open 

Prototype 

intel_ssgdma_dev *intel_ssgdma_open(const char *name) 

Include 

<intel_ssgdma.h> 

Parameters 

name - Character pointer to name of ssgdma device. 

Return 

intel_ssgdma_dev *dev - Success.  

Null - Invalid name or device is not registered. 

Description 

Retrieve a pointer to the ssgdma device instance of the given name. For this api to work properly, instance must be within the scope, where this function is called. 

Table 69.  intel_ssgdma_init

Prototype 

void intel_ssgdma_init(intel_ssgdma_dev *const dev, const FPGA_INTERRUPT_HANDLE irq_controller_id, const FPGA_INTERRUPT_HANDLE irq, const FPGA_MMIO_INTERFACE_HANDLE mmio_handle, const uint16_t num_D2H_ST_device_ports, const uint16_t num_H2D_ST_device_ports, const uint16_t num_H2D_MM_device_ports, const uint16_t total_device_ports, const bool restrict_unaligned_access) 

Include 

<intel_ssgdma.h> 

Parameters 
  • dev - pointer to the SSGDMA device structure.  
  • irq_controller_id - interrupt controller id.  
  • irq - interrupt number.  
  • mmio_handle - memory in out handler for the device.  
  • num_D2H_ST_device_ports - total number of Host to Device memory mapped port.  
  • num_H2D_ST_device_ports - total number of Host to Device streaming port.  
  • num_H2D_MM_device_ports - total number of Device to Host streaming port.  
  • total_device_ports - total number of all device ports.  
  • restrict_unaligned_access - For 32-bit system, restrict 32 bytes aligned address for descriptor and multiple of 4 for length. Doubles for 64-bit system. 

Return 

None 

Description 

Initializes the Scalable Scatter-Gather DMA controller. This routine is called from the INTEL_SSGDMA_INIT macro and is called automatically by alt_sys_init.c in HAL system. 

 
Table 70.  intel_ssgdma_register_global_error_callback  

Prototype 

intel_ssgdma_return_e intel_ssgdma_register_global_error_callback( intel_ssgdma_dev *dev, intel_ssgdma_global_error_callback callback, void *user_context) 

Include 

<intel_ssgdma.h> 

Parameters 
  • dev - Pointer to ssgdma device (instance) structure.  
  • callback - Pointer to callback routine to execute at interrupt level. 
  • user_context - user defined context. 

Return 

E_INTEL_SSGDMA_OK : 0 -> Success.

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1 -> Invalid arguments. 

Description 

Function is set user callback function for ISR from application. User may use this function to handle global errors.  

 

Notes: When defining global error callback, user should set a flag in user_context to initiate device global reset flow. Please do not call the API directly in the callback, as most of the API blocks until the hw is stopped or reset. The user callback is called directly in the intel_ssgdma_irq.  

 

Suggested global reset flow:  

  • intel_ssgdma_global_soft_pause  
  • intel_ssgdma_global_soft_reset  
  • intel_ssgdma_global_resume 

Callback Details 

typedef void (*intel_ssgdma_global_error_callback)(void *user_context, const FPGA_MMIO_INTERFACE_HANDLE csr_base, const uint32_t global_status);

Callback Arguments:
  • user_context - pointer to user defined callback context
  • csr_base - Base address to identify the interrupting device.
  • global_status - saved value of global status register upon interrupt. 
Table 71.  intel_ssgdma_register_queue_error_callback 

Prototype 

intel_ssgdma_return_e intel_ssgdma_register_queue_error_callback( 

intel_ssgdma_dev *dev, intel_ssgdma_queue_error_callback callback, 

void *user_context) 

Include 

<intel_ssgdma.h> 

Parameters 
  • dev - Pointer to ssgdma device (instance) structure. 
  • callback - Pointer to callback routine to execute at interrupt level 
  • user_context - user defined context. 

Return 

E_INTEL_SSGDMA_OK                                  :  0  -> Success. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid arguments. 

Description 

Function is set user callback function for ISR from application. 

User may use this function to handle device port or descriptor errors. 

 

Notes: 

When defining queue error callback, user should set a flag in user_context 

to initiate device port reset flow. Please do not call the API directly 

in the callback, as most of the API blocks until the hw is stopped or reset. 

The user callback is called directly in intel_ssgdma_irq. 

Suggested device port reset flow: 
  • intel_ssgdma_device_port_soft_pause 
  • intel_ssgdma_device_port_soft_reset 
  • intel_ssgdma_device_port_reuse_setup 

Callback Details 

typedef void (*intel_ssgdma_queue_error_callback)(void *user_context, const FPGA_MMIO_INTERFACE_HANDLE csr_base, const intel_ssgdma_port_type_e port_type, const uint16_t port_num, const uint32_t q_status);

Callback Arguments: 
  • user_context  - user defined callback context
  • csr_base - Base address to identify the interrupting device. 
  • port_type - port type to identify the interrupting device port. 
  • port_num - port num to identify the interrupting device port. 
  • q_status  - saved value of queue status register upon interrupt.
Table 72.  intel_ssgdma_register_complete_callback  

Prototype 

intel_ssgdma_return_e intel_ssgdma_register_complete_callback( 

    intel_ssgdma_dev *dev, intel_ssgdma_complete_callback callback, 

    void *user_context) 

Include 

<intel_ssgdma.h> 

Parameters 
  • dev - Pointer to ssgdma device (instance) structure. 
  • callback - Pointer to callback routine to execute at interrupt level 
  • user_context  - user defined context

Return 

E_INTEL_SSGDMA_OK                                  :  0  -> Success. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid arguments. 

Description 

Function is set to user callback function for ISR from application. 

You may use this function to handle responder completed event. 

Notes: 

When defining completion callback, user should set a flag in user_context 

to signal transfer completion. Please do not call the API directly 

in the callback, as most of the API blocks until the hw is stopped or reset. 

The user callback is called by intel_ssgdma_service_all_completed_resp in 

intel_ssgdma_irq. 

Callback Details 

typedef void (*intel_ssgdma_complete_callback)(void *user_context,  const FPGA_MMIO_INTERFACE_HANDLE csr_base, const intel_ssgdma_port_type_e port_type,  const uint16_t port_num, const uint16_t completed_resp_num); 

Callback Arguments: 
  • user_context  - user defined callback context
  • csr_base - Base address to identify the interrupting device
  • port_type - port type to identify the interrupting device port
  • port_num  - port num to identify the interrupting device port
  • completed_resp_num - number of completed responder, since last service
Table 73.  intel_ssgdma_register_video_flushing_callback

Prototype 

intel_ssgdma_return_e intel_ssgdma_register_video_flushing_callback( 

    intel_ssgdma_dev *dev, intel_ssgdma_video_flushing_callback callback, 

    void *user_context) 

Include 

<intel_ssgdma.h> 

Parameters 
  • dev                    - Pointer to ssgdma device (instance) structure. 
  • callback            - Pointer to callback routine to execute at interrupt level 
  • user_context   - user defined context

Return 

E_INTEL_SSGDMA_OK                                  :  0  -> Success. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid arguments. 

Description 

Function is set user callback function for ISR from application. 

You may use this function to handle video flushing event. 

Notes: 

When defining video flushing callback, you should set a flag in user_context 

to signal transfer completion. Please do not call the API directly 

in the callback, as most of the API blocks until the hw is stopped or reset. 

The user callback is called by intel_ssgdma_video_flushing_event in 

intel_ssgdma_irq. 

Callback Details 

typedef void (*intel_ssgdma_video_flushing_callback)(void *user_context, const FPGA_MMIO_INTERFACE_HANDLE csr_base, const intel_ssgdma_port_type_e port_type, const uint16_t port_num, const uint16_t next_pend_desc_hw_idx, const uint32_t q_bytessent, const uint32_t q_total_bytessent); 

Callback Arguments: 

- user_context  - user defined callback context 

- csr_base          - Base address to identify the interrupting device. 

- port_type        - port type to identify the interrupting device port. 

- port_num        - port num to identify the interrupting device port. 

- next_pend_desc_hw_idx - hw index of the descriptor, that is being flushed. 

- q_bytessent                       - bytes sent during flushing event. 

- q_total_bytessent            - total byte sent since first flushing event. 

Table 74.  intel_ssgdma_cal_host_mem_size 

Prototype 

intel_ssgdma_return_e intel_ssgdma_cal_host_mem_size( intel_ssgdma_dev *dev, uint16_t total_desc_block, uint16_t total_resp_block, size_t *total_alloc_bytes) 

Include 

<intel_ssgdma.h> 

Parameters 
  • dev - Pointer to the ssgdma device structure.  
  • total_desc_block - Total number of descriptor blocks for all ports.
  • total_resp_block - Total number of responder blocks for all ports. 
  • total_alloc_bytes - Pointer to total bytes that should be allocated.

Return 

E_INTEL_SSGDMA_OK : 0 → Success.

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1 → Invalid arguments. 

E_INTEL_SSGDMA_ALREADY_SETUP : -9 → Already calculated. Please reset before calling this function.

Description 

Calculates required host memory allocation to hold descriptors and responders for dma operations. You are advised to allocate at least 1 descriptor block to each device port. This function can only be called once. Please call intel_ssgdma_global_soft_reset to start again.

After this you should use total_alloc_bytes to allocate host memory and call intel_ssgdma_set_desc_start to assign the memory to the driver.

Table 75.  intel_ssgdma_set_desc_start 

Prototype 

intel_ssgdma_return_e intel_ssgdma_cal_host_mem_size( intel_ssgdma_dev *dev, uint16_t total_desc_block, uint16_t total_resp_block, size_t *total_alloc_bytes) 

Include 

<intel_ssgdma.h> 

Parameters 
  • dev - Pointer to the ssgdma device structure.  
  • desc_start - pointer to host memory, which is used to store the first descriptor of the ssgdma device instance..

Return 

E_INTEL_SSGDMA_OK : 0 → Success.

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1 → Invalid arguments. 

E_INTEL_SSGDMA_MEMALLOC_ERROR : -4 → Given desc_start is null pointer or unaligned address.

E_INTEL_SSGDMA_ALREADY_SETUP: -9 → Already assigned. Please reset before calling this function.

Description 

Assign the allocated host memory as the address of the first descriptor of the device port. This function can only be called once. Please call intel_ssgdma_global_soft_reset to start again..

Before this function, you must first call intel_ssgdma_cal_host_mem_size.

Level Two Title