source: lib/libtrace_int.h @ 6a6e6a8

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

More documentation, including some renaming and modifications to behaviour

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