--- a/doc/TCH-special-feature	Wed Jun 01 01:24:15 2016 +0000
+++ b/doc/TCH-special-feature	Wed Jun 01 02:06:44 2016 +0000
@@ -79,7 +79,9 @@
 first 3 words (6 bytes) contains the DSP's own status information (not fully
 understood by us yet, but we let you see what the DSP tells us without redacting
 anything out), and the remaining 17 words (34 bytes) are supposed to contain
-the TCH bits received from the GSM network in the FR codec format.
+the TCH bits received from the GSM network in the FR codec format.  Each DSP
+API word is sent in the big-endian byte order, i.e., the most significant byte
+followed by the least significant byte.
 
 If you wish to send your own TCH uplink bits, replacing the output of the
 built-in vocoder with your own alternate uplink data, you will need to send
@@ -92,9 +94,10 @@
 0x02: closing flag
 
 Sending 260 bits requires only 33 bytes, but the DSP operates in terms of
-16-bit words, hence 17 of those words are used.  The upper byte of the last
-word is not expected to be used, but if you send 34 bytes rather than 33, you
-will have control over every bit going into the DSP API RAM in this case.
+16-bit words, hence 17 of those words are used.  The least significant byte of
+the last word (i.e., the very last byte with our big-endian transmission order)
+is not expected to be used, but if you send 34 bytes rather than 33, you will
+have control over every bit going into the DSP API RAM in this case.
 
 There is a queue inside the firmware in which these TCH uplink data blocks are
 stored; this queue is filled by the serial packet receiving handler and drained
@@ -109,13 +112,25 @@
 Testing
 =======
 
-The just-described mechanism has been tested to the following extent: I have
-sent TCH_CONFIG_REQ packets to the modem, requesting that TCH downlink
-forwarding be enabled or disabled, and observed that the flow of TCH_DLBITS_IND
-packets from the modem to the host starts and stops as expected.  I have not
-done any further work to verify the correctness of the FR codec payload bits
-within these packets.  However, the TCH uplink substitution mechanism has not
-been tested at all, as I do not have a source of FR codec bits for testing.
+The just-described mechanism has been tested as follows:
+
+1. I placed a call to WWV (+1-303-499-7111), and after verifying with my ear
+   that the downlink audio was good, I recorded the downlink TCH bits on that
+   call into a file with the tch record command in fc-shell.
+
+2. I placed a call to another phone (running over a live commercial GSM network)
+   and played the saved recording from WWV into the call uplink with the
+   tch play command in fc-shell.
+
+3. The audio heard on the other end of the call in the previous step: the
+   recording from WWV was definitely recognizable, but it didn't sound perfect,
+   i.e., it was rather garbled.
+
+Further debugging of this mechanism will require two things which I currently
+lack: (1) proper understanding of the workings of the GSM 06.10 FR codec and
+(2) a test GSM network (as in OpenBTS/OpenBSC/etc) that could be used instead
+of live commercial ones, so we could see exactly what the test MS is
+transmitting on the air and what the BTS transmits in the downlink.
 
 Host side reference implementation
 ==================================
@@ -124,3 +139,38 @@
 modems via the RVTMUX binary packet interface, we strongly recommend that you
 use our rvinterf and fc-shell Unix/Linux host utilities as your starting point.
 You can find their source code in the rvinterf subtree.
+
+The following test commands have been added to fc-shell for exercising the
+experimental TCH rerouting mechanism:
+
+tch record <filename>
+
+	Sends a TCH_CONFIG_REQ packet to the target, commanding the firmware to
+	start forwarding TCH downlink bits to the external host, and starts
+	recording the bits it receives in the named file.  The file is written
+	with the same ordering of GSM 06.10 bits as used by the popular libgsm
+	implementation of this codec, i.e., the bits received from the GSM
+	device (ultimately coming from TI's DSP) are reordered before being
+	written into the file.  It is only a reordering of bits with no change
+	in the information content.
+
+	I was hoping that the resulting files could be played with the SoX play
+	command under Slackware Linux, but all I got was garbled audio, and my
+	audio-fu is not good enough to figure out what is wrong.
+
+tch record stop
+
+	Stops TCH downlink recording and closes the file into which the bytes
+	were being written; until the file is thus closed, it may not be
+	actually written out to the file system.
+
+tch play <filename>
+
+	Plays GSM 06.10 FR speech frames from the named file in libgsm format
+	(same as written by the tch record command) into the call uplink.
+
+tch play stop
+
+	Terminates the TCH UL play-from-file operation.  This command is
+	normally not needed, as the play session will end automatically when
+	the end of file is reached.