Functions

qdma_eth_dev_init

Syntax:

int qdma_eth_dev_init (struct rte_eth_dev* dev)

Details:

DPDK callback to register an Ethernet PCIe device.

The Following actions are performed by this function:

  • Parse and validate device arguments
  • Identify PCIe BARs present in the device
  • Register device operations
  • Enable MM C2H and H2C channels
  • Register PCIe device with Queue Resource Manager
  • Program the QDMA IP global registers (by 1st PF that was probed)
  • Enable HW errors and launch QDMA HW error monitoring thread (by 1st PF that was probed)
  • If VF is enabled, then enable Mailbox interrupt and register Rx message handling function as interrupt handler

Parameters:

dev Pointer to Ethernet device structure

Returns:

0 on success, < 0 on failure

qdma_dev_configure

Syntax:

int qdma_dev_configure (struct rte_eth_dev* dev)

Details:

DPDK callback for Ethernet device configuration.

This API requests the queue base from Queue Resource Manager and programs the queue base and queue count in function map (FMAP)

Parameters:

dev Pointer to Ethernet device structure

Returns:

0 on success, < 0 on failure

qdma_dev_infos_get

Syntax:

int qdma_dev_infos_get (
    struct rte_eth_dev* dev,
    struct rte_eth_dev_info* dev_info
    )

Details:

DPDK callback to get information about the device

Parameters:

dev Pointer to Ethernet device structure
dev_info Pointer to Device information structure

qdma_dev_rx_queue_setup

Syntax:

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
    )

Details:

DPDK callback to configure a RX queue.

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

Parameters:

dev Pointer to Ethernet device structure.
rx_queue_id RX queue index relative to the PCIe function pointed by dev
nb_rx_desc Number of C2H descriptors to configure for this queue
socket_id NUMA socket on which memory must be allocated
rx_conf Rx queue configuration parameters
mb_pool Memory pool to use for buffer allocations on this queue

Returns:

0 on success, < 0 on failure

qdma_dev_tx_queue_setup

Syntax:

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
    )

Details:

DPDK callback to configure a TX queue.

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

Parameters:

dev Pointer to Ethernet device structure
tx_queue_id TX queue index
nb_tx_desc Number of descriptors to configure in queue
socket_id NUMA socket on which memory must be allocated
tx_conf Tx queue configuration parameters

Returns:

0 on success, < 0 on failure

qdma_dev_rxq_info_get

Syntax:

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

Details:

DPDK callback to get Rx queue info of an Ethernet device

Parameters:

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

qdma_dev_txq_info_get

Syntax:

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

Details:

DPDK callback to get Tx queue info of an Ethernet device

Parameters:

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

qdma_dev_start

Syntax:

int qdma_dev_start (struct rte_eth_dev* dev)

Details:

DPDK callback to start the device.

This API starts the Ethernet device by initializing 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.

Parameters:

dev Pointer to Ethernet device structure

Returns:

0 on success, < 0 on failure

qdma_dev_rx_queue_start

Syntax:

int qdma_dev_rx_queue_start (
    struct rte_eth_dev* dev,
    uint16_t qid
    )

Details:

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

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

Parameters:

dev Pointer to Ethernet device structure
qid Rx queue index

Returns:

0 on success, < 0 on failure

qdma_dev_tx_queue_start

Syntax:

int qdma_dev_tx_queue_start (
    struct rte_eth_dev* dev,
    uint16_t qid
    )

Details:

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

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

Parameters:

dev Pointer to Ethernet device structure
qid Tx queue index

Returns:

0 on success, < 0 on failure

qdma_recv_pkts

Syntax:

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

Details:

DPDK callback for receiving packets in burst.

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

Parameters:

rx_queue Generic pointer to Rx queue structure
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
nb_pkts Maximum number of packets to retrieve

Returns:

Number of packets successfully received (<= nb_pkts)

qdma_xmit_pkts

Syntax:

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

Details:

DPDK callback for transmitting packets in burst.

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

Parameters:

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

Returns:

Number of packets successfully transmitted (<= nb_pkts)

qdma_dev_stats_get

Syntax:

int qdma_dev_stats_get (
    struct rte_eth_dev* dev,
    struct rte_eth_stats* eth_stats
    )

Details:

DPDK callback for retrieving Port statistics.

This API updates Port statistics in rte_eth_stats structure parameters

Parameters:

dev Pointer to Ethernet device structure
eth_stats Pointer to structure containing statistics

Returns:

0 on success, < 0 on failure

qdma_dev_stats_reset

Syntax:

int qdma_dev_stats_reset (struct rte_eth_dev* dev)

Details:

DPDK callback to reset Port statistics.

Parameters:

dev Pointer to Ethernet device structure.

qdma_dev_queue_stats_mapping

Syntax:

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

Details:

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

Parameters:

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

Returns:

0 on success, -EINVAL on failure

qdma_dev_rx_queue_count

Syntax:

uint32_t qdma_dev_rx_queue_count (
    struct rte_eth_dev* dev,
    uint16_t rx_queue_id
    )

Details:

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

Parameters:

dev Pointer to Ethernet device structure
rx_queue_id The RX queue on the Ethernet device for which information will be retrieved

Returns:

The number of used descriptors in the specific queue

qdma_dev_rx_descriptor_status

Syntax:

int qdma_dev_rx_descriptor_status (
    void* rx_queue,
    uint16_t offset
    )

Details:

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

Parameters:

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

Returns:

  • (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.

qdma_dev_tx_descriptor_status

Syntax:

int qdma_dev_tx_descriptor_status (
    void* tx_queue,
    uint16_t offset
    )

Details:

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

Parameters:

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

Returns:

  • (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.

qdma_dev_tx_done_cleanup

Syntax:

int qdma_dev_tx_done_cleanup (
    void* tx_queue,
    uint32_t free_cnt
    )

Details:

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

Parameters:

tx_queue Pointer to Tx queue specific data structure
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.

Returns:

  • Failure: < 0
  • Success: >= 0 0-n: Number of packets freed. More packets may still remain in ring that are in use.

qdma_dev_get_regs

Syntax:

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

Details:

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

Parameters:

dev Pointer to Ethernet device structure
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.

Returns:

0 on success, -ENOTSUP on failure

qdma_dev_rx_queue_stop

Syntax:

int qdma_dev_rx_queue_stop (
    struct rte_eth_dev* dev,
    uint16_t qid
    )

Details:

DPDK callback to stop a C2H queue

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.

Parameters:

dev Pointer to Ethernet device structure
qid Rx queue index

Returns:

0 on success, < 0 on failure

qdma_dev_tx_queue_stop

Syntax:

int qdma_dev_tx_queue_stop (
    struct rte_eth_dev* dev,
    uint16_t qid
    )

Details:

qdma_dev_tx_queue_stop() - DPDK callback to stop a queue in H2C direction

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

Parameters:

dev Pointer to Ethernet device structure
qid TX queue index

Returns:

0 on success, < 0 on failure

qdma_dev_stop

Syntax:

int qdma_dev_stop (struct rte_eth_dev* dev)

Details:

DPDK callback to stop the device.

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.

Parameters:

dev Pointer to Ethernet device structure

qdma_dev_rx_queue_release

Syntax:

void qdma_dev_rx_queue_release (void* rqueue)

Details:

DPDK callback to release a Rx queue.

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

Parameters:

rqueue Generic Rx queue pointer

qdma_dev_tx_queue_release

Syntax:

void qdma_dev_tx_queue_release (void* tqueue)

Details:

DPDK callback to release a Tx queue.

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

Parameters:

tqueue Generic Tx queue pointer

qdma_dev_close

Syntax:

int qdma_dev_close (struct rte_eth_dev* dev)

Details:

DPDK callback to close the device.

This API frees the descriptor rings and objects beonging to all the queues of the given port. It also clears the FMAP.

Parameters:

dev Pointer to Ethernet device structure

qdma_vf_dev_close

Syntax:

int qdma_vf_dev_close (struct rte_eth_dev* dev)

Details:

DPDK callback to close the VF device.

This API frees the descriptor rings and objects beonging to all the queues of the given port. It also clears the FMAP.

Parameters:

dev Pointer to Ethernet device structure

qdma_dev_reset

Syntax:

int qdma_dev_reset (struct rte_eth_dev* dev)

Details:

DPDK callback to reset the device.

This callback is invoked when applcation calls rte_eth_dev_reset() API to reset a device. This callback uninitialzes PF device after waiting for all its VFs to shutdown. It initialize back PF device and then send Reset done mailbox message to all its VFs to come online again.

Parameters:

dev Pointer to Ethernet device structure

Returns:

0 on success, negative errno value on failure

qdma_eth_dev_uninit

Syntax:

int qdma_eth_dev_uninit (struct rte_eth_dev* dev)

Details:

DPDK callback to deregister a PCI device.

The Following actions are performed by this function:

  • Flushes out pending actions from the Tx Mailbox List
  • Terminate Tx Mailbox thread
  • Disable Mailbox interrupt and unregister interrupt handler
  • Unregister PCIe device from Queue Resource Manager
  • Cancel QDMA HW error monitoring thread if created by this device
  • Disable MM C2H and H2C channels

Parameters:

dev Pointer to Ethernet device structure

Returns:

0 on success, < 0 on failure