Scalable Scatter-Gather DMA Intel® FPGA IP User Guide

Download PDF
ID 823097
Date 1/27/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.5. intel_ssgdma_descriptor.c 

Table 107.  intel_ssgdma_fill_h2d_st 

Prototype 

intel_ssgdma_return_e intel_ssgdma_fill_h2d_st(intel_ssgdma_dev *dev, 

    uint16_t port_num, uint8_t control, uint32_t length, 

    INTEL_SSGDMA_ADDR_T addr, uint16_t sideband_signal, 

    uint32_t host_interface_control, uint32_t max_length_per_desc, 

    bool irq_en_last_desc) 

Include 

<intel_ssgdma.h> 

Parameters 
  •  dev - pointer to the SSGDMA device structure. 
  •  port_num - port number of interface. (starts from 0). 
  •  control - control field of the descriptor. 
  •  length - length of the data. 
  •  addr - start address of the source data. 
  •  sideband_signal - Value for user defined sideband signal. 
  •  host_interface_control - Set host attributes for AXI protocol. 
  •  max_length_per_desc - Maximum length of the data per descriptor. 
  •  irq_en_last_desc - enable interrupt for last filled descriptor. 

Return 

E_INTEL_SSGDMA_OK : 0  -> Success. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid device port number or length of data is 0. E_INTEL_SSGDMA_NO_INITI : -2  -> Device port is not setup or port_csr_base is 0. 

Please check setup or init. 

E_INTEL_SSGDMA_Q_FULL : -7  -> Queue is full. E_INTEL_SSGDMA_NOT_ENOUGH_DESC : -11 -> q_size is not enough. Please reset and set larger size or reduce the number of descriptors. 

E_INTEL_SSGDMA_ADDRESS_OVERFLOW : -12 -> Overflow of address would happen, before all data is transferred. Please check start address. 

Description 

Fills the next host to device streaming transfer (h2d_st) descriptor. 

Please setup the device port (intel_ssgdma_setup_device_port) before using this function. 

Notes: 

  • Descriptor index is initialized by calling intel_ssgdma_setup_device_port.
  • For host_interface_control, please refer to AMBA AXI and ACE Protocol and use the macro INTEL_SSGDMA_SET_INTERFACE_CONTROL_FIELD to set the values. 
  • Please refer to intel_ssgdma_descriptor.h for bit mask of control. 
  • The input max_length_per_desc can be used to split a chunk of data into several descriptors. Each descriptor is limited with max_length_per_desc. 

    Example: length = 1032 and max_length_per_desc = 128, 9 descriptors are filled by this API. 

  • If max_length_per_desc is not zero, the driver is set to Start of Packet (SOP) for the first descriptor and End of Packet(EOP) for the last descriptor. If there is only one descriptor, both SOP and EOP is set.
  • If max_length_per_desc is zero, the API only fills one descriptor per call. The driver overwrites max_length_per_desc to UINT32_MAX and you can set the SOP and EOP for each descriptor manually. If this is not accepted, the transfer is identified as an undefined behavior. 
Table 108.  intel_ssgdma_fill_d2h_st 

Prototype 

intel_ssgdma_return_e intel_ssgdma_fill_d2h_st(intel_ssgdma_dev *dev, 

    uint16_t port_num, uint8_t control, uint32_t length, 

    INTEL_SSGDMA_ADDR_T addr, uint32_t host_interface_control, 

    uint32_t max_length_per_desc, bool irq_en_last_desc) 

Include 

<intel_ssgdma.h> 

Parameters 
  •  dev                                - pointer to the SSGDMA device structure. 
  •  port_num                         - port number of interface. (starts from 0). 
  •  control                              - control field of the descriptor. 
  •  length                                - length of the data. 
  •  addr                                   - start address of the destination data. 
  •  host_interface_control  - Set host attributes for AXI protocol. 
  •  max_length_per_desc   - Maximum length of the data per descriptor. 
  •  irq_en_last_desc             - enable interrupt for last filled descriptor. 

Return 

E_INTEL_SSGDMA_OK                                  :  0  ->  Success. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid device port number or length of data is 0. 

E_INTEL_SSGDMA_NO_INITI                        : -2  -> Device port is not setup or port_csr_base is 0. 

Please check setup or init. 

E_INTEL_SSGDMA_Q_FULL  : -7   -> Queue is full. 

E_INTEL_SSGDMA_NOT_ENOUGH_DESC   : -11 -> q_size is not enough. Please reset and set larger size or reduce the number of descriptors. 

E_INTEL_SSGDMA_ADDRESS_OVERFLOW : -12 -> Overflow of address would happen, before all data is transferred. 

Please check start address. 

Description 

Fills the next device to host streaming transfer (d2h_st) descriptor. 

Please setup the device port (intel_ssgdma_setup_device_port) before using this function. 

Notes: 

  • Descriptor index is initialized by calling intel_ssgdma_setup_device_port.
  • For host_interface_control, please refer to AMBA AXI and ACE Protocol Specification and use the macro INTEL_SSGDMA_SET_INTERFACE_CONTROL_FIELD to set the values. 
  • Please refer to intel_ssgdma_descriptor.h for bit mask of control. 
  • The input max_length_per_desc can be used to split a chunk of data into several descriptors. Each descriptor is limited with max_length_per_desc. 

    Example: length = 1032 and max_length_per_desc = 128, 9 descriptors are filled by this API. 

  • If max_length_per_desc is not zero, the driver sets Start of Packet (SOP) for the first descriptor and End of Packet(EOP) for the last descriptor. If there is only one descriptor, both SOP and EOP is set.

If max_length_per_desc is zero, the API only fills one descriptor per call. The driver overwrites max_length_per_desc to UINT32_MAX and you set the SOP and EOP for each descriptor manually. If this is not accepted, the transfer is identified as undefined behavior. 

Table 109.  intel_ssgdma_fill_h2d_mem

Prototype 

intel_ssgdma_return_e intel_ssgdma_fill_h2d_mem(intel_ssgdma_dev *dev, 

    uint16_t port_num, uint8_t control, uint32_t length, 

    INTEL_SSGDMA_ADDR_T src, INTEL_SSGDMA_ADDR_T dest, 

    uint32_t host_interface_control, uint32_t device_interface_control, 

    uint32_t max_length_per_desc, bool irq_en_last_desc) 

Include 

<intel_ssgdma.h> 

Parameters 
  •  dev - pointer to the SSGDMA device structure. 
  •  port_num - port number of interface. (starts from 0). 
  •  control - control field of the descriptor. 
  •  length - length of the data. 
  •  host_addr - start address of the source data (host). 
  •  dev_addr - start address of the destination (device). 
  •  host_interface_control - Set host attributes for AXI protocol. 
  •  device_interface_control - Set device attributes for AXI protocol. 
  •  max_length_per_desc - Maximum length of the data per descriptor. 
  •  irq_en_last_desc - enable interrupt for last filled descriptor. 

Return 

E_INTEL_SSGDMA_OK :  0  -> Success. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid device port number or length of data is 0. 

E_INTEL_SSGDMA_NO_INITI : -2  -> Device port is not setup or port_csr_base is 0. Please check setup or init.  

E_INTEL_SSGDMA_Q_FULL : -7  -> Queue is full. 

E_INTEL_SSGDMA_NOT_ENOUGH_DESC : -11 -> q_size is not enough. Please reset and set larger size or reduce the number of descriptors. 

E_INTEL_SSGDMA_ADDRESS_OVERFLOW : -12 -> Overflow of address would happen, before all data is transferred.

Please check start address. 

Description 

Fills the next descriptor to write from host to external device memory. 

Please setup the device port (intel_ssgdma_setup_device_port) before using this function. 

Notes: 

  • Descriptor index is initialized by calling intel_ssgdma_setup_device_port. 
  • For host_interface_control and device_interface_control, please refer to AMBA AXI and ACE Protocol Specification and use the macro   INTEL_SSGDMA_SET_INTERFACE_CONTROL_FIELD to set the values. 
  • Please refer to intel_ssgdma_descriptor.h for bit mask of control. 
  • The input max_length_per_desc can be used to split a chunk of data into several descriptors. Each descriptor is limited with max_length_per_desc. 

    Example: length = 1032 and max_length_per_desc = 128, 9 descriptors are filled by this API. 

  • If max_length_per_desc is set to 0, the driver overwrites this value with UINT32_MAX. Only one descriptor is filled per API call. 
Table 110.  intel_ssgdma_fill_d2h_mem

Prototype 

intel_ssgdma_return_e intel_ssgdma_fill_d2h_mem(intel_ssgdma_dev *dev, 

    uint16_t port_num, uint8_t control, uint32_t length, 

    INTEL_SSGDMA_ADDR_T src, INTEL_SSGDMA_ADDR_T dest, 

    uint32_t host_interface_control, uint32_t device_interface_control, 

    uint32_t max_length_per_desc, bool irq_en_last_desc) 

Include 

<intel_ssgdma.h> 

Parameters 
  •  dev                                   - pointer to the SSGDMA device structure. 
  •  port_num                             - port number of interface. (starts from 0). 
  •  control                                  - control field of the descriptor. 
  •  length                                    - length of the data. 
  •  host_addr                            - start address of the source data (host). 
  •  dev_addr                             - start address of the destination (device). 
  •  host_interface_control      - Set host attributes for AXI protocol. 
  •  device_interface_control  - Set device attributes for AXI protocol. 
  •  max_length_per_desc       - Maximum length of the data per descriptor. 
  •  irq_en_last_desc                - enable interrupt for last filled descriptor. 

Return 

E_INTEL_SSGDMA_OK                                  :  0  -> Success. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid device port number  or length of data is 0. E_INTEL_SSGDMA_NO_INITI                       : -2  -> Device port is not setup or port_csr_base is 0.

Please check setup or init. 

E_INTEL_SSGDMA_Q_FULL                          : -7  -> Queue is full. 

E_INTEL_SSGDMA_NOT_ENOUGH_DESC  : -11 -> q_size is not enough. Please reset and set larger size or reduce the number of descriptors. 

E_INTEL_SSGDMA_ADDRESS_OVERFLOW : -12 -> Overflow of address would happen, before all data is transferred. 

Please check start address. 

Description 

Fills the next descriptor to read from external device to host memory. 

Please setup the device port (intel_ssgdma_setup_device_port) before using this function. 

Notes: 

  • Descriptor index is initialized by calling intel_ssgdma_setup_device_port. 
  • For host_interface_control and device_interface_control, please refer to AMBA AXI and ACE Protocol Specification and use the macro INTEL_SSGDMA_SET_INTERFACE_CONTROL_FIELD to set the values. 
  • Please refer to intel_ssgdma_descriptor.h for bit mask of control. 
  • The input max_length_per_desc can be used to split a chunk of data into several descriptors. Each descriptor is limited with max_length_per_desc. 

    Example: length = 1032 and max_length_per_desc = 128, 9 descriptors are filled by this API. 

  • If max_length_per_desc is set to 0, the driver overwrites this value with UINT32_MAX. Only one descriptor is filled per API call. 
Table 111.  intel_ssgdma_check_current_resp_for_completion

Prototype 

intel_ssgdma_resp_return_e intel_ssgdma_check_current_resp_for_completion( 

    intel_ssgdma_dev *dev, intel_ssgdma_port_type_e port_type, 

    unsigned int port_num) 

Include 

<intel_ssgdma.h> 

Parameters 
  • dev            - pointer to the SSGDMA device structure. 
  • port_type  - type of port (D2H_ST, H2D_ST, H2D_MM). 
  • port_num  - port number of interface. (starts from 0). 

Return 

E_INTEL_SSGDMA_RESP_PENDING           :  0  -> current responder is still pending 

E_INTEL_SSGDMA_RESP_COMPLETED     :  1  -> current responder is completed. 

E_INTEL_SSGDMA_RESP_INVALID_PORT : -2  -> device port is invalid. 

E_INTEL_SSGDMA_RESP_NOT_ENABLED : -3  -> responder is not enabled by driver. 

E_INTEL_SSGDMA_RESP_NO_PENDING  : -4  -> there are no pending dma transfer. 

Description 

This function evaluates current responder to checks if a pending dma transfer 

is completed. Current responder refers to the first responder, that is still not processed by the software. Current responder tracked internally by the driver. Please do not modify the complete status of responder manually, as this may cause the internal tracking to malfunction. 

You can use this function to poll for completion, if they did not enable any interrupt for completion. This function does not block. 

intel_ssgdma_setup_device_port should be called before this function. 
Table 112.  intel_ssgdma_get_last_completed_desc_hw_idx 

Prototype 

int intel_ssgdma_get_last_completed_desc _hw_idx(intel_ssgdma_dev *dev, 

    intel_ssgdma_port_type_e port_type, uint16_t port_num) 

Include 

<intel_ssgdma.h> 

Parameters 
  • dev             - pointer to the SSGDMA device structure. 
  • port_type   - type of port (D2H_ST, H2D_ST, H2D_MM). 
  • port_num   - port number of interface. (starts from 0). 

Return 

 sw_extract_hw_idx                -> Hardware index of last completed descriptor. 

 0                                                -> No completed descriptor. 

 INTEL_SSGDMA_ERROR : -1 -> Invalid port_type and port_num. 

Description 

This function returns the hardware index of the last completed descriptor. 
Table 113.  intel_ssgdma_set_resp_ptr_tmp_idx 

Prototype 

intel_ssgdma_return_e intel_ssgdma_set_resp_ptr_tmp_idx(intel_ssgdma_dev *dev, 

    intel_ssgdma_port_type_e port_type, uint16_t port_num, 

    uint16_t previous_n_resp) 

Include 

<intel_ssgdma.h> 

Parameters 
  • dev                           - pointer to the SSGDMA device structure. 
  • port_type                - type of port (D2H_ST, H2D_ST, H2D_MM). 
  • port_num                - port number of interface. (starts from 0). 
  • previous_n_resp    - previous n completed responder. 

Return 
  • E_INTEL_SSGDMA_OK                                  :  0  -> Success. 
  • E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid arguments. 
  • E_INTEL_SSGDMA_RESP_DISABLED           : -3  -> responder block is disabled. 

Description 

Set helper index to backtrace previously completed descriptor. 

The input previous_n_resp defines how many descriptors should be back traced. 

previous_n_resp can be obtained from intel_ssgdma_complete_callback or intel_ssgdma_device_port_poll_for_completion. 

After calling this function, please use intel_ssgdma_get_next_tmp_resp to get the next resp_ptr for evaluation. 
Table 114.  intel_ssgdma_get_next_tmp_resp

Prototype 

const intel_ssgdma_hw_queue_desc *intel_ssgdma_get_next_tmp_resp( 

    intel_ssgdma_dev *dev, intel_ssgdma_port_type_e port_type, 

    uint16_t port_num) 

Include 

<intel_ssgdma.h> 

Parameters 
  • dev                           - pointer to the SSGDMA device structure. 
  • port_type                - type of port (D2H_ST, H2D_ST, H2D_MM). 
  • port_num                - port number of interface. (starts from 0). 

Return 
  • NULL                        - invalid device port or responder not enabled. 
  • resp_ptr                  -pointer to responder for evaluation. 

Description 

Before calling this function, please call intel_ssgdma_set_resp_ptr_tmp_idx to set resp_ptr_tmp_idx to the correct position. 

Based on the number of completed descriptors, this function should be called in a loop to evaluate the responders. The number of completed descriptors can be obtained from intel_ssgdma_complete_callback or intel_ssgdma_device_port_poll_for_completion. 
Note: The driver only clears the complete status of the responder. 

Please check the other fields of the responder, for example, DeviceError status or EarlyTermination status. 
Level Two Title