Scalable Scatter-Gather DMA FPGA IP User Guide

Download PDF
ID 823097
Date 9/22/2025
Public
Document Table of Contents
Document Table of Contents x
1. Product Discontinuance Notification 2. Terms and Acronyms 3. Introduction 4. Functional Description 5. Interfaces 6. HAL Driver for DMA SoC Mode  7. Parameters 8. Registers 9. Document Revision History for the Scalable Scatter-Gather DMA Intel® FPGA IP User Guide
3. Introduction x
3.1. Device Family Support 3.2. Release Information 3.3. Resource Utilization
4. Functional Description x
4.1. DMA PCIe* Mode 4.2. DMA SoC Mode 4.3. Device Port 4.4. Prefetcher Engine 4.5. DMA Arbiter 4.6. DMA Router 4.7. CSRUnit 4.8. Descriptor Handling 4.9. Interrupts 4.10. Reset Initialization Flows 4.11. Transaction Flow
4.1. DMA PCIe* Mode x
4.1.1. Submodules
4.1.1. Submodules x
4.1.1.1. PCIe* TLP Constructor 4.1.1.2. PCIe* TLP ID Generation 4.1.1.3. PCIe TX Credit Controller 4.1.1.4. PCIe* TX Scheduler 4.1.1.5. PCIe TLP Completer 4.1.1.6. PCIe RX Router 4.1.1.7. PCIe* MSI-X Controller 4.1.1.8. PCIe BAR0 4.1.1.9. PCIe Bursting Manager (BAM) 4.1.1.10. Completion Timeout Parser 4.1.1.11. Control Shadow Parser
4.2. DMA SoC Mode x
4.2.1. Interrupt Controller 4.2.2. Host AXI-4 Agent 4.2.3. Host CSR AXI-4 Lite Agent
4.3. Device Port x
4.3.1. ST Source Agent/ST Sink Agent/MM Agent 4.3.2. Descriptor Engine 4.3.3. Agent Controller 4.3.4. Constructor 4.3.5. Responder 4.3.6. Width Adaptation FIFO
4.8. Descriptor Handling x
4.8.1. Link Descriptor 4.8.2. Data Descriptor 4.8.3. Responder Descriptor 4.8.4. Descriptor Chain 4.8.5. Aligned and Unaligned Transfer Support
4.8.2. Data Descriptor x
4.8.2.1. Data Descriptor - H2D Streaming Transfer 4.8.2.2. Data Descriptor - D2H Streaming Transfer 4.8.2.3. Data Descriptor - H2D Memory Transfer
4.8.3. Responder Descriptor x
4.8.3.1. Responder Descriptor - H2D Streaming Transfer 4.8.3.2. Responder Descriptor - D2H Streaming Transfer 4.8.3.3. Responder Descriptor - H2D Memory Transfer
4.8.4. Descriptor Chain x
4.8.4.1. Descriptor Fetch and Status Update Mechanism
4.11. Transaction Flow x
4.11.1. General DMA Operation Flow 4.11.2. Host to Device (H2D) Flow 4.11.3. Device to Host (D2H) Flow 4.11.4. Soft Reset Handshake Flow
5. Interfaces x
5.1. Port List 5.2. DMA PCIe* Mode Interfaces 5.3. DMA SoC Mode Interfaces 5.4. Device Port Interfaces 5.5. Resets 5.6. Clocks
5.2. DMA PCIe* Mode Interfaces x
5.2.1. Application Packet Receive Interface 5.2.2. Application Packet Transmit Interface 5.2.3. Control Shadow Interface 5.2.4. Transmit Flow Control Credit Interface 5.2.5. Completion Timeout Interface 5.2.6. PCIe* Miscellaneous Signals 5.2.7. Control and Status Register Responder Manager Interface 5.2.8. Bursting Manager Interface
5.3. DMA SoC Mode Interfaces x
5.3.1. Host AXI-4 Memory Map Manager Interface 5.3.2. Host AXI-4 Lite CSR Memory Map Subordinate Interface 5.3.3. Interrupt Interface
5.4. Device Port Interfaces x
5.4.1. Device to Host <PORT#> AXI-ST Subordinate Interface 5.4.2. Device to Host <PORT#> Avalon-ST Sink Interface 5.4.3. Host to Device <PORT#> AXI-ST Manager Interface 5.4.4. Host to Device <PORT#> Avalon-ST Source Interface 5.4.5. Host to Device <PORT#> AXI-4 Manager Interface
6. HAL Driver for DMA SoC Mode  x
6.1. Descriptor Indexing  6.2. HAL Public API 
6.1. Descriptor Indexing  x
6.1.1. Data Descriptors  6.1.2. Responders 
6.2. HAL Public API  x
6.2.1. Software Features 6.2.2. intel_ssgdma.c  6.2.3. intel_ssgdma_global.c 6.2.4. intel_ssgdma_device_port.c  6.2.5. intel_ssgdma_descriptor.c 
7. Parameters x
7.1. DMA Settings 7.2. Device Port Settings 7.3. DMA PCIe Mode Settings 7.4. DMA SoC Mode Settings 7.5. Example Design
7.2. Device Port Settings x
7.2.1. H2D MM 7.2.2. H2D ST 7.2.3. D2H ST
8. Registers x
8.1. Global CSR 8.2. MSI-X Memory Space 8.3. Device Port Control Register
1. Product Discontinuance Notification
2. Terms and Acronyms
3. Introduction
4. Functional Description
5. Interfaces
6. HAL Driver for DMA SoC Mode 
7. Parameters
8. Registers
9. Document Revision History for the Scalable Scatter-Gather DMA Intel® FPGA IP User Guide

8.3. Device Port Control Register

Device Port CSR space contains individual port control and status information as well as the Responder table. The register space supports up to 8 ports(H2D/D2H), where each port is allocated up to 2 kB region of register space. However, the actual number depends on the parameters input at IP generation time.
Table 134.  Device Port CSR
Address Description
[10:0] Registers for the ports
[14:11] Port number, 0, 1...7
[17:15] Reserve
[19:18] 0 = D2H ST, 1=H2D ST, 2=H2D MM, 3 = Reserved

The following registers are defined for H2D/D2H ports. The base address for each port is different based on the given parameters configured in build time:

NUM_H2D_MM_PORTS = 1, NUM_H2D_ST_PORTS = 1, NUM_D2H_ST_PORTS = 1

Device Port Type H2D MM H2D ST D2H ST
Port 0 22’h280000 22’h240000 22’h200000

NUM_H2D_MM_PORTS = 3, NUM_H2D_ST_PORTS = 4, NUM_D2H_ST_PORTS = 2

Device Port Type H2D MM H2D ST D2H ST
Port 0 22’h280000 22’h240000 22’h200000
Port 1 22’h280800 22’h240800 22’h200800
Port 2 22’h281000 22’h241000 NA
Port 3 NA 22’h241800 NA

NUM_H2D_MM_PORTS = 2, NUM_H2D_ST_PORTS = 3, NUM_D2H_ST_PORTS = 0

Device Port Type H2D MM H2D ST D2H ST
Port 0 22’h280000 22’h240000 NA
Port 1 22’h280800 22’h240800 NA
Port 3 NA 22’h241000 NA
Table 135.  Device Port Register Map
Register Name Address Offset Access Type Description
Q_CTRL 0x0 R/W/W1S/RO

Control register.
Q_STATUS 0x4 R/W1C/RO

Status register.
Q_START_ADDR_L 0x8 R/W Lower 32-bit of queue base address in system memory. This is the beginning of the linked list of 4KB pages containing the descriptors.
Q_START_ADDR_H 0xC R/W Upper 32-bit of queue base address in system memory. This is the beginning of the linked list of 4KB pages containing the descriptors.
Q_SIZE 0x10 R/W/RO Number of max descriptor block entries in a queue.
Q_EXTRACT_POINTER 0x14 RO Current pointer to the last descriptor that was completed. This register is updated by Prefetcher Engine.
Q_INSERT_POINTER 0x18 R/W Current pointer to the last valid descriptor queue entry in the host memory.
RESERVED 0x1C - 0x28 RO Reserved.
Q_SCRATCH 0x2C R/W Scratch register
Q_BYTEACK 0x30 R/W Number of bytes acknowledged by Host for video flushing event. Applicable to D2H ST port only.
Q_BYTESSENT 0x34 RO Number of bytes transferred for D2H ST for video flushing event. Applicable to D2H ST port only.
Q_PORT_PARAM1 0x38 RO The parameter settings configured during IP Generation time.
Q_RESP_SIZE 0x3C R/W The actual number of responder block entries that is configured by software in the Responder table.
Q_EXTRACT_POINTER_ACK 0x40 R/W/RO Pointer to the last descriptor that was acknowledged and serviced by software.
RESERVED 0x44-0x3FC RO Reserved.
Q_RESPONDER_ADDR_L

0x400+(#n*0x8)

 R/W
  • Lower 32-bit of responder base address in system memory. This is the base address for each 4KB page which is capable to cater up to 128 write-back descriptor entries.
  • #n: 0, 1, 2, 3…127
  • Offset values: 0x400, 0x408,…,0x7F8.
Note: The Q_RESPONDER_ADDR_L value configured by software must be aligned to 4kB page boundary by setting the bits[11:0] to zero.
Q_RESPONDER_ADDR_H 0x404+(#n*0x8) R/W
  • Upper 32-bit of responder base address in system memory. This is the base address for each 4KB page which is capable to cater up to 128 write-back descriptor entries.
  • #n: 0, 1, 2, 3…127
  • Offset values: 0x404, 0x40C,…,0x7FC.
Note:
  • W1C register attribute means software can write 1 to clear the field. Software writing 0 to this field has no effect.
  • W1S register attribute means software can write 1 to set the field. Software writing 0 to this field has no effect.
Table 136.  Q_CTRL (Offset 0x0)
Bit [31:0] Name R/W Access Default Description
[31:8] rsvd RO 0 Reserved.
[7:6] unused_qcsr_ctrl_bit R/W 0 This field is set to 0. Write access to this field has no effect.
[5] q_en R/W1S 0

Enable. Once it is set, the Prefetcher Engine is able to forward descriptors to descriptor engine. This bit is cleared when following conditions are fulfilled:

  • q_pause_agent_control bit is set
  • q_sw_reset_req bit is set
  • hard reset
  • completion timeout.
[4] wb_en R/W 1 Enable write back upon descriptor completion. By default, the write back/response are enabled and host processor can decide whether write-back is triggered based on the granularity level of each descriptor.
[3] prefetch_irq_en R/W 1 Enable interrupt generation in the event if any unexpected descriptor fetching issue happened from Prefetcher Engine. By default, the write back/response are enabled and host processor can decide whether interrupt is triggered based on the granularity level of each descriptor.
[2] irq_en R/W 1 Enable interrupt generation upon descriptor completion. By default, the write back/response are enabled and host processor can decide whether interrupt is triggered based on the granularity level of each descriptor.
[1] q_pause_agent_control R/W1S 0
  • Setting this bit to pause the agent controller in the middle of the operation. Any occurring transaction is allowed to complete. This bit is cleared upon acknowledgement of the issued request.
  • Read the paused status register to determine when the agent controller has paused. After stop operation, the agent controller defaults to a start mode of operation.
  • The q_en bit is also cleared, software required to set q_en bit to resume the device agent operation.
[0] q_sw_reset_req R/W1S 0
Software set this bit to issue a reset request to the device port. Software is responsible to follow the reset sequence as described in reset initialization flow section before write to the reset request bit. This bit is cleared upon acknowledgement of the issued request. The SSGDMA IP acknowledges this bit and proceed to execute the following tasks:
  • Monitor if q_agent_control_paused bit is asserted.
  • Set the q_resetting bit to indicate the initialization of reset cycle.
  • Reset all registers of the device agent to initial state.
  • Clear the q_resetting bit to indicate the completion of reset cycle.

Since resets can take multiple clock cycles to complete due to transfers being in flight on the fabric, software reads the q_resetting bit from Q_STATUS register to determine when a full reset cycle has completed.
Table 137.  Q_STATUS (Offset 0x4)
Bit [31:0] Name R/W Access Default Description
[31] q_irq R/W1C 0
Set when there is an interrupt asserted based on any event happening as indicated from bits[30:27]. Software should poll this bit in all available device ports and check on the bits[30:27] to identify the source of interrupt assertion and clearing it. 
Note: Applicable for DMA SoC mode only. For DMA PCIe* mode, the interrupt source is coming from MSI-X TLP to PCIe* host.
[30] rsvd RO 0 Reserved
[29]

q_prefetch_error 

 R/W1C 0

Set when there is any unexpected issue/error(for example, response timeout) happened during descriptor fetching from Prefetcher Engine. Software should poll and clear this bit upon receiving any interrupt issued from SSGDMA. 
[28]

q_desc_completion 

R/W1C 

 0

Set upon descriptor completion from hardware. Software should poll and clear this bit upon receiving any interrupt issued from SSGDMA. 

Before the software clears this bit, the software updates Q_EXTRACT_POINTER_ACK to acknowledge that the descriptor has been serviced. This bit remains asserted by hardware if Q_EXTRACT_POINTER and Q_EXTRACT_POINTER_ACK are mismatched.

 
Note: Applicable only for DMA SoC mode. 
[27] q_video_flushing_event R/W1C 0 Set when the SSGDMA IP has transferred an intermediate flushed packet to the host upon a detected flushing event at the D2H AXI-ST Subordinate Interface. Software should poll and clear this bit upon receiving any interrupt issued from the SSGDMA.
Note: Applicable for DMA SoC mode and D2H ST device port type only.
[26:24] unused_qcst_status_field R/W 0 This field is set to 0. Write access to this field has no effect.
[23:8] rsvd RO 0 Reserved
[7] unused_qcsr_status_bit R/W 0 This field is set to 0. Write access to this field has no effect.
[6] q_agent_control_paused R/W1C 0

This bit is asserted after the agent controller has completed all transactions that were already in progress upon the q_pause_agent_control bit assertion in Q_CTRL register.

Set when following conditions are fulfilled:
  • Controller is in idle state.
  • Constructor has completed any occurring transactions.
  • Responder has received all occurring responses. Software polls for this bit and decides the subsequent actions:
    • Action 1: Clear the bit and set q_en bit to resume the device port operation.
    • Action 2: Set the q_sw_reset_req bit to request soft reset sequence on the device port.
[5] q_resp_buffer_full RO 0 Set when the response buffer is full.
[4] q_resp_buffer_empty RO 1 Set when the response buffer is empty.
[3] q_descr_buffer_full RO 0 Set when the descriptor buffer is full.
[2] q_descr_buffer_empty RO 1 Set when the descriptor buffer is empty.
[1] q_resetting RO 0
  • Set when software set the q_sw_reset_req bit from Q_CTRL and the device port is in the middle of a reset cycle. This bit is cleared by hardware upon reset completion.
  • This reset cycle is necessary to make sure there are no incoming transfers on the fabric. When this bit de-asserts software can start using the device port again.
[0] q_busy RO 0 Set when following conditions fulfill:
  • The descriptor engine still has commands/ responses buffered.
  • Constructor is still transferring data.
  • Responder is waiting for responses to return if the remaining responses are still returning.
  • ST agent is still transferring/ receiving data.
This bit is cleared by hardware when the following conditions are fulfilled:
  • q_sw_reset_req bit is set
  • hard reset
Note: If there is packet transferring in the middle, the valid is de-asserted however there won't be any EOP generated. User logic is responsible to handle it when q_pause_agent_control bit is set in this case.
Table 138.  Q_START_ADDR_L (0x8)
Bit [31:0] Name R/W Access Default Description
[31:0] q_strt_addr_l R/W 0
After software allocate the descriptor ring buffer, it writes the lower 32-bit allocated address to this register. The Prefetcher Engine uses this address and the pending Insert/Extract pointer to fetch the descriptors.
Note: The Q_START_ADDR_L configured by software must be aligned to 4kB page boundary by setting the bits[11:0] to zero.
Table 139.  Q_START_ADDR_H (0xC)
Bit [31:0] Name R/W Access Default Description
[31:0] q_strt_addr_h R/W 0 After software allocate the descriptor ring buffer, it writes the upper 32-bit allocated address to this register. The Prefetcher Engine uses this address and the pending Insert/Extract pointer to fetch the descriptors.
Table 140.  Q_SIZE (0x10)
Bit [31:0] Name R/W Access Default Description
[31:8] rsvd RO 0 Reserved.
[7:0] q_size RW 1

The number of descriptor block entries allocated by software during the Initialization flow. A value of 1 indicates one descriptor block with 4k in size(up to 128 descriptors) is allocated in the system memory.

The maximum entries is up to 255 descriptor block entries.

Note: Altera recommends you to allocate identical buffer sizes to both q_resp_size and q_size for optimized performance. The SSGDMA IP defaults to using a value of 1 if an illegal value, for example, 0 is written.
Table 141.  Q_EXTRACT_POINTER (0x14)
Bit [31:0] Name R/W Access Default Description
[31:16] rsvd RO 0 Reserved.
[15:0] q_extr_ptr RO 0 After SSGDMA completed the descriptors from the descriptor buffer, up to the Q_INSERT_POINTER, it updates this register with that last completed descriptor position. The Prefetcher Engine only fetches descriptors if the Q_INSERT_POINTER and Q_EXTRACT_POINTER are not equal.
Table 142.  Q_INSERT_POINTER (0x18)
Bit [31:0] Name R/W Access Default Description
[31:16] rsvd RO 0 Reserved.
[15:0] q_ins_ptr R/W 0 After software sets up a last valid descriptor in the descriptor buffer, it programs this register with the position of the last valid descriptor that is ready to be executed. The Prefetcher Engine fetches descriptors from the buffer up to this position of the buffer.
Table 143.  Q_SCRATCH (0x2C)
Bit [31:0] Name R/W Access Default Description
[31:0] q_scratch R/W 0 Scratch register for testing register read and write operations.
Table 144.  Q_BYTEACK (0x30)
Bit [31:0] Name R/W Access Default Description
[31:0] q_byteack R/W 0 Number of bytes acknowledged by the host for video flushing event. Applicable for the D2H ST port only.
Table 145.  Q_BYTESSENT (0x34)
Bit [31:0] Name R/W Access Default Description
[31:0] q_bytessent RO 0

Number of bytes transferred for the D2H ST port for video flushing event. Applicable to the D2H ST port only.
Table 146.  Q_PORT_PARAM1 (0x38)
Bit [31:0] Name R/W Access Default Description
[31:10] rsvd RO 0 Reserved.
[9] st_ptp_port_en RO Build time configured Build time configured. Enable PTP Timestamp Input parameter setting. Applicable for ST Device Port Type only.
[8] st_port_pkt_mode RO Build time configured Build time configured packet-based mode setting. Applicable for ST Device Port Type only.
[7] st_port_int_type RO Build time configured Build time configured interface type setting. Applicable for ST Device Port Type only.
  • 0: AXI-ST
  • 1: Avalon-ST
[6] rsvd RO 0 Reserved
[5] d2h_st_port_init_flush_en RO Build time configured Build time configured. Enable Flush for D2H_ST Port Upon Initialization parameter settings. Applicable for D2H ST Device Port type only.
[4:0] rsvd RO 0 Reserved
Table 147.  Q_RESP_SIZE (0x3C)
Bit [31:0] Name R/W Access Default Description
[31:8] rsvd RO 0 Reserved
[7:0] q_resp_size R/W 1
  • The actual number of responder block entries that is configured by software in the Responder table.
  • The maximum entries is up to 128 responder block entries, software need to set this according to actual block entries allocated in the system memory. E.g. If there are only 4 responder blocks allocated by software (for example, only 4 entries are configured to the responder table), the value of 4 is set to this register in this case.
Note:

Altera recommends you to allocate identical buffer sizes to both q_resp_size and q_size for optimized performance.

If software is not required, there is a responder write back, the software should only set the wb_en in the Q_CTRL register to zero.

The SSGDMA IP defaults to using a value of 1 if an illegal value, for example, 0 is written.
Table 148.  Q_EXTRACT_POINTER_ACK (0x40)
Bit [31:0] Name R/W Access Default Description
SW HW
[31:16] rsvd RO NA 0
Reserved.
Note: Write access to this field responds with slave error when parameter Enable error response status for Host AXI-4 Lite CSR Interface is set to 1 for DMA SoC mode.
[15:0] q_extr_ptr_ack R/W RO 0

The position of the last descriptor that is acknowledged and serviced by software.

When Q_EXTRACT_POINTER_ACK and Q_EXTRACT_POINTER are mismatched, it means that there is pending descriptor to be served. Hardware asserts the interrupt for descriptor completion by setting q_desc_completion bit in the Q_STATUS register.
Note: Applicable only for DMA SoC mode.

Q_RESPONDER_ADDR_L and Q_RESPONDER_ADDR_H (0x400 - 0x7FF)

Responder Table memory space is mapped to a 1kB region (0x400 - 0x7FF) of the Device Port CSR register space. Allocated memory space can support up to 128 Responder block entries. Actual amount of memory depends on the IP configuration. The Responder Table Array contains two DWORDs which consists of Upper & Lower Responder Address(64 bits/8 bytes). The Responder Table format is shown below.

Figure 24. Responder Table Structure
Level Two Title