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
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.
-
struct pfring_zc_timespec
- #include <pfring_zc.h>
Struct for nsec time (similar to struct timespec).
-
struct pfring_zc_pkt_buff
- #include <pfring_zc.h>
Buffer handle.
-
struct pfring_zc_queue_info
- #include <pfring_zc.h>
Queue info.
-
struct pfring_zc_cluster_info
- #include <pfring_zc.h>
Cluster required resources info.
-
struct pfring_zc_cluster_mem_info
- #include <pfring_zc.h>
Cluster memory info.