source: lib/libtrace_int.h @ 6b98325

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

Removes pconfig_input() and replaces trace_config() with trace_set_<option>

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