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

Go to the source code of this file.

Data Structures

struct  pfring_zc_stat
 Queue stats structure. More...
 
struct  pfring_zc_timespec
 Struct for nsec time (similar to struct timespec). More...
 
struct  pfring_zc_pkt_buff
 Buffer handle. More...
 
struct  pfring_zc_queue_info
 Buffer handle. More...
 

Macros

#define PF_RING_ZC_DEVICE_ASYMMETRIC_RSS   (1 << 0)
 pfring_zc_open_device() flag: use asymmetric hw RSS for multiqueue devices. More...
 
#define PF_RING_ZC_DEVICE_FIXED_RSS_Q_0   (1 << 1)
 pfring_zc_open_device() flag: redirect all traffic to the first hw queue. More...
 
#define PF_RING_ZC_DEVICE_SW_TIMESTAMP   (1 << 2)
 pfring_zc_open_device() flag: compute sw timestamp (please note: this adds per-packet overhead). More...
 
#define PF_RING_ZC_DEVICE_HW_TIMESTAMP   (1 << 3)
 pfring_zc_open_device() flag: enable hw timestamp, when available More...
 
#define PF_RING_ZC_DEVICE_STRIP_HW_TIMESTAMP   (1 << 4)
 pfring_zc_open_device() flag: strip hw timestamp from packet, when available More...
 
#define PF_RING_ZC_DEVICE_IXIA_TIMESTAMP   (1 << 5)
 pfring_zc_open_device() flag: extract IXIA timestamp from packet More...
 
#define PF_RING_ZC_DEVICE_NOT_REPROGRAM_RSS   (1 << 6)
 pfring_zc_open_device() flag: do not reprogram RSS redirection table More...
 
#define PF_RING_ZC_DEVICE_CAPTURE_TX   (1 << 7)
 pfring_zc_open_device() flag: capture RX+TX traffic (ignored in kernel-bypass mode) More...
 
#define PF_RING_ZC_DEVICE_IPONLY_RSS   (1 << 8)
 pfring_zc_open_device() flag: compute RSS hash on IP only (not 4-tuple) More...
 
#define PF_RING_ZC_DEVICE_NOT_PROMISC   (1 << 9)
 pfring_zc_open_device() flag: do NOT set the device in promiscuos mode More...
 
#define UNDEFINED_QUEUEID   0xFFFFFFFF
 pfring_zc_get_queue_id() return val: queue id is not valid More...
 
#define QUEUE_IS_DEVICE(i)   (i > 0xFFFF)
 pfring_zc_get_queue_id() return val: queue id is an encoded device index More...
 
#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) More...
 
#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) More...
 
#define PF_RING_ZC_PKT_FLAGS_GOOD_IP_CS   (1 << 0)
 pfring_zc_pkt_buff.flags: valid IP checksum detected More...
 
#define PF_RING_ZC_PKT_FLAGS_BAD_IP_CS   (1 << 1)
 pfring_zc_pkt_buff.flags: bad IP checksum detected More...
 
#define PF_RING_ZC_PKT_FLAGS_GOOD_L4_CS   (1 << 2)
 pfring_zc_pkt_buff.flags: valid TCP/UDP checksum detected More...
 
#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!) More...
 

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 int32_t(* pfring_zc_distribution_func )(pfring_zc_pkt_buff *pkt_handle, pfring_zc_queue *in_queue, void *user)
 The distribution function prototype. More...
 
typedef void(* pfring_zc_idle_callback )()
 The idle callback prototype. More...
 

Enumerations

enum  pfring_zc_queue_mode { rx_only, tx_only }
 List of possible queue modes. More...
 
enum  pfring_zc_recv_policy { round_robin_policy = 0, round_robin_bursts_policy }
 List of possible policies when receiving packets from multiple queues. More...
 

Functions

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. More...
 
pfring_zc_clusterpfring_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. More...
 
void pfring_zc_destroy_cluster (pfring_zc_cluster *cluster)
 Destroy a cluster. More...
 
pfring_zc_queuepfring_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. More...
 
pfring_zc_queuepfring_zc_create_queue (pfring_zc_cluster *cluster, u_int32_t queue_len)
 Create a SPSC queue. More...
 
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. More...
 
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. More...
 
int pfring_zc_queue_is_empty (pfring_zc_queue *queue)
 Check if the queue is empty. More...
 
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(). More...
 
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. More...
 
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. More...
 
int pfring_zc_queue_is_full (pfring_zc_queue *queue)
 Check if the queue is full. More...
 
void pfring_zc_sync_queue (pfring_zc_queue *queue, pfring_zc_queue_mode direction)
 Sync/flush a queue. More...
 
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. More...
 
int pfring_zc_remove_hw_rule (pfring_zc_queue *queue, u_int16_t rule_id)
 Remove an hw filtering rule from the network device. More...
 
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)
 Get the cluster id. More...
 
u_int32_t pfring_zc_get_queue_id (pfring_zc_queue *queue)
 Read the queue id. More...
 
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. More...
 
u_int32_t pfring_zc_get_queue_speed (pfring_zc_queue *queue)
 Read queue speed. More...
 
int pfring_zc_stats (pfring_zc_queue *queue, pfring_zc_stat *stats)
 Read the queue stats. More...
 
pfring_zc_pkt_buffpfring_zc_get_packet_handle (pfring_zc_cluster *cluster)
 Allocate a buffer from global resources. More...
 
void pfring_zc_release_packet_handle (pfring_zc_cluster *cluster, pfring_zc_pkt_buff *pkt_handle)
 Release a buffer to global resources. More...
 
pfring_zc_multi_queuepfring_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. More...
 
int pfring_zc_send_pkt_multi (pfring_zc_multi_queue *multi_queue, pfring_zc_pkt_buff **pkt_handle, u_int32_t queues_mask, u_int8_t flush_packet)
 Send a packet to multiple queues bound to a multi-queue object. More...
 
pfring_zc_workerpfring_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. More...
 
pfring_zc_workerpfring_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. More...
 
pfring_zc_workerpfring_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. More...
 
void pfring_zc_kill_worker (pfring_zc_worker *worker)
 Kill the worker. More...
 
pfring_zc_buffer_poolpfring_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. More...
 
pfring_zc_pkt_buffpfring_zc_get_packet_handle_from_pool (pfring_zc_buffer_pool *pool)
 Allocate a buffer from a pool resource. More...
 
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. More...
 
void pfring_zc_ipc_init (const char *hugepages_mountpoint)
 Initialise the inter-process support on a slave. More...
 
pfring_zc_buffer_poolpfring_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. More...
 
void pfring_zc_ipc_detach_buffer_pool (pfring_zc_buffer_pool *pool)
 Detach a pool. More...
 
pfring_zc_queuepfring_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. More...
 
void pfring_zc_ipc_detach_queue (pfring_zc_queue *queue)
 Detach a queue. More...
 
int pfring_zc_vm_register (pfring_zc_cluster *cluster, const char *vm_monitor_socket_path)
 (Host) Initialise the KVM support for a VM. More...
 
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(). More...
 
void pfring_zc_vm_guest_init (const char *uio_device)
 (Guest) Initialise the inter-VM support on a slave. More...
 
u_int32_t pfring_zc_builtin_ip_hash (pfring_zc_pkt_buff *pkt_handle, pfring_zc_queue *queue)
 Computes an IP-based packet hash. More...
 
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. More...
 
int pfring_zc_set_proc_stats (pfring_zc_cluster *cluster, char *stats)
 Write custom stats under /proc/net/pf_ring/stats/<cluster file>=""> More...
 
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>=""> More...
 
int pfring_zc_set_device_app_name (pfring_zc_queue *queue, const char *name)
 Write application name under /proc/net/pf_ring/<socket> More...
 
char * pfring_zc_version ()
 Return the ZC version. More...
 
int pfring_zc_check_license ()
 Check if ZC is running in demo mode (using adapters in zero-copy mode without a valid license) More...
 
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. More...
 
int pfring_zc_numa_get_cpu_node (int core_id)
 Return the NUMA node bound to the selected core. More...
 
int pfring_zc_numa_set_numa_affinity (int node_id)
 Set the NUMA affinity to the selected NUMA node (for memory allocation) More...
 

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

#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)

#define PF_RING_ZC_DEVICE_ASYMMETRIC_RSS   (1 << 0)

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

#define PF_RING_ZC_DEVICE_CAPTURE_TX   (1 << 7)

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

#define PF_RING_ZC_DEVICE_FIXED_RSS_Q_0   (1 << 1)

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

#define PF_RING_ZC_DEVICE_HW_TIMESTAMP   (1 << 3)

pfring_zc_open_device() flag: enable hw timestamp, when available

#define PF_RING_ZC_DEVICE_IPONLY_RSS   (1 << 8)

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

#define PF_RING_ZC_DEVICE_IXIA_TIMESTAMP   (1 << 5)

pfring_zc_open_device() flag: extract IXIA timestamp from packet

#define PF_RING_ZC_DEVICE_NOT_PROMISC   (1 << 9)

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

#define PF_RING_ZC_DEVICE_NOT_REPROGRAM_RSS   (1 << 6)

pfring_zc_open_device() flag: do not reprogram RSS redirection table

#define PF_RING_ZC_DEVICE_STRIP_HW_TIMESTAMP   (1 << 4)

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

#define PF_RING_ZC_DEVICE_SW_TIMESTAMP   (1 << 2)

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

#define PF_RING_ZC_PKT_FLAGS_BAD_IP_CS   (1 << 1)

pfring_zc_pkt_buff.flags: bad IP checksum detected

#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!)

#define PF_RING_ZC_PKT_FLAGS_GOOD_IP_CS   (1 << 0)

pfring_zc_pkt_buff.flags: valid IP checksum detected

#define PF_RING_ZC_PKT_FLAGS_GOOD_L4_CS   (1 << 2)

pfring_zc_pkt_buff.flags: valid TCP/UDP checksum detected

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

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

#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)

#define UNDEFINED_QUEUEID   0xFFFFFFFF

pfring_zc_get_queue_id() return val: queue id is not valid

Typedef Documentation

typedef void pfring_zc_buffer_pool
typedef void pfring_zc_cluster
typedef int32_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.
typedef void(* pfring_zc_idle_callback)()

The idle callback prototype.

typedef void pfring_zc_multi_queue
typedef void pfring_zc_queue
typedef void pfring_zc_worker

Enumeration Type Documentation

List of possible queue modes.

Enumerator
rx_only 

RX only mode.

tx_only 

TX only mode.

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

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.
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.
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.
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.
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_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_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_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.

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_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).
void pfring_zc_destroy_cluster ( pfring_zc_cluster cluster)

Destroy a cluster.

Parameters
clusterThe cluster handle.
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_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_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.
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.
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).
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_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_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).
void pfring_zc_ipc_detach_buffer_pool ( pfring_zc_buffer_pool pool)

Detach a pool.

Parameters
poolThe pool handle.
void pfring_zc_ipc_detach_queue ( pfring_zc_queue queue)

Detach a queue.

Parameters
queueThe queue handle.
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.
void pfring_zc_kill_worker ( pfring_zc_worker worker)

Kill the worker.

Parameters
workerThe worker handle.
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.
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_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).
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.
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.
int pfring_zc_queue_is_empty ( pfring_zc_queue queue)

Check if the queue is empty.

Parameters
queueThe queue handle.
Returns
1 on empty queue, 0 otherwise.
int pfring_zc_queue_is_full ( pfring_zc_queue queue)

Check if the queue is full.

Parameters
queueThe queue handle.
Returns
1 on full queue, 0 otherwise.
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.
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.
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.
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.
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_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_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_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).
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.
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.
int pfring_zc_send_pkt_multi ( pfring_zc_multi_queue multi_queue,
pfring_zc_pkt_buff **  pkt_handle,
u_int32_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.
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.
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.
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.
void pfring_zc_set_rxfh_indir ( pfring_zc_queue queue,
u_int8_t *  indir_table 
)
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.
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.
char* pfring_zc_version ( )

Return the ZC version.

Returns
The PF_RING ZC version.
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.
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.
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.