source: lib/libtrace_int.h @ c7e547e

cachetimestampsdevelopdpdk-ndagetsiliverc-4.0.3rc-4.0.4ringdecrementfixringperformance
Last change on this file since c7e547e was c7e547e, checked in by Shane Alcock <salcock@…>, 3 years ago

Added a dpdkndag format for faster ndag reading

Instead of joining a multicast group and receiving nDAG packets
via the networking stack, this new format uses DPDK to sniff
the multicast direct from the wire. This should save some effort
shuffling the packets back through the kernel's networking stack.

  • Property mode set to 100644
File size: 42.3 KB
Line 
1/*
2 *
3 * Copyright (c) 2007-2016 The University of Waikato, Hamilton, New Zealand.
4 * All rights reserved.
5 *
6 * This file is part of libtrace.
7 *
8 * This code has been developed by the University of Waikato WAND
9 * research group. For further information please see http://www.wand.net.nz/
10 *
11 * libtrace is free software; you can redistribute it and/or modify
12 * it under the terms of the GNU Lesser General Public License as published by
13 * the Free Software Foundation; either version 3 of the License, or
14 * (at your option) any later version.
15 *
16 * libtrace is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19 * GNU Lesser General Public License for more details.
20 *
21 * You should have received a copy of the GNU Lesser General Public License
22 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
23 *
24 *
25 */
26/** @file
27 *
28 * @brief Header file containing definitions for structures and functions that
29 * are internal
30 *
31 * @author Daniel Lawson
32 * @author Perry Lorier
33 * @author Shane Alcock
34 *
35 * @version $Id$
36 *
37 * All of the structures and functions defined in this header file are intended
38 * for internal use within Libtrace only. They should not be exported as part
39 * of the library API as we don't want users accessing things like the
40 * contents of the libtrace packet structure directly!
41 */
42#ifndef LIBTRACE_INT_H
43#define LIBTRACE_INT_H
44
45#ifdef __cplusplus
46extern "C" {
47#endif
48
49#include "config.h"
50#include "common.h"
51#include "libtrace_parallel.h"
52#include "wandio.h"
53#include "lt_bswap.h"
54
55#ifdef _MSC_VER
56// warning: deprecated function
57#pragma warning(disable:4996)
58// warning: benign redefinitions of types
59#pragma warning(disable:4142)
60#endif
61
62#ifdef HAVE_INTTYPES_H
63# include <inttypes.h>
64#else
65# include "lt_inttypes.h"
66#endif
67
68#ifdef HAVE_STDDEF_H
69# include <stddef.h>
70#else
71#ifndef WIN32
72# error "Can't find stddev.h -- do you define ptrdiff_t elsewhere?"
73#endif
74#endif
75
76
77#include "rt_protocol.h"
78       
79/* Prefer net/bpf.h over pcap-bpf.h for format_bpf.c on MacOS */
80#ifdef HAVE_NET_BPF_H
81#    include <net/bpf.h>
82#    define HAVE_BPF 1
83#else
84#ifdef HAVE_PCAP_BPF_H
85#  include <pcap-bpf.h>
86#  define HAVE_BPF 1
87#endif
88#endif
89
90#ifdef HAVE_PCAP_H
91#  include <pcap.h>
92#  ifdef HAVE_PCAP_INT_H
93#    include <pcap-int.h>
94#  endif
95#endif
96
97#ifdef HAVE_ZLIB_H
98#  include <zlib.h>
99#endif
100
101#ifndef HAVE_STRNDUP
102char *strndup(const char *s, size_t size);
103#endif
104
105#ifndef HAVE_STRNCASECMP
106# ifndef HAVE__STRNICMP
107/** A local implementation of strncasecmp (as some systems do not have it) */
108int strncasecmp(const char *str1, const char *str2, size_t n);
109# else
110# define strncasecmp _strnicmp
111# endif
112#endif
113
114#ifndef HAVE_SNPRINTF
115# ifndef HAVE_SPRINTF_S
116/** A local implementation of snprintf (as some systems do not have it) */
117int snprintf(char *str, size_t size, const char *format, ...);
118# else
119# define snprintf sprintf_s
120# endif
121#endif
122
123#include "daglegacy.h"
124       
125#ifdef HAVE_DAG_API
126#  include "dagnew.h"
127#  include "dagapi.h"
128#       if DAG_VERSION == 24
129#               include <erftypes.h>
130#       else
131#               include <daginf.h>
132#       endif
133#  include "erftypes.h"
134#else
135#  include "dagformat.h"
136#endif
137
138#ifdef HAVE_LLVM
139#include "bpf-jit/bpf-jit.h"
140#endif
141
142#include "data-struct/ring_buffer.h"
143#include "data-struct/object_cache.h"
144#include "data-struct/vector.h"
145#include "data-struct/message_queue.h"
146#include "data-struct/deque.h"
147#include "data-struct/linked_list.h"
148#include "data-struct/sliding_window.h"
149#include "data-struct/buckets.h"
150#include "pthread_spinlock.h"
151
152//#define RP_BUFSIZE 65536U
153
154/** Data about the most recent event from a trace file */
155struct libtrace_event_status_t {
156        /** A libtrace packet to store the packet when a PACKET event occurs */
157        libtrace_packet_t *packet;
158        /** Time between the timestamp for the current packet and the current
159         * walltime */
160        double tdelta;
161        /** The timestamp of the previous PACKET event */
162        double trace_last_ts;
163        /** The size of the current PACKET event */
164        int psize;
165        /** Whether there is a packet stored in *packet above waiting for an
166         * event to occur */
167        bool waiting;
168};
169
170enum thread_types {
171        THREAD_EMPTY,
172        THREAD_HASHER,
173        THREAD_PERPKT,
174        THREAD_REPORTER,
175        THREAD_KEEPALIVE
176};
177
178enum thread_states {
179        THREAD_RUNNING,
180        THREAD_FINISHING,
181        THREAD_FINISHED,
182        THREAD_PAUSED,
183        THREAD_STATE_MAX
184};
185
186/**
187 * Information of this thread
188 */
189struct libtrace_thread_t {
190        uint64_t accepted_packets; // The number of packets accepted only used if pread
191        uint64_t filtered_packets;
192        // is retreving packets
193        // Set to true once the first packet has been stored
194        bool recorded_first;
195        // For thread safety reason we actually must store this here
196        int64_t tracetime_offset_usec;
197        void* user_data; // TLS for the user to use
198        void* format_data; // TLS for the format to use
199        libtrace_message_queue_t messages; // Message handling
200        libtrace_ringbuffer_t rbuffer; // Input
201        libtrace_t * trace;
202        void* ret;
203        enum thread_types type;
204        enum thread_states state;
205        pthread_t tid;
206        int perpkt_num; // A number from 0-X that represents this perpkt threads number
207                                // in the table, intended to quickly identify this thread
208                                // -1 represents NA (such as the case this is not a perpkt thread)
209} ALIGN_STRUCT(CACHE_LINE_SIZE);
210
211/**
212 * Storage to note time value against each.
213 * Used both internally to do trace time playback
214 * and can be used externally to assist applications which need
215 * a trace starting time such as tracertstats.
216 */
217struct first_packets {
218        pthread_spinlock_t lock;
219        size_t count; // If == perpkt_thread_count threads we have all
220        size_t first; // Valid if count != 0
221        struct {
222                libtrace_packet_t * packet;
223                struct timeval tv;
224        } * packets;
225};
226
227#define TRACE_STATES \
228        X(STATE_NEW) \
229        X(STATE_RUNNING) \
230        X(STATE_PAUSING) \
231        X(STATE_PAUSED) \
232        X(STATE_FINISHED) \
233        X(STATE_FINISHING) \
234        X(STATE_DESTROYED) \
235        X(STATE_JOINED) \
236        X(STATE_ERROR)
237
238#define X(a) a,
239enum trace_state {
240        TRACE_STATES
241};
242#undef X
243
244#define X(a) case a: return #a;
245static inline char *get_trace_state_name(enum trace_state ts){
246        switch(ts) {
247                TRACE_STATES
248                default:
249                        return "UNKNOWN";
250        }
251}
252#undef X
253
254#define READ_EOF 0
255#define READ_ERROR -1
256#define READ_MESSAGE -2
257// Used for inband tick message
258#define READ_TICK -3
259
260/**
261 * Tuning the parallel sizes
262 * See the user documentation trace_set_x
263 */
264struct user_configuration {
265        size_t cache_size;
266        size_t thread_cache_size;
267        bool fixed_count;
268        size_t burst_size;
269        size_t tick_interval;
270        size_t tick_count;
271        size_t perpkt_threads;
272        size_t hasher_queue_size;
273        bool hasher_polling;
274        bool reporter_polling;
275        size_t reporter_thold;
276        bool debug_state;
277};
278#define ZERO_USER_CONFIG(config) memset(&config, 0, sizeof(struct user_configuration));
279
280struct callback_set {
281
282        fn_cb_starting message_starting;
283        fn_cb_dataless message_stopping;
284        fn_cb_dataless message_resuming;
285        fn_cb_dataless message_pausing;
286        fn_cb_packet message_packet;
287        fn_cb_result message_result;
288        fn_cb_first_packet message_first_packet;
289        fn_cb_tick message_tick_count;
290        fn_cb_tick message_tick_interval;
291        fn_cb_usermessage message_user;
292};
293
294/** A libtrace input trace
295 * @internal
296 */
297struct libtrace_t {
298        /** The capture format for the input trace */
299        struct libtrace_format_t *format; 
300        /** Details of the most recent PACKET event reported by the trace */
301        struct libtrace_event_status_t event;
302        /** Pointer to the "global" data for the capture format module */       
303        void *format_data;             
304        /** A BPF filter to be applied to all packets read by the trace -
305         * used only if the capture format does not support filters natively */
306        struct libtrace_filter_t *filter; 
307        /** The snap length to be applied to all packets read by the trace -
308         * used only if the capture format does not support snapping natively */
309        size_t snaplen;                 
310        /** Count of the number of packets returned to the libtrace user */
311        uint64_t accepted_packets;
312        /** Count of the number of packets filtered by libtrace */
313        uint64_t filtered_packets;
314        /** The sequence is like accepted_packets but we don't reset this after a pause. */
315        uint64_t sequence_number;
316        /** The packet read out by the trace, backwards compatibility to allow us to finalise
317         * a packet when the trace is destroyed */
318        libtrace_packet_t *last_packet;
319        /** The filename from the uri for the trace */
320        char *uridata;
321        /** The libtrace IO reader for this trace (if applicable) */
322        io_t *io;
323        /** Error information for the trace */
324        libtrace_err_t err;
325        /** Boolean flag indicating whether the trace has been started */
326        bool started;
327        /** Synchronise writes/reads across this format object and attached threads etc */
328        pthread_mutex_t libtrace_lock;
329        /** Packet read lock, seperate from libtrace_lock as to not block while reading a burst */
330        pthread_mutex_t read_packet_lock;
331        /** State */
332        enum trace_state state;
333        /** Use to control pausing threads and finishing threads etc always used with libtrace_lock */
334        pthread_cond_t perpkt_cond;
335        /** Keeps track of counts of threads in any given state */
336        int perpkt_thread_states[THREAD_STATE_MAX]; 
337
338        /** Set to indicate a perpkt's queue is full as such the writing perpkt cannot proceed */
339        bool perpkt_queue_full;
340        /** Global storage for this trace, shared among all the threads  */
341        void* global_blob;
342        /** The actual freelist */
343        libtrace_ocache_t packet_freelist;
344        /** The hasher function */
345        enum hasher_types hasher_type;
346        /** The hasher function - NULL implies they don't care or balance */
347        fn_hasher hasher;
348        void *hasher_data;
349        /** The pread_packet choosen path for the configuration */
350        int (*pread)(libtrace_t *, libtrace_thread_t *, libtrace_packet_t **, size_t);
351
352        libtrace_thread_t hasher_thread;
353        libtrace_thread_t reporter_thread;
354        libtrace_thread_t keepalive_thread;
355        int perpkt_thread_count;
356        libtrace_thread_t * perpkt_threads; // All our perpkt threads
357        // Used to keep track of the first packet seen on each thread
358        struct first_packets first_packets;
359        int tracetime;
360
361        /*
362         * Caches statistic counters in the case that our trace is
363         * paused or stopped before this counter is taken
364         */
365        libtrace_stat_t *stats;
366        struct user_configuration config;
367        libtrace_combine_t combiner;
368       
369        /* Set of callbacks to be executed by per packet threads in response
370         * to various messages. */
371        struct callback_set *perpkt_cbs;
372        /* Set of callbacks to be executed by the reporter thread in response
373         * to various messages. */
374        struct callback_set *reporter_cbs;
375};
376
377#define LIBTRACE_STAT_MAGIC 0x41
378
379void trace_fin_packet(libtrace_packet_t *packet);
380void libtrace_zero_thread(libtrace_thread_t * t);
381void store_first_packet(libtrace_t *libtrace, libtrace_packet_t *packet, libtrace_thread_t *t);
382libtrace_thread_t * get_thread_table(libtrace_t *libtrace);
383
384
385void send_message(libtrace_t *trace, libtrace_thread_t *target,
386                const enum libtrace_messages type,
387                libtrace_generic_t data, libtrace_thread_t *sender);
388
389/** A libtrace output trace
390 * @internal
391 */
392struct libtrace_out_t {
393        /** The capture format for the output trace */
394        struct libtrace_format_t *format;
395        /** Pointer to the "global" data for the capture format module */
396        void *format_data;             
397        /** The filename for the uri for the output trace */
398        char *uridata;                 
399        /** Error information for the output trace */
400        libtrace_err_t err;
401        /** Boolean flag indicating whether the trace has been started */
402        bool started;
403};
404
405/** Sets the error status on an input trace
406 *
407 * @param trace         The input trace to set the error status for
408 * @param errcode       The code for the error - can be a libtrace error code or a regular errno value
409 * @param msg           A message to print when reporting the error
410 */
411void trace_set_err(libtrace_t *trace, int errcode,const char *msg,...) 
412
413                                                                PRINTF(3,4);
414/** Sets the error status on an output trace
415 *
416 * @param trace         The output trace to set the error status for
417 * @param errcode       The code for the error - can be a libtrace error code or a regular errno value
418 * @param msg           A message to print when reporting the error
419 */
420void trace_set_err_out(libtrace_out_t *trace, int errcode, const char *msg,...)
421                                                                PRINTF(3,4);
422
423/** Clears the cached values for a libtrace packet
424 *
425 * @param packet        The libtrace packet that requires a cache reset
426 */
427void trace_clear_cache(libtrace_packet_t *packet);
428
429
430#ifndef PF_RULESET_NAME_SIZE
431#define PF_RULESET_NAME_SIZE 16
432#endif
433
434#ifndef IFNAMSIZ
435#define IFNAMSIZ 16
436#endif
437
438
439/** A local definition of a PFLOG header */
440typedef struct libtrace_pflog_header_t {
441        uint8_t    length;     
442        sa_family_t   af;
443        uint8_t    action;
444        uint8_t    reason;
445        char       ifname[IFNAMSIZ];
446        char       ruleset[PF_RULESET_NAME_SIZE];
447        uint32_t   rulenr;
448        uint32_t   subrulenr;
449        uint8_t    dir;
450        uint8_t    pad[3];
451} PACKED libtrace_pflog_header_t;
452
453/** A libtrace capture format module */
454/* All functions should return -1, or NULL on failure */
455struct libtrace_format_t {
456        /** The name of this module, used in the libtrace URI to identify the
457         * capture format */
458        const char *name;
459        /** The version of this module */
460        const char *version;
461        /** The RT protocol type of this module */
462        enum base_format_t type;
463
464
465        /** Given a filename, return if this is the most likely capture format
466         * (used for devices). Used to "guess" the capture format when the
467         * URI is not fully specified.
468         *
469         * @param fname         The name of the device or file to examine
470         * @return 1 if the name matches the capture format, 0 otherwise
471         */
472        int (*probe_filename)(const char *fname);
473       
474        /** Given a file, looks at the start of the file to determine if this
475         * is the capture format. Used to "guess" the capture format when the
476         * URI is not fully specified.
477         *
478         * @param io            An open libtrace IO reader for the file to check
479         * @return 1 if the file matches the capture format, 0 otherwise
480         */
481        int (*probe_magic)(io_t *io);
482
483        /** Initialises an input trace using the capture format.
484         *
485         * @param libtrace      The input trace to be initialised
486         * @return 0 if successful, -1 in the event of error
487         */
488        int (*init_input)(libtrace_t *libtrace);
489       
490        /** Applies a configuration option to an input trace.
491         *
492         * @param libtrace      The input trace to apply the option to
493         * @param option        The option that is being configured
494         * @param value         A pointer to the value that the option is to be
495         *                      set to
496         * @return 0 if successful, -1 if the option is unsupported or an error
497         * occurs
498         */
499        int (*config_input)(libtrace_t *libtrace,trace_option_t option,void *value);
500        /** Starts or unpauses an input trace - note that this function is
501         * often the one that opens the file or device for reading.
502         *
503         * @param libtrace      The input trace to be started or unpaused
504         * @return 0 if successful, -1 in the event of error */
505        int (*start_input)(libtrace_t *libtrace);
506
507        /** Pauses an input trace - this function should close or detach the
508         * file or device that is being read from.
509         *
510         * @param libtrace      The input trace to be paused
511         * @return 0 if successful, -1 in the event of error
512         */
513        int (*pause_input)(libtrace_t *libtrace);
514
515        /** Initialises an output trace using the capture format.
516         *
517         * @param libtrace      The output trace to be initialised
518         * @return 0 if successful, -1 in the event of error
519         */
520        int (*init_output)(libtrace_out_t *libtrace);
521       
522        /** Applies a configuration option to an output trace.
523         *
524         * @param libtrace      The output trace to apply the option to
525         * @param option        The option that is being configured
526         * @param value         A pointer to the value that the option is to be
527         *                      set to
528         * @return 0 if successful, -1 if the option is unsupported or an error
529         * occurs
530         * */
531        int (*config_output)(libtrace_out_t *libtrace, trace_option_output_t option, void *value);
532
533        /** Starts an output trace - note that this function is often the one
534         * that opens the file or device for writing.
535         *
536         * @param libtrace      The output trace to be started
537         * @return 0 if successful, -1 if an error occurs
538         *
539         * There is no pause for output traces, as writing is not performed
540         * asynchronously.
541         */
542        int (*start_output)(libtrace_out_t *libtrace);
543
544        /** Concludes an input trace and cleans up the capture format data.
545         *
546         * @param libtrace      The input trace to be concluded
547         * @return 0 if successful, -1 if an error occurs
548         *
549         * Libtrace will call the pause_input function if the input trace is
550         * currently active prior to calling this function.
551         */
552        int (*fin_input)(libtrace_t *libtrace);
553
554        /** Concludes an output trace and cleans up the capture format data.
555         *
556         * @param libtrace      The output trace to be concluded
557         * @return 0 if successful, -1 if an error occurs
558         */
559        int (*fin_output)(libtrace_out_t *libtrace);
560
561        /** Reads the next packet from an input trace into the provided packet
562         * structure.
563         *
564         * @param libtrace      The input trace to read from
565         * @param packet        The libtrace packet to read into
566         * @return The size of the packet read (in bytes) including the capture
567         * framing header, or -1 if an error occurs. 0 is returned in the
568         * event of an EOF or -2 in the case of interrupting the parallel API.
569         *
570         * If no packets are available for reading, this function should block
571         * until one appears or return 0 if the end of a trace file has been
572         * reached.
573         */
574        int (*read_packet)(libtrace_t *libtrace, libtrace_packet_t *packet);
575       
576        /** Converts a buffer containing a packet record into a libtrace packet
577         *
578         * @param libtrace      An input trace in the capture format for the
579         *                      packet
580         * @param packet        A libtrace packet to put the prepared packet
581         *                      into
582         * @param buffer        The buffer containing the packet record
583         *                      (including the capture format header)
584         * @param rt_type       The RT type for the packet
585         * @param flags         Flags describing properties that should be
586         *                      applied to the new packet
587         * @return 0 if successful, -1 if an error occurs.
588         *
589         * Updates internal trace and packet details, such as payload pointers,
590         * loss counters and packet types to match the packet record provided
591         * in the buffer. This is a zero-copy function.
592         *
593         * Intended (at this stage) only for internal use, particularly by
594         * RT which needs to decapsulate RT packets */
595        int (*prepare_packet)(libtrace_t *libtrace, libtrace_packet_t *packet,
596                        void *buffer, libtrace_rt_types_t rt_type, 
597                        uint32_t flags);
598       
599        /** Frees any resources allocated by the capture format module for a
600         * libtrace packet.
601         *
602         * @param The packet to be finalised
603         *       */
604        void (*fin_packet)(libtrace_packet_t *packet);
605
606        /** Write a libtrace packet to an output trace.
607         *
608         * @param libtrace      The output trace to write the packet to
609         * @param packet        The packet to be written out
610         * @return The number of bytes written, or -1 if an error occurs
611         */
612        int (*write_packet)(libtrace_out_t *libtrace, libtrace_packet_t *packet);
613        /** Returns the libtrace link type for a packet.
614         *
615         * @param packet        The packet to get the link type for
616         * @return The libtrace link type, or -1 if this link type is unknown
617         */ 
618        libtrace_linktype_t (*get_link_type)(const libtrace_packet_t *packet);
619
620        /** Returns the direction of a packet.
621         *
622         * @param packet        The packet to get the direction for
623         * @return The direction of the packet, or -1 if no direction tag is
624         * present or an error occurs
625         */ 
626        libtrace_direction_t (*get_direction)(const libtrace_packet_t *packet);
627       
628        /** Sets the direction of a packet.
629         *
630         * @param packet        The packet to set the direction for
631         * @param direction     The direction to assign to the packet
632         * @return The updated direction for the packet, or -1 if an error
633         * occurs
634         *
635         * @note Some capture formats do not feature direction tagging, so it
636         * will not make sense to implement a set_direction function for them.
637         */ 
638        libtrace_direction_t (*set_direction)(libtrace_packet_t *packet, libtrace_direction_t direction);
639       
640        /** Returns the timestamp for a packet in the ERF timestamp format.
641         *
642         * @param packet        The packet to get the timestamp from
643         * @return The 64-bit ERF timestamp
644         *
645         * @note Each format must implement at least one of the four "get
646         * timestamp" functions.
647         *
648         * If not implemented, libtrace will convert the result of one of the
649         * other timestamp functions into the appropriate format instead.
650         * This means each capture format only needs to implement the most
651         * sensible of the four and let libtrace handle any conversions.
652         *
653         */
654        uint64_t (*get_erf_timestamp)(const libtrace_packet_t *packet);
655
656        /** Returns the timestamp for a packet in the timeval format
657         *
658         * @param packet        The packet to get the timestamp from
659         * @return The timestamp from the packet as a timeval
660         *
661         * @note Each format must implement at least one of the four "get
662         * timestamp" functions.
663         *
664         * If not implemented, libtrace will convert the result of one of the
665         * other timestamp functions into the appropriate format instead.
666         * This means each capture format only needs to implement the most
667         * sensible of the four and let libtrace handle any conversions.
668         */
669        struct timeval (*get_timeval)(const libtrace_packet_t *packet);
670       
671        /** Returns the timestamp for a packet in the timespec format.
672         *
673         * @param packet        The packet to get the timestamp from
674         * @return The timestamp from the packet as a timespec
675         *
676         * @note Each format must implement at least one of the four "get
677         * timestamp" functions.
678         *
679         * If not implemented, libtrace will convert the result of one of the
680         * other timestamp functions into the appropriate format instead.
681         * This means each capture format only needs to implement the most
682         * sensible of the four and let libtrace handle any conversions.
683         */
684        struct timespec (*get_timespec)(const libtrace_packet_t *packet);
685       
686        /** Returns the timestamp for a packet in floating point seconds.
687         *
688         * @param packet        The packet to get the timestamp from
689         * @return The timestamp from the packet as a floating point number of
690         * seconds since 1970-01-01 00:00:00 UTC
691         *
692         * @note Each format must implement at least one of the four "get
693         * timestamp" functions.
694         *
695         * If not implemented, libtrace will convert the result of one of the
696         * other timestamp functions into the appropriate format instead.
697         * This means each capture format only needs to implement the most
698         * sensible of the four and let libtrace handle any conversions.
699         */
700        double (*get_seconds)(const libtrace_packet_t *packet);
701       
702        /** Moves the read pointer to a certain ERF timestamp within an input
703         * trace file.
704         *
705         * @param trace         The input trace to seek within
706         * @param timestamp     The timestamp to seek to, as an ERF timestamp
707         *
708         * @return 0 on success, -1 on failure.
709         *
710         * The next packet read from this trace will now be the first packet
711         * to have a timestamp equal to or greater than the provided timestamp.
712         *
713         * @note Each format that supports seeking must implement at least one
714         * of the seek functions.
715         *
716         * If not implemented, libtrace will convert the timestamp into the
717         * appropriate format to use a seek function that has been implemented.
718         * This means each capture format only needs to implement the seek
719         * function that matches the native timestamp format for that capture.
720         *
721         */
722        int (*seek_erf)(libtrace_t *trace, uint64_t timestamp);
723        /** Moves the read pointer to a certain timestamp represented using a
724         * timeval within an input trace file.
725         *
726         * @param trace         The input trace to seek within
727         * @param timestamp     The timestamp to seek to, as a timeval
728         *
729         * @return 0 on success, -1 on failure.
730         *
731         * The next packet read from this trace will now be the first packet
732         * to have a timestamp equal to or greater than the provided timestamp.
733         *
734         * @note Each format that supports seeking must implement at least one
735         * of the seek functions.
736         *
737         * If not implemented, libtrace will convert the timestamp into the
738         * appropriate format to use a seek function that has been implemented.
739         * This means each capture format only needs to implement the seek
740         * function that matches the native timestamp format for that capture.
741         *
742         */
743        int (*seek_timeval)(libtrace_t *trace, struct timeval tv);
744       
745        /** Moves the read pointer to a certain timestamp represented using
746         * floating point seconds within an input trace file.
747         *
748         * @param trace         The input trace to seek within
749         * @param timestamp     The timestamp to seek to, as floating point
750         *                      seconds since 1970-01-01 00:00:00 UTC
751         *
752         * @return 0 on success, -1 on failure.
753         *
754         * The next packet read from this trace will now be the first packet
755         * to have a timestamp equal to or greater than the provided timestamp.
756         *
757         * @note Each format that supports seeking must implement at least one
758         * of the seek functions.
759         *
760         * If not implemented, libtrace will convert the timestamp into the
761         * appropriate format to use a seek function that has been implemented.
762         * This means each capture format only needs to implement the seek
763         * function that matches the native timestamp format for that capture.
764         *
765         */
766        int (*seek_seconds)(libtrace_t *trace, double seconds);
767       
768        /** Returns the payload length of the captured packet record.
769         *
770         * @param packet        The packet to get the capture length from
771         * @return The capture length for the packet, or -1 if an error occurs
772         *
773         * Capture length is the current size of the packet record itself,
774         * following any truncation that may have occurred during the capture
775         * process. This length does not include the capture format framing
776         * header.
777         */
778        int (*get_capture_length)(const libtrace_packet_t *packet);
779
780        /** Returns the original length of the packet as it was on the wire.
781         *
782         * @param packet        The packet to get the wire length from
783         * @return The length of the packet on the wire at the time of capture,
784         * or -1 if an error occurs
785         *
786         * Wire length is the original size of the packet prior to any
787         * truncation that may have occurred as part of the capture process.
788         * This length does not include the capture format framing header.
789         */
790        int (*get_wire_length)(const libtrace_packet_t *packet);
791       
792        /** Returns the length of the capture format framing header
793         *
794         * @param packet        The packet to get the framing length from
795         * @return The length of the framing header, or -1 if an error occurs
796         *
797         * The framing header is the extra metadata that the capture process
798         * records about a packet.  The framing length does not include any
799         * of the packet payload itself. The total size of the packet record
800         * can be calculated be adding this value with the capture length.
801         */
802        int (*get_framing_length)(const libtrace_packet_t *packet);
803
804        /** Sets the capture length for a packet.
805         *
806         * @param packet        The packet to adjust the capture length for.
807         * @param size          The new capture length
808         * @return The new capture length of the packet, or -1 if an error
809         * occurs
810         *
811         * @note This function should only reduce the capture length. If the
812         * provided length is larger than the current capture length, -1 should
813         * be returned.
814         */
815        size_t (*set_capture_length)(struct libtrace_packet_t *packet,size_t size);
816        /** Returns the number of packets observed by an input trace.
817         *
818         * @param trace         The input trace to get the packet count for
819         * @return The number of packets observed by an input trace, or
820         * UINT64_MAX if the number is unknown
821         *
822         * This count includes packets that have been filtered and dropped.
823         */
824        uint64_t (*get_received_packets)(libtrace_t *trace);
825
826        /** Returns the number of packets filtered by an input trace.
827         *
828         * @param trace         The input trace to get the filtered count for
829         * @return The number of packets filtered by the input trace, or
830         * UINT64_MAX if the number is unknown
831         *
832         */
833        uint64_t (*get_filtered_packets)(libtrace_t *trace);
834       
835        /** Returns the number of packets dropped by an input trace.
836         *
837         * @param trace         The input trace to get the dropped count for
838         * @return The number of packets dropped by the input trace, or
839         * UINT64_MAX if the number is unknown
840         *
841         */
842        uint64_t (*get_dropped_packets)(libtrace_t *trace);
843
844        /** Returns statistics about a trace.
845         *
846         * @param trace The libtrace object
847         * @param stat [in,out] A statistics structure ready to be filled
848         *
849         * The filtered and accepted statistics will be set to the values
850         * stored in the library. All other statistics are not set.
851         *
852         * @note If filtering of packets is performed by a trace and the number
853         * of filtered packets is unknown this should be marked as invalid by
854         * the format.
855         */
856        void (*get_statistics)(libtrace_t *trace, libtrace_stat_t *stat);
857       
858        /** Returns the file descriptor used by the input trace.
859         *
860         * @param trace         The input trace to get the file descriptor for
861         * @return The file descriptor used by the input trace to read packets
862         *
863         */
864        int (*get_fd)(const libtrace_t *trace);
865       
866        /** Returns the next libtrace event for the input trace.
867         *
868         * @param trace         The input trace to get the next event from
869         * @param packet        A libtrace packet to read a packet into
870         * @return A libtrace event describing the event that occured
871         *
872         * The event API allows for non-blocking reading of packets from an
873         * input trace. If a packet is available and ready to be read, a packet
874         * event should be returned. Otherwise a sleep or fd event should be
875         * returned to indicate that the caller needs to wait. If the input
876         * trace has an error or reaches EOF, a terminate event should be
877         * returned.
878         */
879        struct libtrace_eventobj_t (*trace_event)(libtrace_t *trace, libtrace_packet_t *packet);       
880
881        /** Prints some useful help information to standard output. */
882        void (*help)(void);
883       
884        /** Next pointer, should always be NULL - used by the format module
885         * manager. */
886        struct libtrace_format_t *next;
887
888        /** Holds information about the trace format */
889        struct libtrace_info_t info;
890
891        /**
892         * Starts or unpauses an input trace in parallel mode - note that
893         * this function is often the one that opens the file or device for
894         * reading.
895         *
896         * @param libtrace      The input trace to be started or unpaused
897         * @return 0 upon success.
898         *         Otherwise in event of an error -1 is returned.
899         *
900         */
901        int (*pstart_input)(libtrace_t *trace);
902       
903        /**
904         * Read a batch of packets from the input stream related to thread.
905         * At most read nb_packets, however should return with less if packets
906         * are not waiting. However still must return at least 1, 0 still indicates
907         * EOF.
908         *
909         * @param libtrace      The input trace
910         * @param t     The thread
911         * @param packets       An array of packets
912         * @param nb_packets    The number of packets in the array (the maximum to read)
913         * @return The number of packets read, or 0 in the case of EOF or -1 in error or -2 to represent
914         * interrupted due to message waiting before packets had been read.
915         */
916        int (*pread_packets)(libtrace_t *trace, libtrace_thread_t *t, libtrace_packet_t **packets, size_t nb_packets);
917       
918        /** Pause a parallel trace
919         *
920         * @param libtrace      The input trace to be paused
921         */
922        int (*ppause_input)(libtrace_t *trace);
923       
924        /** Called after all threads have been paused, Finish (close) a parallel trace
925         *
926         * @param libtrace      The input trace to be stopped
927         */
928        int (*pfin_input)(libtrace_t *trace);
929
930        /**
931         * Register a thread for use with the format or using the packets produced
932         * by it. This is NOT only used for threads reading packets in fact all
933         * threads use this.
934         *
935         * The libtrace lock is not held by this format but can be aquired
936         * by the format.
937         *
938         * Some use cases include setting up any thread local storage required for
939         * to read packets and free packets. For DPDK we require any thread that
940         * may release or read a packet to have have an internal number associated
941         * with it.
942         *
943         * The thread type can be used to see if this thread is going to be used
944         * to read packets or otherwise.
945         *
946         * @return 0 if successful, -1 if the option is unsupported or an error
947         * occurs (such as a maximum of threads being reached)
948         */
949        int (*pregister_thread)(libtrace_t *libtrace, libtrace_thread_t *t, bool reader);
950
951        /**
952         * If needed any memory allocated with pregister_thread can be released
953         * in this function. The thread will be destroyed directly after this
954         * function is called.
955         */
956        void (*punregister_thread)(libtrace_t *libtrace, libtrace_thread_t *t);
957
958        /** Returns statistics for a single thread.
959         *
960         * @param trace The libtrace object
961         * @param t The thread to return statistics for
962         * @param stat [in,out] A statistics structure ready to be filled
963         *
964         * The filtered and accepted statistics will be set to the values
965         * stored in the library. All other statistics are not set.
966         *
967         * @note If filtering of packets is performed by a trace and the number
968         * of filtered packets is unknown this should be marked as invalid by
969         * the format.
970         */
971        void (*get_thread_statistics)(libtrace_t *libtrace,
972                                      libtrace_thread_t *t,
973                                      libtrace_stat_t *stat);
974};
975
976/** Macro to zero out a single thread format */
977#define NON_PARALLEL(live) \
978        {live, 1},              /* trace info */ \
979        NULL,                   /* pstart_input */ \
980        NULL,                   /* pread_packet */ \
981        NULL,                   /* ppause_input */ \
982        NULL,                   /* pfin_input */ \
983        NULL,                   /* pregister_thread */ \
984        NULL,                   /* punregister_thread */ \
985        NULL,                   /* get_thread_statistics */
986
987/** The list of registered capture formats */
988//extern struct libtrace_format_t *form;
989
990/** Specifies whether any blocking packet readers should cease reading
991 * immediately
992 */
993extern volatile int libtrace_halt;
994
995/**
996 * Used by a format to check if trace_interrupt or if a trace_pause/stop has
997 * been called. Provides backwards compatibility with traditional read
998 * functions when trace_read_packet() is used by the parallel API.
999 *
1000 * Returns -1 if not halting otherwise returns the code that the read
1001 * operation should pass on.
1002 */
1003static inline int is_halted(libtrace_t *trace) {
1004        if (!(libtrace_halt || trace->state == STATE_PAUSING)) {
1005                return -1;
1006        } else if (libtrace_halt) {
1007                return READ_EOF;
1008        } else {
1009                return READ_MESSAGE;
1010        }
1011}
1012
1013/** Registers a new capture format module.
1014 *
1015 * @param format        The format module to be registered
1016 */
1017void register_format(struct libtrace_format_t *format);
1018
1019/** Converts a timeval into a timestamp in microseconds since the epoch.
1020 *
1021 * @param tv    The timeval to be converted.
1022 * @return A 64 bit timestamp in microseconds since the epoch.
1023 */
1024uint64_t tv_to_usec(const struct timeval *tv);
1025
1026/** Converts a PCAP DLT into a libtrace link type.
1027 *
1028 * @param linktype      The PCAP DLT to be converted
1029 * @return The libtrace link type that is equivalent to the provided DLT, or
1030 * -1 if the DLT is unknown
1031 */
1032libtrace_linktype_t pcap_linktype_to_libtrace(libtrace_dlt_t linktype);
1033
1034/** Converts a PCAP DLT into an RT protocol type.
1035 *
1036 * @param linktype      The PCAP DLT to be converted
1037 * @return The RT type that is equivalent to the provided DLT
1038 */
1039libtrace_rt_types_t pcap_linktype_to_rt(libtrace_dlt_t linktype);
1040
1041/** Converts a PCAP-NG DLT into an RT protocol type.
1042 *
1043 * @param linktype      The PCAP DLT to be converted
1044 * @return The RT type that is equivalent to the provided DLT
1045 */
1046libtrace_rt_types_t pcapng_linktype_to_rt(libtrace_dlt_t linktype);
1047
1048/** Converts a libtrace link type into a PCAP linktype.
1049 *
1050 * @param type          The libtrace link type to be converted
1051 * @return The PCAP linktype that is equivalent to the provided libtrace link
1052 * type, or -1 if the link type is unknown
1053 */
1054libtrace_dlt_t libtrace_to_pcap_linktype(libtrace_linktype_t type);
1055
1056/** Converts a libtrace link type into a PCAP DLT.
1057 *
1058 * @param type          The libtrace link type to be converted
1059 * @return The PCAP DLT that is equivalent to the provided libtrace link
1060 * type, or -1 if the link type is unknown
1061 */
1062libtrace_dlt_t libtrace_to_pcap_dlt(libtrace_linktype_t type);
1063
1064/** Converts an RT protocol type into a PCAP DLT.
1065 *
1066 * @param rt_type       The RT type to be converted
1067 * @return The PCAP DLT that is equivalent to the provided RT protocol
1068 */
1069libtrace_dlt_t rt_to_pcap_linktype(libtrace_rt_types_t rt_type);
1070
1071/** Converts a PCAP DLT into an RT protocol type for the BPF format.
1072 *
1073 * @param linktype      The PCAP DLT to be converted
1074 * @return The RT type that is equivalent to the provided DLT for BPF
1075 */
1076libtrace_rt_types_t bpf_linktype_to_rt(libtrace_dlt_t linktype);
1077
1078/** Converts an ERF type into a libtrace link type.
1079 *
1080 * @param erf           The ERF type to be converted
1081 * @return The libtrace link type that is equivalent to the provided ERF type,
1082 * or -1 if the ERF type is unknown
1083 */
1084libtrace_linktype_t erf_type_to_libtrace(uint8_t erf);
1085
1086/** Converts a libtrace link type into an ERF type.
1087 *
1088 * @param linktype      The libtrace link type to be converted
1089 * @return The ERF type that is equivalent to the provided libtrace link type,
1090 * or -1 if the link type cannot be matched to an ERF type.
1091 */
1092uint8_t libtrace_to_erf_type(libtrace_linktype_t linktype);
1093
1094/** Converts an ARPHRD type into a libtrace link type.
1095 *
1096 * @param arphrd        The ARPHRD type to be converted
1097 * @return The libtrace link type that is equivalent to the provided ARPHRD
1098 * type, or -1 if the ARPHRD type is unknown
1099 */
1100libtrace_linktype_t arphrd_type_to_libtrace(unsigned int arphrd);
1101
1102/** Converts a libtrace link type into an ARPHRD type.
1103 *
1104 * @param type          The libtrace link type to be converted
1105 * @return The ARPHRD type that is equivalent to the provided libtrace link
1106 * type, or -1 if the link type cannot be matched to an ARPHRD type
1107 */
1108unsigned int libtrace_to_arphrd_type(libtrace_linktype_t type);
1109
1110/** Converts a libtrace packet to the Linux SLL type.
1111 *
1112 * @param packet        The packet to be promoted
1113 *
1114 * @note This will involve memcpy() so use sparingly.
1115 *
1116 * This function prepends a Linux SLL header to a packet so that we can store
1117 * direction tagging information.
1118 */
1119void promote_packet(libtrace_packet_t *packet);
1120
1121/** Attempts to demote a packet by removing the first header.
1122 *
1123 * @param packet        The packet to be demoted
1124 * @return True if the packet was demoted, false otherwise.
1125 *
1126 * Essentially the opposite of promote_packet, except that it will also remove
1127 * an ATM header as well as Linux SLL.
1128 *
1129 */
1130bool demote_packet(libtrace_packet_t *packet);
1131
1132/** Returns a pointer to the header following a Linux SLL header.
1133 *
1134 * @param link          A pointer to the Linux SLL header to be skipped
1135 * @param[out] arphrd_type      The arp hardware type of the packet
1136 * @param[out] next_header      The ethertype of the next header
1137 * @param[in,out] remaining     Updated with the number of captured bytes
1138 *                              remaining
1139 * @return A pointer to the header following the Linux SLL header, or NULL if
1140 * no subsequent header is present.
1141 *
1142 * Remaining must point to the number of bytes captured from the Linux SLL
1143 * header and beyond.  It will be decremented by the number of bytes skipped
1144 * to find the payload.
1145 *
1146 * If the Linux SLL header is complete but there are zero bytes of payload
1147 * after the end of the header, a pointer to where the payload would be is
1148 * returned and remaining will be set to zero. If the Linux SLL header is
1149 * incomplete (truncated), then NULL is returned and remaining will be set to
1150 * 0. Therefore, it is very important to check the value of remaining after
1151 * calling this function.
1152 */     
1153void *trace_get_payload_from_linux_sll(const void *link,
1154                uint16_t *arphrd_type, 
1155                uint16_t *next_header, 
1156                uint32_t *remaining);
1157
1158/** Returns a pointer to the header following an ATM header.
1159 *
1160 * @param link          A pointer to the ATM header to be skipped
1161 * @param[out] type     The ethertype of the next header
1162 * @param[in,out] remaining     Updated with the number of captured bytes
1163 *                              remaining
1164 * @return A pointer to the header following the ATM header, or NULL if
1165 * no subsequent header is present.
1166 *
1167 * Remaining must point to the number of bytes captured from the ATM header
1168 * and beyond.  It will be decremented by the number of bytes skipped to find
1169 * the payload.
1170 *
1171 * If the ATM header is complete but there are zero bytes of payload
1172 * after the end of the header, a pointer to where the payload would be is
1173 * returned and remaining will be set to zero. If the ATM header is
1174 * incomplete (truncated), then NULL is returned and remaining will be set to
1175 * 0. Therefore, it is very important to check the value of remaining after
1176 * calling this function.
1177 */     
1178DLLEXPORT void *trace_get_payload_from_atm(void *link, uint8_t *type, 
1179                uint32_t *remaining);
1180
1181
1182#ifdef HAVE_BPF
1183/* A type encapsulating a bpf filter
1184 * This type covers the compiled bpf filter, as well as the original filter
1185 * string
1186 *
1187 */
1188
1189/** Internal representation of a BPF filter */
1190struct libtrace_filter_t {
1191        struct bpf_program filter;      /**< The BPF program itself */
1192        char * filterstring;            /**< The filter string */
1193        int flag;                       /**< Indicates if the filter is valid */
1194        struct bpf_jit_t *jitfilter;
1195};
1196#else
1197/** BPF not supported by this system, but we still need to define a structure
1198 * for the filter */
1199struct libtrace_filter_t {};
1200#endif
1201
1202/** Local definition of a PCAP header */
1203typedef struct libtrace_pcapfile_pkt_hdr_t {
1204        uint32_t ts_sec;        /* Seconds portion of the timestamp */
1205        uint32_t ts_usec;       /* Microseconds portion of the timestamp */
1206        uint32_t caplen;        /* Capture length of the packet */
1207        uint32_t wirelen;       /* The wire length of the packet */
1208} libtrace_pcapfile_pkt_hdr_t;
1209
1210#ifdef HAVE_DAG
1211/** Constructor for the DAG format module */
1212void dag_constructor(void);
1213#endif
1214/** Constructor for the ERF format module */
1215void erf_constructor(void);
1216/** Constructor for the TSH format module */
1217void tsh_constructor(void);
1218/** Constructor for the Legacy DAG format module */
1219void legacy_constructor(void);
1220/** Constructor for the Linux Native format module */
1221void linuxnative_constructor(void);
1222/** Constructor for the Linux Ring format module */
1223void linuxring_constructor(void);
1224/** Constructor for the PCAP format module */
1225void pcap_constructor(void);
1226/** Constructor for the PCAP File format module */
1227void pcapfile_constructor(void);
1228/** Constructor for the PCAP-NG File format module */
1229void pcapng_constructor(void);
1230/** Constructor for the RT format module */
1231void rt_constructor(void);
1232/** Constructor for the DUCK format module */
1233void duck_constructor(void);
1234/** Constructor for the ATM Header format module */
1235void atmhdr_constructor(void);
1236/** Constructor for the network DAG format module */
1237void ndag_constructor(void);
1238#ifdef HAVE_BPF
1239/** Constructor for the BPF format module */
1240void bpf_constructor(void);
1241#endif
1242#if HAVE_DPDK
1243/** Constructor for Intels DPDK format module */
1244void dpdk_constructor(void);
1245
1246/** Constructor for receiving network DAG via Intels DPDK format module */
1247void dpdkndag_constructor(void);
1248
1249#endif
1250
1251/** Extracts the RadioTap flags from a wireless link header
1252 *
1253 * @param link          A pointer to the wireless link header
1254 * @param linktype      The link type of the wireless header
1255 * @param[out] flags    Space to store the extracted flags
1256 * @return True if libtrace was able to extract flags from the link header,
1257 * false otherwise.
1258 *
1259 * This function has been left internal because it is not portable across
1260 * drivers.
1261 */
1262bool trace_get_wireless_flags(void *link, libtrace_linktype_t linktype, uint8_t *flags);
1263#define TRACE_RADIOTAP_F_FCS 0x10
1264       
1265#ifdef __cplusplus
1266}
1267#endif
1268
1269#endif /* LIBTRACE_INT_H */
Note: See TracBrowser for help on using the repository browser.