Scalable Scatter-Gather DMA Intel® FPGA IP User Guide

ID 823097
Date 4/07/2025
Public
Document Table of Contents

5.2.4. intel_ssgdma_device_port.c 

Table 88.  intel_ssgdma_queue_ctrl_writeback_set_state

Prototype 

intel_ssgdma_return_e intel_ssgdma_queue_ctrl_writeback_set_state( 

    intel_ssgdma_dev *dev, intel_ssgdma_port_type_e port_type, 

    uint16_t port_num, bool enable) 

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). 
  • enable        - 1 for enable and 0 for disable. 

Return 

E_INTEL_SSGDMA_OK                                  :  0  -> Success. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid arguments. 

E_INTEL_SSGDMA_NO_INITI                       : -2  -> Port_csr_base is 0. Check init. 

Description 

Enable or disable write back/response. 

By default, the write back/response are enabled in the hardware and host processor can decide whether write-back interrupt should be triggered based on the granularity level of each descriptor. 

Table 89.  intel_ssgdma_queue_ctrl_prefetch_irq_error_set_state

Prototype 

intel_ssgdma_return_e intel_ssgdma_queue_ctrl_prefetch_irq_error_set_state( 

    intel_ssgdma_dev *dev, intel_ssgdma_port_type_e port_type, 

    uint16_t port_num, bool enable) 

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). 
  • enable        - 1 for enable and 0 for disable. 

Return 

E_INTEL_SSGDMA_OK                                  :  0  -> Success. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid arguments. 

E_INTEL_SSGDMA_NO_INITI                       : -2  -> Port_csr_base is 0. Check init. 

Description 

Enable or disable interrupt generation in the event if any unexpected descriptor fetching issue happened from Prefetcher Engine. 

By default, the this is enabled in the hardware and host processor can decide whether interrupt should be triggered based on the granularity level of each descriptor. 

Table 90.  intel_ssgdma_queue_ctrl_irq_set_state

Prototype 

intel_ssgdma_return_e intel_ssgdma_queue_ctrl_irq_set_state( 

    intel_ssgdma_dev *dev, intel_ssgdma_port_type_e port_type, 

    uint16_t port_num, bool enable) 

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). 
  • enable        - 1 for enable and 0 for disable. 

Return 

E_INTEL_SSGDMA_OK                                  :  0  -> Success. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid arguments. 

E_INTEL_SSGDMA_NO_INITI                       : -2  -> Port_csr_base is 0. Check init. 

Description 

Enable or disable interrupt generation upon descriptor completion. 

By default, the this is enabled in the hardware and host processor can decide whether interrupt should be triggered based on the granularity level of each descriptor. 

Table 91.  intel_ssgdma_queue_get_size

Prototype 

intel_ssgdma_return_e intel_ssgdma_queue_get_size(intel_ssgdma_dev *dev, 

    intel_ssgdma_port_type_e port_type, uint16_t port_num, uint8_t *q_size_ptr) 

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). 
  • q_size_ptr   - pointer to return the hw value of q_size. 

Return 

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

E_INTEL_SSGDMA_INVALID_ARGUMENT  : -1  -> Invalid arguments. 

E_INTEL_SSGDMA_NO_INITI                        : -2  -> Port_csr_base is 0. Check init. 

Description 

Get the maximum number for descriptor blocks(q_size) by reading the hardware register. This value is stored in software, and written to the hardware when you call intel_ssgdma_setup_device_port (input value: desc_block_size). 

Table 92.  intel_ssgdma_queue_get_q_responder_size 

Prototype 

intel_ssgdma_return_e intel_ssgdma_queue_get_q_responder_size( 

    intel_ssgdma_dev *dev, intel_ssgdma_port_type_e port_type,  

    uint16_t port_num, uint8_t *q_resp_size_ptr) 

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). 
  • q_resp_size_ptr - pointer to return the hw value of q_resp_size. 

Return 

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

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid arguments. 

E_INTEL_SSGDMA_NO_INITI                       : -2  -> Port_csr_base is 0. Check init. 

Description 

Get the maximum number for responder blocks(q_resp_size) by reading the hardware register. This value is stored in software, and written to the hardware when you call intel_ssgdma_setup_device_port (input value: resp_block_size). 

Table 93.  intel_ssgdma_queue_get_extract_ptr

Prototype 

intel_ssgdma_return_e intel_ssgdma_queue_get_extract_ptr(intel_ssgdma_dev *dev, 

    intel_ssgdma_port_type_e port_type, uint16_t port_num, 

    uint16_t *extract_ptr) 

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). 
  • extract_ptr              - pointer to return the hw value of extract_ptr 

Return 

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

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid arguments. 

E_INTEL_SSGDMA_NO_INITI                       : -2  -> Port_csr_base is 0. Check init. 

Description 

Function to get extract pointer (index of last completed descriptor) from a device port. If user wish to block and poll for completion, intel_ssgdma_device_port_poll_for_completion can be used. 

 
Table 94.  intel_ssgdma_queue_get_insert_ptr

Prototype 

intel_ssgdma_return_e intel_ssgdma_queue_get_insert_ptr(intel_ssgdma_dev *dev, 

    intel_ssgdma_port_type_e port_type, uint16_t port_num, uint16_t *insert_ptr) 

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). 
  • insert_ptr               - pointer to return the hw value of insert_ptr 

Return 

E_INTEL_SSGDMA_OK                                  :  0  ->  Success. *insert_ptr is valid 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  ->  Invalid arguments. 

E_INTEL_SSGDMA_NO_INITI                       : -2  ->  Port_csr_base is 0. Check init. 

Description 

Function to get insert pointer (index of last valid descriptor in queue) from a device port. If you wish to block and poll for completion, intel_ssgdma_device_port_poll_for_completion can be used. 

Table 95.  intel_ssgdma_queue_update_insert_ptr 

Prototype 

intel_ssgdma_return_e intel_ssgdma_queue_update_insert_ptr( 

    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). 
  • DescrIDX - Descriptor index to set 

Return 

E_INTEL_SSGDMA_OK                                  :  0  -> Success. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid arguments. 

E_INTEL_SSGDMA_NO_INITI                       : -2  -> Port_csr_base is 0. Check init.

E_INTEL_SSGDMA_Q_DISABLED: -14 → please set q_en before updating ptr. 

Description 

Sets the index of last valid descriptor, by using the index tracked 

internally in software. You may fill a number of descriptor in the software, 

before setting the insert pointer at the hardware. 

This function blocks attempts to update the insert pointer if q_en is deasserted. If q_en is asserted, this function updates hardware with the index from software. 

Table 96.  intel_ssgdma_queue_get_status

Prototype 

intel_ssgdma_return_e intel_ssgdma_queue_get_status(intel_ssgdma_dev *dev, 

    intel_ssgdma_port_type_e port_type, uint16_t port_num, uint32_t *q_status) 

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). 
  • q_status    - pointer to return the status 

Return 

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

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid arguments. 

E_INTEL_SSGDMA_NO_INITI                       : -2  -> Port_csr_base is 0. Check init. 

Description 

Function to get status register of the device port. 

Table 97.  intel_ssgdma_queue_get_ctrl

Prototype 

intel_ssgdma_return_e intel_ssgdma_queue_get_ctrl(intel_ssgdma_dev *dev, 

    intel_ssgdma_port_type_e port_type, uint16_t port_num, uint32_t *q_ctrl) 

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). 
  • q_ctrl         - pointer to return the control value 

Return 

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

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid arguments. 

E_INTEL_SSGDMA_NO_INITI                       : -2  -> Port_csr_base is 0. Check init. 

Description 

Function to get control register of the device port. 

Table 98.  intel_ssgdma_queue_get port_param1

Prototype 

intel_ssgdma_return_e intel_ssgdma_queue_get_port_param1( 

    intel_ssgdma_dev *dev, intel_ssgdma_port_type_e port_type, 

    uint16_t port_num, uint32_t *port_param1) 

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). 
  • port_param1   - pointer to return hardware port parameters. 

Return 

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

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid arguments. 

E_INTEL_SSGDMA_NO_INITI                       : -2  -> Port_csr_base is 0. Check init. 

Description 

Function to get hardware port parameters. 

The parameter settings are configured in qsys. 

Table 99.  intel_ssgdma_setup_device_port 

Prototype 

intel_ssgdma_return_e intel_ssgdma_setup_device_port(intel_ssgdma_dev *dev, 

    intel_ssgdma_port_type_e port_type, uint16_t port_num, 

    uint16_t port_num, uint8_t desc_block_size, uint8_t resp_block_size); 

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). 
  • desc_block_size        - number of descriptor blocks. 
  • resp_block_size        - number of responder blocks. 

Return 

  • E_INTEL_SSGDMA_OK                                  :  0  -> Success. 
  • E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid arguments. 
  • E_INTEL_SSGDMA_NO_INITI                       : -2  -> Port_csr_base is 0. Check init. 
  • E_INTEL_SSGDMA_MEMALLOC_ERROR    : -4  -> Memory allocation error 
  • E_INTEL_SSGDMA_HW_SW_MISMATCH  : -8  -> the generated software configuration does not match with the hardware. 
  • E_INTEL_SSGDMA_ALREADY_SETUP          : -9  -> Device port already setup. 
  • Please reset before setup. 

Description 

Setup a device port. If intel_ssgdma_device_port_soft_reset is used 

to performed reset and reuse_setup is set, setup from last call of 

intel_ssgdma_setup_device_port is used, when intel_ssgdma_device_port_soft_resume is called. 

Note: 
  • Responders are written by the hardware to host memory. There is no backpressure for the responder. Therefore, you should consider setting the same desc_block_size and resp_block_size. If not, make sure that the responders are processed, before the hardware overwrites them. 
  • This memory allocated for data and responder descriptors are contiguous.
  • You need to manually edit the driver if they would like to allocate non-contiguous memory for descriptors. 
  • If this function is not called, most API in intel_ssgdma_descriptor.c would not work as expected. 
  • If input resp_block_size is 0, it does not mean that the driver sets q_resp_size to 0 for the hw. In this case, the driver clears QCSR_CTRL_WB_EN bit in QCSR_CTRL.
Table 100.  intel_ssgdma_device_port_poll_for_completion

Prototype 

intel_ssgdma_return_e intel_ssgdma_device_port_poll_for_completion( 

    intel_ssgdma_dev *dev, intel_ssgdma_port_type_e port_type, 

    uint16_t port_num, uint16_t *const completed_resp_num_ptr) 

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_OK                                  :  0  -> Transfer is completed. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid arguments. 

E_INTEL_SSGDMA_NO_INITI                       : -2  -> Port_csr_base is 0. Check init. 

E_INTEL_SSGDMA_TIMEOUT                      : -6  -> Polling timeout for completion 

E_INTEL_SSGDMA_HW_SW_MISMATCH  : -8  -> hw insert/extract pointer does not match with software. Please check if  intel_ssgdma_queue_update_insert_ptr is called before polling. Please also pause and reset the port. 

Description 

This function blocks and polls for transfer completion. 

A transfer is complete, when hw insert_pointer = extract_pointer. 

Before polling, please make sure that intel_ssgdma_queue_update_insert_ptr is called. In case of mismatch between insert/extract pointer of software/hardware, please pause and reset the port. 

Table 101.  intel_ssgdma_device_port_is_paused  

Prototype 

int intel_ssgdma_device_port_is_paused(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 

INTEL_SSGDMA_NO         :  0 -> If is not paused. 

INTEL_SSGDMA_YES        :  1 -> If is paused. 

INTEL_SSGDMA_ERROR  : -1 -> Invalid arguments or port_csr_base no init. 

Description 

This function checks if a device port is paused. It does not block. 

Table 102.  intel_ssgdma_device_port_soft_pause 

Prototype 

intel_ssgdma_return_e intel_ssgdma_device_port_soft_pause(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 

E_INTEL_SSGDMA_OK                                  :  0  -> Success. Device port is paused. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid input device. 

E_INTEL_SSGDMA_NO_INITI                       : -2  -> Port_csr_base is 0. Check init. 

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

Description 

This function blocks until a device port is paused. 

If blocking is not desired, you could refer to the flow in this function to implement their own function. 

Note: Soft pause is currently not supported for H2D_ST and H2D_MM ports.
Table 103.  intel_ssgdma_device_port_soft_reset 

Prototype 

intel_ssgdma_return_e intel_ssgdma_device_port_soft_reset(intel_ssgdma_dev *dev, intel_ssgdma_port_type_e port_type, uint16_t port_num, bool reuse_setup) 

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). 
  • reuse_setup - reuse previous setup. 

Return 

E_INTEL_SSGDMA_OK                                  :  0  -> Device port is ready. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid arguments. 

E_INTEL_SSGDMA_NO_INITI                       : -2  -> Port_csr_base is 0. Check init. 

E_INTEL_SSGDMA_BUSY                              : -5  -> Device port is not paused. 

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

Description 

This function blocks until a device port is reset. If E_INTEL_SSGDMA_BUSY is returned, please pause by calling intel_ssgdma_device_port_soft_pause. 

If blocking is not desired, you could refer to the flow in this function to implement their own function. 

Table 104.  intel_ssgdma_device_port_soft_resume 

Prototype 

intel_ssgdma_return_e intel_ssgdma_device_port_soft_resume( 

    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 

E_INTEL_SSGDMA_OK                                  :  0  -> Device port is resumed. 

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid arguments. 

E_INTEL_SSGDMA_NO_INITI                       : -2  -> Port_csr_base is 0. Check init. 

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

Description 

This function resumes a device port after paused or reset. 

Table 105.  intel_ssgdma_queue_get_device_port_error_flags

Prototype 

intel_ssgdma_return_e intel_ssgdma_queue_get_device_port_error_flags( 

    intel_ssgdma_dev *dev, intel_ssgdma_port_type_e port_type, 

    uint16_t port_num, uint16_t *error_flag) 

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). 
  • error_flag   - pointer to return the device port error flags. 

Return 

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

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid argument. 

Description 

Get the value of device_port_errors_flags. 

These flags are set to indicate abnormal operation during interrupt. 

Table 106.  intel_ssgdma_queue_clear_device_port_error_flags

Prototype 

intel_ssgdma_return_e intel_ssgdma_queue_clear_device_port_error_flags( 

    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 

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

E_INTEL_SSGDMA_INVALID_ARGUMENT : -1  -> Invalid argument. 

Description 

Get the value of device_port_errors_flags. 

These flags are set to indicate abnormal operation during interrupt and needs to be manually cleared. 

Table 107.  intel_ssgdma_get_device_port_csr_base

Prototype 

FPGA_MMIO_INTERFACE_HANDLE intel_ssgdma_get_device_port_csr_base( 

    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 

FPGA_MMIO_INTERFACE_HANDLE port_csr_base -> port csr base address. 

NULL -> Invalid argument or port_csr_base is not initialized. 

Description 

Get the port csr base address. This function returns NULL for an invalid port type and port number combination, or port_csr_base is not initialized.