source: lib/libtrace_int.h @ 823d8e1

cachetimestampsdeveloprc-4.0.4ringdecrementfixringperformance
Last change on this file since 823d8e1 was 823d8e1, checked in by Alistair King <alistair@…>, 2 years ago

Replace AC_CHECK_FUNCS with AC_CHECK_DECLS

It seems that AC_CHECK_FUNCS does not correctly detect when these "functions" are implemented as macros. (I've seen this happening on macOS, and Ubuntu 16.04 with snprintf and strndup respectively.) Replacing AC_CHECK_FUNCS (and the similar AC_REPLACE_FUNCS) with AC_CHECK_DECLS seems to solve this problem, though I don't have access to any systems that do not have these functions to be sure that it correctly detects them as missing.

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