Changeset 2e223eca for lib

Timestamp:

02/24/06 14:31:30 (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:

0d768c8

Parents:

c6a6c3a

Message:

Documentation, and cleanup use of 64bit constants

Location:

lib

Files:

• libtrace.h (modified) (6 diffs)
• libtrace_int.h (modified) (2 diffs)
• trace.c (modified) (3 diffs)

lib/libtrace.h

@@ -86 +86 @@
 typedef struct libtrace_filter_t libtrace_filter_t;
 
-/* the letters p and e are magic numbers used to detect if the packet
+/** if a packet has memory allocated
+ * If the packet has allocated it's own memory it's buffer_control should
+ * be TRACE_CTRL_PACKET, when the packet is destroyed it's memory will be
+ * free()'d.  If it's doing zerocopy out of memory owned by something else
+ * it should be TRACE_CTRL_EXTERNAL.
+ * @note the letters p and e are magic numbers used to detect if the packet
  * wasn't created properly
  */
-typedef enum {TRACE_CTRL_PACKET='p', TRACE_CTRL_EXTERNAL='e' } buf_control_t;
+typedef enum {
+        TRACE_CTRL_PACKET='p',
+        TRACE_CTRL_EXTERNAL='e' 
+} buf_control_t;
 /** Structure holding information about a packet */
 #define LIBTRACE_PACKET_BUFSIZE 65536
@@ -247 +255 @@
 typedef struct libtrace_ether
 {
-  u_int8_t ether_dhost[6];      /* destination ether addr */
-  u_int8_t ether_shost[6];      /* source ether addr */
-  u_int16_t ether_type;         /* packet type ID field (next-header) */
+  u_int8_t ether_dhost[6];      /**< destination ether addr */
+  u_int8_t ether_shost[6];      /**< source ether addr */
+  u_int16_t ether_type;         /**< packet type ID field (next-header) */
 } __attribute__ ((packed)) libtrace_ether_t;
 
@@ -255 +263 @@
 typedef struct libtrace_8021q 
 {
-  u_int8_t  ether_dhost[6];      /* destination eth addr */
-  u_int8_t  ether_shost[6];      /* source ether addr    */
-  u_int16_t ether_type;          /* packet type ID field , 0x8100 for VLAN */
-  unsigned int vlan_pri:3;       /* vlan user priority */
-  unsigned int vlan_cfi:1;       /* vlan format indicator, 0 for ethernet, 1 for token ring */
-  unsigned int vlan_id:12;       /* vlan id */
-  u_int16_t vlan_ether_type;     /* vlan sub-packet type ID field (next-header)*/
+  u_int8_t  ether_dhost[6];      /**< destination eth addr */
+  u_int8_t  ether_shost[6];      /**< source ether addr    */
+  u_int16_t ether_type;          /**< packet type ID field , 0x8100 for VLAN */
+  unsigned int vlan_pri:3;       /**< vlan user priority */
+  unsigned int vlan_cfi:1;       /**< vlan format indicator, 
+                                   * 0 for ethernet, 1 for token ring */
+  unsigned int vlan_id:12;       /**< vlan id */
+  u_int16_t vlan_ether_type;     /**< vlan sub-packet type ID field 
+                                   * (next-header)*/
 } __attribute__ ((packed)) libtrace_8021q_t;
 
@@ -326 +336 @@
  *  - wag:/path/to/wag/socket
  *
- *  If an error occured when attempting to open the trace file, NULL is returned
- *  and trace_errno is set. Use trace_perror() to get more information.  
- *  The trace is created in the configuration state, you must call trace_start
- *  to start the capture.
- */
-struct libtrace_t *trace_create(const char *uri);
+ *  If an error occured when attempting to open the trace file, an error
+ *  trace is returned and trace_get_error should be called to find out
+ *  if an error occured, and what that error was.  The trace is created in the
+ *  configuration state, you must call trace_start to start the capture.
+ */
+libtrace_t *trace_create(const char *uri);
 
 /** Creates a "dummy" trace file that has only the format type set.
@@ -337 +347 @@
  * @return opaque pointer to a (sparsely initialised) libtrace_t
  *
- * IMPORTANT: Do not attempt to call trace_read_packet or other such functions with
- * the dummy trace. Its intended purpose is to act as a packet->trace for libtrace_packet_t's
- * that are not associated with a libtrace_t structure.
- */
-struct libtrace_t *trace_create_dead(const char *uri);
+ * IMPORTANT: Do not attempt to call trace_read_packet or other such functions
+ * with the dummy trace. Its intended purpose is to act as a packet->trace for
+ * libtrace_packet_t's that are not associated with a libtrace_t structure.
+ */
+libtrace_t *trace_create_dead(const char *uri);
 
 /** Creates a trace output file from a URI. 
@@ -927 +937 @@
 const char *trace_parse_uri(const char *uri, char **format);
 
-/* Base format type definitions */
+/** RT protocol base format identifiers
+ * This is used to say what kind of packet is being sent over the rt protocol
+ */ 
 enum base_format_t {
         TRACE_FORMAT_ERF          =1,

lib/libtrace_int.h

@@ -94 +94 @@
         struct libtrace_format_t *format; /**< format driver pointer */
         struct libtrace_format_data_t *format_data; /**<format data pointer */
-        bool started;
-        libtrace_err_t err;
-        struct libtrace_event_t event;
-        char *uridata;
-        struct tracefifo_t *fifo;   
+        bool started;                   /**< if this trace has started */
+        libtrace_err_t err;             /**< error information */
+        struct libtrace_event_t event;  /**< the next event */
+        char *uridata;                  /**< the uri of this trace */
+        struct tracefifo_t *fifo;       /**< fifo used in this trace */
         struct libtrace_filter_t *filter; /**< used by libtrace if the module
                                             * doesn't support filters natively
@@ -107 +107 @@
 };
 
+/** Information about output traces
+ * @internal
+ */
 struct libtrace_out_t {
-        struct libtrace_format_t *format;
-        struct libtrace_format_data_out_t *format_data;
+        struct libtrace_format_t *format;       /**< format driver */
+        struct libtrace_format_data_out_t *format_data; /**< format data */
         bool started;
-        libtrace_err_t err;
-        char *uridata;
-        struct tracefifo_t *fifo;
+        libtrace_err_t err;             /**< Associated error */
+        char *uridata;                  /**< URI associated with this trace */
 };
 

lib/trace.c

@@ -386 +386 @@
 
 
-        libtrace->fifo = create_tracefifo(1048576);
-        assert( libtrace->fifo);
         free(scan);
         libtrace->started=false;
@@ -511 +509 @@
         libtrace->format->fin_output(libtrace);
         free(libtrace->uridata);
-        destroy_tracefifo(libtrace->fifo);
         free(libtrace);
 }
@@ -1074 +1071 @@
 #error "What on earth are you running this on?"
 #endif
-                ts = (1000000 * (ts & 0xffffffffULL));
-                ts += (ts & 0x80000000ULL) << 1;
-                tv.tv_usec = ts >> 32;
+                tv.tv_usec = ((ts&0xFFFFFFFF)*1000000)>>32;
                 if (tv.tv_usec >= 1000000) {
                         tv.tv_usec -= 1000000;