source: lib/libtrace_int.h @ 3296252

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

Fixes pausing the trace in the edge case that some threads have already ended.
Tidy up the state system, for both threads and the the overall state.
General tidies to the code.

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