source: lib/libtrace_int.h @ 2fa43fa

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

Fixes an issue with old programs reusing a packet over multi traces

Fixes a bug that Shane found. In the case an old libtrace program used
a single packet and cycled over multiple traces. Closing the trace
and then reusing the packet with a new trace will try to finish
the packet which requires the old format to be present.

As such we now keep track of the last packet against the format,
and finish this when the trace is destroyed.

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