source: lib/libtrace_int.h @ 5732e9b

cachetimestampsdevelopdpdk-ndagetsilivendag_formatrc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformance
Last change on this file since 5732e9b was ed5b2ce, checked in by Shane Alcock <salcock@…>, 4 years ago

Add support for reading pcapng traces

Also added special macro: IS_LIBTRACE_META_PACKET()
This macro can be used to easily recognise if a "packet" is a
genuine packet record or a meta record (such as a pcapng interface
block or an RT control message).

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