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)

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.

Return

0 to drop the packet, 1 to pass the packet.

Parameters

pkt_handle: The received buffer handle.
in_queue: The ingress queues handle from which the packet arrived.
user: The pointer to the user data.

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

The distribution function prototype.

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.

Parameters

pkt_handle: The received buffer handle.
in_queue: The ingress queues handle from which the packet arrived.
user: The pointer to the user data.

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

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.

Parameters

pkt_handle: The received buffer handle.
in_queue: The ingress queues handle from which the packet arrived.
user: The pointer to the user data.

typedef void (*pfring_zc_idle_callback)()¶: The idle callback prototype.

Enums

enum pfring_zc_queue_mode¶

List of possible queue modes.

Values:

rx_only¶: RX only mode.

tx_only¶: TX only mode.

management_only¶: No capture/transmission.

enum pfring_zc_recv_policy¶

List of possible policies when receiving packets from multiple queues.

Values:

round_robin_policy = 0¶: Round-Robin policy.

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

Return

The pointer on success, NULL otherwise.

Parameters

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

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

Return

The pointer on success, NULL otherwise.

Parameters

pkt_handle: The buffer handle.
cluster: The cluster handle.

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.

Return

The buffer handle on success, NULL otherwise.

Parameters

data: The packet data pointer.
cluster: The cluster handle.

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.

Return

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

Parameters

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

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.

Return

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

Parameters

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

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.

Return

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

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

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

Parameters

info: Out

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

Return

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

Parameters

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

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.

Return

The cluster id.

Parameters

cluster: The cluster handle.

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.

Return

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

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

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.

Return

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

Parameters

cluster: The cluster handle.
queue_len: The queue length.

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.

Return

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

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)

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.

Return

1 on success, 0 on empty queue (non-blocking only), a negative value otherwise.

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.

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.

Return

The number of received packets on success, 0 on empty queue (non-blocking only), a negative value otherwise.

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.

int pfring_zc_queue_is_empty(pfring_zc_queue *queue)¶

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

Return

1 on empty queue, 0 otherwise.

Parameters

queue: The queue handle.

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.

Return

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

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.

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.

Return

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

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.

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.

Return

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.

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.

int pfring_zc_queue_is_full(pfring_zc_queue *queue)¶

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

Return

1 on full queue, 0 otherwise.

Parameters

queue: The queue handle.

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, char *filter)¶

Set a BPF filter.

Return

0 on success, a negative value otherwise.

Parameters

queue: The queue handle.
filter: The BPF filter.

int pfring_zc_remove_bpf_filter(pfring_zc_queue *queue)¶

Remove the BPF filter.

Return

0 on success, a negative value otherwise.

Parameters

queue: The queue handle.

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.

Return

0 on success, a negative value otherwise.

Parameters

queue: The queue handle.
rule: The filtering 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.

Return

0 on success, a negative value otherwise.

Parameters

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

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)

Return

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)

Parameters

queue: The queue handle.

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.

Return

The queue speed in Mbit/s, 0 if unknown.

Parameters

queue: The queue handle.

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

Read the queue stats.

Return

0 on success, a negative value otherwise.

Parameters

queue: The queue handle.
stats: The stats structure.

pfring_zc_pkt_buff *pfring_zc_get_packet_handle(pfring_zc_cluster *cluster)¶

Allocate a buffer from global resources.

Return

The buffer handle on success, NULL otherwise.

Parameters

cluster: The cluster handle.

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

Return

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

Parameters

queues: The array with the queues to bind to the multi-queue object.
num_queues: The number of egress 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)¶

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

Return

The number of packet copies enqueued.

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.

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

Return

The number of packet copies enqueued.

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.

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

Return

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

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.

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

Return

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

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.

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

Return

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

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.

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)

Return

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

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.

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.

Return

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

Parameters

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

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.

Return

The buffer handle on success, NULL otherwise.

Parameters

pool: The pool 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

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.

Return

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

Parameters

cluster_id: The cluster identifier.
pool_id: The pool identifier.

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.

Return

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

Parameters

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

void pfring_zc_ipc_detach_queue(pfring_zc_queue *queue)¶

Detach a queue.

Parameters

queue: The queue handle.

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

(Host) Initialise the KVM support for a VM.

Return

0 on success, a negative value otherwise.

Parameters

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

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

Return

0 on success, a negative value otherwise.

Parameters

cluster: The cluster handle.

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>

Return

The packet hash.

Parameters

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

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>

Return

The packet hash.

Parameters

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

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
Return

The packet hash.

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)

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
Return

The packet hash.

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

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

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

Return

0 on success, a negative value otherwise.

Parameters

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

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

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

Return

0 on success, a negative value otherwise.

Parameters

cluster: The cluster handle.
name: The application name.

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

Return

0 on success, a negative value otherwise.

Parameters

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

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

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

Return

0 on success, a negative value otherwise.

Parameters

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

char *pfring_zc_version()¶

Return the ZC version

Return: 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)

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

Return

1 if the license is valid, and set the expiration epoch accordingly, 0 otherwise.

Parameters

queue: The queue handle for the device.
expiration_epoch: The variable (ptr) that will contain the expiration epoch as return value.

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.

Return

1 if the license is valid, and set the expiration epoch accordingly, 0 otherwise.

Parameters

device_name: The interface name.
expiration_epoch: The variable (ptr) that will contain the expiration epoch as return value.

int pfring_zc_numa_get_cpu_node(int core_id)¶

Return the NUMA node bound to the selected core

Return

node id on success, -1 otherwise.

Parameters

core_id: The core id

int pfring_zc_numa_set_numa_affinity(int node_id)¶

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

Return

0 on success, -1 otherwise.

Parameters

node_id: The NUMA node id

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.