source: lib/libtrace_int.h @ a49a9eb

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

Add an object cache with thread local caches
All packets used by a trace are put through this.
Adds bulk read/write operations to the ringbuffer (used by the object cache)
Replace semaphores with condition variables to support these bulk operations.
Internally use bulk read operations from a single threaded formats to reduce lock overhead.
Replaces the asserts around pthread_* functions with a version that will still run the command if NDEBUG

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