source: lib/libtrace_int.h @ 6cf3ca0

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

Gets the ring format back to a working state, the bulk of the refactoring
is now done.

I've opted to remove the inheritance way of grabbing shared functions
and replaced it with a file containing the common functions. Hopefully
this is more obvious that both int and ring depend on these.

I've also reworked the formats to be stream orientated, which removed
duplicates of heaps of functions. And allows the parallel and single
thread code to be almost identical.

After doing this many of the places where we had differences in
functions between ring and int disappeared.

I've also upped the MAX_ORDER to 11, used in allocating memory
from the kernel for the ring format.
Since this seems to work on the testing machines.
And we'll continue to fallback to smaller values if needed anyway.

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