source: lib/libtrace_int.h @ 5e3f16c

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivendag_formatrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 5e3f16c was 5e3f16c, checked in by Richard Sanger <rsanger@…>, 4 years ago

Fix for issue #39 - ring and int pstop() fails on older kernels when using threads

The problem here is that on old kernels without PACKET_FANOUT support
(added in v3.1) will only include the single threaded versions of int
and ring. When used with multiple threads the libtrace API will
fallback to using read rather than pread which does not check message
queues.

To fix this issue, in any format without pread support:

  • We check for new messages with each loop around read_packet as we fill the burst
  • Within read_packet we update the halt to include the pausing state
  • Use a seperate lock to the main lock when reading a burst of packets, otherwise trace_ppause has to wait for a burst to read.

This is not 100% perfect as a single packet might still need to be received
before a generic message can be received.
A proper fix in the future would be to move all format internals purely to the
parallel API.

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