PF_RING API
API documentation for PF_RING: high-speed packet capture, filtering and analysis framework.
pfring_zc.h File Reference

PF_RING ZC library header file. More...

#include <sys/types.h>
#include <linux/pf_ring.h>

Go to the source code of this file.

Classes

struct  pfring_zc_stat
 
struct  pfring_zc_timespec
 
struct  pfring_zc_pkt_buff
 
struct  pfring_zc_queue_info
 

Macros

#define PF_RING_ZC_DEVICE_ASYMMETRIC_RSS   (1 << 0)
 
#define PF_RING_ZC_DEVICE_FIXED_RSS_Q_0   (1 << 1)
 
#define PF_RING_ZC_DEVICE_SW_TIMESTAMP   (1 << 2)
 
#define PF_RING_ZC_DEVICE_HW_TIMESTAMP   (1 << 3)
 
#define PF_RING_ZC_DEVICE_STRIP_HW_TIMESTAMP   (1 << 4)
 
#define PF_RING_ZC_DEVICE_IXIA_TIMESTAMP   (1 << 5)
 
#define PF_RING_ZC_DEVICE_NOT_REPROGRAM_RSS   (1 << 6)
 
#define PF_RING_ZC_DEVICE_CAPTURE_TX   (1 << 7)
 
#define PF_RING_ZC_DEVICE_IPONLY_RSS   (1 << 8)
 
#define PF_RING_ZC_DEVICE_NOT_PROMISC   (1 << 9)
 
#define UNDEFINED_QUEUEID   0xFFFFFFFF
 
#define QUEUE_IS_DEVICE(i)   (i > 0xFFFF)
 
#define QUEUEID_TO_IFINDEX(i)   (i >> 16)
 
#define IFINDEX_TO_QUEUEID(i)   (i << 16)
 
#define PF_RING_ZC_PKT_FLAGS_GOOD_IP_CS   (1 << 0)
 
#define PF_RING_ZC_PKT_FLAGS_BAD_IP_CS   (1 << 1)
 
#define PF_RING_ZC_PKT_FLAGS_GOOD_L4_CS   (1 << 2)
 
#define PF_RING_ZC_PKT_FLAGS_BAD_L4_CS   (1 << 3)
 
#define PF_RING_ZC_PKT_FLAGS_FLOW_OFFLOAD_UPDATE   (1 << 6)
 
#define PF_RING_ZC_PKT_FLAGS_FLOW_OFFLOAD_PACKET   (1 << 7)
 
#define PF_RING_ZC_PKT_FLAGS_FLOW_OFFLOAD_MARKER   (1 << 8)
 

Typedefs

typedef void pfring_zc_cluster
 
typedef void pfring_zc_queue
 
typedef void pfring_zc_buffer_pool
 
typedef void pfring_zc_worker
 
typedef void pfring_zc_multi_queue
 
typedef int64_t(* pfring_zc_distribution_func) (pfring_zc_pkt_buff *pkt_handle, pfring_zc_queue *in_queue, void *user)
 
typedef void(* pfring_zc_idle_callback) ()
 

Enumerations

enum  pfring_zc_queue_mode { rx_only, tx_only }
 
enum  pfring_zc_recv_policy { round_robin_policy = 0, round_robin_bursts_policy }
 

Functions

u_char * pfring_zc_pkt_buff_data (pfring_zc_pkt_buff *pkt_handle, pfring_zc_queue *queue)
 
pfring_zc_cluster * pfring_zc_create_cluster (u_int32_t cluster_id, u_int32_t buffer_len, u_int32_t metadata_len, u_int32_t tot_num_buffers, int32_t numa_node_id, const char *hugepages_mountpoint)
 
void pfring_zc_destroy_cluster (pfring_zc_cluster *cluster)
 
pfring_zc_queue * pfring_zc_open_device (pfring_zc_cluster *cluster, const char *device_name, pfring_zc_queue_mode queue_mode, u_int32_t flags)
 
pfring_zc_queue * pfring_zc_create_queue (pfring_zc_cluster *cluster, u_int32_t queue_len)
 
int pfring_zc_recv_pkt (pfring_zc_queue *queue, pfring_zc_pkt_buff **pkt_handle, u_int8_t wait_for_incoming_packet)
 
int pfring_zc_recv_pkt_burst (pfring_zc_queue *queue, pfring_zc_pkt_buff **pkt_handles, u_int32_t max_num_packets, u_int8_t wait_for_incoming_packet)
 
int pfring_zc_queue_is_empty (pfring_zc_queue *queue)
 
void pfring_zc_queue_breakloop (pfring_zc_queue *queue)
 
int pfring_zc_send_pkt (pfring_zc_queue *queue, pfring_zc_pkt_buff **pkt_handle, u_int8_t flush_packet)
 
int pfring_zc_send_pkt_burst (pfring_zc_queue *queue, pfring_zc_pkt_buff **pkt_handles, u_int32_t num_packets, u_int8_t flush_packets)
 
int pfring_zc_queue_is_full (pfring_zc_queue *queue)
 
void pfring_zc_sync_queue (pfring_zc_queue *queue, pfring_zc_queue_mode direction)
 
int pfring_zc_set_bpf_filter (pfring_zc_queue *queue, char *filter)
 
int pfring_zc_remove_bpf_filter (pfring_zc_queue *queue)
 
int pfring_zc_add_hw_rule (pfring_zc_queue *queue, hw_filtering_rule *rule)
 
int pfring_zc_remove_hw_rule (pfring_zc_queue *queue, u_int16_t rule_id)
 
void pfring_zc_set_rxfh_indir (pfring_zc_queue *queue, u_int8_t *indir_table)
 
u_int32_t pfring_zc_get_cluster_id (pfring_zc_cluster *cluster)
 
u_int32_t pfring_zc_get_queue_id (pfring_zc_queue *queue)
 
void pfring_zc_get_queue_settings (pfring_zc_queue *queue, pfring_zc_queue_info *info)
 
u_int32_t pfring_zc_get_queue_speed (pfring_zc_queue *queue)
 
int pfring_zc_stats (pfring_zc_queue *queue, pfring_zc_stat *stats)
 
pfring_zc_pkt_buffpfring_zc_get_packet_handle (pfring_zc_cluster *cluster)
 
void pfring_zc_release_packet_handle (pfring_zc_cluster *cluster, pfring_zc_pkt_buff *pkt_handle)
 
pfring_zc_multi_queue * pfring_zc_create_multi_queue (pfring_zc_queue *queues[], u_int32_t num_queues)
 
int pfring_zc_send_pkt_multi (pfring_zc_multi_queue *multi_queue, pfring_zc_pkt_buff **pkt_handle, u_int64_t queues_mask, u_int8_t flush_packet)
 
pfring_zc_worker * pfring_zc_run_balancer (pfring_zc_queue *in_queues[], pfring_zc_queue *out_queues[], u_int32_t num_in_queues, u_int32_t num_out_queues, pfring_zc_buffer_pool *working_set_pool, pfring_zc_recv_policy recv_policy, pfring_zc_idle_callback callback, pfring_zc_distribution_func func, void *user_data, u_int32_t active_wait, int32_t core_id_affinity)
 
pfring_zc_worker * pfring_zc_run_fanout (pfring_zc_queue *in_queues[], pfring_zc_multi_queue *out_multi_queue, u_int32_t num_in_queues, pfring_zc_buffer_pool *working_set_pool, pfring_zc_recv_policy recv_policy, pfring_zc_idle_callback callback, pfring_zc_distribution_func func, void *user_data, u_int32_t active_wait, int32_t core_id_affinity)
 
pfring_zc_worker * pfring_zc_run_fifo (pfring_zc_queue *in_queues[], pfring_zc_queue *out_queue, u_int32_t num_in_queues, pfring_zc_buffer_pool *working_set_pool, pfring_zc_idle_callback callback, pfring_zc_distribution_func func, void *user_data, u_int32_t active_wait, int32_t core_id_affinity_sorter, int32_t core_id_affinity_timer)
 
void pfring_zc_kill_worker (pfring_zc_worker *worker)
 
pfring_zc_buffer_pool * pfring_zc_create_buffer_pool (pfring_zc_cluster *cluster, u_int32_t pool_len)
 
pfring_zc_pkt_buffpfring_zc_get_packet_handle_from_pool (pfring_zc_buffer_pool *pool)
 
void pfring_zc_release_packet_handle_to_pool (pfring_zc_buffer_pool *pool, pfring_zc_pkt_buff *pkt_handle)
 
void pfring_zc_ipc_init (const char *hugepages_mountpoint)
 
pfring_zc_buffer_pool * pfring_zc_ipc_attach_buffer_pool (u_int32_t cluster_id, u_int32_t pool_id)
 
void pfring_zc_ipc_detach_buffer_pool (pfring_zc_buffer_pool *pool)
 
pfring_zc_queue * pfring_zc_ipc_attach_queue (u_int32_t cluster_id, u_int32_t queue_id, pfring_zc_queue_mode queue_mode)
 
void pfring_zc_ipc_detach_queue (pfring_zc_queue *queue)
 
int pfring_zc_vm_register (pfring_zc_cluster *cluster, const char *vm_monitor_socket_path)
 
int pfring_zc_vm_backend_enable (pfring_zc_cluster *cluster)
 
void pfring_zc_vm_guest_init (const char *uio_device)
 
u_int32_t pfring_zc_builtin_ip_hash (pfring_zc_pkt_buff *pkt_handle, pfring_zc_queue *queue)
 
u_int32_t pfring_zc_builtin_gtp_hash (pfring_zc_pkt_buff *pkt_handle, pfring_zc_queue *queue)
 
u_int32_t pfring_zc_builtin_gre_hash (pfring_zc_pkt_buff *pkt_handle, pfring_zc_queue *queue)
 
int pfring_zc_set_proc_stats (pfring_zc_cluster *cluster, char *stats)
 
int pfring_zc_set_app_name (pfring_zc_cluster *cluster, const char *name)
 
int pfring_zc_set_device_proc_stats (pfring_zc_queue *queue, const char *stats)
 
int pfring_zc_set_device_app_name (pfring_zc_queue *queue, const char *name)
 
char * pfring_zc_version ()
 
int pfring_zc_check_license ()
 
int pfring_zc_check_device_license (pfring_zc_queue *queue, u_int32_t *expiration_epoch)
 
int pfring_zc_check_device_license_by_name (char *device_name, u_int32_t *expiration_epoch)
 
int pfring_zc_numa_get_cpu_node (int core_id)
 
int pfring_zc_numa_set_numa_affinity (int node_id)
 
void pfring_zc_debug ()
 

Detailed Description

PF_RING ZC library header file.

This header file is automatically included in any PF_RING-based applications (when the HAVE_PF_RING_ZC macro is defined).

Macro Definition Documentation

◆ IFINDEX_TO_QUEUEID

#define IFINDEX_TO_QUEUEID (   i)    (i << 16)

pfring_zc_get_queue_id() return val: convert back device index to queue id, if QUEUE_IS_DEVICE(id)

◆ PF_RING_ZC_DEVICE_ASYMMETRIC_RSS

#define PF_RING_ZC_DEVICE_ASYMMETRIC_RSS   (1 << 0)

pfring_zc_open_device() flag: use asymmetric hw RSS for multiqueue devices.

◆ PF_RING_ZC_DEVICE_CAPTURE_TX

#define PF_RING_ZC_DEVICE_CAPTURE_TX   (1 << 7)

pfring_zc_open_device() flag: capture RX+TX traffic (ignored in kernel-bypass mode)

◆ PF_RING_ZC_DEVICE_FIXED_RSS_Q_0

#define PF_RING_ZC_DEVICE_FIXED_RSS_Q_0   (1 << 1)

pfring_zc_open_device() flag: redirect all traffic to the first hw queue.

◆ PF_RING_ZC_DEVICE_HW_TIMESTAMP

#define PF_RING_ZC_DEVICE_HW_TIMESTAMP   (1 << 3)

pfring_zc_open_device() flag: enable hw timestamp, when available

◆ PF_RING_ZC_DEVICE_IPONLY_RSS

#define PF_RING_ZC_DEVICE_IPONLY_RSS   (1 << 8)

pfring_zc_open_device() flag: compute RSS hash on IP only (not 4-tuple)

◆ PF_RING_ZC_DEVICE_IXIA_TIMESTAMP

#define PF_RING_ZC_DEVICE_IXIA_TIMESTAMP   (1 << 5)

pfring_zc_open_device() flag: extract IXIA timestamp from packet

◆ PF_RING_ZC_DEVICE_NOT_PROMISC

#define PF_RING_ZC_DEVICE_NOT_PROMISC   (1 << 9)

pfring_zc_open_device() flag: do NOT set the device in promiscuos mode

◆ PF_RING_ZC_DEVICE_NOT_REPROGRAM_RSS

#define PF_RING_ZC_DEVICE_NOT_REPROGRAM_RSS   (1 << 6)

pfring_zc_open_device() flag: do not reprogram RSS redirection table

◆ PF_RING_ZC_DEVICE_STRIP_HW_TIMESTAMP

#define PF_RING_ZC_DEVICE_STRIP_HW_TIMESTAMP   (1 << 4)

pfring_zc_open_device() flag: strip hw timestamp from packet, when available

◆ PF_RING_ZC_DEVICE_SW_TIMESTAMP

#define PF_RING_ZC_DEVICE_SW_TIMESTAMP   (1 << 2)

pfring_zc_open_device() flag: compute sw timestamp (please note: this adds per-packet overhead).

◆ PF_RING_ZC_PKT_FLAGS_BAD_IP_CS

#define PF_RING_ZC_PKT_FLAGS_BAD_IP_CS   (1 << 1)

pfring_zc_pkt_buff.flags: bad IP checksum detected

◆ PF_RING_ZC_PKT_FLAGS_BAD_L4_CS

#define PF_RING_ZC_PKT_FLAGS_BAD_L4_CS   (1 << 3)

pfring_zc_pkt_buff.flags: bad TCP/UDP checksum detected (note: UDP checksum 0 is detected as bad on some cards!)

◆ PF_RING_ZC_PKT_FLAGS_FLOW_OFFLOAD_MARKER

#define PF_RING_ZC_PKT_FLAGS_FLOW_OFFLOAD_MARKER   (1 << 8)

pfring_zc_pkt_buff.flags: buffer belongs to a flow that has been marked

◆ PF_RING_ZC_PKT_FLAGS_FLOW_OFFLOAD_PACKET

#define PF_RING_ZC_PKT_FLAGS_FLOW_OFFLOAD_PACKET   (1 << 7)

pfring_zc_pkt_buff.flags: buffer contains a raw packet

◆ PF_RING_ZC_PKT_FLAGS_FLOW_OFFLOAD_UPDATE

#define PF_RING_ZC_PKT_FLAGS_FLOW_OFFLOAD_UPDATE   (1 << 6)

pfring_zc_pkt_buff.flags: buffer contains flow metadata

◆ PF_RING_ZC_PKT_FLAGS_GOOD_IP_CS

#define PF_RING_ZC_PKT_FLAGS_GOOD_IP_CS   (1 << 0)

pfring_zc_pkt_buff.flags: valid IP checksum detected

◆ PF_RING_ZC_PKT_FLAGS_GOOD_L4_CS

#define PF_RING_ZC_PKT_FLAGS_GOOD_L4_CS   (1 << 2)

pfring_zc_pkt_buff.flags: valid TCP/UDP checksum detected

◆ QUEUE_IS_DEVICE

#define QUEUE_IS_DEVICE (   i)    (i > 0xFFFF)

pfring_zc_get_queue_id() return val: queue id is an encoded device index

◆ QUEUEID_TO_IFINDEX

#define QUEUEID_TO_IFINDEX (   i)    (i >> 16)

pfring_zc_get_queue_id() return val: convert queue id to device index, if QUEUE_IS_DEVICE(id)

◆ UNDEFINED_QUEUEID

#define UNDEFINED_QUEUEID   0xFFFFFFFF

pfring_zc_get_queue_id() return val: queue id is not valid

Typedef Documentation

◆ pfring_zc_distribution_func

typedef int64_t(* pfring_zc_distribution_func) (pfring_zc_pkt_buff *pkt_handle, pfring_zc_queue *in_queue, void *user)

The distribution function prototype.

Parameters
pkt_handleThe received buffer handle.
in_queueThe ingress queues handle from which the packet arrived.
userThe pointer to the user data.
Returns
The egress queue index (or a negative value to drop the packet) in case of balancing, the egress queues bit-mask in case of fan-out.

◆ pfring_zc_idle_callback

typedef void(* pfring_zc_idle_callback) ()

The idle callback prototype.

Enumeration Type Documentation

◆ pfring_zc_queue_mode

List of possible queue modes.

Enumerator
rx_only 

RX only mode.

tx_only 

TX only mode.

◆ pfring_zc_recv_policy

List of possible policies when receiving packets from multiple queues.

Enumerator
round_robin_policy 

Round-Robin policy.

round_robin_bursts_policy 

Round-Robin policy using bursts.

Function Documentation

◆ pfring_zc_add_hw_rule()

int pfring_zc_add_hw_rule ( pfring_zc_queue *  queue,
hw_filtering_rule *  rule 
)

Add an hw filtering rule to the network device, when the queue is bound to a supported card.

Parameters
queueThe queue handle.
ruleThe filtering rule.
Returns
0 on success, a negative value otherwise.

◆ pfring_zc_builtin_gre_hash()

u_int32_t pfring_zc_builtin_gre_hash ( pfring_zc_pkt_buff pkt_handle,
pfring_zc_queue *  queue 
)

Computes a Inner-IP-based packet hash on GRE packets, Outer-IP/Port-based packet hash otherwise.

Parameters
pkt_handleThe pointer to the buffer handle.
queueThe queue from which the packet is arrived or destined.
Returns
The packet hash.

◆ pfring_zc_builtin_gtp_hash()

u_int32_t pfring_zc_builtin_gtp_hash ( pfring_zc_pkt_buff pkt_handle,
pfring_zc_queue *  queue 
)

Computes a GTP-C Seq-based packet hash and a GTP-U Inner-IP/Port-based packet hash, Outer-IP/Port-based packet hash otherwise.

Parameters
pkt_handleThe pointer to the buffer handle.
queueThe queue from which the packet is arrived or destined.
Returns
The packet hash.

◆ pfring_zc_builtin_ip_hash()

u_int32_t pfring_zc_builtin_ip_hash ( pfring_zc_pkt_buff pkt_handle,
pfring_zc_queue *  queue 
)

Computes an IP-based packet hash.

Parameters
pkt_handleThe pointer to the buffer handle.
queueThe queue from which the packet is arrived or destined.
Returns
The packet hash.

◆ pfring_zc_check_device_license()

int pfring_zc_check_device_license ( pfring_zc_queue *  queue,
u_int32_t *  expiration_epoch 
)

Check if the license for a ZC device is valid and returns the license expiration epoch.

Parameters
queueThe queue handle for the device.
expiration_epochThe variable (ptr) that will contain the expiration epoch as return value.
Returns
1 if the license is valid, and set the expiration epoch accordingly, 0 otherwise.

◆ pfring_zc_check_device_license_by_name()

int pfring_zc_check_device_license_by_name ( char *  device_name,
u_int32_t *  expiration_epoch 
)

Check if the license for a ZC device is valid and returns the license expiration epoch.

Parameters
device_nameThe interface name.
expiration_epochThe variable (ptr) that will contain the expiration epoch as return value.
Returns
1 if the license is valid, and set the expiration epoch accordingly, 0 otherwise.

◆ pfring_zc_check_license()

int pfring_zc_check_license ( )

Check if ZC is running in demo mode (using adapters in zero-copy mode without a valid license)

Returns
1 if ZC is running with no demo limit, 0 otherwise.

◆ pfring_zc_create_buffer_pool()

pfring_zc_buffer_pool* pfring_zc_create_buffer_pool ( pfring_zc_cluster *  cluster,
u_int32_t  pool_len 
)

Create a buffer pool to reserve a subset of the global resources.

Parameters
clusterThe cluster handle.
pool_lenThe number of buffers to reserve for the pool.
Returns
The pool handle on success, NULL otherwise (errno is set appropriately).

◆ pfring_zc_create_cluster()

pfring_zc_cluster* pfring_zc_create_cluster ( u_int32_t  cluster_id,
u_int32_t  buffer_len,
u_int32_t  metadata_len,
u_int32_t  tot_num_buffers,
int32_t  numa_node_id,
const char *  hugepages_mountpoint 
)

Create a new cluster.

Parameters
cluster_idThe unique cluster identifier.
buffer_lenThe size of each buffer: it must be at least as large as the MTU + L2 header (it will be rounded up to cache line) and not bigger than the page size.
metadata_lenThe size of each buffer metadata.
tot_num_buffersThe total number of buffers to reserve for queues/devices/extra allocations.
numa_node_idThe NUMA node id for cpu/memory binding.
hugepages_mountpointThe HugeTLB mountpoint (NULL for auto-detection) for memory allocation.
Returns
The cluster handle on success, NULL otherwise (errno is set appropriately).

◆ pfring_zc_create_multi_queue()

pfring_zc_multi_queue* pfring_zc_create_multi_queue ( pfring_zc_queue *  queues[],
u_int32_t  num_queues 
)

Create a multi-queue object to send the same packet to multiple queues. Constraints: when using fan-out with multiqueue (i.e. calling pfring_zc_send_pkt_multi() with multiple bits set in queues_mask) it is not possible to have multiple multiqueue sharing the same consumers (expect metadata corruptions in this case). Note: this call will disable standard send on the queues (only pfring_zc_send_pkt_multi() is allowed).

Parameters
queuesThe array with the queues to bind to the multi-queue object.
num_queuesThe number of egress queues.
Returns
The multi-queue handle on success, NULL otherwise (errno is set appropriately).

◆ pfring_zc_create_queue()

pfring_zc_queue* pfring_zc_create_queue ( pfring_zc_cluster *  cluster,
u_int32_t  queue_len 
)

Create a SPSC queue.

Parameters
clusterThe cluster handle.
queue_lenThe queue length.
Returns
The queue handle on success, NULL otherwise (errno is set appropriately).

◆ pfring_zc_debug()

void pfring_zc_debug ( )

Enable debug mode

◆ pfring_zc_destroy_cluster()

void pfring_zc_destroy_cluster ( pfring_zc_cluster *  cluster)

Destroy a cluster.

Parameters
clusterThe cluster handle.

◆ pfring_zc_get_cluster_id()

u_int32_t pfring_zc_get_cluster_id ( pfring_zc_cluster *  cluster)

Get the cluster id.

Parameters
clusterThe cluster handle.
Returns
The cluster id.

◆ pfring_zc_get_packet_handle()

pfring_zc_pkt_buff* pfring_zc_get_packet_handle ( pfring_zc_cluster *  cluster)

Allocate a buffer from global resources.

Parameters
clusterThe cluster handle.
Returns
The buffer handle on success, NULL otherwise.

◆ pfring_zc_get_packet_handle_from_pool()

pfring_zc_pkt_buff* pfring_zc_get_packet_handle_from_pool ( pfring_zc_buffer_pool *  pool)

Allocate a buffer from a pool resource.

Parameters
poolThe pool handle.
Returns
The buffer handle on success, NULL otherwise.

◆ pfring_zc_get_queue_id()

u_int32_t pfring_zc_get_queue_id ( pfring_zc_queue *  queue)

Read the queue id. If the actual queue is a device, it is possible to convert the ID to the device index using QUEUEID_TO_IFINDEX(id)

Parameters
queueThe queue handle.
Returns
The queue id.

◆ pfring_zc_get_queue_settings()

void pfring_zc_get_queue_settings ( pfring_zc_queue *  queue,
pfring_zc_queue_info info 
)

Read queue settings, including queue len, buffers len, metadata len.

Parameters
queueThe queue handle.
infoThe queue settings (out).

◆ pfring_zc_get_queue_speed()

u_int32_t pfring_zc_get_queue_speed ( pfring_zc_queue *  queue)

Read queue speed.

Parameters
queueThe queue handle.
Returns
The queue speed in Mbit/s, 0 if unknown.

◆ pfring_zc_ipc_attach_buffer_pool()

pfring_zc_buffer_pool* pfring_zc_ipc_attach_buffer_pool ( u_int32_t  cluster_id,
u_int32_t  pool_id 
)

Attach to a pool created by a cluster in another process.

Parameters
cluster_idThe cluster identifier.
pool_idThe pool identifier.
Returns
The pool handle on success, NULL otherwise (errno is set appropriately).

◆ pfring_zc_ipc_attach_queue()

pfring_zc_queue* pfring_zc_ipc_attach_queue ( u_int32_t  cluster_id,
u_int32_t  queue_id,
pfring_zc_queue_mode  queue_mode 
)

Attach to a queue created by a cluster on another process.

Parameters
cluster_idThe cluster identifier.
queue_idThe queue identifier.
queue_modeThe direction to open, RX or TX.
Returns
The queue handle on success, NULL otherwise (errno is set appropriately).

◆ pfring_zc_ipc_detach_buffer_pool()

void pfring_zc_ipc_detach_buffer_pool ( pfring_zc_buffer_pool *  pool)

Detach a pool.

Parameters
poolThe pool handle.

◆ pfring_zc_ipc_detach_queue()

void pfring_zc_ipc_detach_queue ( pfring_zc_queue *  queue)

Detach a queue.

Parameters
queueThe queue handle.

◆ pfring_zc_ipc_init()

void pfring_zc_ipc_init ( const char *  hugepages_mountpoint)

Initialise the inter-process support on a slave.

Parameters
hugepages_mountpointThe HugeTLB mountpoint (NULL for auto-detection) for the shared memory.

◆ pfring_zc_kill_worker()

void pfring_zc_kill_worker ( pfring_zc_worker *  worker)

Kill the worker.

Parameters
workerThe worker handle.

◆ pfring_zc_numa_get_cpu_node()

int pfring_zc_numa_get_cpu_node ( int  core_id)

Return the NUMA node bound to the selected core

Parameters
core_idThe core id
Returns
node id on success, -1 otherwise.

◆ pfring_zc_numa_set_numa_affinity()

int pfring_zc_numa_set_numa_affinity ( int  node_id)

Set the NUMA affinity to the selected NUMA node (for memory allocation)

Parameters
node_idThe NUMA node id
Returns
0 on success, -1 otherwise.

◆ pfring_zc_open_device()

pfring_zc_queue* pfring_zc_open_device ( pfring_zc_cluster *  cluster,
const char *  device_name,
pfring_zc_queue_mode  queue_mode,
u_int32_t  flags 
)

Open a network device.

Parameters
clusterThe cluster handle.
device_nameThe device name.
queue_modeThe direction, RX or TX.
flagsOptional flags.
Returns
The queue handle on success, NULL otherwise (errno is set appropriately).

◆ pfring_zc_pkt_buff_data()

u_char* pfring_zc_pkt_buff_data ( pfring_zc_pkt_buff pkt_handle,
pfring_zc_queue *  queue 
)

Returns the pointer to the actual packet data.

Parameters
pkt_handleThe buffer handle.
queueThe queue from which the packet is arrived or destined.
Returns
The pointer on success, NULL otherwise.

◆ pfring_zc_queue_breakloop()

void pfring_zc_queue_breakloop ( pfring_zc_queue *  queue)

Break the receive loop in case of blocking pfring_zc_recv_pkt()/pfring_zc_recv_pkt_burst().

Parameters
queueThe queue handle.

◆ pfring_zc_queue_is_empty()

int pfring_zc_queue_is_empty ( pfring_zc_queue *  queue)

Check if the queue is empty (rx only for devices).

Parameters
queueThe queue handle.
Returns
1 on empty queue, 0 otherwise.

◆ pfring_zc_queue_is_full()

int pfring_zc_queue_is_full ( pfring_zc_queue *  queue)

Check if the queue is full (tx only for devices).

Parameters
queueThe queue handle.
Returns
1 on full queue, 0 otherwise.

◆ pfring_zc_recv_pkt()

int pfring_zc_recv_pkt ( pfring_zc_queue *  queue,
pfring_zc_pkt_buff **  pkt_handle,
u_int8_t  wait_for_incoming_packet 
)

Read the next packet from the queue.

Parameters
queueThe queue handle.
pkt_handleThe pointer to the buffer handle for the received buffer. The buffer handle must have been allocated earlier with get_packet_handle()/get_packet_handle_from_pool().
wait_for_incoming_packetThe flag indicating whether this call is blocking or not.
Returns
1 on success, 0 on empty queue (non-blocking only), a negative value otherwise.

◆ pfring_zc_recv_pkt_burst()

int pfring_zc_recv_pkt_burst ( pfring_zc_queue *  queue,
pfring_zc_pkt_buff **  pkt_handles,
u_int32_t  max_num_packets,
u_int8_t  wait_for_incoming_packet 
)

Read a burst of packets from the queue.

Parameters
queueThe queue handle.
pkt_handlesThe array with the buffer handles for the received buffers. The buffer handles must have been allocated earlier with get_packet_handle()/get_packet_handle_from_pool().
max_num_packetsThe maximum number of packets to read from the queue.
wait_for_incoming_packetThe flag indicating whether this call is blocking or not.
Returns
The number of received packets on success, 0 on empty queue (non-blocking only), a negative value otherwise.

◆ pfring_zc_release_packet_handle()

void pfring_zc_release_packet_handle ( pfring_zc_cluster *  cluster,
pfring_zc_pkt_buff pkt_handle 
)

Release a buffer to global resources.

Parameters
clusterThe cluster handle.
pkt_handleThe buffer handle.

◆ pfring_zc_release_packet_handle_to_pool()

void pfring_zc_release_packet_handle_to_pool ( pfring_zc_buffer_pool *  pool,
pfring_zc_pkt_buff pkt_handle 
)

Release a buffer to a pool.

Parameters
poolThe pool handle.
pkt_handleThe buffer handle.

◆ pfring_zc_remove_bpf_filter()

int pfring_zc_remove_bpf_filter ( pfring_zc_queue *  queue)

Remove the BPF filter.

Parameters
queueThe queue handle.
Returns
0 on success, a negative value otherwise.

◆ pfring_zc_remove_hw_rule()

int pfring_zc_remove_hw_rule ( pfring_zc_queue *  queue,
u_int16_t  rule_id 
)

Remove an hw filtering rule from the network device.

Parameters
queueThe queue handle.
rule_idThe filtering rule identifier.
Returns
0 on success, a negative value otherwise.

◆ pfring_zc_run_balancer()

pfring_zc_worker* pfring_zc_run_balancer ( pfring_zc_queue *  in_queues[],
pfring_zc_queue *  out_queues[],
u_int32_t  num_in_queues,
u_int32_t  num_out_queues,
pfring_zc_buffer_pool *  working_set_pool,
pfring_zc_recv_policy  recv_policy,
pfring_zc_idle_callback  callback,
pfring_zc_distribution_func  func,
void *  user_data,
u_int32_t  active_wait,
int32_t  core_id_affinity 
)

Run a balancer worker.

Parameters
in_queuesThe ingress queues handles array.
out_queuesThe egress queues handles array.
num_in_queuesThe number of ingress queues.
num_out_queuesThe number of egress queues.
working_set_poolThe pool handle for working set buffers allocation. The worker uses 8 buffers in burst mode, 1 otherwise.
recv_policyThe receive policy.
callbackThe function called when there is no incoming packet.
funcThe distribution function, or NULL for the defualt IP-based distribution function.
user_dataThe user data passed to distribution function.
active_waitThe flag indicating whether the worker should use active or passive wait for incoming packets.
core_id_affinityThe core affinity for the worker thread.
Returns
The worker handle on success, NULL otherwise (errno is set appropriately).

◆ pfring_zc_run_fanout()

pfring_zc_worker* pfring_zc_run_fanout ( pfring_zc_queue *  in_queues[],
pfring_zc_multi_queue *  out_multi_queue,
u_int32_t  num_in_queues,
pfring_zc_buffer_pool *  working_set_pool,
pfring_zc_recv_policy  recv_policy,
pfring_zc_idle_callback  callback,
pfring_zc_distribution_func  func,
void *  user_data,
u_int32_t  active_wait,
int32_t  core_id_affinity 
)

Run a fan-out worker.

Parameters
in_queuesThe ingress queues handles array.
out_multi_queuesThe egress multi-queue handle.
num_in_queuesThe number of ingress queues.
working_set_poolThe pool handle for working set buffers allocation. The worker uses 8 buffers in burst mode, 1 otherwise.
recv_policyThe receive policy.
callbackThe function called when there is no incoming packet.
funcThe distribution function, or NULL to send all the packets to all the egress queues.
user_dataThe user data passed to distribution function.
active_waitThe flag indicating whether the worker should use active or passive wait for incoming packets.
core_id_affinityThe core affinity for the worker thread.
Returns
The worker handle on success, NULL otherwise (errno is set appropriately).

◆ pfring_zc_run_fifo()

pfring_zc_worker* pfring_zc_run_fifo ( pfring_zc_queue *  in_queues[],
pfring_zc_queue *  out_queue,
u_int32_t  num_in_queues,
pfring_zc_buffer_pool *  working_set_pool,
pfring_zc_idle_callback  callback,
pfring_zc_distribution_func  func,
void *  user_data,
u_int32_t  active_wait,
int32_t  core_id_affinity_sorter,
int32_t  core_id_affinity_timer 
)

Run a fifo worker. (experimental)

Parameters
in_queuesThe ingress queues handles array.
out_queueThe egress queue handle, or NULL for processing packets directly using the provided func.
num_in_queuesThe number of ingress queues.
working_set_poolThe pool handle for working set buffers allocation. The worker uses num_in_queues * 32 buffers.
callbackThe function called when there is no incoming packet.
funcThe packet processing function.
user_dataThe user data passed to func.
active_waitThe flag indicating whether the worker should use active or passive wait for incoming packets.
core_id_affinity_sorterThe core affinity for the sorter thread.
core_id_affinity_timerThe core affinity for the timer thread.
Returns
The worker handle on success, NULL otherwise (errno is set appropriately).

◆ pfring_zc_send_pkt()

int pfring_zc_send_pkt ( pfring_zc_queue *  queue,
pfring_zc_pkt_buff **  pkt_handle,
u_int8_t  flush_packet 
)

Insert a packet into the queue.

Parameters
queueThe queue handle.
pkt_handleThe pointer to the buffer handle to send. Once a packet has been sent, the buffer handle can be reused or if not longer necessary it must be freed by calling pfring_zc_release_packet_handle().
flush_packetThe flag indicating whether this call should flush the enqueued packet, and older packets if any.
Returns
The packet length on success, a negative value otherwise.

◆ pfring_zc_send_pkt_burst()

int pfring_zc_send_pkt_burst ( pfring_zc_queue *  queue,
pfring_zc_pkt_buff **  pkt_handles,
u_int32_t  num_packets,
u_int8_t  flush_packets 
)

Send a burst of packets to the queue.

Parameters
queueThe queue handle.
pkt_handlesThe array with the buffer handles for the buffers to send.
num_packetsThe number of packets to send to the queue.
flush_packetThe flag indicating whether this call should flush the enqueued packets, and older packets if any.
Returns
The number of packets successfully sent, a negative value in case of error.

◆ pfring_zc_send_pkt_multi()

int pfring_zc_send_pkt_multi ( pfring_zc_multi_queue *  multi_queue,
pfring_zc_pkt_buff **  pkt_handle,
u_int64_t  queues_mask,
u_int8_t  flush_packet 
)

Send a packet to multiple queues bound to a multi-queue object.

Parameters
multi_queueThe multi-queue handle.
pkt_handleThe pointer to the buffer handle to send. Once a packet has been sent, the buffer handle can be reused or if not longer necessary it must be freed by calling pfring_zc_release_packet_handle().
queues_maskThe mask with the egress queues where the buffer should be inserted. The LSB indicates the first queue in the multi-queue array.
flush_packetThe flag indicating whether this call should flush the enqueued packet, and older packets if any.
Returns
The number of packet copies enqueued.

◆ pfring_zc_set_app_name()

int pfring_zc_set_app_name ( pfring_zc_cluster *  cluster,
const char *  name 
)

Write application name under /proc/net/pf_ring/<socket>

Parameters
nameThe application name.
Returns
0 on success, a negative value otherwise.

◆ pfring_zc_set_bpf_filter()

int pfring_zc_set_bpf_filter ( pfring_zc_queue *  queue,
char *  filter 
)

Set a BPF filter.

Parameters
queueThe queue handle.
filterThe BPF filter.
Returns
0 on success, a negative value otherwise.

◆ pfring_zc_set_device_app_name()

int pfring_zc_set_device_app_name ( pfring_zc_queue *  queue,
const char *  name 
)

Write application name under /proc/net/pf_ring/<socket>

Parameters
queueThe queue handle for the device.
nameThe application name.
Returns
0 on success, a negative value otherwise.

◆ pfring_zc_set_device_proc_stats()

int pfring_zc_set_device_proc_stats ( pfring_zc_queue *  queue,
const char *  stats 
)

Write custom device stats under /proc/net/pf_ring/stats/<device file>="">

Parameters
queueThe queue handle for the device.
statsThe stats string to write.
Returns
0 on success, a negative value otherwise.

◆ pfring_zc_set_proc_stats()

int pfring_zc_set_proc_stats ( pfring_zc_cluster *  cluster,
char *  stats 
)

Write custom stats under /proc/net/pf_ring/stats/<cluster file>="">

Parameters
clusterThe cluster handle.
statsThe stats string to write.
Returns
0 on success, a negative value otherwise.

◆ pfring_zc_set_rxfh_indir()

void pfring_zc_set_rxfh_indir ( pfring_zc_queue *  queue,
u_int8_t *  indir_table 
)

Change the hw RSS indirection table (RETA) for Intel igb/ixgbe-based cards.

Parameters
queueThe queue handle.
indir_tableThe indirection table (128 cells), with the destination queue for each hash value input.

◆ pfring_zc_stats()

int pfring_zc_stats ( pfring_zc_queue *  queue,
pfring_zc_stat stats 
)

Read the queue stats.

Parameters
queueThe queue handle.
statsThe stats structure.
Returns
0 on success, a negative value otherwise.

◆ pfring_zc_sync_queue()

void pfring_zc_sync_queue ( pfring_zc_queue *  queue,
pfring_zc_queue_mode  direction 
)

Sync/flush a queue.

Parameters
queueThe queue handle.
directionThe direction to sync/flush, RX or TX.

◆ pfring_zc_version()

char* pfring_zc_version ( )

Return the ZC version

Returns
The PF_RING ZC version.

◆ pfring_zc_vm_backend_enable()

int pfring_zc_vm_backend_enable ( pfring_zc_cluster *  cluster)

(Host) Enable the KVM support for all the VMs registered with pfring_zc_vm_register().

Parameters
clusterThe cluster handle.
Returns
0 on success, a negative value otherwise.

◆ pfring_zc_vm_guest_init()

void pfring_zc_vm_guest_init ( const char *  uio_device)

(Guest) Initialise the inter-VM support on a slave.

Parameters
uio_deviceThe UIO device path for the shared memory.

◆ pfring_zc_vm_register()

int pfring_zc_vm_register ( pfring_zc_cluster *  cluster,
const char *  vm_monitor_socket_path 
)

(Host) Initialise the KVM support for a VM.

Parameters
clusterThe cluster handle.
vm_monitor_socket_pathThe monitor socket of the VM to initialise.
Returns
0 on success, a negative value otherwise.