--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/TRAU-UL-testing	Sun Jun 23 23:21:45 2024 +0000
@@ -0,0 +1,104 @@
+In order to conduct behavioral reverse eng of the historical TRAU we have in
+our lab (Nokia TCSM2), we will need to feed TRAU-UL frames to its Ater interface
+(first GSM 08.60 FR and EFR, then later GSM 08.61 HR), exercising various
+combinations of speech parameters and out-of-band control bits.  In order to
+conduct these exercises, we need some test file formats of our own invention:
+
+* The source format for human editing is ASCII-based, friendly toward arbitrary
+  manipulation of speech parameters and flags.  We call this ad hoc ASCII source
+  format *.tsrc, for TRAU-UL source.
+
+* trau-ul-compile program in the present code repository will compile these
+  *.tsrc source files into *.tul (TRAU-UL) binary format;
+
+* The Ater test program in ice1-trau-tester repository will read binary frames
+  from our ad hoc *.tul file format and turn them into actual TRAU-UL bits
+  going to E1.
+
+*.tul binary format
+===================
+
+Each frame (FR or EFR) is stored as a fixed record of 34 bytes.  The format for
+FR is:
+
+* 33 bytes of standard RTP format representing 260 bits of payload;
+* 1 byte of BFI+SID flags.
+
+The format for EFR is:
+
+* 31 bytes of standard RTP format representing 244 bits of payload;
+* 1 byte controlling CRC inversion;
+* 1 byte spare;
+* 1 byte of BFI+SID flags.
+
+Because each *.tul record begins with an FR or EFR frame in standard RTP
+encoding, and the latter includes a signature (0xD or 0xC) in the upper nibble
+of the first byte, each *.tul record can be trivially checked if it is for FR
+or EFR testing.
+
+Byte of BFI+SID flags
+---------------------
+
+Bit 0x80 is BFI, bits 0x03 are SID, the rest are reserved.
+
+EFR CRC inversion control
+-------------------------
+
+We can generate EFR TRAU-UL frames with either correct or inverted CRC.
+Furthermore, GSM 08.60 frame format for EFR has 5 separate CRC fields covering
+different parts of the frame, and we can independently control the correct-or-
+inverted choice for each.
+
+The CRC manipulation byte included in *.tul frames for EFR has 5 used and 3
+reserved bits.  The 5 most significant bits correspond to the 5 CRC fields in
+GSM 08.60 frame format; control bit equal to 0 means send correct CRC, otherwise
+send inverted CRC.
+
+ASCII source format
+===================
+
+Example for FR:
+
+Frame_FR {
+	LARc 9 23 15 8 7 3 3 2
+	sf 40 0 0 0 4 4 4 4 4 4 4 4 4 4 4 4 4
+	sf 40 0 0 0 4 4 4 4 4 4 4 4 4 4 4 4 4
+	sf 40 0 0 0 4 4 4 4 4 4 4 4 4 4 4 4 4
+	sf 40 0 0 0 4 4 4 4 3 4 4 4 4 4 4 4 4
+}
+
+Example for EFR:
+
+Frame_EFR {
+	BFI 0
+	LPC 4 47 180 144 62
+	sf 342 11 0 1 15 1 13 0 3 0 3 0 3
+	sf 54 1 8 8 5 8 1 0 0 1 1 0 0
+	sf 342 0 0 0 0 0 0 0 0 0 0 0 0
+	sf 54 11 0 0 0 0 0 0 0 0 0 0 0
+	SID 0
+}
+
+Each frame to be encoded must be given as a block beginning with "Frame_FR {"
+or "Frame_EFR {" opening line and closing with "}".  The opening brace must be
+on the same line as the frame type keyword, and that line must have no other
+fields; the closing brace must be on its own line.  (The actual parser is line-
+based, despite the appearance of braces.)
+
+Each interior line shall consist of a keyword followed by numbers; the keyword
+indicates which part of the frame is being set.  LARc for FR or LPC for EFR sets
+the frame-global speech parameters (8 for FR and 5 for EFR); sf sets subframe
+parameters.  Every frame must have one LARc/LPC line and exactly 4 sf lines.
+
+BFI and SID settings are optional.  If BFI is not set, it defaults to 0; if SID
+is not set, it is computed from the speech parameters per standard bit counting
+rules of GSM 06.31 or 06.81 section 6.1.1.
+
+For EFR only, there will also be an optional crc-inv setting that sets the CRC
+manipulation byte, defaulting to 0 (correct CRC).
+
+Aside from the required line structure, white space (' ' and '\t') can appear
+anywhere and is ignored.  '#' character introduces a comment, continuing to the
+end of the line.
+
+All keywords are case-insensitive.