PcapPlusPlus  23.09
pcpp::DpdkDevice Class Reference

#include <DpdkDevice.h>

Inheritance diagram for pcpp::DpdkDevice:
pcpp::IDevice

Classes

struct  DpdkDeviceConfiguration
 
struct  DpdkDeviceStats
 
struct  LinkStatus
 
struct  RxTxStats
 

Public Types

enum  DpdkRssHashFunction {
  RSS_NONE = 0, RSS_IPV4 = 0x1, RSS_FRAG_IPV4 = 0x2, RSS_NONFRAG_IPV4_TCP = 0x4,
  RSS_NONFRAG_IPV4_UDP = 0x8, RSS_NONFRAG_IPV4_SCTP = 0x10, RSS_NONFRAG_IPV4_OTHER = 0x20, RSS_IPV6 = 0x40,
  RSS_FRAG_IPV6 = 0x80, RSS_NONFRAG_IPV6_TCP = 0x100, RSS_NONFRAG_IPV6_UDP = 0x200, RSS_NONFRAG_IPV6_SCTP = 0x400,
  RSS_NONFRAG_IPV6_OTHER = 0x800, RSS_L2_PAYLOAD = 0x1000, RSS_IPV6_EX = 0x2000, RSS_IPV6_TCP_EX = 0x4000,
  RSS_IPV6_UDP_EX = 0x8000, RSS_PORT = 0x10000, RSS_VXLAN = 0x20000, RSS_GENEVE = 0x40000,
  RSS_NVGRE = 0x80000, RSS_ALL_SUPPORTED = -1, RSS_DEFAULT = 0x123456
}
 

Public Member Functions

int getDeviceId () const
 
std::string getDeviceName () const
 
MacAddress getMacAddress () const
 
std::string getPMDName () const
 
DpdkPMDType getPMDType () const
 
std::string getPciAddress () const
 
uint16_t getMtu () const
 
bool setMtu (uint16_t newMtu)
 
bool isVirtual () const
 
void getLinkStatus (LinkStatus &linkStatus) const
 
uint32_t getCurrentCoreId () const
 
uint16_t getNumOfOpenedRxQueues () const
 
uint16_t getNumOfOpenedTxQueues () const
 
uint16_t getTotalNumOfRxQueues () const
 
uint16_t getTotalNumOfTxQueues () const
 
uint16_t receivePackets (MBufRawPacketVector &rawPacketsArr, uint16_t rxQueueId) const
 
uint16_t receivePackets (MBufRawPacket **rawPacketsArr, uint16_t rawPacketArrLength, uint16_t rxQueueId) const
 
uint16_t receivePackets (Packet **packetsArr, uint16_t packetsArrLength, uint16_t rxQueueId) const
 
uint16_t sendPackets (MBufRawPacket **rawPacketsArr, uint16_t arrLength, uint16_t txQueueId=0, bool useTxBuffer=false)
 
uint16_t sendPackets (Packet **packetsArr, uint16_t arrLength, uint16_t txQueueId=0, bool useTxBuffer=false)
 
uint16_t sendPackets (MBufRawPacketVector &rawPacketsVec, uint16_t txQueueId=0, bool useTxBuffer=false)
 
uint16_t sendPackets (RawPacketVector &rawPacketsVec, uint16_t txQueueId=0, bool useTxBuffer=false)
 
bool sendPacket (RawPacket &rawPacket, uint16_t txQueueId=0, bool useTxBuffer=false)
 
bool sendPacket (MBufRawPacket &rawPacket, uint16_t txQueueId=0, bool useTxBuffer=false)
 
bool sendPacket (Packet &packet, uint16_t txQueueId=0, bool useTxBuffer=false)
 
bool setFilter (GeneralFilter &filter)
 
bool setFilter (std::string filterAsString)
 
bool openMultiQueues (uint16_t numOfRxQueuesToOpen, uint16_t numOfTxQueuesToOpen, const DpdkDeviceConfiguration &config=DpdkDeviceConfiguration())
 
bool startCaptureSingleThread (OnDpdkPacketsArriveCallback onPacketsArrive, void *onPacketsArriveUserCookie)
 
bool startCaptureMultiThreads (OnDpdkPacketsArriveCallback onPacketsArrive, void *onPacketsArriveUserCookie, CoreMask coreMask)
 
void stopCapture ()
 
int getAmountOfFreeMbufs () const
 
int getAmountOfMbufsInUse () const
 
void getStatistics (DpdkDeviceStats &stats) const
 
void clearStatistics ()
 
uint16_t flushTxBuffer (bool flushOnlyIfTimeoutExpired=false, uint16_t txQueueId=0)
 
bool isDeviceSupportRssHashFunction (DpdkRssHashFunction rssHF) const
 
bool isDeviceSupportRssHashFunction (uint64_t rssHFMask) const
 
uint64_t getSupportedRssHashFunctions () const
 
uint64_t getConfiguredRssHashFunction () const
 
std::vector< std::string > rssHashFunctionMaskToString (uint64_t rssHFMask) const
 
bool open ()
 
void close ()
 
- Public Member Functions inherited from pcpp::IDevice
bool isOpened ()
 

Detailed Description

Encapsulates a DPDK port and enables receiving and sending packets using DPDK as well as getting interface info & status, packet statistics, etc. This class has no public c'tor as it's constructed by DpdkDeviceList during initialization.

RX/TX queues: modern NICs provide hardware load-balancing for packets. This means that each packet received by the NIC is hashed by one or more parameter (IP address, port, etc.) and goes into one of several RX queues provided by the NIC. This enables applications to work in a multi-core environment where each core can read packets from different RX queue(s). Same goes for TX queues: it's possible to write packets to different TX queues and the NIC is taking care of sending them to the network. Different NICs provide different number of RX and TX queues. DPDK supports this capability and enables the user to open the DPDK port (DpdkDevice) with a single or multiple RX and TX queues. When receiving packets the user can decide from which RX queue to read from, and when transmitting packets the user can decide to which TX queue to send them to. RX/TX queues are configured when opening the DpdkDevice (see openMultiQueues())

Capturing packets: there are two ways to capture packets using DpdkDevice:

Sending packets: DpdkDevice has various methods for sending packets. They enable sending raw packets, parsed packets, etc. for all opened TX queues. Also, DPDK provides an option to buffer TX packets and send them only when reaching a certain threshold (you can read more about it here: http://dpdk.org/doc/api/rte__ethdev_8h.html#a0e941a74ae1b1b886764bc282458d946). DpdkDevice supports that option as well. See DpdkDevice::sendPackets()

Get interface info: DpdkDevice provides all kind of information on the interface/device such as MAC address, MTU, link status, PCI address, PMD (poll-mode-driver) used for this port, etc. In addition it provides RX/TX statistics when receiving or sending packets

Known limitations:

  • BPF filters are currently not supported by this device (as opposed to other PcapPlusPlus device types. This means that the device cannot filter packets before they get to the user
  • It's not possible to set or change NIC load-balancing method. DPDK provides this capability but it's still not supported by DpdkDevice

Member Enumeration Documentation

◆ DpdkRssHashFunction

An enum describing all RSS (Receive Side Scaling) hash functions supported in DPDK. Notice not all PMDs support all types of hash functions

Enumerator
RSS_NONE 

No RSS

RSS_IPV4 

IPv4 based flow

RSS_FRAG_IPV4 

Fragmented IPv4 based flow

RSS_NONFRAG_IPV4_TCP 

Non-fragmented IPv4 + TCP flow

RSS_NONFRAG_IPV4_UDP 

Non-fragmented IPv4 + UDP flow

RSS_NONFRAG_IPV4_SCTP 

Non-fragmented IPv4 + SCTP flow

RSS_NONFRAG_IPV4_OTHER 

Non-fragmented IPv4 + non TCP/UDP/SCTP flow

RSS_IPV6 

IPv6 based flow

RSS_FRAG_IPV6 

Fragmented IPv6 based flow

RSS_NONFRAG_IPV6_TCP 

Non-fragmented IPv6 + TCP flow

RSS_NONFRAG_IPV6_UDP 

Non-fragmented IPv6 + UDP flow

RSS_NONFRAG_IPV6_SCTP 

Non-fragmented IPv6 + SCTP flow

RSS_NONFRAG_IPV6_OTHER 

Non-fragmented IPv6 + non TCP/UDP/SCTP flow

RSS_L2_PAYLOAD 

L2 payload based flow

RSS_IPV6_EX 

IPv6 Ex based flow

RSS_IPV6_TCP_EX 

IPv6 + TCP Ex based flow

RSS_IPV6_UDP_EX 

IPv6 + UDP Ex based flow

RSS_PORT 

Consider device port number as a flow differentiator

RSS_VXLAN 

VXLAN protocol based flow

RSS_GENEVE 

GENEVE protocol based flow

RSS_NVGRE 

NVGRE protocol based flow

RSS_ALL_SUPPORTED 

All RSS functions supported by the device

RSS_DEFAULT 

A default set of RSS functions supported by the device

Member Function Documentation

◆ clearStatistics()

void pcpp::DpdkDevice::clearStatistics ( )

Clear device statistics

◆ close()

void pcpp::DpdkDevice::close ( )
virtual

Close the DpdkDevice. When device is closed it's not possible work with it

Implements pcpp::IDevice.

◆ flushTxBuffer()

uint16_t pcpp::DpdkDevice::flushTxBuffer ( bool  flushOnlyIfTimeoutExpired = false,
uint16_t  txQueueId = 0 
)

DPDK supports an option to buffer TX packets and send them only when reaching a certain threshold. This method enables the user to flush a TX buffer for certain TX queue and send the packets stored in it (you can read about it here: http://dpdk.org/doc/api/rte__ethdev_8h.html#a0e941a74ae1b1b886764bc282458d946). It has the option to flush only when timeout that was set in DpdkDeviceConfiguration::flushTxBufferTimeout expired or flush immediately regardless of the timeout. The usage of this method can be in the main loop where you can call this method once every a couple of iterations to make sure TX buffers are flushed

Parameters
[in]flushOnlyIfTimeoutExpiredWhen set to true, flush will happen only if the timeout defined in DpdkDeviceConfiguration::flushTxBufferTimeout expired. If set to false flush will happen immediately. Default value is false
[in]txQueueIdThe TX queue ID to flush its buffer. Default is 0
Returns
The number of packets sent after buffer was flushed

◆ getAmountOfFreeMbufs()

int pcpp::DpdkDevice::getAmountOfFreeMbufs ( ) const
Returns
The number of free mbufs in device's mbufs pool

◆ getAmountOfMbufsInUse()

int pcpp::DpdkDevice::getAmountOfMbufsInUse ( ) const
Returns
The number of mbufs currently in use in device's mbufs pool

◆ getConfiguredRssHashFunction()

uint64_t pcpp::DpdkDevice::getConfiguredRssHashFunction ( ) const
Returns
The RSS hash function mask configured for this device (PMD)

◆ getCurrentCoreId()

uint32_t pcpp::DpdkDevice::getCurrentCoreId ( ) const
Returns
The core ID used in this context

◆ getDeviceId()

int pcpp::DpdkDevice::getDeviceId ( ) const
inline
Returns
The device ID (DPDK port ID)

◆ getDeviceName()

std::string pcpp::DpdkDevice::getDeviceName ( ) const
inline
Returns
The device name which is in the format of 'DPDK_[PORT-ID]'

◆ getLinkStatus()

void pcpp::DpdkDevice::getLinkStatus ( LinkStatus linkStatus) const

Get the link status (link up/down, link speed and link duplex)

Parameters
[out]linkStatusA reference to object the result shall be written to

◆ getMacAddress()

MacAddress pcpp::DpdkDevice::getMacAddress ( ) const
inline
Returns
The MAC address of the device (DPDK port)

◆ getMtu()

uint16_t pcpp::DpdkDevice::getMtu ( ) const
inline
Returns
The device's maximum transmission unit (MTU) in bytes

◆ getNumOfOpenedRxQueues()

uint16_t pcpp::DpdkDevice::getNumOfOpenedRxQueues ( ) const
inline
Returns
The number of RX queues currently opened for this device (as configured in openMultiQueues() )

◆ getNumOfOpenedTxQueues()

uint16_t pcpp::DpdkDevice::getNumOfOpenedTxQueues ( ) const
inline
Returns
The number of TX queues currently opened for this device (as configured in openMultiQueues() )

◆ getPciAddress()

std::string pcpp::DpdkDevice::getPciAddress ( ) const
inline
Returns
The PCI address of the device

◆ getPMDName()

std::string pcpp::DpdkDevice::getPMDName ( ) const
inline
Returns
The name of the PMD (poll mode driver) DPDK is using for this device. You can read about PMDs in the DPDK documentation: http://dpdk.org/doc/guides/prog_guide/poll_mode_drv.html

◆ getPMDType()

DpdkPMDType pcpp::DpdkDevice::getPMDType ( ) const
inline
Returns
The enum type of the PMD (poll mode driver) DPDK is using for this device. You can read about PMDs in the DPDK documentation: http://dpdk.org/doc/guides/prog_guide/poll_mode_drv.html

◆ getStatistics()

void pcpp::DpdkDevice::getStatistics ( DpdkDeviceStats stats) const

Retrieve RX/TX statistics from device

Parameters
[out]statsA reference to a DpdkDeviceStats object where stats will be written into

◆ getSupportedRssHashFunctions()

uint64_t pcpp::DpdkDevice::getSupportedRssHashFunctions ( ) const
Returns
A mask of all RSS hash functions supported by this device (PMD). This mask is built from values in DpdkRssHashFunction enum. Value of zero means RSS is not supported by this device

◆ getTotalNumOfRxQueues()

uint16_t pcpp::DpdkDevice::getTotalNumOfRxQueues ( ) const
inline
Returns
The total number of RX queues available on this device

◆ getTotalNumOfTxQueues()

uint16_t pcpp::DpdkDevice::getTotalNumOfTxQueues ( ) const
inline
Returns
The total number of TX queues available on this device

◆ isDeviceSupportRssHashFunction() [1/2]

bool pcpp::DpdkDevice::isDeviceSupportRssHashFunction ( DpdkRssHashFunction  rssHF) const

Check whether a specific RSS hash function is supported by this device (PMD)

Parameters
[in]rssHFRSS hash function to check
Returns
True if this hash function is supported, false otherwise

◆ isDeviceSupportRssHashFunction() [2/2]

bool pcpp::DpdkDevice::isDeviceSupportRssHashFunction ( uint64_t  rssHFMask) const

Check whether a mask of RSS hash functions is supported by this device (PMD)

Parameters
[in]rssHFMaskRSS hash functions mask to check. This mask should be built from values in DpdkRssHashFunction enum
Returns
True if all hash functions in this mask are supported, false otherwise

◆ isVirtual()

bool pcpp::DpdkDevice::isVirtual ( ) const
Returns
True if this device is a virtual interface (such as VMXNET3, 1G/10G virtual function, etc.), false otherwise

◆ open()

bool pcpp::DpdkDevice::open ( )
inlinevirtual

Overridden method from IPcapDevice. It calls openMultiQueues() with 1 RX queue and 1 TX queue. Notice opening the device only makes it ready to use, it doesn't start packet capturing. The device is opened in promiscuous mode

Returns
True if the device was opened successfully, false if device is already opened, if RX/TX queues configuration failed or of DPDK port configuration and startup failed

Implements pcpp::IDevice.

◆ openMultiQueues()

bool pcpp::DpdkDevice::openMultiQueues ( uint16_t  numOfRxQueuesToOpen,
uint16_t  numOfTxQueuesToOpen,
const DpdkDeviceConfiguration config = DpdkDeviceConfiguration() 
)

Open the DPDK device. Notice opening the device only makes it ready to use, it doesn't start packet capturing. This method initializes RX and TX queues, configures the DPDK port and starts it. Call close() to close the device. The device is opened in promiscuous mode

Parameters
[in]numOfRxQueuesToOpenNumber of RX queues to setup. This number must be smaller or equal to the return value of getTotalNumOfRxQueues()
[in]numOfTxQueuesToOpenNumber of TX queues to setup. This number must be smaller or equal to the return value of getTotalNumOfTxQueues()
[in]configOptional parameter for defining special port configuration parameters such as number of receive/transmit descriptors. If not set the default parameters will be set (see DpdkDeviceConfiguration)
Returns
True if the device was opened successfully, false if device is already opened, if RX/TX queues configuration failed or of DPDK port configuration and startup failed

◆ receivePackets() [1/3]

uint16_t pcpp::DpdkDevice::receivePackets ( MBufRawPacketVector rawPacketsArr,
uint16_t  rxQueueId 
) const

Receive raw packets from the network

Parameters
[out]rawPacketsArrA vector where all received packets will be written into
[in]rxQueueIdThe RX queue to receive packets from
Returns
The number of packets received. If an error occurred 0 will be returned and the error will be printed to log

◆ receivePackets() [2/3]

uint16_t pcpp::DpdkDevice::receivePackets ( MBufRawPacket **  rawPacketsArr,
uint16_t  rawPacketArrLength,
uint16_t  rxQueueId 
) const

Receive raw packets from the network. Please notice that in terms of performance, this is the best method to use for receiving packets because out of all receivePackets overloads this method requires the least overhead and is almost as efficient as receiving packets directly through DPDK. So if performance is a critical factor in your application, please use this method

Parameters
[out]rawPacketsArrA pointer to an array of MBufRawPacket pointers where all received packets will be written into. The array is expected to be allocated by the user and its length should be provided in rawPacketArrLength. Number of packets received will be returned. Notice it's the user responsibility to free the array and its content when done using it
[out]rawPacketArrLengthThe length of MBufRawPacket pointers array
[in]rxQueueIdThe RX queue to receive packets from
Returns
The number of packets received. If an error occurred 0 will be returned and the error will be printed to log

◆ receivePackets() [3/3]

uint16_t pcpp::DpdkDevice::receivePackets ( Packet **  packetsArr,
uint16_t  packetsArrLength,
uint16_t  rxQueueId 
) const

Receive parsed packets from the network

Parameters
[out]packetsArrA pointer to an allocated array of Packet pointers where all received packets will be written into. The array is expected to be allocated by the user and its length should be provided in packetsArrLength. Number of packets received will be returned. Notice it's the user responsibility to free the array and its content when done using it
[out]packetsArrLengthThe length of Packet pointers array
[in]rxQueueIdThe RX queue to receive packets from
Returns
The number of packets received. If an error occurred 0 will be returned and the error will be printed to log

◆ rssHashFunctionMaskToString()

std::vector<std::string> pcpp::DpdkDevice::rssHashFunctionMaskToString ( uint64_t  rssHFMask) const

Translate RSS hash function mask to a list of their string representation

Parameters
rssHFMaskRSS hash function mask
Returns
RSS hash functions as strings

◆ sendPacket() [1/3]

bool pcpp::DpdkDevice::sendPacket ( RawPacket rawPacket,
uint16_t  txQueueId = 0,
bool  useTxBuffer = false 
)

Send a raw packet to the network. Please notice that if the raw packet isn't of type MBufRawPacket, a new temp MBufRawPacket will be created and the data will be copied to it. This is necessary to allocate an mbuf which will store the data to be sent. If performance is a critical factor please make sure you send a raw packet of type MBufRawPacket. Please also notice that the mbuf used or allocated in this method isn't freed by this method, it will be transparently freed by DPDK

Parameters
[in]rawPacketThe raw packet to send
[in]txQueueIdAn optional parameter which indicates to which TX queue the packet will be sent to. The default is TX queue 0
[in]useTxBufferA flag which indicates whether to use TX buffer mechanism or not. To read more about DPDK's TX buffer mechanism please refer to DpdkDevice class description. Default value is false (don't use this mechanism)
Returns
True if packet was sent successfully or false if device is not opened, TX queue isn't opened, or if the packet wasn't sent for any other reason. Please notice that when using TX buffers the packet may be buffered and not sent immediately, which may also result in returning false

◆ sendPacket() [2/3]

bool pcpp::DpdkDevice::sendPacket ( MBufRawPacket rawPacket,
uint16_t  txQueueId = 0,
bool  useTxBuffer = false 
)

Send a MBufRawPacket to the network. Please notice that the mbuf used in this method isn't freed by this method, it will be transparently freed by DPDK

Parameters
[in]rawPacketThe MBufRawPacket to send
[in]txQueueIdAn optional parameter which indicates to which TX queue the packet will be sent to. The default is TX queue 0
[in]useTxBufferA flag which indicates whether to use TX buffer mechanism or not. To read more about DPDK's TX buffer mechanism please refer to DpdkDevice class description. Default value is false (don't use this mechanism)
Returns
True if packet was sent successfully or false if device is not opened, TX queue isn't opened, or if the packet wasn't sent for any other reason. Please notice that when using TX buffers the packet may be buffered and not sent immediately, which may also result in returning false

◆ sendPacket() [3/3]

bool pcpp::DpdkDevice::sendPacket ( Packet packet,
uint16_t  txQueueId = 0,
bool  useTxBuffer = false 
)

Send a parsed packet to the network. Please notice that the mbuf used or allocated in this method isn't freed by this method, it will be transparently freed by DPDK

Parameters
[in]packetThe parsed packet to send. Please notice that if the packet contains a raw packet which isn't of type MBufRawPacket, a new temp MBufRawPacket will be created and the data will be copied to it. This is necessary to allocate an mbuf which will store the data to be sent. If performance is a critical factor please make sure you send a parsed packet that contains a raw packet of type MBufRawPacket
[in]txQueueIdAn optional parameter which indicates to which TX queue the packet will be sent on. The default is TX queue 0
[in]useTxBufferA flag which indicates whether to use TX buffer mechanism or not. To read more about DPDK's TX buffer mechanism please refer to DpdkDevice class description. Default value is false (don't use this mechanism)
Returns
True if packet was sent successfully or false if device is not opened, TX queue isn't opened, or if the packet wasn't sent for any other reason. Please notice that when using TX buffers the packet may be buffered and not sent immediately, which may also result in returning false

◆ sendPackets() [1/4]

uint16_t pcpp::DpdkDevice::sendPackets ( MBufRawPacket **  rawPacketsArr,
uint16_t  arrLength,
uint16_t  txQueueId = 0,
bool  useTxBuffer = false 
)

Send an array of MBufRawPacket to the network. Please notice the following:

  • In terms of performance, this is the best method to use for sending packets because out of all sendPackets overloads this method requires the least overhead and is almost as efficient as sending the packets directly through DPDK. So if performance is a critical factor in your application, please use this method
  • If the number of packets to send is higher than 64 this method will run multiple iterations of sending packets to DPDK, each iteration of 64 packets
  • If the number of packets to send is higher than a threshold of 80% of total TX descriptors (which is typically around 400 packets), then after reaching this threshold there is a built-in 0.2 sec sleep to let the TX descriptors clean
  • The mbufs used in this method aren't freed by this method, they will be transparently freed by DPDK

    Parameters
    [in]rawPacketsArrA pointer to an array of MBufRawPacket
    [in]arrLengthThe length of the array
    [in]txQueueIdAn optional parameter which indicates to which TX queue the packets will be sent to. The default is TX queue 0
    [in]useTxBufferA flag which indicates whether to use TX buffer mechanism or not. To read more about DPDK's TX buffer mechanism please refer to DpdkDevice class description. Default value is false (don't use this mechanism)
    Returns
    The number of packets actually and successfully sent. If device is not opened or TX queue isn't open, 0 will be returned. Also, if TX buffer is being used and packets are buffered, some or all may not be actually sent

◆ sendPackets() [2/4]

uint16_t pcpp::DpdkDevice::sendPackets ( Packet **  packetsArr,
uint16_t  arrLength,
uint16_t  txQueueId = 0,
bool  useTxBuffer = false 
)

Send an array of parsed packets to the network. Please notice the following:

  • If some or all of the packets contain raw packets which aren't of type MBufRawPacket, a new temp MBufRawPacket instances will be created and packet data will be copied to them. This is necessary to allocate mbufs which will store the data to be sent. If performance is a critical factor please make sure you send parsed packets that contain only raw packets of type MBufRawPacket
  • If the number of packets to send is higher than 64 this method will run multiple iterations of sending packets to DPDK, each iteration of 64 packets
  • If the number of packets to send is higher than a threshold of 80% of total TX descriptors (which is typically around 400 packets), then after reaching this threshold there is a built-in 0.2 sec sleep to let the TX descriptors clean
  • The mbufs used or allocated in this method aren't freed by this method, they will be transparently freed by DPDK

    Parameters
    [in]packetsArrA pointer to an array of parsed packet pointers
    [in]arrLengthThe length of the array
    [in]txQueueIdAn optional parameter which indicates to which TX queue the packets will be sent to. The default is TX queue 0
    [in]useTxBufferA flag which indicates whether to use TX buffer mechanism or not. To read more about DPDK's TX buffer mechanism please refer to DpdkDevice class description. Default value is false (don't use this mechanism)
    Returns
    The number of packets actually and successfully sent. If device is not opened or TX queue isn't open, 0 will be returned. Also, if TX buffer is being used and packets are buffered, some or all may not be actually sent

◆ sendPackets() [3/4]

uint16_t pcpp::DpdkDevice::sendPackets ( MBufRawPacketVector rawPacketsVec,
uint16_t  txQueueId = 0,
bool  useTxBuffer = false 
)

Send a vector of MBufRawPacket pointers to the network. Please notice the following:

  • If the number of packets to send is higher than 64 this method will run multiple iterations of sending packets to DPDK, each iteration of 64 packets
  • If the number of packets to send is higher than a threshold of 80% of total TX descriptors (which is typically around 400 packets), then after reaching this threshold there is a built-in 0.2 sec sleep to let the TX descriptors clean
  • The mbufs used in this method aren't freed by this method, they will be transparently freed by DPDK

    Parameters
    [in]rawPacketsVecThe vector of raw packet
    [in]txQueueIdAn optional parameter which indicates to which TX queue the packets will be sent to. The default is TX queue 0
    [in]useTxBufferA flag which indicates whether to use TX buffer mechanism or not. To read more about DPDK's TX buffer mechanism please refer to DpdkDevice class description. Default value is false (don't use this mechanism)
    Returns
    The number of packets actually and successfully sent. If device is not opened or TX queue isn't open, 0 will be returned. Also, if TX buffer is being used and packets are buffered, some or all may not be actually sent

◆ sendPackets() [4/4]

uint16_t pcpp::DpdkDevice::sendPackets ( RawPacketVector rawPacketsVec,
uint16_t  txQueueId = 0,
bool  useTxBuffer = false 
)

Send a vector of RawPacket pointers to the network. Please notice the following:

  • If some or all of the raw packets aren't of type MBufRawPacket, a new temp MBufRawPacket instances will be created and packet data will be copied to them. This is necessary to allocate mbufs which will store the data to be sent. If performance is a critical factor please make sure you send only raw packets of type MBufRawPacket (or use the sendPackets overload that sends MBufRawPacketVector)
  • If the number of packets to send is higher than 64 this method will run multiple iterations of sending packets to DPDK, each iteration of 64 packets
  • If the number of packets to send is higher than a threshold of 80% of total TX descriptors (which is typically around 400 packets), then after reaching this threshold there is a built-in 0.2 sec sleep to let the TX descriptors clean
  • The mbufs used or allocated in this method aren't freed by this method, they will be transparently freed by DPDK

    Parameters
    [in]rawPacketsVecThe vector of raw packet
    [in]txQueueIdAn optional parameter which indicates to which TX queue the packets will be sent to. The default is TX queue 0
    [in]useTxBufferA flag which indicates whether to use TX buffer mechanism or not. To read more about DPDK's TX buffer mechanism please refer to DpdkDevice class description. Default value is false (don't use this mechanism)
    Returns
    The number of packets actually and successfully sent. If device is not opened or TX queue isn't open, 0 will be returned. Also, if TX buffer is being used and packets are buffered, some or all may not be actually sent

◆ setFilter() [1/2]

bool pcpp::DpdkDevice::setFilter ( GeneralFilter filter)

Overridden method from IPcapDevice. BPF filters are currently not implemented for DpdkDevice

Parameters
[in]filterNot used in this method
Returns
Always false with a "Filters aren't supported in DPDK device" error message

◆ setFilter() [2/2]

bool pcpp::DpdkDevice::setFilter ( std::string  filterAsString)

Overridden method from IPcapDevice. BPF filters are currently not implemented for DpdkDevice

Parameters
[in]filterAsStringNot used in this method
Returns
Always false with a "Filters aren't supported in DPDK device" error message

◆ setMtu()

bool pcpp::DpdkDevice::setMtu ( uint16_t  newMtu)

Set a new maximum transmission unit (MTU) for this device

Parameters
[in]newMtuThe new MTU in bytes
Returns
True if MTU was set successfully, false if operation failed or if PMD doesn't support changing the MTU

◆ startCaptureMultiThreads()

bool pcpp::DpdkDevice::startCaptureMultiThreads ( OnDpdkPacketsArriveCallback  onPacketsArrive,
void *  onPacketsArriveUserCookie,
CoreMask  coreMask 
)

This method does exactly what startCaptureSingleThread() does, but with more than one RX queue / capturing thread. It's called with a core mask as a parameter and creates a packet capture thread on every core. Each capturing thread is assigned with a specific RX queue. This method assumes all cores in the core-mask are available and there are enough opened RX queues to match for each thread. If these assumptions are not true an error is returned. After invoking all threads, all of them run in an endless loop and try to capture packets from their designated RX queues. Each time a burst of packets is captured the callback is invoked with the user cookie and the thread ID that captured the packets

Parameters
[in]onPacketsArriveThe user callback which will be invoked each time a burst of packets is captured by the device
[in]onPacketsArriveUserCookieThe user callback is invoked with this cookie as a parameter. It can be used to pass information from the user application to the callback
coreMaskThe core-mask for creating the cpature threads
Returns
True if all capture threads started successfully or false if device is already in capture mode, not all cores in the core-mask are available to DPDK, there are not enough opened RX queues to match all cores in the core-mask, or if thread invocation failed. In all of these cases an appropriate error message will be printed

◆ startCaptureSingleThread()

bool pcpp::DpdkDevice::startCaptureSingleThread ( OnDpdkPacketsArriveCallback  onPacketsArrive,
void *  onPacketsArriveUserCookie 
)

There are two ways to capture packets using DpdkDevice: one of them is using worker threads (see DpdkDeviceList::startDpdkWorkerThreads() ) and the other way is setting a callback which is invoked each time a burst of packets is captured. This method implements the second way. After invoking this method the DpdkDevice enters capture mode and starts capturing packets. This method assumes there is only 1 RX queue opened for this device, otherwise an error is returned. It then allocates a core and creates 1 thread that runs in an endless loop and tries to capture packets using DPDK. Each time a burst of packets is captured the user callback is invoked with the user cookie as a parameter. This loop continues until stopCapture() is called. Notice: since the callback is invoked for every packet burst using this method can be slower than using worker threads. On the other hand, it's a simpler way comparing to worker threads

Parameters
[in]onPacketsArriveThe user callback which will be invoked each time a packet burst is captured by the device
[in]onPacketsArriveUserCookieThe user callback is invoked with this cookie as a parameter. It can be used to pass information from the user application to the callback
Returns
True if capture thread started successfully or false if device is already in capture mode, number of opened RX queues isn't equal to 1, if the method couldn't find an available core to allocate for the capture thread, or if thread invocation failed. In all of these cases an appropriate error message will be printed

◆ stopCapture()

void pcpp::DpdkDevice::stopCapture ( )

If device is in capture mode started by invoking startCaptureSingleThread() or startCaptureMultiThreads(), this method will stop all capturing threads and set the device to non-capturing mode