Add some information based on a Tektronix manual whose name popped up in

an email I found when looking for some other stuff and which I then
found with a Google search.

svn path=/trunk/; revision=35898

diff --git a/wiretap/k12.c b/wiretap/k12.c
index 0b029de9d1f5c986d840c608c8188a8ecaf3bf54..7163b0f997177720b3e6be8cd1edb9300eb8f3e7 100644 (file)
--- a/wiretap/k12.c
+++ b/wiretap/k12.c
@@ -40,6 +40,20 @@
 
 #include <wsutil/str_util.h>
 
+/*
+ * See
+ *
+ *  http://www2.tek.com/cmswpt/madownload.lotr?ct=MA&cs=mpm&ci=11284&lc=EN
+ *
+ * for some information about the file format.  You may have to fill in
+ * a form to download the document ("Recored File API Programmer Manual").
+ *
+ * Unfortunately, it describes an API that delivers records from an rf5
+ * file, not the raw format of an rf5 file, so, while it gives the formats
+ * of the records with various types, it does not indicate how those records
+ * are stored in the file.
+ */
+
 /* #define DEBUG_K12 */
 #ifdef DEBUG_K12
 #include <stdio.h>
@@ -147,6 +161,37 @@ typedef struct _k12_src_desc_t {
 } k12_src_desc_t;
 
 
+/*
+ * According to the Tektronix documentation, this value is a combination of
+ * a "group" code and a "type" code, with both being 2-byte values and
+ * with the "group" code followe by the "type" code.  The "group" values
+ * are:
+ *
+ *     0x0001 - "data event"
+ *     0x0002 - "text or L1 event"
+ *     0x0007 - "configuration event"
+ *
+ * and the "type" values are:
+ *
+ *  data events:
+ *     0x0020 - "frame" (i.e., "an actual packet")
+ *     0x0021 - "transparent frame"
+ *     0x0022 - "bit data (TRAU frame)"
+ *     0x0024 - "used to mark the frame which is a fragment"
+ *     0x0026 - "used to mark the frame which is a fragment"
+ *     0x0028 - "used to mark the frame which is generated by the LSA"
+ *     0x002A - "used to mark the frame which is generated by the LSA"
+ *
+ *  text or L1 events:
+ *     0x0030 - "text event"
+ *     0x0031 - "L1 event"
+ *     0x0032 - "L1 event (BAI)"
+ *     0x0033 - "L1 event (VX)"
+ *
+ *  configuration events:
+ *     0x0040 - Logical Data Source configuration event
+ *     0x0041 - Logical Link configuration event
+ */
 /* so far we've seen these types of records */
 #define K12_REC_PACKET        0x00010020 /* an actual packet */
 #define K12_REC_SRCDSC        0x00070041 /* port-stack mapping + more, the key of the whole thing */
@@ -157,7 +202,14 @@ typedef struct _k12_src_desc_t {
 #define K12_REC_START         0x00020030 /* a string containing human readable start time  */
 #define K12_REC_STOP          0x00020031 /* a string containing human readable stop time */
 
-#define K12_MASK_PACKET       0xfffffff0  /* the last nibble in packet records somentimes change (not yet understood why) */
+/*
+ * According to the Tektronix documentation, packets, i.e. "data events",
+ * have several different group/type values, which differ in the last
+ * nibble of the type code.  For now, we just mask that nibble off; the
+ * format of the items are different, so we might have to treat different
+ * data event types differently.
+ */
+#define K12_MASK_PACKET       0xfffffff0
 
 /* offsets of elements in the records */
 #define K12_RECORD_LEN         0x0 /* uint32, in bytes */
@@ -739,7 +791,10 @@ int k12_open(wtap *wth, int *err, gchar **err_info) {
 
             /* XXX - this is assumed, in a number of places (not just in the
                ascii_strdown_inplace() call below) to be null-terminated;
-               is that guaranteed (even with a corrupt file)? */
+               is that guaranteed (even with a corrupt file)?
+              Obviously not, as a corrupt file could contain anything
+              here; the Tektronix document says the strings "must end
+              with \0", but a bad file could fail to add the \0. */
             rec->input_name = g_memdup(read_buffer + K12_SRCDESC_EXTRATYPE + extra_len, name_len);
             rec->stack_file = g_memdup(read_buffer + K12_SRCDESC_EXTRATYPE + extra_len + name_len, stack_len);