source: lib/libtrace_int.h @ be3f75b

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

Fixs statistic counters for parallel traces

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