pktdev.h File Reference

#include <cne_common.h>
#include <errno.h>
#include <stddef.h>
#include <stdint.h>
#include <x86intrin.h>
#include <mempool.h>
#include <pktmbuf.h>
#include <emmintrin.h>
#include <stdbool.h>
#include <tmmintrin.h>
#include <cne_lport.h>
#include <pktdev_api.h>
#include <pktdev_core.h>
#include "cne_log.h"

Go to the source code of this file.

Data Structures
struct	pktdev_rxq_info
struct	pktdev_txq_info
struct	pktdev_portconf
struct	pktdev_info

Macros
#define	PKTDEV_FALLBACK_RX_RINGSIZE   512

Functions
static uint16_t	pktdev_rx_burst (uint16_t lport_id, pktmbuf_t **rx_pkts, const uint16_t nb_pkts)
static uint16_t	pktdev_tx_burst (uint16_t lport_id, pktmbuf_t **tx_pkts, uint16_t nb_pkts)
static uint16_t	pktdev_tx_prepare (uint16_t lport_id, pktmbuf_t **tx_pkts, uint16_t nb_pkts)
static void	pktdev_mac_swap (void *data)

Detailed Description

A simple Ethernet interface routines for AF_XDP and related virtual interfaces.

Definition in file pktdev.h.

Macro Definition Documentation

PKTDEV_FALLBACK_RX_RINGSIZE

#define PKTDEV_FALLBACK_RX_RINGSIZE   512

Fallback default preferred Rx/Tx lport parameters. These are used if an application requests default parameters but the PMD does not provide preferred values.

Definition at line 35 of file pktdev.h.

Function Documentation

pktdev_rx_burst()

static uint16_t pktdev_rx_burst ( uint16_t  lport_id, pktmbuf_t **  rx_pkts, const uint16_t  nb_pkts  )

inlinestatic

Retrieve a burst of input packets from a receive queue of an Ethernet/virtual device. The retrieved packets are stored in pktmbuf structures whose pointers are supplied in the rx_pkts array.

The pktdev_rx_burst() function loops, parsing the RX ring of the receive queue, up to nb_pkts packets, and for each completed RX descriptor in the ring, it performs the following operations:

• Initialize the pktmbuf data structure associated with the RX descriptor according to the information provided by the NIC into that RX descriptor.
• Store the pktmbuf data structure into the next entry of the rx_pkts array.
• Replenish the RX descriptor with a new pktmbuf buffer allocated from the memory pool associated with the receive queue at initialization time.

The pktdev_rx_burst() function returns the number of packets actually retrieved, which is the number of pktmbuf data structures effectively supplied into the rx_pkts array. A return value equal to nb_pkts indicates that the RX queue contained at least rx_pkts packets, and this is likely to signify that other received packets remain in the input queue. Applications implementing a "retrieve as much received packets as possible" policy can check this specific case and keep invoking the pktdev_rx_burst() function until a value less than nb_pkts is returned.

This receive method has the following advantages:

• It allows a run-to-completion network stack engine to retrieve and to immediately process received packets in a fast burst-oriented approach, avoiding the overhead of unnecessary intermediate packet queue/dequeue operations.
• Conversely, it also allows an asynchronous-oriented processing method to retrieve bursts of received packets and to immediately queue them for further parallel processing by another logical core, for instance. However, instead of having received packets being individually queued by the driver, this approach allows the caller of the pktdev_rx_burst() function to queue a burst of retrieved packets at a time and therefore dramatically reduce the cost of enqueue/dequeue operations per packet.
• It allows the pktdev_rx_burst() function of the driver to take advantage of burst-oriented hardware features (CPU cache, prefetch instructions, and so on) to minimize the number of CPU cycles per packet.

To summarize, the proposed receive API enables many burst-oriented optimizations in both synchronous and asynchronous packet processing environments with no overhead in both cases.

The pktdev_rx_burst() function does not provide any error notification to avoid the corresponding overhead. As a hint, the upper-level application might check the status of the device link once being systematically returned a 0 value for a given number of tries.

Parameters

lport_id	The lport identifier of the Ethernet device.
rx_pkts	The address of an array of pointers to pktmbuf structures that must be large enough to store nb_pkts pointers in it.
nb_pkts	The maximum number of packets to retrieve.

Returns

The number of packets actually retrieved, which is the number of pointers to pktmbuf structures effectively supplied to the rx_pkts array. returns 0xFFFF on admin_state_down

Examples

examples/cndpfwd/acl-func.c, examples/cndpfwd/main.c, and examples/dlb_test/dlb_test.c.

Definition at line 183 of file pktdev.h.

pktdev_tx_burst()

static uint16_t pktdev_tx_burst ( uint16_t  lport_id, pktmbuf_t **  tx_pkts, uint16_t  nb_pkts  )

inlinestatic

Send a burst of output packets on a transmit queue of an Ethernet/virtual device.

The pktdev_tx_burst() function is invoked to transmit output packets on the output queue queue_id of the device designated by its lport_id.

The nb_pkts parameter is the number of packets to send which are supplied in the tx_pkts array of pktmbuf structures, each of them allocated from a pool created with pktmbuf_pool_create(). The pktdev_tx_burst() function loops, sending nb_pkts packets, up to the number of transmit descriptors available in the TX ring of the transmit queue. For each packet to send, the pktdev_tx_burst() function performs the following operations:

• Pick up the next available descriptor in the transmit ring.
• Free the network buffer previously sent with that descriptor, if any.
• Initialize the transmit descriptor with the information provided in the *pktmbuf data structure.

In the case of a segmented packet composed of a list of pktmbuf buffers, the pktdev_tx_burst() function uses several transmit descriptors of the ring.

The pktdev_tx_burst() function returns the number of packets it actually sent. A return value equal to nb_pkts means that all packets have been sent, and this is likely to signify that other output packets could be immediately transmitted again. Applications that implement a "send as many packets to transmit as possible" policy can check this specific case and keep invoking the pktdev_tx_burst() function until a value less than nb_pkts is returned.

It is the responsibility of the pktdev_tx_burst() function to transparently free the memory buffers of packets previously sent.

See also

pktdev_tx_prepare to perform some prior checks or adjustments for offloads.

Parameters

lport_id	The lport identifier of the Ethernet device.
tx_pkts	The address of an array of nb_pkts pointers to pktmbuf structures which contain the output packets.
nb_pkts	The maximum number of packets to transmit.

Returns

The number of output packets actually stored in transmit descriptors of the transmit ring. The return value can be less than the value of the tx_pkts parameter when the transmit ring is full or has been filled up. returns 0xFFFF on admin_state_down

Examples

examples/cndpfwd/main.c.

Definition at line 258 of file pktdev.h.

pktdev_tx_prepare()

static uint16_t pktdev_tx_prepare ( uint16_t  lport_id, pktmbuf_t **  tx_pkts, uint16_t  nb_pkts  )

inlinestatic

Process a burst of output packets on a transmit queue of an Ethernet device.

The pktdev_tx_prepare() function is invoked to prepare output packets to be transmitted on the output queue queue_id of the device designated by its lport_id. The nb_pkts parameter is the number of packets to be prepared which are supplied in the tx_pkts array of pktmbuf structures, each of them allocated from a pool created with pktmbuf_pool_create(). For each packet to send, the pktdev_tx_prepare() function performs the following operations:

• Check if packet meets devices requirements for tx offloads.
• Check limitations about number of segments.
• Check additional requirements when debug is enabled.
• Update and/or reset required checksums when tx offload is set for packet.

Since this function can modify packet data, provided mbufs must be safely writable (e.g. modified data cannot be in shared segment).

The pktdev_tx_prepare() function returns the number of packets ready to be sent. A return value equal to nb_pkts means that all packets are valid and ready to be sent, otherwise stops processing on the first invalid packet and leaves the rest packets untouched.

When this functionality is not implemented in the driver, all packets are are returned untouched.

Parameters

lport_id	The lport identifier of the Ethernet device. The value must be a valid lport id.
tx_pkts	The address of an array of nb_pkts pointers to pktmbuf structures which contain the output packets.
nb_pkts	The maximum number of packets to process.

Returns

The number of packets correct and ready to be sent. The return value can be less than the value of the tx_pkts parameter when some packet doesn't meet devices requirements with errno set appropriately:

• EINVAL: offload flags are not correctly set
• ENOTSUP: the offload feature is not supported by the hardware

Definition at line 330 of file pktdev.h.

pktdev_mac_swap()

static void pktdev_mac_swap ( void *  data )

inlinestatic

Swap the MAC addresses in a ethernet packet using AVX instructions

Parameters

data	Pointer to the start of the L2 header

Returns

The MAC addresses will be swapped.

shuffle mask be used to shuffle the 16 bytes. byte 0-5 wills be swapped with byte 6-11. byte 12-15 will keep unchanged.

Definition at line 351 of file pktdev.h.