source: lib/libtrace_int.h @ 526d9d0

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

Move the accepted packet count to dispatching packets for threads.
Accounting for the doubled count when using a single threaded format.

Rework statistics logic slightly to remove duplicated code.

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