6.2.4. intel_ssgdma_device_port.c

Scalable Scatter-Gather DMA FPGA IP User Guide

Download PDF

ID 823097

Date 9/22/2025

Version

Public

6.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.