3. PF_RING ZC API

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

Defines

PF_RING_ZC_ENABLE_VM_SUPPORT: pfring_zc_create_cluster() flag: enable KVM support (memory is rounded up to power of 2 thus it allocates more memory!)

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

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

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

PF_RING_ZC_DEVICE_HW_TIMESTAMP: pfring_zc_open_device() flag: enable hw timestamp, when available

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

PF_RING_ZC_DEVICE_IXIA_TIMESTAMP: pfring_zc_open_device() flag: extract IXIA timestamp from packet

PF_RING_ZC_DEVICE_NOT_REPROGRAM_RSS: pfring_zc_open_device() flag: do not reprogram RSS redirection table

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

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

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

PF_RING_ZC_DO_NOT_STRIP_FCS: pfring_zc_open_device() flag: do NOT strip the FCS (CRC), when not stripped out by the adapter

PF_RING_ZC_DEVICE_ARISTA_TIMESTAMP: pfring_zc_open_device() flag: extract Arista 7150 series timestamp from packet

PF_RING_ZC_DEVICE_METAWATCH_TIMESTAMP: pfring_zc_open_device() flag: extract Arista Metawatch timestamp from packet

PF_RING_ZC_DEVICE_CAPTURE_INJECTED: pfring_zc_open_device() flag: capture also injected packets (see PF_RING_DISCARD_INJECTED_PKTS)

PF_RING_ZC_DEVICE_HW_TIMESTAMP_UNSYNC: pfring_zc_open_device() flag: do not set hw clock when using PF_RING_ZC_DEVICE_HW_TIMESTAMP

UNDEFINED_QUEUEID: pfring_zc_get_queue_id() return val: queue id is not valid

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

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

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

PF_RING_ZC_PKT_FLAGS_GOOD_IP_CS: pfring_zc_pkt_buff.flags: valid IP checksum detected

PF_RING_ZC_PKT_FLAGS_BAD_IP_CS: pfring_zc_pkt_buff.flags: bad IP checksum detected

PF_RING_ZC_PKT_FLAGS_GOOD_L4_CS: pfring_zc_pkt_buff.flags: valid TCP/UDP checksum detected

PF_RING_ZC_PKT_FLAGS_BAD_L4_CS: 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_UPDATE: pfring_zc_pkt_buff.flags: Deprecated

PF_RING_ZC_PKT_FLAGS_FLOW_OFFLOAD_PACKET: pfring_zc_pkt_buff.flags: Deprecated

PF_RING_ZC_PKT_FLAGS_FLOW_OFFLOAD_MARKER: pfring_zc_pkt_buff.flags: Deprecated

PF_RING_ZC_PKT_FLAGS_FLOW_OFFLOAD_1ST: pfring_zc_pkt_buff.flags: Deprecated

PF_RING_ZC_BUILTIN_GTP_HASH_FLAGS_V1: pfring_zc_builtin_gtp_hash flags: GTP v1

PF_RING_ZC_BUILTIN_GTP_HASH_FLAGS_V2: pfring_zc_builtin_gtp_hash flags: GTP v2

PF_RING_ZC_BUILTIN_GTP_HASH_FLAGS_GTPC: pfring_zc_builtin_gtp_hash flags: GTP-C

PF_RING_ZC_BUILTIN_GTP_HASH_FLAGS_GTPU: pfring_zc_builtin_gtp_hash flags: GTP-U

PF_RING_ZC_API_CLUSTER_INFO

PF_RING_ZC_SEND_PKT_MULTI_MAX_QUEUES: pfring_zc_send_pkt_multi: max number of queues in queues_mask

PF_RING_ZC_SEND_PKT_MULTI_V3_MAX_QUEUES: pfring_zc_send_pkt_multi_v3: max number of queues in queues_mask

PF_RING_ZC_BUFFER_HEAD_ROOM

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_filtering_func)(pfring_zc_pkt_buff *pkt_handle, pfring_zc_queue *in_queue, void *user)

The filtering function prototype.

Param pkt_handle:: The received buffer handle.
Param in_queue:: The ingress queues handle from which the packet arrived.
Param user:: The pointer to the user data.
Return:: 0 to drop the packet, 1 to pass the packet.

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

The distribution function prototype.

Param pkt_handle:: The received buffer handle.
Param in_queue:: The ingress queues handle from which the packet arrived.
Param user:: The pointer to the user data.
Return:: 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 __int128_t (*pfring_zc_distribution_func_v3)(pfring_zc_pkt_buff *pkt_handle, pfring_zc_queue *in_queue, void *user)

The distribution function prototype (v3 - up to 128 queues with pfring_zc_run_fanout_v3).

Param pkt_handle:: The received buffer handle.
Param in_queue:: The ingress queues handle from which the packet arrived.
Param user:: The pointer to the user data.
Return:: 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.

Enums

enum pfring_zc_queue_mode

List of possible queue modes.

Values:

enumerator rx_only: RX only mode.

enumerator tx_only: TX only mode.

enumerator management_only: No capture/transmission.

enum pfring_zc_recv_policy

List of possible policies when receiving packets from multiple queues.

Values:

enumerator round_robin_policy: Round-Robin policy.

enumerator round_robin_bursts_policy: Round-Robin policy using bursts.

Functions

u_char *pfring_zc_pkt_buff_data(pfring_zc_pkt_buff *pkt_handle, pfring_zc_queue *queue)

Return the pointer to the actual packet data (same as pfring_zc_pkt_buff_data_from_cluster).

Parameters:

pkt_handle – The buffer handle.
queue – Any queue from the cluster (e.g. the queue from which the packet is arrived or destined).

Returns:

The pointer on success, NULL otherwise.

u_char *pfring_zc_pkt_buff_data_from_cluster(pfring_zc_pkt_buff *pkt_handle, pfring_zc_cluster *cluster)

Return the pointer to the actual packet data (same as pfring_zc_pkt_buff_data).

Parameters:

pkt_handle – The buffer handle.
cluster – The cluster handle.

Returns:

The pointer on success, NULL otherwise.

pfring_zc_pkt_buff *pfring_zc_pkt_data_buff(u_char *data, pfring_zc_cluster *cluster)

Return the buffer handle given a pointer to a actual packet data. This is the reverse of pfring_zc_pkt_buff_data.

Parameters:

data – The packet data pointer.
cluster – The cluster handle.

Returns:

The buffer handle on success, NULL otherwise.

u_char *pfring_zc_pkt_buff_pull(pfring_zc_pkt_buff *pkt_handle, pfring_zc_queue *queue, u_int16_t len)

Remove data from the start of a buffer.

Parameters:

pkt_handle – The buffer handle.
queue – Any queue from the cluster.
len – The number of bytes to remove.

Returns:

The pointer to the start of the buffer on success, NULL otherwise.

u_char *pfring_zc_pkt_buff_push(pfring_zc_pkt_buff *pkt_handle, pfring_zc_queue *queue, u_int16_t len)

Add data to the start of a buffer.

Parameters:

pkt_handle – The buffer handle.
queue – Any queue from the cluster.
len – The number of bytes to add.

Returns:

The pointer to the start of the buffer on success, NULL otherwise.

void pfring_zc_pkt_buff_pull_only(pfring_zc_pkt_buff *pkt_handle, u_int16_t len)

Remove data from the start of a buffer.

Parameters:

pkt_handle – The buffer handle.
len – The number of bytes to remove.

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, u_int32_t flags)

Create a new cluster.

Parameters:

cluster_id – The unique cluster identifier.
buffer_len – The 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_len – The size of each buffer metadata.
tot_num_buffers – The total number of buffers to reserve for queues/devices/extra allocations.
numa_node_id – The NUMA node id for cpu/memory binding.
hugepages_mountpoint – The HugeTLB mountpoint (NULL for auto-detection) for memory allocation.

flags – Optional flags:

PF_RING_ZC_ENABLE_VM_SUPPORT enable KVM support (memory is rounded up to power of 2 thus it allocates more memory!)

Returns:

The cluster handle on success, NULL otherwise (errno is set appropriately).

int pfring_zc_precompute_cluster_settings(pfring_zc_cluster_info *info, u_int32_t buffer_len, u_int32_t metadata_len, u_int32_t tot_num_buffers, u_int32_t flags)

Return information about the resources that will be allocated the cluster including the max amount of memory.

Parameters:

info – Out
info – A struct that is filled with the cluster information.
buffer_len – The 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_len – The size of each buffer metadata.
tot_num_buffers – The total number of buffers to reserve for queues/devices/extra allocations.

flags – Optional flags:

PF_RING_ZC_ENABLE_VM_SUPPORT enable KVM support (memory is rounded up to power of 2 thus it allocates more memory!)

Returns:

0 on success, a negative value otherwise (errno is also set appropriately)

int pfring_zc_get_memory_info(pfring_zc_cluster *cluster, pfring_zc_cluster_mem_info *mem_info)

Return information about allocated resources.

Parameters:

cluster – The cluster handle.
mem_info – The returned information.

u_int32_t pfring_zc_get_cluster_id(pfring_zc_cluster *cluster)

Get the cluster id.

Parameters:: cluster – The cluster handle.
Returns:: The cluster id.

void pfring_zc_destroy_cluster(pfring_zc_cluster *cluster)

Destroy a cluster.

Parameters:: cluster – The cluster handle.

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:

cluster – The cluster handle.
device_name – The device name.
queue_mode – The direction, RX or TX.

flags – Optional flags:

PF_RING_ZC_DEVICE_ASYMMETRIC_RSS use asymmetric hw RSS for multiqueue devices
PF_RING_ZC_DEVICE_FIXED_RSS_Q_0 redirect all traffic to the first hw queue
PF_RING_ZC_DEVICE_SW_TIMESTAMP compute sw timestamp (please note: this adds per-packet overhead).
PF_RING_ZC_DEVICE_HW_TIMESTAMP enable hw timestamp, when available 
PF_RING_ZC_DEVICE_STRIP_HW_TIMESTAMP strip hw timestamp from packet, when available
PF_RING_ZC_DEVICE_IXIA_TIMESTAMP extract IXIA timestamp from packet
PF_RING_ZC_DEVICE_NOT_REPROGRAM_RSS do not reprogram RSS redirection table
PF_RING_ZC_DEVICE_CAPTURE_TX capture RX+TX traffic (ignored in kernel-bypass mode)
PF_RING_ZC_DEVICE_IPONLY_RSS compute RSS hash on IP only (not 4-tuple)
PF_RING_ZC_DEVICE_NOT_PROMISC  do NOT set the device in promiscuos mode
PF_RING_ZC_DO_NOT_STRIP_FCS do NOT strip the FCS (CRC), when not stripped out by the adapter
PF_RING_ZC_DEVICE_ARISTA_TIMESTAMP extract Arista 7150s timestamp from packet
PF_RING_ZC_DEVICE_METAWATCH_TIMESTAMP extract Arista Metawatch timestamp from packet

Returns:

The 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. Please note that in order to create queues to be used by external processes, pfring_zc_create_queue_pool_pair is recommended.

Parameters:

cluster – The cluster handle.
queue_len – The queue length.

Returns:

The queue handle on success, NULL otherwise (errno is set appropriately).

int pfring_zc_create_queue_pool_pair(pfring_zc_cluster *cluster, u_int32_t queue_len, u_int32_t pool_len, pfring_zc_queue **queue, pfring_zc_buffer_pool **pool)

Create a pair of SPSC queue and Pool with the same ID. This can be used to create queues to be used by external processes.

Parameters:

cluster – The cluster handle.
queue_len – The queue length.
pool_len – The number of buffers to reserve for the pool.
queue – The queue handle on success, NULL otherwise (out)
pool – The pool handle on success, NULL otherwise (out)

Returns:

0 on success, a negative value otherwise (errno is also set appropriately)

void pfring_zc_close_device(pfring_zc_queue *queue)

Close a queue tied to a network device. Please note that by using this API to release a SPSC hugepages, memory is not actually released for a few reasons (e.g. memory becomes fragmented, and there could be consumer processes still mapping this memory). Please note that both devices and SPSC queues are automatically released calling pfring_zc_destroy_cluster.

Parameters:: queue – The queue handle.

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:

queue – The queue handle.
pkt_handle – The 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_packet – The 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:

queue – The queue handle.
pkt_handles – The 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_packets – The maximum number of packets to read from the queue.
wait_for_incoming_packet – The 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.

int pfring_zc_queue_is_empty(pfring_zc_queue *queue)

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

Parameters:: queue – The queue handle.
Returns:: 1 on empty queue, 0 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:: queue – The queue handle.

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:

queue – The queue handle.
pkt_handle – The 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_packet – The flag indicating whether this call should flush the enqueued packet, and older packets if any.

Returns:

The packet length on success, 0 if filtered out (bpf), a negative value otherwise.

int pfring_zc_send_pkt_get_time(pfring_zc_queue *queue, pfring_zc_pkt_buff **pkt_handle, u_int8_t flush_packet, struct timespec *ts)

Insert a packet into the queue and return the (hardware when available) send time.

Parameters:

queue – The queue handle.
pkt_handle – The 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_packet – This flag is currently ignored, packets is immediately sent out flushing also older packets if any.
ts – The send time.

Returns:

The packet length on success, 0 if filtered out (bpf), 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:

queue – The queue handle.
pkt_handles – The array with the buffer handles for the buffers to send.
num_packets – The number of packets to send to the queue.
flush_packets – The 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. Note: packets sent can be less than num_packets in case there is not enough room in the TX queue or in case of BPF filters.

int pfring_zc_queue_is_full(pfring_zc_queue *queue)

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

Parameters:: queue – The queue handle.
Returns:: 1 on full queue, 0 otherwise.

void pfring_zc_sync_queue(pfring_zc_queue *queue, pfring_zc_queue_mode direction)

Sync/flush a queue.

Parameters:

queue – The queue handle.
direction – The direction to sync/flush, RX or TX.

int pfring_zc_get_device_clock(pfring_zc_queue *queue, struct timespec *ts)

Read the time from the device hardware clock (if supported by the underlying device)

Parameters:

queue – The queue handle.
ts – The time.

int pfring_zc_set_device_clock(pfring_zc_queue *queue, struct timespec *ts)

Set the time in the device hardware clock (if supported by the underlying device)

Parameters:

queue – The queue handle.
ts – The time.

int pfring_zc_adjust_device_clock(pfring_zc_queue *queue, struct timespec *offset, int8_t sign)

Adjust the time in the device hardware clock with an offset (if supported by the underlying device)

Parameters:

queue – The queue handle.
offset – The time offset.
sign – The sign.

int pfring_zc_set_bpf_filter(pfring_zc_queue *queue, const char *filter)

Set a BPF filter.

Parameters:

queue – The queue handle.
filter – The BPF filter.

Returns:

0 on success, a negative value otherwise.

int pfring_zc_remove_bpf_filter(pfring_zc_queue *queue)

Remove the BPF filter.

Parameters:: queue – The queue handle.
Returns:: 0 on success, a negative value otherwise.

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:

queue – The queue handle.
rule – The filtering rule.

Returns:

0 on success, a negative value otherwise.

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:

queue – The queue handle.
rule_id – The filtering rule identifier.

Returns:

0 on success, a negative value otherwise.

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:

queue – The queue handle.
indir_table – The indirection table (128 cells), with the destination queue for each hash value input.

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:

queue – The queue handle.

Returns:

The queue id. A few macros are available to check the queue id:

UNDEFINED_QUEUEID queue id is not valid
QUEUE_IS_DEVICE(i) queue id is an encoded device index
QUEUEID_TO_IFINDEX(i) convert queue id to device index, if QUEUE_IS_DEVICE(id)
IFINDEX_TO_QUEUEID(i) convert back device index to queue id, if QUEUE_IS_DEVICE(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:

queue – The queue handle.
info – The queue settings (out).

u_int32_t pfring_zc_get_queue_speed(pfring_zc_queue *queue)

Read queue speed (in case of device queue).

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

u_int32_t pfring_zc_get_num_rx_channels(pfring_zc_queue *queue)

Read total number of RSS queues (in case of device).

Parameters:: queue – The queue handle.
Returns:: The number of RSS queues for the bound device.

int pfring_zc_stats(pfring_zc_queue *queue, pfring_zc_stat *stats)

Read the queue stats.

Parameters:

queue – The queue handle.
stats – The stats structure.

Returns:

0 on success, a negative value otherwise.

pfring_zc_pkt_buff *pfring_zc_get_packet_handle(pfring_zc_cluster *cluster)

Allocate a buffer from global resources.

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

void pfring_zc_release_packet_handle(pfring_zc_cluster *cluster, pfring_zc_pkt_buff *pkt_handle)

Release a buffer to global resources.

Parameters:

cluster – The cluster handle.
pkt_handle – The buffer handle.

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:

queues – The array with the queues to bind to the multi-queue object.
num_queues – The number of egress queues.

Returns:

The multi-queue handle on success, NULL otherwise (errno is set appropriately).

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 (up to 64 queues).

Parameters:

multi_queue – The multi-queue handle.
pkt_handle – The 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_mask – The mask with the egress queues where the buffer should be inserted. The LSB indicates the first queue in the multi-queue array. The max number of queues is defined in PF_RING_ZC_SEND_PKT_MULTI_MAX_QUEUES.
flush_packet – The 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_send_pkt_multi_v3(pfring_zc_multi_queue *multi_queue, pfring_zc_pkt_buff **pkt_handle, __int128_t queues_mask, u_int8_t flush_packet)

Send a packet to multiple queues bound to a multi-queue object (v3 - up to 128 queues).

Parameters:

multi_queue – The multi-queue handle.
pkt_handle – The 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_mask – The mask with the egress queues where the buffer should be inserted. The LSB indicates the first queue in the multi-queue array. The max number of queues is defined in PF_RING_ZC_SEND_PKT_MULTI_V3_MAX_QUEUES.
flush_packet – The flag indicating whether this call should flush the enqueued packet, and older packets if any.

Returns:

The number of packet copies enqueued.

pfring_zc_worker *pfring_zc_run_balancer_v2(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 idle_func, pfring_zc_filtering_func filter_func, void *filter_user_data, pfring_zc_distribution_func distr_func, void *distr_user_data, u_int32_t active_wait, int32_t core_id_affinity)

Run a balancer worker (v2).

Parameters:

in_queues – The ingress queues handles array.
out_queues – The egress queues handles array.
num_in_queues – The number of ingress queues.
num_out_queues – The number of egress queues.
working_set_pool – The pool handle for working set buffers allocation. The worker uses 8 buffers in burst mode, 1 otherwise.
recv_policy – The receive policy.
idle_func – The function called when there is no incoming packet.
filter_func – The filtering function, or NULL for no filtering.
filter_user_data – The user data passed to the filtering function.
distr_func – The distribution function, or NULL for the defualt IP-based distribution function.
distr_user_data – The user data passed to distribution function.
active_wait – The flag indicating whether the worker should use active or passive wait for incoming packets.
core_id_affinity – The core affinity for the worker thread.

Returns:

The worker handle on success, NULL otherwise (errno is set appropriately).

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 idle_func, pfring_zc_distribution_func distr_func, void *distr_user_data, u_int32_t active_wait, int32_t core_id_affinity): Same as pfring_zc_run_balancer_v2 but without a filtering function. (deprecated)

pfring_zc_worker *pfring_zc_run_fanout_v3(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 idle_func, pfring_zc_filtering_func filter_func, void *filter_user_data, pfring_zc_distribution_func_v3 distr_func, void *distr_user_data, u_int32_t active_wait, int32_t core_id_affinity)

Run a fan-out worker (v3 - up to 128 queues).

Parameters:

in_queues – The ingress queues handles array.
out_multi_queue – The egress multi-queue handle.
num_in_queues – The number of ingress queues.
working_set_pool – The pool handle for working set buffers allocation. The worker uses 8 buffers in burst mode, 1 otherwise.
recv_policy – The receive policy.
idle_func – The function called when there is no incoming packet.
filter_func – The filtering function, or NULL for no filtering.
filter_user_data – The user data passed to the filtering function.
distr_func – The distribution function, or NULL to send all the packets to all the egress queues.
distr_user_data – The user data passed to distribution function.
active_wait – The flag indicating whether the worker should use active or passive wait for incoming packets.
core_id_affinity – The 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_v2(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 idle_func, pfring_zc_filtering_func filter_func, void *filter_user_data, pfring_zc_distribution_func distr_func, void *distr_user_data, u_int32_t active_wait, int32_t core_id_affinity)

Run a fan-out worker (v2 - up to 64 queues).

Parameters:

in_queues – The ingress queues handles array.
out_multi_queue – The egress multi-queue handle.
num_in_queues – The number of ingress queues.
working_set_pool – The pool handle for working set buffers allocation. The worker uses 8 buffers in burst mode, 1 otherwise.
recv_policy – The receive policy.
idle_func – The function called when there is no incoming packet.
filter_func – The filtering function, or NULL for no filtering.
filter_user_data – The user data passed to the filtering function.
distr_func – The distribution function, or NULL to send all the packets to all the egress queues.
distr_user_data – The user data passed to distribution function.
active_wait – The flag indicating whether the worker should use active or passive wait for incoming packets.
core_id_affinity – The 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 idle_func, pfring_zc_distribution_func distr_func, void *distr_user_data, u_int32_t active_wait, int32_t core_id_affinity): Same as pfring_zc_run_fanout_v2 but without a filtering function. (deprecated)

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_queues – The ingress queues handles array.
out_queue – The egress queue handle, or NULL for processing packets directly using the provided func.
num_in_queues – The number of ingress queues.
working_set_pool – The pool handle for working set buffers allocation. The worker uses num_in_queues * 32 buffers.
callback – The function called when there is no incoming packet.
func – The packet processing function.
user_data – The user data passed to func.
active_wait – The flag indicating whether the worker should use active or passive wait for incoming packets.
core_id_affinity_sorter – The core affinity for the sorter thread.
core_id_affinity_timer – The core affinity for the timer thread.

Returns:

The worker handle on success, NULL otherwise (errno is set appropriately).

void pfring_zc_kill_worker(pfring_zc_worker *worker)

Kill the worker.

Parameters:: worker – The worker handle.

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:

cluster – The cluster handle.
pool_len – The number of buffers to reserve for the pool.

Returns:

The pool handle on success, NULL otherwise (errno is set appropriately).

u_int32_t pfring_zc_get_pool_id(pfring_zc_buffer_pool *pool)

Read pool id.

Parameters:: pool – The pool handle.

pfring_zc_pkt_buff *pfring_zc_get_packet_handle_from_pool(pfring_zc_buffer_pool *pool)

Allocate a buffer from a pool resource.

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

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:

pool – The pool handle.
pkt_handle – The buffer handle.

void pfring_zc_ipc_init(const char *hugepages_mountpoint)

Initialise the inter-process support on a slave.

Parameters:: hugepages_mountpoint – The HugeTLB mountpoint (NULL for auto-detection) for the shared memory.

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_id – The cluster identifier.
pool_id – The pool identifier.

Returns:

The pool 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:: pool – The pool handle.

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_id – The cluster identifier.
queue_id – The queue identifier.
queue_mode – The direction to open, RX or TX.

Returns:

The queue handle on success, NULL otherwise (errno is set appropriately).

void pfring_zc_ipc_detach_queue(pfring_zc_queue *queue)

Detach a queue.

Parameters:: queue – The queue handle.

int pfring_zc_ipc_queue_in_use(u_int32_t cluster_id, u_int32_t queue_id, pfring_zc_queue_mode queue_mode)

Check if a (rx or tx) queue is locked by another (live or dead) process. This function opens a new pfring file descriptor.

Parameters:

cluster_id – The cluster identifier.
queue_id – The queue identifier.
queue_mode – The direction to open, RX or TX.

Returns:

1 is the queue is in use, 0 otherwise, -1 on failure checking.

int pfring_zc_ipc_queue_in_use_from_cluster(pfring_zc_cluster *cluster, u_int32_t queue_id, pfring_zc_queue_mode queue_mode)

Check if a (rx or tx) queue is locked by another (live or dead) process. This function uses the file descriptor from a cluster handle.

Parameters:

cluster – The cluster handle.
queue_id – The queue identifier.
queue_mode – The direction to open, RX or TX.

Returns:

1 is the queue is in use, 0 otherwise, -1 on failure checking.

int pfring_zc_ipc_queue_in_use_from_queue(pfring_zc_queue *queue, pfring_zc_queue_mode queue_mode)

Check if a (rx or tx) queue is locked by another (live or dead) process.

Parameters:

queue – The queue handle.
queue_mode – The direction to open, RX or TX.

Returns:

1 is the queue is in use, 0 otherwise, -1 on failure checking.

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

(Host) Initialise the KVM support for a VM.

Parameters:

cluster – The cluster handle.
vm_monitor_socket_path – The monitor socket of the VM to initialise.

Returns:

0 on success, a negative value otherwise.

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:: cluster – The 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_device – The UIO device path for the shared memory.

u_int32_t pfring_zc_builtin_ip_hash(pfring_zc_pkt_buff *pkt_handle, pfring_zc_queue *queue)

Computes an IP-based packet hash. Hash input: <src ip, dst ip>

Parameters:

pkt_handle – The pointer to the buffer handle.
queue – The queue from which the packet is arrived or destined.

Returns:

The packet hash.

u_int32_t pfring_zc_builtin_5tuple_hash(pfring_zc_pkt_buff *pkt_handle, pfring_zc_queue *queue)

Computes a 5-tuple packet hash. Hash input: <src ip, dst ip, src port, dst port, protocol>

Parameters:

pkt_handle – The pointer to the buffer handle.
queue – The queue from which the packet is arrived or destined.

Returns:

The packet hash.

u_int32_t pfring_zc_builtin_gtp_hash(pfring_zc_pkt_buff *pkt_handle, pfring_zc_queue *queue, u_int32_t *flags)

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. Hash input:

<GTP-C Seq> for GTP-C packets
<inner src ip, inner dst ip, inner src port, inner dst port> for GTP-U packets
<src ip, dst ip, src port, dst port> for non GTP packets

Parameters:

pkt_handle – The pointer to the buffer handle.
queue – The queue from which the packet is arrived or destined.
flags – Flags with info about the GTP content (version, GTP-c/GTP-u, etc)

Returns:

The packet 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. Hash input:

<inner src ip, inner dst ip> for GRE packets
<src ip, dst ip, src port, dst port> for non GRE packets

Parameters:

pkt_handle – The pointer to the buffer handle.
queue – The queue from which the packet is arrived or destined.

Returns:

The packet hash.

int pfring_zc_set_proc_stats(pfring_zc_cluster *cluster, char *stats)

Write custom stats under /proc/net/pf_ring/stats/CLUSTER-FILE

Parameters:

cluster – The cluster handle.
stats – The stats string to write.

Returns:

0 on success, a negative value otherwise.

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

Write application name under /proc/net/pf_ring/SOCKET

Parameters:

cluster – The cluster handle.
name – The 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:

queue – The queue handle for the device.
stats – The stats string to write.

Returns:

0 on success, a negative value otherwise.

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

Write application name under /proc/net/pf_ring/SOCKET

Parameters:

queue – The queue handle for the device.
name – The application name.

Returns:

0 on success, a negative value otherwise.

char *pfring_zc_version()

Return the ZC version

Returns:: The PF_RING ZC version.

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.

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:

queue – The queue handle for the device.
expiration_epoch – The 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_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_name – The interface name.
expiration_epoch – The 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_numa_get_cpu_node(int core_id)

Return the NUMA node bound to the selected core

Parameters:: core_id – The 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_id – The NUMA node id
Returns:: 0 on success, -1 otherwise.

void pfring_zc_debug(): Enable debug mode

struct pfring_zc_stat

#include <pfring_zc.h>

Queue stats structure.

Public Members

u_int64_t recv

u_int64_t sent

u_int64_t drop

struct pfring_zc_timespec

#include <pfring_zc.h>

Struct for nsec time (similar to struct timespec).

Public Members

u_int32_t tv_sec

u_int32_t tv_nsec

struct pfring_zc_pkt_buff

#include <pfring_zc.h>

Buffer handle.

Public Members

u_int16_t len: Packet length.

u_int16_t flags: Packet flags (see PF_RING_ZC_PKT_FLAGS_*).

u_int32_t hash: Packet hash.

pfring_zc_timespec ts: Packet timestamp (nsec)

u_char user[]: Start of user metadata, if any.

struct pfring_zc_queue_info

#include <pfring_zc.h>

Queue info.

Public Members

u_int32_t buffer_len: Max packet length.

u_int32_t metadata_len: User metadata length.

struct pfring_zc_cluster_info

#include <pfring_zc.h>

Cluster required resources info.

Public Members

u_int64_t total_memory: Total amount of allocated memory.

u_int32_t buffer_len: Max packet length.

u_int32_t real_buffer_len: Real size of allocated buffers (including head room and padding).

struct pfring_zc_cluster_mem_info

#include <pfring_zc.h>

Cluster memory info.

Public Members

void *base_addr: Allocated memory base address.

u_int64_t size: Total amount of allocated memory.