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