source: lib/libtrace_int.h @ d391ce0

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

Updated format_rt to use new bucket structure

This should save us from having to memcpy every packet from the read
buffer into the packet buffer.

Added an internalid and srcbucket reference to the libtrace_packet_t
structure, so that trace_fin_packet() can release packets from any buckets
that they are owned by.

Fix race condition on trace->last_packet.

  • Property mode set to 100644
File size: 43.1 KB
Line 
1/*
2 * This file is part of libtrace
3 *
4 * Copyright (c) 2007,2008,2009,2010 The University of Waikato, Hamilton,
5 * New Zealand.
6 *
7 * Authors: Daniel Lawson
8 *          Perry Lorier
9 *          Shane Alcock
10 *         
11 * All rights reserved.
12 *
13 * This code has been developed by the University of Waikato WAND
14 * research group. For further information please see http://www.wand.net.nz/
15 *
16 * libtrace is free software; you can redistribute it and/or modify
17 * it under the terms of the GNU General Public License as published by
18 * the Free Software Foundation; either version 2 of the License, or
19 * (at your option) any later version.
20 *
21 * libtrace is distributed in the hope that it will be useful,
22 * but WITHOUT ANY WARRANTY; without even the implied warranty of
23 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
24 * GNU General Public License for more details.
25 *
26 * You should have received a copy of the GNU General Public License
27 * along with libtrace; if not, write to the Free Software
28 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
29 *
30 * $Id$
31 *
32 */
33
34/** @file
35 *
36 * @brief Header file containing definitions for structures and functions that
37 * are internal
38 *
39 * @author Daniel Lawson
40 * @author Perry Lorier
41 * @author Shane Alcock
42 *
43 * @version $Id$
44 *
45 * All of the structures and functions defined in this header file are intended
46 * for internal use within Libtrace only. They should not be exported as part
47 * of the library API as we don't want users accessing things like the
48 * contents of the libtrace packet structure directly!
49 */
50#ifndef LIBTRACE_INT_H
51#define LIBTRACE_INT_H
52
53#ifdef __cplusplus
54extern "C" {
55#endif
56
57#include "config.h"
58#include "common.h"
59#include "libtrace_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.