source: lib/libtrace_int.h @ 37ee856

developringdecrementfixringperformance
Last change on this file since 37ee856 was 37ee856, checked in by Shane Alcock <salcock@…>, 2 years ago

Tag each packet with the start iteration of the parent trace.

Traces can be started, paused and then restarted. For some
formats (especially live ones), this will mean that buffers
containing received packets can be destroyed and recreated as
a result of that process. However, in our parallel world we might
also have lingering references to packets that lived in a
now-destroyed buffer and bad things will happen if we try to
operate on it.

To try and avoid this, we keep track of how many times a trace has
been "started" and each packet read is tagged with the start count
at the time it was read. Later processing functions can now check
if the packet was read before the most recent "start" -- if it was,
then it is potentially bogus and should be ignored.

This shouldn't change anything for the vast majority of libtrace
use-cases. Normally, pausing is only used prior to ending an
input without subsequent restarting, i.e. there is only one start
iteration.

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