source: lib/libtrace_int.h @ 10c47a0

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

Fixes DAG DUCK reporting for parallel libtrace.
In parallel libtrace DUCK is only ever sent to the first thread.

It is now up each formats pread_packet to tag the trace along with
the error (AKA bytes read) to each packet.

Change logic in parallel libtrace to alwaus prefer pread over read if
it exists.

Fix some unresolved conflict in DPDK that I missed, that was ifdef'd out.

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