source: lib/libtrace_int.h @ 9594cf9

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivelibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 9594cf9 was 9594cf9, checked in by Richard Sanger <rsangerarj@…>, 7 years ago

Remove sliding window option, this was very complicated to ensure thread safety. For now its best left out.

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