DPDK Callback APIs

QEP DPDK driver Callbacks

Callback APIs implemented by the QEP DPDK driver are described below.

int eth_qdma_dev_init(struct rte_eth_dev * dev)

DPDK callback to register an Ethernet PCIe device.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.

Description

The Following actions are performed by this function:
  • Parse and validate device arguments
  • Identify PCIe BARs present in the device
  • Register device operations
  • Register PCIe device with Queue Resource Manager
  • Program the QDMA IP global registers
  • Enable HW errors and launch QDMA HW error monitoring thread
  • Read MAC address from the device and populate in the DPDK maintained device structure

Return

0 on success, < 0 on failure.

int qdma_dev_configure(struct rte_eth_dev * dev)

DPDK callback for Ethernet device configuration.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.

Description

This API requests the queue base from Queue Resource Manager and programs the queue base and queue count in function map (FMAP). Configures the C2H user logic in round robin mode of packets distribution to the Rx queues.

Return

0 on success, < 0 on failure.

void qdma_dev_infos_get(__rte_unused struct rte_eth_dev * dev, struct rte_eth_dev_info * dev_info)

DPDK callback to get information about the device.

Parameters

__rte_unused struct rte_eth_dev * dev
Pointer to Ethernet device structure.
struct rte_eth_dev_info * dev_info
Pointer to Device information structure.

DPDK callback to retrieve the physical link information.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
int wait_to_complete
If 0, get the current link status else, wait till the Ethernet link is up or timeout is reached

DPDK callback to Link up an Ethernet device.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.

Return

0 on success, < 0 on failure.

DPDK callback to Link down an Ethernet device.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.

Return

0 on success, < 0 on failure.

int qdma_dev_rx_queue_setup(struct rte_eth_dev * dev, uint16_t rx_queue_id, uint16_t nb_rx_desc, unsigned int socket_id, const struct rte_eth_rxconf * rx_conf, struct rte_mempool * mb_pool)

DPDK callback to configure a RX queue.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
uint16_t rx_queue_id
RX queue index relative to the device pointed by dev.
uint16_t nb_rx_desc
Number of C2H descriptors to configure for this queue.
unsigned int socket_id
NUMA socket on which memory must be allocated.
const struct rte_eth_rxconf * rx_conf
Rx queue configuration parameters.
struct rte_mempool * mb_pool
Memory pool to use for buffer allocations on this queue.

Description

This API validates queue parameters and allocates Streaming C2H ring and CMPT ring from the DPDK reserved hugepage Memory zones

Return

0 on success, < 0 on failure.

int qdma_dev_tx_queue_setup(struct rte_eth_dev * dev, uint16_t tx_queue_id, uint16_t nb_tx_desc, unsigned int socket_id, const struct rte_eth_txconf * tx_conf)

DPDK callback to configure a TX queue.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
uint16_t tx_queue_id
TX queue index relative to the device pointed by dev.
uint16_t nb_tx_desc
Number of descriptors to configure in queue.
unsigned int socket_id
NUMA socket on which memory must be allocated.
const struct rte_eth_txconf * tx_conf
Tx queue configuration parameters.

Description

This API validates queue parameters and allocates H2C ring from the DPDK reserved hugepage Memory zone

Return

0 on success, < 0 on failure.

int qdma_dev_start(struct rte_eth_dev * dev)

DPDK callback to start the device.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.

Description

This API resets the C2H/H2C user logic and starts the Ethernet device by initializing CMAC, Rx/Tx descriptors and device registers. For the Port queues whose start is not deferred, it calls qdma_dev_tx_queue_start and qdma_dev_rx_queue_start to start the queues for packet processing. It also creates a thread to monitor CMAC link status.

Return

0 on success, < 0 on failure.

int qdma_dev_rx_queue_start(struct rte_eth_dev * dev, uint16_t qid)

DPDK callback to start a C2H queue which has been deferred start.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
uint16_t qid
Rx queue index.

Description

This API clears and then programs the Software, Prefetch and Completion context of the C2H queue

Return

0 on success, < 0 on failure.

int qdma_dev_tx_queue_start(struct rte_eth_dev * dev, uint16_t qid)

DPDK callback to start a H2C queue which has been deferred start.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
uint16_t qid
Tx queue index.

Description

This API clears and then programs the Software context of the H2C queue

Return

0 on success, < 0 on failure.

uint16_t qdma_recv_pkts(void * rx_queue, struct rte_mbuf ** rx_pkts, uint16_t nb_pkts)

DPDK callback for receiving packets in burst.

Parameters

void * rx_queue
Generic pointer to Rx queue structure.
struct rte_mbuf ** rx_pkts
The address of an array of pointers to rte_mbuf structures that must be large enough to store nb_pkts pointers in it.
uint16_t nb_pkts
Maximum number of packets to retrieve.

Description

This API does following operations:
  • Process the Completion ring to determine and store packet information
  • Update CMPT CIDX
  • Process C2H ring to retrieve rte_mbuf pointers corresponding to received packets and store in rx_pkts array.
  • Populate C2H ring with new pointers for packet buffers
  • Update C2H ring PIDX

Return

Number of packets successfully received (<= nb_pkts).

uint16_t qdma_xmit_pkts(void * tx_queue, struct rte_mbuf ** tx_pkts, uint16_t nb_pkts)

DPDK callback for transmitting packets in burst.

Parameters

void * tx_queue
Generic pointer to Tx queue structure.
struct rte_mbuf ** tx_pkts
The address of an array of nb_pkts pointers to rte_mbuf structures which contain the output packets.
uint16_t nb_pkts
The maximum number of packets to transmit.

Description

This API does following operations:
  • Free rte_mbuf pointers to previous transmitted packets, back to the memory pool
  • Retrieve packet buffer pointer from tx_pkts and populate H2C ring with pointers to new packet buffers.
  • Update H2C ring PIDX

Return

Number of packets successfully transmitted (<= nb_pkts).

const uint32_t * qep_dev_supported_ptypes_get(struct rte_eth_dev * dev)

DPDK callback to get packet types supported and identified by device.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.

Return

Pointer to an array of type uint32_t indicating supported packet types. Returns NULL if called from secondary application.
int qdma_dev_stats_get(struct rte_eth_dev * dev, struct rte_eth_stats * eth_stats)

DPDK callback for retrieving Port statistics.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
struct rte_eth_stats * eth_stats
Pointer to structure containing statistics.

Description

This API updates Port statistics in rte_eth_stats structure parameters.

Return

0 on success, < 0 on failure.

int qdma_dev_queue_stats_mapping(struct rte_eth_dev * dev, uint16_t queue_id, uint8_t stat_idx, uint8_t is_rx)

DPDK callback to set a queue statistics mapping for a tx/rx queue of an Ethernet device.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
uint16_t queue_id
Index of the queue for which a queue stats mapping is required.
uint8_t stat_idx
The per-queue packet statistics functionality number that the queue_id is to be assigned.
uint8_t is_rx
Whether queue is a Rx or a Tx queue.

Return

0 on success, -EINVAL on failure.
int qep_dev_xstats_get_names(__rte_unused struct rte_eth_dev * dev, struct rte_eth_xstat_name * xstats_names, __rte_unused unsigned int size)

DPDK callback to get names of extended stats of the device.

Parameters

__rte_unused struct rte_eth_dev * dev
Pointer to Ethernet device structure.
struct rte_eth_xstat_name * xstats_names
Array of name values to be filled in.
__rte_unused unsigned int size
Number of elements in the xstats_names array.

Description

This API updates extended statistics names in xstats_names structure array.

Return

The number of stats names filled into the array.

int qep_dev_xstats_get_names_by_id(struct rte_eth_dev * dev, struct rte_eth_xstat_name * xstats_names, const uint64_t * ids, unsigned int size)

DPDK callback to get names of extended stats of the device.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
struct rte_eth_xstat_name * xstats_names
An rte_eth_xstat_name array of at least size elements to be filled. If set to NULL, the function returns the required number of elements.
const uint64_t * ids
IDs array given by app to retrieve specific statistics
unsigned int size
Number of elements in the xstats_names array

Return

Success: A positive value lower or equal to size. The return value is the number of entries filled in the stats table.

Error: A positive value higher than size, the given statistics table is too small. The return value corresponds to the size that should be given to succeed. The entries in the table are not valid and shall not be used by the caller.

A negative value on other error

int qep_dev_xstats_get(__rte_unused struct rte_eth_dev * dev, struct rte_eth_xstat * xstats, unsigned int size)

DPDK callback to retrieve extended statistics of an Ethernet device.

Parameters

__rte_unused struct rte_eth_dev * dev
Pointer to Ethernet device structure.
struct rte_eth_xstat * xstats
Pointer to the array of structure to be filled with device statistics ids and values
unsigned int size
Number of elements in the xstats array

Description

This API updates device statistics ids and values in xstats structure array.

Return

The number of entries successfully filled into the xstats array

int qep_dev_xstats_get_by_id(struct rte_eth_dev * dev, const uint64_t * ids, uint64_t * values, unsigned int n)

DPDK callback to retrieve extended statistics of an Ethernet device by ID.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
const uint64_t * ids
A pointer to an ids array passed by application. This tells which statistics values function should retrieve.
uint64_t * values
A pointer to a table to be filled with device statistics values
unsigned int n
The size of the ids array (number of elements)

Return

A positive value lower or equal to size: success. The return value is the number of entries filled in the stats table. A positive value higher than size: error, the given statistics table is too small. The return value corresponds to the size that should be given to succeed. The entries in the table are not valid and shall not be used by the caller. A negative value on error.
int qdma_dev_mtu_set(struct rte_eth_dev * dev, uint16_t mtu)

DPDK callback to set MTU of an Ethernet device.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure
uint16_t mtu
MTU to set

Description

This API does following operations:
  • Validates the MTU size provided
  • Sets dev->data->dev_conf.rxmode.offloads to indicate support of Jumbo frames, based on the MTU size requested
  • Configures CMAC with new MTU size
  • Update dev->data->dev_conf.rxmode.max_rx_pkt_len with new MTU size

Return

The number of entries successfully filled into the xstats array

void qep_dev_rxq_info_get(struct rte_eth_dev * dev, uint16_t rx_queue_id, struct rte_eth_rxq_info * qinfo)

DPDK callback to get Rx queue info of an Ethernet device.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure
uint16_t rx_queue_id
The RX queue on the Ethernet device for which information will be retrieved
struct rte_eth_rxq_info * qinfo
A pointer to a structure of type rte_eth_rxq_info to be filled with the information of given Rx queue

Return

0 on success, < 0 on failure.

void qep_dev_txq_info_get(struct rte_eth_dev * dev, uint16_t tx_queue_id, struct rte_eth_txq_info * qinfo)

DPDK callback to get Tx queue info of an Ethernet device.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure
uint16_t tx_queue_id
The TX queue on the Ethernet device for which information will be retrieved
struct rte_eth_txq_info * qinfo
A pointer to a structure of type rte_eth_txq_info to be filled with the information of given Tx queue

Return

0 on success, < 0 on failure.

int qdma_dev_get_regs(struct rte_eth_dev * dev, struct rte_dev_reg_info * regs)

DPDK callback to retrieve device registers and register attributes (number of registers and register size)

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
struct rte_dev_reg_info * regs
Pointer to rte_dev_reg_info structure to fill in. If regs->data is NULL the function fills in the width and length fields. If non-NULL the registers are put into the buffer pointed at by the data field.

Return

0 on success, -ENOTSUP on failure.

uint32_t qdma_dev_rx_queue_count(struct rte_eth_dev * dev, uint16_t rx_queue_id)

DPDK callback to get the number of used descriptors of a rx queue.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
uint16_t rx_queue_id
The RX queue on the Ethernet device for which information will be retrieved

Return

The number of used descriptors in the specific queue.

int qdma_dev_rx_descriptor_status(void * rx_queue, uint16_t offset)

DPDK callback to check the status of a Rx descriptor in the queue.

Parameters

void * rx_queue
Pointer to Rx queue specific data structure.
uint16_t offset
The offset of the descriptor starting from tail (0 is the next packet to be received by the driver).

Return

  • (RTE_ETH_RX_DESC_AVAIL): Descriptor is available for the hardware to receive a packet.
  • (RTE_ETH_RX_DESC_DONE): Descriptor is done, it is filled by hw, but not yet processed by the driver (i.e. in the receive queue).
  • (RTE_ETH_RX_DESC_UNAVAIL): Descriptor is unavailable, either hold by the driver and not yet returned to hw, or reserved by the hw.
  • (-EINVAL) bad descriptor offset.
int qdma_dev_tx_descriptor_status(void * tx_queue, uint16_t offset)

DPDK callback to check the status of a Tx descriptor in the queue.

Parameters

void * tx_queue
Pointer to Tx queue specific data structure.
uint16_t offset
The offset of the descriptor starting from tail (0 is the place where the next packet will be send).

Return

  • (RTE_ETH_TX_DESC_FULL) Descriptor is being processed by the hw, i.e. in the transmit queue.
  • (RTE_ETH_TX_DESC_DONE) Hardware is done with this descriptor, it can be reused by the driver.
  • (RTE_ETH_TX_DESC_UNAVAIL): Descriptor is unavailable, reserved by the driver or the hardware.
  • (-EINVAL) bad descriptor offset.
int qdma_dev_tx_done_cleanup(void * tx_queue, uint32_t free_cnt)

DPDK callback to request the driver to free mbufs currently cached by the driver.

Parameters

void * tx_queue
Pointer to Tx queue specific data structure.
uint32_t free_cnt
Maximum number of packets to free. Use 0 to indicate all possible packets should be freed. Note that a packet may be using multiple mbufs.

Return

Failure < 0 Success >= 0 0-n : Number of packets freed. More packets may still remain in ring that are in use.
int qep_dev_rss_reta_query(struct rte_eth_dev * dev, struct rte_eth_rss_reta_entry64 * reta_conf, uint16_t reta_size)

DPDK callback to retrieve RSS Indirection table.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
struct rte_eth_rss_reta_entry64 * reta_conf
An Array of structure used to retrieve entries of Redirection Table of the Receive Side Scaling (RSS). Each element of array can have 64 entries.
uint16_t reta_size
Size of the RETA table

Return

0 on success, < 0 on failure.

int qep_dev_rss_reta_update(struct rte_eth_dev * dev, struct rte_eth_rss_reta_entry64 * reta_conf, uint16_t reta_size)

DPDK callback to update the RSS indirection table.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
struct rte_eth_rss_reta_entry64 * reta_conf
An Array of structure used to configure entries of Redirection Table of the Receive Side Scaling (RSS).Each element of array can have 64 entries. For each requested reta entry, corresponding bit in mask must be set.
uint16_t reta_size
Size of the RETA table.

Return

0 on success, a negative errno value on failure and rte_errno is set.

int qep_dev_rss_conf_get(struct rte_eth_dev * dev, struct rte_eth_rss_conf * rss_conf)

DPDK callback to get the RSS hash configuration.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
struct rte_eth_rss_conf * rss_conf
RSS configuration data to be stored.

Return

0 on success, a negative errno value on failure and rte_errno is set.

int qep_filter_ctrl(__rte_unused struct rte_eth_dev * dev, enum rte_filter_type filter_type, enum rte_filter_op filter_op, void * arg)

DPDK callback to get rte_flow callbacks and manage filter operations.

Parameters

__rte_unused struct rte_eth_dev * dev
Pointer to Ethernet device structure.
enum rte_filter_type filter_type
Filter type.
enum rte_filter_op filter_op
Operation to perform.
void * arg
Pointer to operation-specific structure.

Return

0 on success, < 0 on failure.

int qdma_dev_rx_queue_stop(struct rte_eth_dev * dev, uint16_t qid)

DPDK callback to stop a C2H queue

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
uint16_t qid
Rx queue index.

Description

This API invalidates Hardware, Software, Prefetch and completion contexts of C2H queue. It also free the rte_mbuf pointers assigned to descriptors prepared for packet reception.

Return

0 on success, < 0 on failure.

int qdma_dev_tx_queue_stop(struct rte_eth_dev * dev, uint16_t qid)

DPDK callback to stop a queue in H2C direction

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
uint16_t qid
TX queue index.

Description

This API invalidates Hardware, Software contexts of H2C queue. It also free the rte_mbuf pointers assigned to descriptors that are pending transmission.

Return

0 on success, < 0 on failure.

void qdma_dev_stop(struct rte_eth_dev * dev)

DPDK callback to stop the device.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.

Description

This API stops the device by invalidating all the contexts of all the queues belonging to the port by calling qdma_dev_tx_queue_stop and qdma_dev_rx_queue_stop for all the queues of the port.

int qdma_dev_reset(struct rte_eth_dev * dev)

DPDK callback to reset the device.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.

Return

0 on success, negative errno value on failure.

void qdma_dev_stats_reset(struct rte_eth_dev * dev)

DPDK callback to reset Port statistics.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
void qep_dev_xstats_reset(struct rte_eth_dev * dev)

DPDK callback to reset extended statistics of an Ethernet device.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
void qdma_dev_rx_queue_release(void * rqueue)

DPDK callback to release a Rx queue.

Parameters

void * rqueue
Generic Rx queue pointer.

Description

This API releases the descriptor rings and any additional memory allocated for given C2H queue

void qdma_dev_tx_queue_release(void * tqueue)

DPDK callback to release a Tx queue.

Parameters

void * tqueue
Generic Tx queue pointer.

Description

This API releases the descriptor rings and any additional memory allocated for given H2C queue

void qdma_dev_close(struct rte_eth_dev * dev)

DPDK callback to close the device.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.

Description

This API frees the descriptor rings and objects beonging to all the queues of the given port. Clears the FMAP (Queue range assigned to the port).

int eth_qdma_dev_uninit(struct rte_eth_dev * dev)

DPDK callback to deregister a PCI device.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.

Description

The Following actions are performed by this function:
  • Unregister PCIe device from Queue Resource Manager
  • Cancel QDMA HW error monitoring thread if created by this device
  • Frees up any memory allocated for the device

Return

0 on success, < 0 on failure.

int qep_flow_validate(struct rte_eth_dev * dev, const struct rte_flow_attr * attr, const struct rte_flow_item pattern, const struct rte_flow_action actions, struct rte_flow_error * error)

DPDK callback to check whether a flow rule can be created on a given dev.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
const struct rte_flow_attr * attr
Flow rule attributes.
const struct rte_flow_item pattern
Pattern specification (list terminated by the END pattern item).
const struct rte_flow_action actions
Associated actions (list terminated by the END action).
struct rte_flow_error * error
Perform verbose error reporting if not NULL.

Return

0 on success, < 0 on failure.

struct rte_flow * qep_flow_create(struct rte_eth_dev * dev, const struct rte_flow_attr * attr, const struct rte_flow_item pattern, const struct rte_flow_action actions, struct rte_flow_error * error)

DPDK callback to create flow on a given dev.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
const struct rte_flow_attr * attr
Flow rule attributes.
const struct rte_flow_item pattern
Pattern specification (list terminated by the END pattern item).
const struct rte_flow_action actions
Associated actions (list terminated by the END action).
struct rte_flow_error * error
Perform verbose error reporting if not NULL.

Return

0 on success, < 0 on failure.

int qep_flow_destroy(struct rte_eth_dev * dev, struct rte_flow * flow, struct rte_flow_error * error)

DPDK callback to destroy a flow rule on a given dev.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
struct rte_flow * flow
Device private flow rule handle to destroy.
struct rte_flow_error * error
Perform verbose error reporting if not NULL.

Return

0 on success, < 0 on failure.

int qep_flow_flush(struct rte_eth_dev * dev, __rte_unused struct rte_flow_error * error)

DPDK callback to destroy all flow rule on a given dev.

Parameters

struct rte_eth_dev * dev
Pointer to Ethernet device structure.
__rte_unused struct rte_flow_error * error
Perform verbose error reporting if not NULL.

Return

0 on success, < 0 on failure.