source: lib/libtrace_int.h @ f051c1b

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

Tidies up the state messages received, now all states are passed through created->resumed->paused->stopped this might simplify some code. Removed the extra paused state.
Hooks up the reporter method through trace_pstart, hopefully resulting in simpler code most of the time. Also renames this from reducer to reporter anywhere it was not already. Adds a test for this also.
Removes is_packet from a result in favour of a more generic type, with packet being one of these.
Moves configuration for tuning relelated settings into a single structure.

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