pfring.h

Go to the documentation of this file.

/*
 *
 * (C) 2005-2018 - ntop.org
 *
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesses General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
 * (at your option) any later version.
 *
 */

#ifndef _PFRING_H_
#define _PFRING_H_

#include <sys/types.h>
#include <stdio.h>
#include <stdarg.h>

#ifndef HAVE_PCAP
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <sys/mman.h>
#include <errno.h>
#include <poll.h>
#include <sys/socket.h>
#include <linux/sockios.h>
#endif

#ifdef ENABLE_BPF
#include <pcap/pcap.h>
#include <pcap/bpf.h>
#endif

#include <linux/if_packet.h>
#include <arpa/inet.h>
#include <sys/ioctl.h>
#include <sys/socket.h>
#include <sys/un.h>
#include <sys/time.h>
#include <time.h>
#include <poll.h>
#include <string.h>
#include <pthread.h>
#include <linux/pf_ring.h>
#include <linux/if_ether.h>

#ifdef HAVE_REDIRECTOR
#include <librdi.h>
#endif

#define MAX_CAPLEN             65535
#define PAGE_SIZE               4096

#define DEFAULT_POLL_DURATION   500

#define POLL_SLEEP_STEP           10 /* ns = 0.1 ms */
#define POLL_SLEEP_MIN          POLL_SLEEP_STEP
#define POLL_SLEEP_MAX          1000 /* ns */
#define POLL_QUEUE_MIN_LEN       500 /* # packets */

#define pfring_rwlock_t       pthread_rwlock_t       
#define pfring_rwlock_init    pthread_rwlock_init    
#define pfring_rwlock_rdlock  pthread_rwlock_rdlock  
#define pfring_rwlock_wrlock  pthread_rwlock_wrlock  
#define pfring_rwlock_unlock  pthread_rwlock_unlock  
#define pfring_rwlock_destroy pthread_rwlock_destroy 

#define timespec_is_before(a, b) \
  ((((a)->tv_sec<(b)->tv_sec)||(((a)->tv_sec==(b)->tv_sec)&&((a)->tv_nsec<(b)->tv_nsec)))?1:0)

/* ********************************* */

#ifndef likely
#define likely(x)       __builtin_expect((x),1)
#endif

#ifndef unlikely
#define unlikely(x)     __builtin_expect((x),0)
#endif

/* ********************************* */

/* See also __builtin_prefetch
 * http://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html */
#define prefetch(x) __asm volatile("prefetcht0 %0" :: "m" (*(const unsigned long *)x));

/* ********************************* */

#ifdef __cplusplus
extern "C" {
#endif

#ifdef SAFE_RING_MODE
static char staticBucket[2048];
#endif

typedef void (*pfringProcesssPacket)(const struct pfring_pkthdr *h, const u_char *p, const u_char *user_bytes);

/* ********************************* */

typedef struct __pfring pfring; /* Forward declaration */

/* ********************************* */

typedef struct {
  u_int32_t max_packet_size;
  u_int32_t rx_ring_slots;
  u_int32_t tx_ring_slots;
} pfring_card_settings;

/* ********************************* */

typedef struct {
  u_int64_t recv;
  u_int64_t drop;
  u_int64_t shunt;
} pfring_stat;

/* ********************************* */

typedef enum {
  hardware_and_software = 0,
  hardware_only,
  software_only
} filtering_mode;

/* ********************************* */

typedef enum {
  FULL_PACKET_SLICING = 0,
  L2_SLICING = 2,
  L3_SLICING = 3,
  L4_SLICING = 4
} packet_slicing_level;

/* ********************************* */

typedef enum {
  PCAP_CHUNK,
  PCAP_NSEC_CHUNK,
  UNKNOWN_CHUNK_TYPE
} pfring_chunk_type;

typedef struct {
  u_int32_t length;
  pfring_chunk_type type;
} pfring_chunk_info;

/* ********************************* */

#ifndef BPF_RELEASE
struct pfring_bpf_program {
  u_int bf_len; 
  void *bf_insns; 
};
#endif

/* ********************************* */

typedef struct pfring_if {
  char *name;
  char *system_name;
  char *module;
  char *sn;
  char mac[6];
  struct { /* Bus ID: "%04X:%02X:%02X.%X", slot, bus, device, function */
    int slot;
    int bus;
    int device;
    int function;
  } bus_id;
  int status; /* 1: up, 0: down*/
  int license; /* 1: valid, 0: invalid or not installed */
  struct pfring_if *next;
} pfring_if_t;

/* ********************************* */

struct __pfring {
  u_int8_t initialized;
  u_int8_t enabled;
  u_int8_t long_header;

  u_int8_t force_timestamp;
  u_int8_t strip_hw_timestamp;

  u_int8_t disable_parsing;

  u_int8_t disable_timestamp;
  u_int8_t ixia_timestamp_enabled;
  u_int8_t vss_apcon_timestamp_enabled;

  u_int8_t chunk_mode_enabled;

  u_int8_t userspace_bpf;
  u_int8_t force_userspace_bpf;

  u_int32_t rss_mode;
  packet_direction direction; /* Specify the capture direction for packets */
  socket_mode mode;

#ifdef BPF_RELEASE
  struct bpf_program
#else
  struct pfring_bpf_program
#endif
    userspace_bpf_filter;

  /* Hardware Timestamp */
  struct {
    u_int8_t force_timestamp;
    u_int8_t is_silicom_hw_timestamp_card;
    u_int8_t enable_hw_timestamp;
    u_int8_t last_hw_timestamp_head_offset;
    struct timespec last_hw_timestamp;
  } hw_ts;

  struct {
    u_int8_t enabled_rx_packet_send;
    struct pfring_pkthdr *last_received_hdr; /* Header of the past packet that has been received on this socket */
  } tx;

  u_int8_t zc_device;

  void *priv_data; /* module private data */

  void      (*close)                        (pfring *);
  int       (*stats)                        (pfring *, pfring_stat *);
  int       (*recv)                         (pfring *, u_char**, u_int, struct pfring_pkthdr *, u_int8_t);
  int       (*set_poll_watermark)           (pfring *, u_int16_t);
  int       (*set_poll_watermark_timeout)   (pfring *, u_int16_t);
  int       (*set_poll_duration)            (pfring *, u_int);
  int       (*set_tx_watermark)             (pfring *, u_int16_t);
  int       (*set_channel_id)               (pfring *, u_int32_t);
  int       (*set_channel_mask)             (pfring *, u_int64_t);
  int       (*set_application_name)         (pfring *, char *);
  int       (*set_application_stats)        (pfring *, char *);
  char*     (*get_appl_stats_file_name)     (pfring *ring, char *path, u_int path_len);
  int       (*set_vlan_id)                  (pfring *, u_int16_t);
  int       (*bind)                         (pfring *, char *);
  int       (*send)                         (pfring *, char *, u_int, u_int8_t);
  int       (*send_get_time)                (pfring *, char *, u_int, struct timespec *);
  u_int8_t  (*get_num_rx_channels)          (pfring *);
  int       (*get_card_settings)            (pfring *, pfring_card_settings *);
  int       (*set_sampling_rate)            (pfring *, u_int32_t);
  int       (*set_packet_slicing)           (pfring *, packet_slicing_level, u_int32_t);
  int       (*get_selectable_fd)            (pfring *);
  int       (*set_direction)                (pfring *, packet_direction);
  int       (*set_socket_mode)              (pfring *, socket_mode);
  int       (*set_cluster)                  (pfring *, u_int, cluster_type);
  int       (*remove_from_cluster)          (pfring *);
  int       (*set_master_id)                (pfring *, u_int32_t);
  int       (*set_master)                   (pfring *, pfring *);
  u_int32_t (*get_ring_id)                  (pfring *);
  u_int32_t (*get_num_queued_pkts)          (pfring *);
  int       (*get_hash_filtering_rule_stats)(pfring *, hash_filtering_rule *, char *, u_int *);
  int       (*handle_hash_filtering_rule)   (pfring *, hash_filtering_rule *, u_char);
  int       (*purge_idle_hash_rules)        (pfring *, u_int16_t);
  int       (*add_filtering_rule)           (pfring *, filtering_rule *);
  int       (*remove_filtering_rule)        (pfring *, u_int16_t);
  int       (*purge_idle_rules)             (pfring *, u_int16_t);
  int       (*get_filtering_rule_stats)     (pfring *, u_int16_t, char *, u_int *);
  int       (*toggle_filtering_policy)      (pfring *, u_int8_t);
  int       (*enable_rss_rehash)            (pfring *);
  int       (*poll)                         (pfring *, u_int);
  int       (*is_pkt_available)             (pfring *);
  int       (*next_pkt_time)                (pfring *, struct timespec *);
  int       (*next_pkt_raw_timestamp)       (pfring *, u_int64_t *ts);
  int       (*version)                      (pfring *, u_int32_t *);
  int       (*get_bound_device_address)     (pfring *, u_char [6]);
  int       (*get_bound_device_ifindex)     (pfring *, int *);
  int       (*get_device_ifindex)           (pfring *, char *, int *);
  u_int16_t (*get_slot_header_len)          (pfring *);
  int       (*set_virtual_device)           (pfring *, virtual_filtering_device_info *);
  int       (*add_hw_rule)                  (pfring *, hw_filtering_rule *);
  int       (*remove_hw_rule)               (pfring *, u_int16_t);
  int       (*loopback_test)                (pfring *, char *, u_int, u_int);
  int       (*enable_ring)                  (pfring *);
  int       (*disable_ring)                 (pfring *);
  void      (*shutdown)                     (pfring *);
  int       (*set_bpf_filter)               (pfring *, char *);
  int       (*remove_bpf_filter)            (pfring *);
  int       (*get_device_clock)             (pfring *, struct timespec *);
  int       (*set_device_clock)             (pfring *, struct timespec *);
  int       (*adjust_device_clock)          (pfring *, struct timespec *, int8_t);
  void      (*sync_indexes_with_kernel)     (pfring *);
  int       (*send_last_rx_packet)          (pfring *, int);
  void      (*flush_tx_packets)             (pfring *);
  int       (*register_zerocopy_tx_ring)    (pfring *, pfring *);
  int       (*recv_chunk)                   (pfring *, void **, pfring_chunk_info *, u_int8_t); 
  int       (*set_bound_dev_name)           (pfring *, char *);
  int       (*get_metadata)                 (pfring *, u_char **, u_int32_t *);
  u_int32_t (*get_interface_speed)      (pfring *);

  /* Silicom Redirector Only */
  struct {
    int8_t device_id;
    int8_t port_id;
  } rdi;

  filtering_mode ft_mode;
  pfring_device_type ft_device_type;  

  /* All devices */
  char *buffer;
  char *slots;
  char *device_name;

  u_int32_t caplen;
  u_int16_t slot_header_len;
  u_int16_t mtu /* 0 = unknown */;

  u_int32_t sampling_rate;
  u_int32_t sampling_counter;

  packet_slicing_level slicing_level;

  u_int32_t slicing_additional_bytes;

  u_int8_t is_shutting_down;
  u_int8_t socket_default_accept_policy;

  int fd;
  int device_id;

  FlowSlotInfo *slots_info;

  u_int32_t poll_sleep;
  u_int16_t poll_duration;

  u_int8_t promisc;
  u_int8_t ft_enabled; /* PF_RING FT support enabled */
  u_int8_t reentrant;
  u_int8_t break_recv_loop;
  u_long num_poll_calls;

  pfring_rwlock_t rx_lock;
  pfring_rwlock_t tx_lock;

  u_int32_t flags;

  void *ft; /* PF_RING FT handle */

  struct sockaddr_ll sock_tx;

  /* Reflector socket (copy RX packets onto it) */
  pfring *reflector_socket;

  /* Semi-ZC devices (1-copy) */
  pfring *one_copy_rx_pfring;
};

/* ********************************* */

#define PF_RING_ZC_SYMMETRIC_RSS       (1 <<  0) 
#define PF_RING_REENTRANT              (1 <<  1) 
#define PF_RING_LONG_HEADER            (1 <<  2) 
#define PF_RING_PROMISC                (1 <<  3) 
#define PF_RING_TIMESTAMP              (1 <<  4) 
#define PF_RING_HW_TIMESTAMP           (1 <<  5) 
#define PF_RING_RX_PACKET_BOUNCE       (1 <<  6) 
#define PF_RING_ZC_FIXED_RSS_Q_0       (1 <<  7) 
#define PF_RING_STRIP_HW_TIMESTAMP     (1 <<  8) 
#define PF_RING_DO_NOT_PARSE           (1 <<  9) 
#define PF_RING_DO_NOT_TIMESTAMP       (1 << 10) 
#define PF_RING_CHUNK_MODE             (1 << 11) 
#define PF_RING_IXIA_TIMESTAMP         (1 << 12) 
#define PF_RING_USERSPACE_BPF          (1 << 13) 
#define PF_RING_ZC_NOT_REPROGRAM_RSS   (1 << 14) 
#define PF_RING_VSS_APCON_TIMESTAMP    (1 << 15) 
#define PF_RING_ZC_IPONLY_RSS          (1 << 16) 
#define PF_RING_FLOW_OFFLOAD           (1 << 17) 
#define PF_RING_FLOW_OFFLOAD_NOUPDATES (1 << 18) 
#define PF_RING_FLOW_OFFLOAD_NORAWDATA (1 << 19) 
#define PF_RING_L7_FILTERING           (1 << 20) 
/* ********************************* */

/* backward compatibility */
#define PF_RING_DNA_SYMMETRIC_RSS PF_RING_ZC_SYMMETRIC_RSS
#define PF_RING_DNA_FIXED_RSS_Q_0 PF_RING_ZC_FIXED_RSS_Q_0

/* ********************************* */

pfring *pfring_open(const char *device_name, u_int32_t caplen, u_int32_t flags);

u_int8_t pfring_open_multichannel(const char *device_name, u_int32_t caplen, 
                  u_int32_t flags, pfring *ring[MAX_NUM_RX_CHANNELS]);

void pfring_shutdown(pfring *ring);

void pfring_config(u_short cpu_percentage);

int pfring_loop(pfring *ring, pfringProcesssPacket looper, 
         const u_char *user_bytes, u_int8_t wait_for_packet);

void pfring_breakloop(pfring *);

void pfring_close(pfring *ring);

int pfring_stats(pfring *ring, pfring_stat *stats);

int pfring_recv(pfring *ring, u_char** buffer, u_int buffer_len,
        struct pfring_pkthdr *hdr, u_int8_t wait_for_incoming_packet);

int pfring_recv_parsed(pfring *ring, u_char** buffer, u_int buffer_len,
               struct pfring_pkthdr *hdr, u_int8_t wait_for_incoming_packet,
               u_int8_t level /* 1..4 */, u_int8_t add_timestamp, u_int8_t add_hash);

int pfring_get_metadata(pfring *ring, u_char **metadata, u_int32_t *metadata_len);

int pfring_set_poll_watermark(pfring *ring, u_int16_t watermark);

int pfring_set_poll_watermark_timeout(pfring *ring, u_int16_t poll_watermark_timeout);

int pfring_set_poll_duration(pfring *ring, u_int duration);

int pfring_set_tx_watermark(pfring *ring, u_int16_t watermark);

int pfring_add_hw_rule(pfring *ring, hw_filtering_rule *rule);

int pfring_remove_hw_rule(pfring *ring, u_int16_t rule_id);

int pfring_set_channel_id(pfring *ring, u_int32_t channel_id);

int pfring_set_channel_mask(pfring *ring, u_int64_t channel_mask);

int pfring_set_application_name(pfring *ring, char *name);

int pfring_set_application_stats(pfring *ring, char *stats);

char* pfring_get_appl_stats_file_name(pfring *ring, char *path, u_int path_len);

int pfring_set_vlan_id(pfring *ring, u_int16_t vlan_id);
  
int pfring_bind(pfring *ring, char *device_name);

int pfring_send(pfring *ring, char *pkt, u_int pkt_len, u_int8_t flush_packet);

int pfring_send_get_time(pfring *ring, char *pkt, u_int pkt_len, struct timespec *ts);

u_int8_t pfring_get_num_rx_channels(pfring *ring);

int pfring_set_sampling_rate(pfring *ring, u_int32_t rate /* 1 = no sampling */);

int pfring_set_packet_slicing(pfring *ring, packet_slicing_level level, u_int32_t additional_bytes);

int pfring_get_selectable_fd(pfring *ring);

int pfring_set_direction(pfring *ring, packet_direction direction);

int pfring_set_socket_mode(pfring *ring, socket_mode mode);

int pfring_set_cluster(pfring *ring, u_int clusterId, cluster_type the_type);

int pfring_remove_from_cluster(pfring *ring);

int pfring_set_master_id(pfring *ring, u_int32_t master_id);

int pfring_set_master(pfring *ring, pfring *master);

u_int32_t pfring_get_ring_id(pfring *ring);

u_int32_t pfring_get_num_queued_pkts(pfring *ring);

int pfring_handle_hash_filtering_rule(pfring *ring,
                      hash_filtering_rule* rule_to_add,
                      u_char add_rule);

int pfring_add_filtering_rule(pfring *ring, filtering_rule* rule_to_add);

int pfring_remove_filtering_rule(pfring *ring, u_int16_t rule_id);

int pfring_purge_idle_hash_rules(pfring *ring, u_int16_t inactivity_sec);

int pfring_purge_idle_rules(pfring *ring, u_int16_t inactivity_sec);

int pfring_get_hash_filtering_rule_stats(pfring *ring,
                     hash_filtering_rule* rule,
                     char *stats, u_int *stats_len);

int pfring_get_filtering_rule_stats(pfring *ring, u_int16_t rule_id,
                    char* stats, u_int *stats_len);

int pfring_toggle_filtering_policy(pfring *ring, u_int8_t rules_default_accept_policy);

int pfring_enable_rss_rehash(pfring *ring);

int pfring_poll(pfring *ring, u_int wait_duration);

int pfring_is_pkt_available(pfring *ring);

int pfring_next_pkt_time(pfring *ring, struct timespec *ts);

int pfring_next_pkt_raw_timestamp(pfring *ring, u_int64_t *timestamp_ns);

void pfring_version_noring(u_int32_t *version);

int pfring_version(pfring *ring, u_int32_t *version);

int pfring_set_reflector_device(pfring *ring, char *device_name);

int pfring_get_bound_device_address(pfring *ring, u_char mac_address[6]);

u_int16_t pfring_get_slot_header_len(pfring *ring);

int pfring_get_bound_device_ifindex(pfring *ring, int *if_index);

int pfring_get_device_ifindex(pfring *ring, char *device_name, int *if_index);

int pfring_set_virtual_device(pfring *ring, virtual_filtering_device_info *info);

int pfring_loopback_test(pfring *ring, char *buffer, u_int buffer_len, u_int test_len);

int pfring_enable_ring(pfring *ring);

int pfring_disable_ring(pfring *ring);

int pfring_set_bpf_filter(pfring *ring, char *filter_buffer);

int pfring_remove_bpf_filter(pfring *ring);

int pfring_set_filtering_mode(pfring *ring, filtering_mode mode);

int pfring_get_device_clock(pfring *ring, struct timespec *ts);

int pfring_set_device_clock(pfring *ring, struct timespec *ts);

int pfring_adjust_device_clock(pfring *ring, struct timespec *offset, int8_t sign);

void pfring_sync_indexes_with_kernel(pfring *ring);

int pfring_send_last_rx_packet(pfring *ring, int tx_interface_id);

int pfring_get_link_status(pfring *ring);

int pfring_flush_tx_packets(pfring *ring);

int pfring_search_payload(pfring *ring, char *string_to_search);

/* Utils (defined in pfring_utils.c) */

int pfring_parse_pkt(u_char *pkt, struct pfring_pkthdr *hdr, u_int8_t level /* 2..4 */, 
             u_int8_t add_timestamp /* 0,1 */, u_int8_t add_hash /* 0,1 */);
int pfring_set_if_promisc(const char *device, int set_promisc);

int pfring_set_promisc(pfring *ring, int set_promisc);

char* pfring_format_numbers(double val, char *buf, u_int buf_len, u_int8_t add_decimals);

int pfring_enable_hw_timestamp(pfring *ring, char *device_name, u_int8_t enable_rx, u_int8_t enable_tx);

int pfring_get_mtu_size(pfring *ring);

int pfring_get_card_settings(pfring *ring, pfring_card_settings *settings);

int pfring_print_parsed_pkt(char *buff, u_int buff_len, const u_char *p, const struct pfring_pkthdr *h);

int pfring_print_pkt(char *buff, u_int buff_len, const u_char *p, u_int len, u_int caplen);

int pfring_recv_chunk(pfring *ring, void **chunk, pfring_chunk_info *chunk_info, u_int8_t wait_for_incoming_chunk);

int pfring_set_bound_dev_name(pfring *ring, char *custom_dev_name);

int pfring_read_ixia_hw_timestamp(u_char *buffer, u_int32_t buffer_len, struct timespec *ts);

void pfring_handle_ixia_hw_timestamp(u_char* buffer, struct pfring_pkthdr *hdr);

int pfring_read_vss_apcon_hw_timestamp(u_char *buffer, u_int32_t buffer_len, struct timespec *ts);

void pfring_handle_vss_apcon_hw_timestamp(u_char* buffer, struct pfring_pkthdr *hdr);

u_int32_t pfring_get_interface_speed(pfring *ring);

pfring_if_t *pfring_findalldevs(void);

void pfring_freealldevs(pfring_if_t *list);

/* ********************************* */

int pfring_parse_bpf_filter(char *filter_buffer, u_int caplen,
 #ifdef BPF_RELEASE
                            struct bpf_program
#else
                            struct pfring_bpf_program
#endif
                            *filter);

void pfring_free_bpf_filter(
#ifdef BPF_RELEASE
                            struct bpf_program
#else
                            struct pfring_bpf_program
#endif
                            *filter);

u_int32_t pfring_bpf_filter(void *bpf_insn, u_char *buffer, u_int32_t caplen, u_int32_t len);

/* ********************************* */

/* pfring_utils.h */
int32_t gmt_to_local(time_t t);

/* ********************************* */

typedef struct {
  char *name;
  int (*open) (pfring *);
  pfring_if_t *(*findalldevs) (void);
} pfring_module_info;
  
struct thirdparty_func {
  const char *name;  /* Function name */
  void (*ptr)(void); /* Function pointer */
};

/* ********************************* */
  
void pfring_thirdparty_lib_init(const char* thirdparty_lib_name,
                struct thirdparty_func thirdparty_function_ptr[]);

#ifdef __cplusplus
}
#endif

#endif /* _PFRING_H_ */