source: lib/libtrace_int.h @ df87f00

cachetimestampsdevelopetsiliverc-4.0.4ringdecrementfixringperformance
Last change on this file since df87f00 was df87f00, checked in by Shane Alcock <salcock@…>, 3 years ago

First bits of code for an ETSI live format

Will probably remove the dependencies on the ASN.1 stuff
soon, but chucking it all in for now just so everything will
compile nicely.

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