source: lib/libtrace_int.h @ 756b8f9

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivelibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 756b8f9 was d8b05b7, checked in by Shane Alcock <salcock@…>, 6 years ago

Make sure our copyright covers recent years

Consistency across all of our source files is also nice.

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