QDMA DPDK PMD Exported APIs¶

Xilinx QDMA DPDK Interface Definitions

Header file rte_pmd_qdma.h defines data structures and functions exported by QDMA DPDK PMD.

These APIs are subject to change.

enum rte_pmd_qdma_rx_bypass_mode¶: Supported bypass modes in C2H direction

Constants

RTE_PMD_QDMA_RX_BYPASS_NONE: Bypass mode is disabled i.e., internal QDMA mode is enabled
RTE_PMD_QDMA_RX_BYPASS_CACHE: Cache bypass mode, where in the prefetch engine keeps the order of the descriptors to pair with the C2H data packet from the user
RTE_PMD_QDMA_RX_BYPASS_SIMPLE: Simple bypass mode, where in the user application keeps the order of the descriptors to pair with the C2H data packet from the user
RTE_PMD_QDMA_RX_BYPASS_MAX: Unsupported value

Description

Rx (C2H) queue can be configured in one of these bypass modes.

enum rte_pmd_qdma_tx_bypass_mode¶: Supported bypass modes in H2C direction

Constants

RTE_PMD_QDMA_TX_BYPASS_NONE: Bypass mode is disabled i.e., internal QDMA mode is enabled
RTE_PMD_QDMA_TX_BYPASS_ENABLE: H2C bypass mode
RTE_PMD_QDMA_TX_BYPASS_MAX: Unsupported value

Description

Tx (H2C) queue can be configured in one of these bypass modes.

enum rte_pmd_qdma_dir_type¶: Enum to specify the direction i.e. TX or RX

Constants

RTE_PMD_QDMA_TX: H2C or Tx direction
RTE_PMD_QDMA_RX: C2H or Rx direction
RTE_PMD_QDMA_DIR_TYPE_MAX: Unsupported value

enum rte_pmd_qdma_pci_func_type¶: Indicates the type of PCIe function i.e., PF or VF

Constants

RTE_PMD_QDMA_PCI_FUNC_PF: PCIe Physical Function
RTE_PMD_QDMA_PCI_FUNC_VF: PCIe Virtual Function
RTE_PMD_QDMA_PCI_FUNC_TYPE_MAX: Unsupported value

enum rte_pmd_qdma_queue_mode_t¶: Indicates queue interface i.e., Memory mapped or Streaming

Constants

RTE_PMD_QDMA_MEMORY_MAPPED_MODE: Memory mapped mode
RTE_PMD_QDMA_STREAMING_MODE: Streaming mode
RTE_PMD_QDMA_QUEUE_MODE_MAX: Unsupported value

Description

Each queue must be configured in one of these modes.

enum rte_pmd_qdma_tigger_mode_t¶: Indicates the completion trigger mode

Constants

RTE_PMD_QDMA_TRIG_MODE_DISABLE: Completions are not trigerred
RTE_PMD_QDMA_TRIG_MODE_EVERY: Completions are trigerred on every event
RTE_PMD_QDMA_TRIG_MODE_USER_COUNT: Completions are trigerred when specified count of packets is reached
RTE_PMD_QDMA_TRIG_MODE_USER: Completions are trigerred on user defined event
RTE_PMD_QDMA_TRIG_MODE_USER_TIMER: Completions are trigerred on every expiry of the specified time
RTE_PMD_QDMA_TRIG_MODE_USER_TIMER_COUNT: Completions are trigerred either on expiry of specified time or when specified count of packets is reached, whichever is earlier.
RTE_PMD_QDMA_TRIG_MODE_MAX: Unsupported value

enum rte_pmd_qdma_cmpt_desc_len¶: Indicates the completion descriptor size

Constants

RTE_PMD_QDMA_CMPT_DESC_LEN_8B: Completion descriptor size of 8 Bytes
RTE_PMD_QDMA_CMPT_DESC_LEN_16B: Completion descriptor size of 16 Bytes
RTE_PMD_QDMA_CMPT_DESC_LEN_32B: Completion descriptor size of 32 Bytes
RTE_PMD_QDMA_CMPT_DESC_LEN_64B: Completion descriptor size of 64 Bytes
RTE_PMD_QDMA_CMPT_DESC_LEN_MAX: Unsupported value

enum rte_pmd_qdma_bypass_desc_len¶: Indicates the descriptor size of the queue configured in bypass mode

Constants

RTE_PMD_QDMA_BYPASS_DESC_LEN_8B: Bypass descriptor size of 8 Bytes
RTE_PMD_QDMA_BYPASS_DESC_LEN_16B: Bypass descriptor size of 16 Bytes
RTE_PMD_QDMA_BYPASS_DESC_LEN_32B: Bypass descriptor size of 32 Bytes
RTE_PMD_QDMA_BYPASS_DESC_LEN_64B: Bypass descriptor size of 64 Bytes
RTE_PMD_QDMA_BYPASS_DESC_LEN_MAX: Unsupported value

enum rte_pmd_qdma_xdebug_type¶: Indicates the type debug information to dump

Constants

RTE_PMD_QDMA_XDEBUG_QDMA_GLOBAL_CSR: Dump QDMA Global CSR registers
RTE_PMD_QDMA_XDEBUG_QDMA_DEVICE_STRUCT: Dump QDMA device structure maintained by driver
RTE_PMD_QDMA_XDEBUG_QUEUE_INFO: Dump queue contexts maintained by HW and queue specific software information
RTE_PMD_QDMA_XDEBUG_QUEUE_DESC_DUMP: Dump descriptor information of a queue
RTE_PMD_QDMA_XDEBUG_MAX: Unsupported value

enum rte_pmd_qdma_xdebug_desc_type¶: Indicates the type of queue descriptor ring to dump

Constants

RTE_PMD_QDMA_XDEBUG_DESC_C2H: Dump C2H queue’s descriptor
RTE_PMD_QDMA_XDEBUG_DESC_H2C: Dump H2C queue’s descriptor
RTE_PMD_QDMA_XDEBUG_DESC_CMPT: Dump completion queue’s descriptor
RTE_PMD_QDMA_XDEBUG_DESC_MAX: Unsupported value

enum rte_pmd_qdma_device_type¶: Indicates the type of QDMA device

Constants

RTE_PMD_QDMA_DEVICE_SOFT: Soft IP on Ultrascale+ device
RTE_PMD_QDMA_DEVICE_VERSAL: VERSAL device
RTE_PMD_QDMA_DEVICE_VERSAL_CPM5: VERSAL CPM5 device
RTE_PMD_QDMA_DEVICE_NONE: Not a valid QDMA device

enum rte_pmd_qdma_versal_ip_type¶: Indicates the type of QDMA Versal IP

Constants

RTE_PMD_QDMA_VERSAL_HARD_IP: Hard IP
RTE_PMD_QDMA_VERSAL_SOFT_IP: Soft IP
RTE_PMD_QDMA_VERSAL_NONE: Not a versal device

struct rte_pmd_qdma_xdebug_desc_param¶: Defines the parameters needed to dump descriptor information when RTE_PMD_QDMA_XDEBUG_QUEUE_DESC_DUMP is selected

Definition

struct rte_pmd_qdma_xdebug_desc_param {
  uint16_t queue;
  int start;
  int end;
  enum rte_pmd_qdma_xdebug_desc_type type;
};

Members

queue: Queue id of the ring whose descriptor dump is required
start: First index in the ring from where to start the dump
end: Last index in the descriptor ring to dump
type: Type of queue descriptor ring to dump

struct rte_pmd_qdma_dev_attributes¶: QDMA device attributes

Definition

struct rte_pmd_qdma_dev_attributes {
  uint8_t num_pfs;
  uint16_t num_qs;
  uint8_t flr_present:1;
  uint8_t st_en:1;
  uint8_t mm_en:1;
  uint8_t mm_cmpt_en:1;
  uint8_t mailbox_en:1;
  uint8_t mm_channel_max;
  uint8_t cmpt_ovf_chk_dis:1;
  uint8_t sw_desc_64b:1;
  uint8_t cmpt_desc_64b:1;
  uint8_t cmpt_trig_count_timer:1;
  enum rte_pmd_qdma_device_type device_type;
  enum rte_pmd_qdma_versal_ip_type versal_ip_type;
};

Members

num_pfs: Number of PFs
num_qs: Number of Queues supported
flr_present: Indicates FLR support present or not
st_en: Indicates ST mode support present or not
mm_en: Indicates MM mode support present or not
mm_cmpt_en: Indicates MM with Completions supported or not
mailbox_en: Indicates Mailbox supported or not
mm_channel_max: Number of MM channels
cmpt_ovf_chk_dis: Indicates support of overflow check disable in CMPT ring
sw_desc_64b: Indicates support of 64 bytes C2H/H2C descriptor format
cmpt_desc_64b: Indicates support of 64 bytes CMPT descriptor format
cmpt_trig_count_timer: Indicates support of counter + timer trigger mode
device_type: QDMA Device Type
versal_ip_type: Versal IP Type

int rte_pmd_qdma_dbg_regdump(uint8_t portid)¶: Dumps the QDMA configuration registers for the given port.

Parameters

uint8_t portid: Port ID

Return

‘0’ on success, ‘< 0’ on failure

int rte_pmd_qdma_dbg_qdevice(uint8_t portid)¶: Dumps the device specific SW structure for the given port.

Parameters

uint8_t portid: Port ID

Return

‘0’ on success, ‘< 0’ on failure

int rte_pmd_qdma_dbg_qinfo(uint8_t portid, uint16_t queue)¶: Dumps the queue contexts and queue specific SW structures for the given queue ID.

Parameters

uint8_t portid: Port ID
uint16_t queue: Queue ID relative to the Port

Return

‘0’ on success, ‘< 0’ on failure

int rte_pmd_qdma_dbg_qdesc(uint8_t portid, uint16_t queue, int start, int end, enum rte_pmd_qdma_xdebug_desc_type type)¶: Dumps the Queue descriptors.

Parameters

uint8_t portid: Port ID
uint16_t queue: Queue ID relative to the Port
int start: start index of the descriptor to dump
int end: end index of the descriptor to dump
enum rte_pmd_qdma_xdebug_desc_type type: Descriptor type

Return

‘0’ on success, ‘< 0’ on failure

int rte_pmd_qdma_get_bar_details(int portid, int32_t * config_bar_idx, int32_t * user_bar_idx, int32_t * bypass_bar_idx)¶: Returns the BAR indices of the QDMA BARs

Parameters

int portid: Port ID
int32_t * config_bar_idx: Config BAR index
int32_t * user_bar_idx: User BAR index
int32_t * bypass_bar_idx: Bypass BAR index

Return

‘0’ on success, ‘< 0’ on failure

int rte_pmd_qdma_get_queue_base(int portid, uint32_t * queue_base)¶: Returns queue base for given port

Parameters

int portid: Port ID
uint32_t * queue_base: queue base

Return

‘0’ on success, ‘< 0’ on failure

Note

Application can call this API only after successful call to rte_eth_dev_configure() API.

int rte_pmd_qdma_get_pci_func_type(int portid, enum rte_pmd_qdma_pci_func_type * func_type)¶: Retrieves PCI function type i.e. PF or VF

Parameters

int portid: Port ID
enum rte_pmd_qdma_pci_func_type * func_type: Indicates pci function type

Return

‘0’ on success, ‘< 0’ on failure

Note

This API returns the PCIe function type i.e. PF or VF of the given port.

int rte_pmd_qdma_get_immediate_data_state(int portid, uint32_t qid, int * state)¶: Returns immediate data state i.e. whether enabled or disabled, for the specified queue

Parameters

int portid: Port ID
uint32_t qid: Queue ID
int * state: Pointer to the state specifying whether immediate data is enabled or not

Return

‘0’ on success, ‘< 0’ on failure

Note

Application can call this function after rte_eth_rx_queue_setup() is called. This API is applicable for streaming queues only.

int rte_pmd_qdma_set_queue_mode(int portid, uint32_t qid, enum rte_pmd_qdma_queue_mode_t mode)¶: Sets queue interface mode for the specified queue

Parameters

int portid: Port ID
uint32_t qid: Queue ID
enum rte_pmd_qdma_queue_mode_t mode: Queue interface mode to be set

Return

‘0’ on success, ‘< 0’ on failure

Note

Application can call this API after successful call to rte_eth_dev_configure() but, before calling rte_eth_tx_queue_setup()/rte_eth_rx_queue_setup() API. By default, all queues are setup in Streaming mode.

int rte_pmd_qdma_set_immediate_data_state(int portid, uint32_t qid, uint8_t state)¶: Sets immediate data state i.e. enable or disable, for the specified queue. If enabled, the user defined data in the completion ring are dumped in to a queue specific file “q_<qid>_immmediate_data.txt” in the local directory.

Parameters

int portid: Port ID
uint32_t qid: Queue ID
uint8_t state: Immediate data state to be set. Set ‘0’ to disable and ‘1’ to enable

Return

‘0’ on success, ‘< 0’ on failure

Note

Application can call this API after successful call to rte_eth_dev_configure() API. Application can also call this API after successful call to rte_eth_rx_queue_setup() only if rx queue is not in start state. This API is applicable for streaming queues only.

int rte_pmd_qdma_set_cmpt_overflow_check(int portid, uint32_t qid, uint8_t enable)¶: Enables or disables the overflow check (whether PIDX is overflowing the CIDX) performed by QDMA on the completion descriptor ring of specified queue.

Parameters

int portid: Port ID
uint32_t qid: Queue ID
uint8_t enable: ‘1’ to enable and ‘0’ to disable the overflow check

Return

‘0’ on success, ‘< 0’ on failure

Note

Application can call this API after successful call to rte_eth_dev_configure() API. Application can also call this API after successful call to rte_eth_rx_queue_setup()/ rte_pmd_qdma_dev_cmptq_setup() API only if rx/cmpt queue is not in start state.

int rte_pmd_qdma_set_cmpt_descriptor_size(int portid, uint32_t qid, enum rte_pmd_qdma_cmpt_desc_len size)¶: Configures the completion ring descriptor size

Parameters

int portid: Port ID
uint32_t qid: Queue ID
enum rte_pmd_qdma_cmpt_desc_len size: Descriptor size to be configured

Return

‘0’ on success, ‘< 0’ on failure

Note

Application can call this API after successful call to rte_eth_dev_configure() but before rte_eth_rx_queue_setup() API when queue is in streaming mode, and before rte_pmd_qdma_dev_cmptq_setup when queue is in memory mapped mode. By default, the completion desciptor size is set to 8 bytes.

int rte_pmd_qdma_set_cmpt_trigger_mode(int portid, uint32_t qid, enum rte_pmd_qdma_tigger_mode_t mode)¶: Configures the trigger mode for completion ring CIDX updates

Parameters

int portid: Port ID
uint32_t qid: Queue ID
enum rte_pmd_qdma_tigger_mode_t mode: Trigger mode to be configured

Return

‘0’ on success, ‘< 0’ on failure

Note

Application can call this API after successful call to rte_eth_dev_configure() API. Application can also call this API after successful call to rte_eth_rx_queue_setup()/rte_pmd_qdma_dev_cmptq_setup() API only if rx/cmpt queue is not in start state.

int rte_pmd_qdma_set_cmpt_timer(int portid, uint32_t qid, uint32_t value)¶: Configures the timer interval in microseconds to trigger the completion ring CIDX updates

Parameters

int portid: Port ID
uint32_t qid: Queue ID
uint32_t value: Timer interval for completion trigger to be configured

Return

‘0’ on success, ‘< 0’ on failure

Note

Application can call this API after successful call to rte_eth_dev_configure() API. Application can also call this API after successful call to rte_eth_rx_queue_setup()/rte_pmd_qdma_dev_cmptq_setup() API only if rx/cmpt queue is not in start state.

int rte_pmd_qdma_set_c2h_descriptor_prefetch(int portid, uint32_t qid, uint8_t enable)¶: Enables or disables prefetch of the descriptors by prefetch engine

Parameters

int portid: Port ID
uint32_t qid: Queue ID
uint8_t enable: ‘1’ to enable and ‘0’ to disable the descriptor prefetch

Return

‘0’ on success, ‘< 0’ on failure

Note

Application can call this API after successful call to rte_eth_dev_configure() API. Application can also call this API after successful call to rte_eth_rx_queue_setup() API, only if rx queue is not in start state.

int rte_pmd_qdma_set_mm_endpoint_addr(int portid, uint32_t qid, enum rte_pmd_qdma_dir_type dir, uint32_t addr)¶: Sets the PCIe endpoint memory offset at which to perform DMA operation for the specified queue operating in memory mapped mode.

Parameters

int portid: Port ID
uint32_t qid: Queue ID
enum rte_pmd_qdma_dir_type dir: Queue direction i.e. Tx or Rx
uint32_t addr: Destination address for Tx, Source address for Rx

Return

‘0’ on success, ‘< 0’ on failure

Note

This API can be called before Tx/Rx burst API’s (rte_eth_tx_burst() and rte_eth_rx_burst()) are called.

int rte_pmd_qdma_configure_tx_bypass(int portid, uint32_t qid, enum rte_pmd_qdma_tx_bypass_mode bypass_mode, enum rte_pmd_qdma_bypass_desc_len size)¶: Sets the TX bypass mode and bypass descriptor size for the specified queue

Parameters

int portid: Port ID.
uint32_t qid: Queue ID.
enum rte_pmd_qdma_tx_bypass_mode bypass_mode: Bypass mode to be set
enum rte_pmd_qdma_bypass_desc_len size: Bypass descriptor size to be set

Return

‘0’ on success, ‘< 0’ on failure.

Note

Application can call this API after successful call to rte_eth_dev_configure() but before calling rte_eth_tx_queue_setup() API. By default, all queues are configured in internal mode i.e. bypass disabled. If size is specified zero, then the bypass descriptor size is set to the one used in internal mode.

int rte_pmd_qdma_configure_rx_bypass(int portid, uint32_t qid, enum rte_pmd_qdma_rx_bypass_mode bypass_mode, enum rte_pmd_qdma_bypass_desc_len size)¶: Sets the RX bypass mode and bypass descriptor size for the specified queue

Parameters

int portid: Port ID.
uint32_t qid: Queue ID.
enum rte_pmd_qdma_rx_bypass_mode bypass_mode: Bypass mode to be set
enum rte_pmd_qdma_bypass_desc_len size: Bypass descriptor size to be set

Return

‘0’ on success, ‘< 0’ on failure.

Note

Application can call this API after successful call to rte_eth_dev_configure() but before calling rte_eth_rx_queue_setup() API. By default, all queues are configured in internal mode i.e. bypass disabled. If size is specified zero, then the bypass descriptor size is set to the one used in internal mode.

int rte_pmd_qdma_get_device_capabilities(int portid, struct rte_pmd_qdma_dev_attributes * dev_attr)¶: Retrive the device capabilities

Parameters

int portid: Port ID.
struct rte_pmd_qdma_dev_attributes * dev_attr: Pointer to the device capabilities structure

Return

‘0’ on success, ‘< 0’ on failure.

int rte_pmd_qdma_dev_cmptq_setup(int portid, uint32_t qid, uint16_t nb_cmpt_desc, unsigned int socket_id)¶: Allocate and set up a completion queue for memory mapped mode.

Parameters

int portid: Port ID.
uint32_t qid: Queue ID.
uint16_t nb_cmpt_desc: Completion queue ring size.
unsigned int socket_id: The socket_id argument is the socket identifier in case of NUMA. Its value can be SOCKET_ID_ANY if there is no NUMA constraint for the DMA memory allocated for the transmit descriptors of the ring.

Return

‘0’ on success and ‘< 0’ on failure.

Note

Application can call this API after successful call to rte_eth_dev_configure() and rte_pmd_qdma_set_queue_mode() for queues in memory mapped mode.

int rte_pmd_qdma_dev_cmptq_start(int portid, uint32_t qid)¶: Start the MM completion queue.

Parameters

int portid: Port ID.
uint32_t qid: Queue ID.

Return

‘0’ on success and ‘< 0’ on failure.

Note

Application can call this API after successful call to rte_pmd_qdma_dev_cmptq_setup() API when queue is in memory mapped mode.

int rte_pmd_qdma_dev_cmptq_stop(int portid, uint32_t qid)¶: Stop the MM completion queue.

Parameters

int portid: Port ID.
uint32_t qid: Queue ID.

Return

‘0’ on success and ‘< 0’ on failure.

Note

Application can call this API after successful call to rte_pmd_qdma_dev_cmptq_start() API when queue is in memory mapped mode.

uint16_t rte_pmd_qdma_mm_cmpt_process(int portid, uint32_t qid, void * cmpt_buff, uint16_t nb_entries)¶: Process the MM Completion queue entries.

Parameters

int portid: Port ID.
uint32_t qid: Queue ID.
void * cmpt_buff: User buffer pointer to store the completion data.
uint16_t nb_entries: Number of compeltion entries to process.

Return

‘number of entries processed’ on success and ‘< 0’ on failure.

Note

Application can call this API after successful call to rte_pmd_qdma_dev_cmptq_start() API.