Changeset 9de8150 for lib

Timestamp:

02/27/06 11:04:04 (16 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:

• dagformat.h (modified) (5 diffs)
• libtrace_int.h (modified) (2 diffs)

lib/dagformat.h

@@ -9 +9 @@
 #define TYPE_AAL5         4
 
-/* GPP Type 1 */
+/** GPP Type 1 */
 typedef struct pos_rec {
         uint32_t  hdlc;
-        uint8_t   pload[1];
+        uint8_t   pload[1];             /**< payload */
 }  pos_rec_t;
 
-/* GPP Type 2 */
+/** GPP Type 2 */
 typedef struct eth_rec {
         uint8_t   offset;
@@ -21 +21 @@
         uint8_t   dst[6];
         uint8_t   src[6];
-        uint16_t  etype;
-        uint8_t   pload[1];
+        uint16_t  etype;                /**< ether type (?) */
+        uint8_t   pload[1];             /**< payload */
 }  eth_rec_t;
 
-/* GPP Type 3 */
+/** GPP Type 3 */
 typedef struct atm_rec {
         uint32_t  header; 
-        uint8_t   pload[1];
+        uint8_t   pload[1];             /**< payload */
 }  atm_rec_t;
 
-/* GPP Type 4 */
+/** GPP Type 4 */
 typedef struct aal5_rec {
         uint32_t  header; 
-        uint8_t   pload[1];
+        uint8_t   pload[1];             /**< payload */
 }  aal5_rec_t;
 
+/** Flags */
 typedef struct flags {
         unsigned int   iface:2;
@@ -46 +47 @@
 } __attribute__((packed)) flags_t;
 
-/* GPP Global type */
+/** GPP Global type */
 typedef struct dag_record {
-        uint64_t  ts;
-        uint8_t   type;
-        flags_t   flags;
-        uint16_t  rlen;
-        uint16_t  lctr;
-        uint16_t  wlen;
+        uint64_t  ts;           /**< erf timestamp */
+        uint8_t   type;         /**< GPP record type */
+        flags_t   flags;        /**< flags */
+        uint16_t  rlen;         /**< record len (capture+framing) */
+        uint16_t  lctr;         /**< loss counter */
+        uint16_t  wlen;         /**< wire length */
         union {
-                pos_rec_t       pos;
+                pos_rec_t       pos;    
                 eth_rec_t       eth;
                 atm_rec_t       atm;
@@ -62 +63 @@
 } __attribute__((packed)) dag_record_t;
 
+/** Dynamic(?) Universal Clock Kit Information packet */
 typedef struct duck_inf_pkt {
         uint32_t  command;
@@ -85 +87 @@
 } duck_inf;
 
+/** sizeof(dag_record_t) without the payload helpers */
 #define dag_record_size         16
 

lib/libtrace_int.h

@@ -28 +28 @@
  *
  */
+/** @file */
 
 #ifndef LIBTRACE_INT_H
@@ -150 +151 @@
 };
 
+/** Module definition structure */
 struct libtrace_format_t {
+        /** the uri name of this module */
         char *name;
+        /** the version of this module */
         char *version;
+        /** the RT protocol type of this module */
         enum base_format_t type;
+        /** stuff that deals with input @{ */
+        /** initialise an trace (or NULL if input is not supported) */
         int (*init_input)(libtrace_t *libtrace);
+        /** configure an trace (or NULL if input is not supported) */
         int (*config_input)(libtrace_t *libtrace,trace_option_t option,void *value);
+        /** start/unpause an trace (or NULL if input not supported) */
         int (*start_input)(libtrace_t *libtrace);
+        /** pause an trace (or NULL if input not supported) */
         int (*pause_input)(libtrace_t *libtrace);
+        /** @} */
+        /** stuff that deals with output @{ */
+        /** initialise output traces (or NULL if output not supported) */
         int (*init_output)(libtrace_out_t *libtrace);
+        /** configure output traces (or NULL if output not supported) */
         int (*config_output)(libtrace_out_t *libtrace, trace_option_output_t, void *);
+        /** start output traces (or NULL if output not supported) 
+         * There is no pause for output traces, as packets are not arriving
+         * asyncronously
+         */
         int (*start_output)(libtrace_out_t *libtrace);
+        /** @} */
+        /** finish an input trace, cleanup (or NULL if input not supported) */
         int (*fin_input)(libtrace_t *libtrace);
+        /** finish an output trace, cleanup (or NULL if output not supported) */
         int (*fin_output)(libtrace_out_t *libtrace);
+        /** read a packet from a trace into the provided packet structure 
+         * @returns -1 on error, or get_framing_length()+get_capture_length() \
+         * on success.
+         * if this function is not supported, this field may be NULL.
+         */
         int (*read_packet)(libtrace_t *libtrace, struct libtrace_packet_t *packet);
+        /** write a packet to a trace from the provided packet 
+         * (or NULL if output not supported)
+         */
         int (*write_packet)(libtrace_out_t *libtrace, const libtrace_packet_t *packet);
+        /** return the libtrace link type for this packet 
+         * @return the libtrace link type, or -1 if this link type is unknown
+         */ 
         libtrace_linktype_t (*get_link_type)(const libtrace_packet_t *packet);
+        /** return the direction of this packet 
+         * This function pointer may be NULL if the format does not support
+         * getting a direction.
+         */ 
         int8_t (*get_direction)(const libtrace_packet_t *packet);
+        /** set the direction of this packet 
+         * This function pointer may be NULL if the format does not support
+         * setting a direction.
+         */ 
         int8_t (*set_direction)(const libtrace_packet_t *packet, int8_t direction);
+        /** return the erf timestamp of the packet.
+         * @return the 64bit erf timestamp
+         * This field may be NULL in the structure, and libtrace will
+         * synthesise the result from get_timeval or get_seconds if they
+         * exist.  AT least one of get_erf_timestamp, get_timeval or
+         * get_seconds must be implemented.
+         */
         uint64_t (*get_erf_timestamp)(const libtrace_packet_t *packet);
+        /** return the timeval of this packet.
+         * @return the timeval
+         * This field may be NULL in the structure, and libtrace will
+         * synthesise the result from get_erf_timestamp or get_seconds if they
+         * exist.  AT least one of get_erf_timestamp, get_timeval or
+         * get_seconds must be implemented.
+         */
         struct timeval (*get_timeval)(const libtrace_packet_t *packet);
+        /** return the timestamp of this packet.
+         * @return the floating point seconds since 1970-01-01 00:00:00
+         * This field may be NULL in the structure, and libtrace will
+         * synthesise the result from get_timeval or get_erf_timestamp if they
+         * exist.  AT least one of get_erf_timestamp, get_timeval or
+         * get_seconds must be implemented.
+         */
         double (*get_seconds)(const libtrace_packet_t *packet);
+        /** move the pointer within the trace.
+         * @return 0 on success, -1 on failure.
+         * The next packet returned by read_packet be the first
+         * packet in the trace to have a timestamp equal or greater than
+         * timestamp.
+         * @note this function may be NULL if the format does not support
+         * this feature.  If the format implements seek_timeval and/or 
+         * seek_seconds then libtrace will call those functions instead.
+         */
         int (*seek_erf)(libtrace_t *trace, uint64_t timestamp);
+        /** move the pointer within the trace.
+         * @return 0 on success, -1 on failure.
+         * The next packet returned by read_packet be the first
+         * packet in the trace to have a timestamp equal or greater than
+         * timestamp.
+         * @note this function may be NULL if the format does not support
+         * this feature.  If the format implements seek_erf and/or 
+         * seek_seconds then libtrace will call those functions instead.
+         */
         int (*seek_timeval)(libtrace_t *trace, struct timeval tv);
+        /** move the pointer within the trace.
+         * @return 0 on success, -1 on failure.
+         * The next packet returned by read_packet be the first
+         * packet in the trace to have a timestamp equal or greater than
+         * tv.
+         * @note this function may be NULL if the format does not support
+         * this feature.  If the format implements seek_erf and/or 
+         * seek_timeval then libtrace will call those functions instead.
+         */
         int (*seek_seconds)(libtrace_t *trace, double seconds);
+        /** return the captured payload length 
+         * @return the amount of data captured in a trace.
+         * This is the number of bytes actually in the trace.  This does not
+         * include the trace framing length.  This is usually shorter or
+         * equal to the wire length.
+         */
         int (*get_capture_length)(const libtrace_packet_t *packet);
+        /** return the original length of the packet on the wire.
+         * @return the length of the packet on the wire before truncation.
+         * This is the number of bytes actually in the trace.  This does not
+         * include the trace framing length.  This is usually shorter or
+         * equal to the wire length.
+         */
         int (*get_wire_length)(const libtrace_packet_t *packet);
+        /** return the length of the trace framing header
+         * @return the length of the framing header
+         * The framing header is the extra metadata a trace stores about
+         * a packet.  This does not include the wire or capture length
+         * of the packet.  Usually get_framing_length()+get_capture_length()
+         * is the size returned by read_packet
+         */
         int (*get_framing_length)(const libtrace_packet_t *packet);
+        /** truncate (snap) the packet 
+         * @returns the new size
+         * @note This callback may be NULL if not supported.
+         */
         size_t (*set_capture_length)(struct libtrace_packet_t *packet,size_t size);
+        /** return the filedescriptor associated with this interface.
+         * @note This callback may be NULL if not supported.
+         * This function is only needed if you use trace_event_interface
+         * as the pointer for trace_event
+         */
         int (*get_fd)(const libtrace_t *trace);
+        /** return the next event from this source 
+         * @note may be NULL if not supported.
+         */
         struct libtrace_eventobj_t (*trace_event)(libtrace_t *trace, libtrace_packet_t *packet);        
+        /** return information about this trace format to standard out */
         void (*help)();
 };