pfring_zc.h

Go to the documentation of this file.

/*
 * PF_RING ZC API
 *
 * (C) 2013-25 - ntop
 *
 */
 
#ifndef _PF_RING_ZC_H_
#define _PF_RING_ZC_H_
 
#include <sys/types.h>
#include <linux/pf_ring.h> /* needed for hw_filtering_rule */
 
/* pfring_zc_create_cluster flags */
#define PF_RING_ZC_ENABLE_VM_SUPPORT          (1 << 0) 
/* pfring_zc_open_device flags */
#define PF_RING_ZC_DEVICE_ASYMMETRIC_RSS      (1 <<  0) 
#define PF_RING_ZC_DEVICE_FIXED_RSS_Q_0       (1 <<  1) 
#define PF_RING_ZC_DEVICE_SW_TIMESTAMP        (1 <<  2) 
#define PF_RING_ZC_DEVICE_HW_TIMESTAMP        (1 <<  3) 
#define PF_RING_ZC_DEVICE_STRIP_HW_TIMESTAMP  (1 <<  4) 
#define PF_RING_ZC_DEVICE_IXIA_TIMESTAMP      (1 <<  5) 
#define PF_RING_ZC_DEVICE_NOT_REPROGRAM_RSS   (1 <<  6) 
#define PF_RING_ZC_DEVICE_CAPTURE_TX          (1 <<  7) 
#define PF_RING_ZC_DEVICE_IPONLY_RSS          (1 <<  8) 
#define PF_RING_ZC_DEVICE_NOT_PROMISC         (1 <<  9) 
#define PF_RING_ZC_DO_NOT_STRIP_FCS           (1 << 10) 
#define PF_RING_ZC_DEVICE_ARISTA_TIMESTAMP    (1 << 11) 
#define PF_RING_ZC_DEVICE_METAWATCH_TIMESTAMP (1 << 11) 
#define PF_RING_ZC_DEVICE_CAPTURE_INJECTED    (1 << 12) 
#define PF_RING_ZC_DEVICE_HW_TIMESTAMP_UNSYNC (1 << 13) 
#define UNDEFINED_QUEUEID 0xFFFFFFFF    
#define QUEUE_IS_DEVICE(i) (i > 0xFFFF) 
#define QUEUEID_TO_IFINDEX(i) (i >> 16) 
#define IFINDEX_TO_QUEUEID(i) (i << 16) 
#define PF_RING_ZC_PKT_FLAGS_GOOD_IP_CS   (1 << 0) 
#define PF_RING_ZC_PKT_FLAGS_BAD_IP_CS    (1 << 1) 
#define PF_RING_ZC_PKT_FLAGS_GOOD_L4_CS   (1 << 2) 
#define PF_RING_ZC_PKT_FLAGS_BAD_L4_CS    (1 << 3) 
//#define PF_RING_ZC_PKT_FLAGS_TX_IP_CS   (1 << 4) /**< pfring_zc_pkt_buff.flags: compute IP checksum on transmission (when supported) */ 
//#define PF_RING_ZC_PKT_FLAGS_TX_L4_CS   (1 << 5) /**< pfring_zc_pkt_buff.flags: compute TCP checksum on transmission (when supported) */ 
#define PF_RING_ZC_PKT_FLAGS_FLOW_OFFLOAD_UPDATE (1 << 6) 
#define PF_RING_ZC_PKT_FLAGS_FLOW_OFFLOAD_PACKET (1 << 7) 
#define PF_RING_ZC_PKT_FLAGS_FLOW_OFFLOAD_MARKER (1 << 8) 
#define PF_RING_ZC_PKT_FLAGS_FLOW_OFFLOAD_1ST    (1 << 9) 
#define PF_RING_ZC_BUILTIN_GTP_HASH_FLAGS_V1   (1 << 0) 
#define PF_RING_ZC_BUILTIN_GTP_HASH_FLAGS_V2   (1 << 1) 
#define PF_RING_ZC_BUILTIN_GTP_HASH_FLAGS_GTPC (1 << 2) 
#define PF_RING_ZC_BUILTIN_GTP_HASH_FLAGS_GTPU (1 << 3) 
/* New API features defines */
#define PF_RING_ZC_API_CLUSTER_INFO
 
/* Misc defines */
#define PF_RING_ZC_SEND_PKT_MULTI_MAX_QUEUES 64 
#define PF_RING_ZC_SEND_PKT_MULTI_V3_MAX_QUEUES 128 
#define PF_RING_ZC_BUFFER_HEAD_ROOM          64
 
#ifdef __cplusplus
extern "C" {
#endif
 
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 enum {
  rx_only,        
  tx_only,        
  management_only 
} pfring_zc_queue_mode;
 
typedef struct {
  u_int64_t recv;
  u_int64_t sent;
  u_int64_t drop;
} pfring_zc_stat;
 
typedef struct {
  u_int32_t tv_sec;
  u_int32_t tv_nsec;
} pfring_zc_timespec;
 
typedef struct {
  u_int16_t len;         
  u_int16_t flags;       
  u_int32_t hash;        
  pfring_zc_timespec ts; 
  u_char user[];         
} pfring_zc_pkt_buff;
 
typedef struct {
  u_int32_t buffer_len;   
  u_int32_t metadata_len; 
} pfring_zc_queue_info;
 
typedef struct {
  u_int64_t total_memory;    
  u_int32_t buffer_len;      
  u_int32_t real_buffer_len; 
} pfring_zc_cluster_info;
 
typedef struct {
  void *base_addr;   
  u_int64_t size;    
} pfring_zc_cluster_mem_info;
 
u_char *
pfring_zc_pkt_buff_data(
  pfring_zc_pkt_buff *pkt_handle,
  pfring_zc_queue *queue
);
 
u_char *
pfring_zc_pkt_buff_data_from_cluster(
  pfring_zc_pkt_buff *pkt_handle,
  pfring_zc_cluster *cluster
);
 
pfring_zc_pkt_buff *
pfring_zc_pkt_data_buff(
    u_char *data,
    pfring_zc_cluster *cluster
);
 
u_char *
pfring_zc_pkt_buff_pull(
  pfring_zc_pkt_buff *pkt_handle,
  pfring_zc_queue *queue,
  u_int16_t len
);
 
u_char *
pfring_zc_pkt_buff_push(
  pfring_zc_pkt_buff *pkt_handle,
  pfring_zc_queue *queue,
  u_int16_t len
);
 
void
pfring_zc_pkt_buff_pull_only(
  pfring_zc_pkt_buff *pkt_handle,
  u_int16_t len
);
 
/* **************************************************************************************** */
 
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
);
 
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
);
 
int
pfring_zc_get_memory_info(
  pfring_zc_cluster *cluster,
  pfring_zc_cluster_mem_info *mem_info
);
 
u_int32_t
pfring_zc_get_cluster_id(
  pfring_zc_cluster *cluster
);
 
void 
pfring_zc_destroy_cluster(
  pfring_zc_cluster *cluster
);
 
/* **************************************************************************************** */
 
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
);
 
pfring_zc_queue * 
pfring_zc_create_queue(
  pfring_zc_cluster *cluster,
  u_int32_t queue_len
);
 
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
);
 
void
pfring_zc_close_device(
  pfring_zc_queue *queue
);
 
/* **************************************************************************************** */
 
int 
pfring_zc_recv_pkt(
  pfring_zc_queue *queue, 
  pfring_zc_pkt_buff **pkt_handle, 
  u_int8_t wait_for_incoming_packet
);
 
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
); 
 
int 
pfring_zc_queue_is_empty(
  pfring_zc_queue *queue 
); 
 
void
pfring_zc_queue_breakloop(
  pfring_zc_queue *queue 
);
 
/* **************************************************************************************** */
 
int 
pfring_zc_send_pkt(
  pfring_zc_queue *queue, 
  pfring_zc_pkt_buff **pkt_handle,
  u_int8_t flush_packet
);
 
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
);
 
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 
); 
 
int 
pfring_zc_queue_is_full(
  pfring_zc_queue *queue 
); 
 
/* **************************************************************************************** */
 
void
pfring_zc_sync_queue(
  pfring_zc_queue *queue,
  pfring_zc_queue_mode direction 
);
 
/* **************************************************************************************** */
 
int
pfring_zc_get_device_clock(
  pfring_zc_queue *queue,
  struct timespec *ts
);
 
int
pfring_zc_set_device_clock(
  pfring_zc_queue *queue,
  struct timespec *ts
);
 
int
pfring_zc_adjust_device_clock(
  pfring_zc_queue *queue,
  struct timespec *offset,
  int8_t sign
);
 
/* **************************************************************************************** */
 
int
pfring_zc_set_bpf_filter(
  pfring_zc_queue *queue,
  const char *filter
);
 
int
pfring_zc_remove_bpf_filter(
  pfring_zc_queue *queue
);
 
/* **************************************************************************************** */
 
int
pfring_zc_add_hw_rule(
  pfring_zc_queue *queue,
  hw_filtering_rule *rule
);
 
int
pfring_zc_remove_hw_rule(
  pfring_zc_queue *queue,
  u_int16_t rule_id
);
 
/* **************************************************************************************** */
 
void 
pfring_zc_set_rxfh_indir(
  pfring_zc_queue *queue,
  u_int8_t *indir_table
);
 
/* **************************************************************************************** */
 
u_int32_t
pfring_zc_get_queue_id(
  pfring_zc_queue *queue
);
 
void
pfring_zc_get_queue_settings(
  pfring_zc_queue *queue,
  pfring_zc_queue_info *info
);
 
u_int32_t
pfring_zc_get_queue_speed(
  pfring_zc_queue *queue
);
 
u_int32_t
pfring_zc_get_num_rx_channels(
  pfring_zc_queue *queue
);
 
int
pfring_zc_stats(
  pfring_zc_queue *queue,
  pfring_zc_stat *stats
);
 
/* **************************************************************************************** */
 
pfring_zc_pkt_buff * 
pfring_zc_get_packet_handle(
  pfring_zc_cluster *cluster
);
 
void
pfring_zc_release_packet_handle(
  pfring_zc_cluster *cluster,
  pfring_zc_pkt_buff *pkt_handle
);
 
/* **************************************************************************************** */
 
pfring_zc_multi_queue *
pfring_zc_create_multi_queue(
  pfring_zc_queue *queues[],
  u_int32_t num_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
);
 
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
);
 
/* **************************************************************************************** */
 
typedef enum {
  round_robin_policy = 0,   
  round_robin_bursts_policy 
} pfring_zc_recv_policy;
 
typedef int64_t
(*pfring_zc_filtering_func) (
  pfring_zc_pkt_buff *pkt_handle,
  pfring_zc_queue *in_queue,
  void *user
);
 
typedef int64_t
(*pfring_zc_distribution_func) (
  pfring_zc_pkt_buff *pkt_handle,
  pfring_zc_queue *in_queue,
  void *user
);
 
typedef __int128_t
(*pfring_zc_distribution_func_v3) (
  pfring_zc_pkt_buff *pkt_handle,
  pfring_zc_queue *in_queue,
  void *user
);
 
typedef void
(*pfring_zc_idle_callback) (
);
 
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
);
 
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
);
 
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
);
 
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
);
 
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
);
 
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
);
 
void 
pfring_zc_kill_worker(
  pfring_zc_worker *worker
);
 
/* **************************************************************************************** */
 
pfring_zc_buffer_pool *
pfring_zc_create_buffer_pool(
  pfring_zc_cluster *cluster, 
  u_int32_t pool_len
);
 
u_int32_t
pfring_zc_get_pool_id(
  pfring_zc_buffer_pool *pool
);
 
pfring_zc_pkt_buff * 
pfring_zc_get_packet_handle_from_pool(
  pfring_zc_buffer_pool *pool
);
 
void
pfring_zc_release_packet_handle_to_pool(
  pfring_zc_buffer_pool *pool,
  pfring_zc_pkt_buff *pkt_handle
);
 
/* **************************************************************************************** */
 
void
pfring_zc_ipc_init(
  const char *hugepages_mountpoint
);
 
pfring_zc_buffer_pool *
pfring_zc_ipc_attach_buffer_pool(
  u_int32_t cluster_id,
  u_int32_t pool_id
);
 
void
pfring_zc_ipc_detach_buffer_pool(
  pfring_zc_buffer_pool *pool
);
 
pfring_zc_queue *
pfring_zc_ipc_attach_queue(
  u_int32_t cluster_id,
  u_int32_t queue_id,
  pfring_zc_queue_mode queue_mode
);
 
void
pfring_zc_ipc_detach_queue(
  pfring_zc_queue *queue
);
 
int
pfring_zc_ipc_queue_in_use(
  u_int32_t cluster_id,
  u_int32_t queue_id,
  pfring_zc_queue_mode queue_mode
);
 
int
pfring_zc_ipc_queue_in_use_from_cluster(
  pfring_zc_cluster *cluster,
  u_int32_t queue_id,
  pfring_zc_queue_mode queue_mode
);
 
int
pfring_zc_ipc_queue_in_use_from_queue(
  pfring_zc_queue *queue,
  pfring_zc_queue_mode queue_mode
);
 
/* **************************************************************************************** */
 
int
pfring_zc_vm_register(
  pfring_zc_cluster *cluster,
  const char *vm_monitor_socket_path
);
 
int
pfring_zc_vm_backend_enable(
  pfring_zc_cluster *cluster
);
 
/* **************************************************************************************** */
 
void
pfring_zc_vm_guest_init(
  const char *uio_device
);
 
/* **************************************************************************************** */
 
u_int32_t
pfring_zc_builtin_ip_hash(
  pfring_zc_pkt_buff *pkt_handle,
  pfring_zc_queue *queue
);
 
u_int32_t
pfring_zc_builtin_5tuple_hash(
  pfring_zc_pkt_buff *pkt_handle,
  pfring_zc_queue *queue
);
 
u_int32_t
pfring_zc_builtin_gtp_hash(
  pfring_zc_pkt_buff *pkt_handle,
  pfring_zc_queue *queue,
  u_int32_t *flags /* out */
);
 
u_int32_t
pfring_zc_builtin_gre_hash(
  pfring_zc_pkt_buff *pkt_handle,
  pfring_zc_queue *queue
);
 
/* **************************************************************************************** */
 
int
pfring_zc_set_proc_stats(
  pfring_zc_cluster *cluster,
  char *stats
);
 
int
pfring_zc_set_app_name(
  pfring_zc_cluster *cluster,
  const char *name
);
 
/* **************************************************************************************** */
 
int
pfring_zc_set_device_proc_stats(
  pfring_zc_queue *queue,
  const char *stats
);
 
int
pfring_zc_set_device_app_name(
  pfring_zc_queue *queue,
  const char *name
);
 
/* **************************************************************************************** */
 
char *
pfring_zc_version();
 
/* **************************************************************************************** */
 
int
pfring_zc_check_license();
 
/* **************************************************************************************** */
 
int
pfring_zc_check_device_license(
  pfring_zc_queue *queue,
  u_int32_t *expiration_epoch
);
 
int
pfring_zc_check_device_license_by_name(
  char *device_name,
  u_int32_t *expiration_epoch
);
 
/* **************************************************************************************** */
 
int
pfring_zc_numa_get_cpu_node(int core_id);
 
/* **************************************************************************************** */
 
int
pfring_zc_numa_set_numa_affinity(int node_id);
 
/* **************************************************************************************** */
 
void
pfring_zc_debug();
 
/* **************************************************************************************** */
 
#ifdef __cplusplus
}
#endif
 
#endif /* _PF_RING_ZC_H_ */