Changeset 9de8150


Ignore:
Timestamp:
02/27/06 11:04:04 (15 years ago)
Author:
Perry Lorier <perry@…>
Branches:
4.0.1-hotfixes, cachetimestamps, develop, dpdk-ndag, etsilive, getfragoff, help, libtrace4, master, ndag_format, pfring, rc-4.0.1, rc-4.0.2, rc-4.0.3, rc-4.0.4, ringdecrementfix, ringperformance, ringtimestampfixes
Children:
afd0b73
Parents:
0d768c8
Message:

A lot more documentation

Location:
lib
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • lib/dagformat.h

    r7068467 r9de8150  
    99#define TYPE_AAL5         4
    1010
    11 /* GPP Type 1 */
     11/** GPP Type 1 */
    1212typedef struct pos_rec {
    1313        uint32_t  hdlc;
    14         uint8_t   pload[1];
     14        uint8_t   pload[1];             /**< payload */
    1515}  pos_rec_t;
    1616
    17 /* GPP Type 2 */
     17/** GPP Type 2 */
    1818typedef struct eth_rec {
    1919        uint8_t   offset;
     
    2121        uint8_t   dst[6];
    2222        uint8_t   src[6];
    23         uint16_t  etype;
    24         uint8_t   pload[1];
     23        uint16_t  etype;                /**< ether type (?) */
     24        uint8_t   pload[1];             /**< payload */
    2525}  eth_rec_t;
    2626
    27 /* GPP Type 3 */
     27/** GPP Type 3 */
    2828typedef struct atm_rec {
    2929        uint32_t  header;
    30         uint8_t   pload[1];
     30        uint8_t   pload[1];             /**< payload */
    3131}  atm_rec_t;
    3232
    33 /* GPP Type 4 */
     33/** GPP Type 4 */
    3434typedef struct aal5_rec {
    3535        uint32_t  header;
    36         uint8_t   pload[1];
     36        uint8_t   pload[1];             /**< payload */
    3737}  aal5_rec_t;
    3838
     39/** Flags */
    3940typedef struct flags {
    4041        unsigned int   iface:2;
     
    4647} __attribute__((packed)) flags_t;
    4748
    48 /* GPP Global type */
     49/** GPP Global type */
    4950typedef struct dag_record {
    50         uint64_t  ts;
    51         uint8_t   type;
    52         flags_t   flags;
    53         uint16_t  rlen;
    54         uint16_t  lctr;
    55         uint16_t  wlen;
     51        uint64_t  ts;           /**< erf timestamp */
     52        uint8_t   type;         /**< GPP record type */
     53        flags_t   flags;        /**< flags */
     54        uint16_t  rlen;         /**< record len (capture+framing) */
     55        uint16_t  lctr;         /**< loss counter */
     56        uint16_t  wlen;         /**< wire length */
    5657        union {
    57                 pos_rec_t       pos;
     58                pos_rec_t       pos;   
    5859                eth_rec_t       eth;
    5960                atm_rec_t       atm;
     
    6263} __attribute__((packed)) dag_record_t;
    6364
     65/** Dynamic(?) Universal Clock Kit Information packet */
    6466typedef struct duck_inf_pkt {
    6567        uint32_t  command;
     
    8587} duck_inf;
    8688
     89/** sizeof(dag_record_t) without the payload helpers */
    8790#define dag_record_size         16
    8891
  • lib/libtrace_int.h

    r0d768c8 r9de8150  
    2828 *
    2929 */
     30/** @file */
    3031
    3132#ifndef LIBTRACE_INT_H
     
    150151};
    151152
     153/** Module definition structure */
    152154struct libtrace_format_t {
     155        /** the uri name of this module */
    153156        char *name;
     157        /** the version of this module */
    154158        char *version;
     159        /** the RT protocol type of this module */
    155160        enum base_format_t type;
     161        /** stuff that deals with input @{ */
     162        /** initialise an trace (or NULL if input is not supported) */
    156163        int (*init_input)(libtrace_t *libtrace);
     164        /** configure an trace (or NULL if input is not supported) */
    157165        int (*config_input)(libtrace_t *libtrace,trace_option_t option,void *value);
     166        /** start/unpause an trace (or NULL if input not supported) */
    158167        int (*start_input)(libtrace_t *libtrace);
     168        /** pause an trace (or NULL if input not supported) */
    159169        int (*pause_input)(libtrace_t *libtrace);
     170        /** @} */
     171        /** stuff that deals with output @{ */
     172        /** initialise output traces (or NULL if output not supported) */
    160173        int (*init_output)(libtrace_out_t *libtrace);
     174        /** configure output traces (or NULL if output not supported) */
    161175        int (*config_output)(libtrace_out_t *libtrace, trace_option_output_t, void *);
     176        /** start output traces (or NULL if output not supported)
     177         * There is no pause for output traces, as packets are not arriving
     178         * asyncronously
     179         */
    162180        int (*start_output)(libtrace_out_t *libtrace);
     181        /** @} */
     182        /** finish an input trace, cleanup (or NULL if input not supported) */
    163183        int (*fin_input)(libtrace_t *libtrace);
     184        /** finish an output trace, cleanup (or NULL if output not supported) */
    164185        int (*fin_output)(libtrace_out_t *libtrace);
     186        /** read a packet from a trace into the provided packet structure
     187         * @returns -1 on error, or get_framing_length()+get_capture_length() \
     188         * on success.
     189         * if this function is not supported, this field may be NULL.
     190         */
    165191        int (*read_packet)(libtrace_t *libtrace, struct libtrace_packet_t *packet);
     192        /** write a packet to a trace from the provided packet
     193         * (or NULL if output not supported)
     194         */
    166195        int (*write_packet)(libtrace_out_t *libtrace, const libtrace_packet_t *packet);
     196        /** return the libtrace link type for this packet
     197         * @return the libtrace link type, or -1 if this link type is unknown
     198         */
    167199        libtrace_linktype_t (*get_link_type)(const libtrace_packet_t *packet);
     200        /** return the direction of this packet
     201         * This function pointer may be NULL if the format does not support
     202         * getting a direction.
     203         */
    168204        int8_t (*get_direction)(const libtrace_packet_t *packet);
     205        /** set the direction of this packet
     206         * This function pointer may be NULL if the format does not support
     207         * setting a direction.
     208         */
    169209        int8_t (*set_direction)(const libtrace_packet_t *packet, int8_t direction);
     210        /** return the erf timestamp of the packet.
     211         * @return the 64bit erf timestamp
     212         * This field may be NULL in the structure, and libtrace will
     213         * synthesise the result from get_timeval or get_seconds if they
     214         * exist.  AT least one of get_erf_timestamp, get_timeval or
     215         * get_seconds must be implemented.
     216         */
    170217        uint64_t (*get_erf_timestamp)(const libtrace_packet_t *packet);
     218        /** return the timeval of this packet.
     219         * @return the timeval
     220         * This field may be NULL in the structure, and libtrace will
     221         * synthesise the result from get_erf_timestamp or get_seconds if they
     222         * exist.  AT least one of get_erf_timestamp, get_timeval or
     223         * get_seconds must be implemented.
     224         */
    171225        struct timeval (*get_timeval)(const libtrace_packet_t *packet);
     226        /** return the timestamp of this packet.
     227         * @return the floating point seconds since 1970-01-01 00:00:00
     228         * This field may be NULL in the structure, and libtrace will
     229         * synthesise the result from get_timeval or get_erf_timestamp if they
     230         * exist.  AT least one of get_erf_timestamp, get_timeval or
     231         * get_seconds must be implemented.
     232         */
    172233        double (*get_seconds)(const libtrace_packet_t *packet);
     234        /** move the pointer within the trace.
     235         * @return 0 on success, -1 on failure.
     236         * The next packet returned by read_packet be the first
     237         * packet in the trace to have a timestamp equal or greater than
     238         * timestamp.
     239         * @note this function may be NULL if the format does not support
     240         * this feature.  If the format implements seek_timeval and/or
     241         * seek_seconds then libtrace will call those functions instead.
     242         */
    173243        int (*seek_erf)(libtrace_t *trace, uint64_t timestamp);
     244        /** move the pointer within the trace.
     245         * @return 0 on success, -1 on failure.
     246         * The next packet returned by read_packet be the first
     247         * packet in the trace to have a timestamp equal or greater than
     248         * timestamp.
     249         * @note this function may be NULL if the format does not support
     250         * this feature.  If the format implements seek_erf and/or
     251         * seek_seconds then libtrace will call those functions instead.
     252         */
    174253        int (*seek_timeval)(libtrace_t *trace, struct timeval tv);
     254        /** move the pointer within the trace.
     255         * @return 0 on success, -1 on failure.
     256         * The next packet returned by read_packet be the first
     257         * packet in the trace to have a timestamp equal or greater than
     258         * tv.
     259         * @note this function may be NULL if the format does not support
     260         * this feature.  If the format implements seek_erf and/or
     261         * seek_timeval then libtrace will call those functions instead.
     262         */
    175263        int (*seek_seconds)(libtrace_t *trace, double seconds);
     264        /** return the captured payload length
     265         * @return the amount of data captured in a trace.
     266         * This is the number of bytes actually in the trace.  This does not
     267         * include the trace framing length.  This is usually shorter or
     268         * equal to the wire length.
     269         */
    176270        int (*get_capture_length)(const libtrace_packet_t *packet);
     271        /** return the original length of the packet on the wire.
     272         * @return the length of the packet on the wire before truncation.
     273         * This is the number of bytes actually in the trace.  This does not
     274         * include the trace framing length.  This is usually shorter or
     275         * equal to the wire length.
     276         */
    177277        int (*get_wire_length)(const libtrace_packet_t *packet);
     278        /** return the length of the trace framing header
     279         * @return the length of the framing header
     280         * The framing header is the extra metadata a trace stores about
     281         * a packet.  This does not include the wire or capture length
     282         * of the packet.  Usually get_framing_length()+get_capture_length()
     283         * is the size returned by read_packet
     284         */
    178285        int (*get_framing_length)(const libtrace_packet_t *packet);
     286        /** truncate (snap) the packet
     287         * @returns the new size
     288         * @note This callback may be NULL if not supported.
     289         */
    179290        size_t (*set_capture_length)(struct libtrace_packet_t *packet,size_t size);
     291        /** return the filedescriptor associated with this interface.
     292         * @note This callback may be NULL if not supported.
     293         * This function is only needed if you use trace_event_interface
     294         * as the pointer for trace_event
     295         */
    180296        int (*get_fd)(const libtrace_t *trace);
     297        /** return the next event from this source
     298         * @note may be NULL if not supported.
     299         */
    181300        struct libtrace_eventobj_t (*trace_event)(libtrace_t *trace, libtrace_packet_t *packet);       
     301        /** return information about this trace format to standard out */
    182302        void (*help)();
    183303};
Note: See TracChangeset for help on using the changeset viewer.