# HG changeset patch # User Mychaela Falconia # Date 1458540357 0 # Node ID 759b3cbf46aaf3bed885347757fbd8ade307b91f # Parent a6ca9ee289f763401a2354a7106ce92ee056fa7e doc/TCH-special-feature: document written diff -r a6ca9ee289f7 -r 759b3cbf46aa doc/TCH-special-feature --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/TCH-special-feature Mon Mar 21 06:05:57 2016 +0000 @@ -0,0 +1,126 @@ +FreeCalypso GSM firmware implements an optional special feature (needs to be +explicitly enabled at compile time) which we call TCH rerouting. When this +feature is enabled, it applies the following special handling to GSM voice +traffic channels (TCH): + +* All downlink TCH bits passing from the channel decoder to the vocoder block + (260 bits every 20 ms) can be non-invasively intercepted and forwarded to + the external host connected to the RVTMUX serial interface; + +* Using the same serial interface, the external host can supply substitute + uplink TCH bits which will be transmitted in the place of the built-in + vocoder output, i.e., the latter can be effectively suppressed. + +In order to use this feature, you need to compile our firmware in the voice+SMS +pseudo-modem configuration, i.e., the configuration in which the fw expects to +be controlled via AT commands wrapped in the RVTMUX binary packet serial +interface. You can use a target GSM device that has just one accessible serial +port (Mot C1xx and Pirelli DP-L10) or one that has two Calypso UARTs (Openmoko +GTA02 or our future FCDEV3B), but in the latter case you will be using only one +UART - whichever one you have configured to be RVTMUX. + +Whatever system you are building that will act as the source and sink for TCH +bits will need to interface to the FreeCalypso GSM device via a serial port in +the RVTMUX binary packet format. Your system will need to send RVTMUX packets +with AT commands inside them in order to command the FC GSM device to register +with the network and to dial and/or answer calls, and you will need to send +RVTMUX packets of a different kind in order to supply the uplink TCH bits +during calls. In the other direction, your system will receive responses to +the AT commands you send, asynchronous notifications of incoming calls and SMS, +downlink TCH bits and various debug trace output from our FreeCalypso firmware. +The last part (debug trace output) can be simply ignored and discarded if you +wish, but we strongly recommend that you provide a way to view and/or log it +for debugging purposes. + +Please see the RVTMUX document for general background information regarding the +RVTMUX binary packet interface; this document should be considered required +reading for anyone interested in working with the TCH rerouting special feature. + +All packets transferred over the RVTMUX interface begin and end with 0x02. If +a payload byte within a packet equals 0x02 or 0x10, it needs to be prepended +with 0x10 as a transparency escape; all other payload bytes are sent literally. +The first byte within each RVTMUX packet after the opening 0x02 is the packet +type; the two packet types you will need to handle (both generate and receive) +are 0x1A for AT commands and 0x1C for TCH configuration commands. + +To send an AT command to the FreeCalypso GSM device, prepend the 0x1A packet +type in front of the "AT" characters, wrap the packet with 0x02 bytes on both +ends, and send it to the modem. Responses to AT commands and asynchronous +notification messages such as "RING" for incoming calls will be sent to the +host as RVTMUX packets also beginning with the 0x1A packet type; they will be +interspersed among other packet types, mostly debug trace output. Your system +will need to receive the RVTMUX serial byte stream continuously, parsing the +packet structure and looking at the type of each packet (the first byte after +the opening 0x02) in order to detect if the modem has sent something you may be +interested in. + +If you wish to receive a copy of all downlink TCH bits on the serial channel, +you will need to send the following 5-byte command packet to the modem: + +0x02: opening flag +0x1C: RVTMUX packet type for TCH +0x11: TCH_CONFIG_REQ command opcode +0x01: payload byte indicating that the "forward downlink" state should be + set to enabled +0x02: closing flag + +The modem will respond with a TCH_CONFIG_CONF confirmation message (opcode +0x12), and then during all voice calls your external host will receive the +following packet every 20 ms: + +0x02: opening flag +0x1C: RVTMUX packet type for TCH +0x15: TCH_DLBITS_IND opcode +- 40 (decimal) bytes of payload - +0x02: closing flag + +The 40 bytes of payload sent in every TCH_DLBITS_IND packet directly correspond +to the 20 16-bit words provided by the Calypso DSP in its a_dd_0 buffer. The +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. + +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 +your uplink TCH bits to the modem in packets of the following format: + +0x02: opening flag +0x1C: RVTMUX packet type for TCH +0x13: TCH_ULBITS_REQ opcode +- 33 or 34 (decimal) bytes of payload - +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. + +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 +by the L1S (synchronous) code that executes at the right times in the GSM TDMA +multiplex when uplink TCH transmission is expected. Up to 4 blocks can be +queued up; as each queued-up block is transmitted on the air (more precisely, +as it is passed to the DSP for channel encoding and transmission), a +TCH_ULBITS_CONF short packet (consisting of just the opcode and nothing more) +is sent to the host. These confirmation packets can be used to pace the sending +of further TCH_ULBITS_REQs. + +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. + +Host side reference implementation +================================== + +If you are going to implement your system for talking to FreeCalypso GSM pseudo- +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.