FreeCalypso > hg > gsm-codec-lib

comparison doc/Calypso-TCH-downlink @ 168:486e19acc66f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Calypso-TCH-downlink: document new utilities
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 25 Dec 2022 09:48:02 +0000
parents 8eb0e7a39409
children 62c0359ff2a8
comparison
equal deleted inserted replaced
167:80c93ef82a51 168:486e19acc66f
1 It has been discovered that the DSP ROM in the Calypso GSM baseband processor 1 It has been discovered that the implementation of standard signal processing
2 implements one nifty feature which is not used at all in standard phone or modem 2 chains for speech TCH downlink and uplink in the DSP ROM in the Calypso GSM
3 operation, but which can be used for all kinds of interesting hacks: the traffic 3 baseband processor allows these signal processing chains to be tapped at certain
4 channel (TCH) bits coming out of the GSM 05.03 channel decoder in the downlink 4 points, as detailed in the TCH-tap-modes article in our freecalypso-docs Hg
5 direction (to be fed to one of several speech decoders) can be read out of the 5 repository. There is a mechanism to capture the stream of received traffic
6 DSP's API RAM in real time, and in the uplink direction the user can feed her 6 frames on TCH DL, and there is another mechanism by which an externally supplied
7 own bits to the input of the GSM 05.03 channel encoder, effectively suppressing 7 stream can be "played" into TCH UL.
8 the output of the internal vocoder.
9 8
10 I (Mother Mychaela) previously played with this functionality back in 2016, and 9 I (Mother Mychaela) previously played with this functionality back in 2016, and
11 it's been mostly shelved since then. This functionality is now getting renewed 10 it's been mostly shelved since then. This functionality is now getting renewed
12 attention in late 2022: now that we have a proper set of codec libraries (the 11 attention in late 2022: now that we have a proper set of codec libraries (the
13 present package) and a proper understanding of Rx DTX handling requirements, we 12 present package) and a proper understanding of Rx DTX handling requirements, we
14 can take another shot at decoding TCH downlink captures taken from Calypso GSM 13 can take another shot at decoding TCH downlink captures taken from Calypso GSM
15 MS. 14 MS.
16 15
17 For reasons of project resource planning, the work to study Calypso DSP downlink 16 The overall functionality is described in the TCH-tap-modes article in
18 bits in EFR mode is currently postponed until after we build our long-overdue FC 17 freecalypso-docs; the mechanism for capturing TCH DL bits from Calypso DSP is
19 Venus board, but in the case of FR1 codec, we have a TCH downlink recording that 18 split between FreeCalypso GSM MS firmware (added to FC Tourmaline as of
20 was captured back in 2016, and by analyzing this recording, we can make the 19 2022-12-23) and the fc-shell utility in the FC host tools package - the updated
21 following observations: 20 version (required for use with current Tourmaline fw) will be released as part
21 of fc-host-tools-r18. There is also a set of utilities included in the present
22 GSM codec libraries & utilities package for parsing and decoding these Calypso
23 TCH DL captures; the present document describes these utilities.
22 24
23 * DSP status word 0 contains various flags; we already knew some of them, but 25 As explained in the TCH-tap-modes article in freecalypso-docs, the mechanism
24 now we got additional knowledge: 26 for capturing TCH DL is currently implemented for TCH/FS, TCH/HS and TCH/EFS,
27 corresponding to FR1, HR1 and EFR codecs. However, further parsing and decoding
28 support has only been implemented for FR1 and EFR codecs in the present package,
29 in the form of the following utilities:
25 30
26 bit 2 is BFI 31 gsmfr-dlcap-parse This program reads a TCH/FS DL capture file and parses
27 bits 4:3 give a 2-bit SID flag per GSM 06.31 section 6.1.1 32 it for human analysis. All input fields are passed
33 through to the output, but the program also computes
34 the ternary SID flag of GSM 06.31 section 6.1.1 from
35 the payload bits (for comparison against what the DSP
36 wrote in its status word 0) and prints all broken-down
37 parameter fields of each GSM 06.10 FR1 codec frame.
28 38
29 Unfortunately I couldn't find TAF anywhere - but oh well. 39 gsmfr-dlcap-gsmx This program reads a TCH/FS DL capture file and converts
40 it into an extended-libgsm (gsmx) file containing a mix
41 of FR1 codec frames and Themyscira BFI markers. The
42 latter BFI markers will be emitted in those frame
43 positions where FACCH was received instead of speech,
44 or where the DSP otherwise indicated BFI=1. The gsmx
45 output from this utility needs to be fed to gsmfr-decode
46 from the present package, so that our FR1 Rx DTX
47 preprocessor will take care of SIDs and BFIs, completing
48 the required GSM MS processing chain for TCH/FS DL.
30 49
31 * DSP status word 1 appears to be garbage, DSP status word 2 appears to be some 50 gsmefr-dlcap-parse This program reads a TCH/EFS DL capture file and parses
32 kind of error count - no new knowledge here. 51 it for human analysis. All input fields are passed
52 through to the output, but the program also computes
53 the ternary SID flag of GSM 06.81 section 6.1.1 from
54 the payload bits (for comparison against what the DSP
55 wrote in its status word 0) and prints all broken-down
56 parameter fields of each EFR codec frame. Finally, each
57 triplicated bit group of GSM 05.03 section 3.1.1.2 is
58 printed as an octal digit, to aid human analysis of how
59 the DSP writes these bits in its a_dd_0 buffer.
33 60
34 * By heeding the newly-understood BFI flag in DSP status word 0, we can do a 61 gsmefr-dlcap-gsmx This program reads a TCH/EFS DL capture file and
35 much cleaner decoding of TCH downlink capture than we did back in 2016. 62 converts it into a gsmx binary file, containing a mix
63 of EFR codec frames and Themyscira BFI markers. The
64 latter BFI markers will be emitted in those frame
65 positions where FACCH was received instead of speech,
66 or where the DSP otherwise indicated BFI=1. The gsmx
67 output from this utility needs to be fed to
68 gsmefr-decode (or gsmefr-decode-r) from the present
69 package.
36 70
37 The new gsmfr-cvt-dlcap utility in the present package replaces the old 71 gsmefr-dlcap-dec This program reads a TCH/EFS DL capture file and feeds
38 fc-tch2fr utility from FC host tools - the latter should now be considered a 72 it directly to the EFR reference decoder implemented in
39 bogon. The output from gsmfr-cvt-dlcap is in our gsmx format, containing 73 libgsmefr, without going through a gsmx intermediary.
40 Themyscira BFI markers in those frame positions where Calypso DSP indicated BFI 74
41 on TCH downlink, and it needs to be fed to gsmfr-decode from the present 75 Additional notes:
42 package; our FR1 Rx DTX preprocessor will take care of SIDs and BFIs, and the 76
43 complete decoding chain should then closely replicate what must be happening 77 * The new gsmfr-dlcap-gsmx utility described above replaces the old fc-tch2fr
44 inside the original DSP. 78 utility from FC host tools - the latter should now be considered a bogon.
79 The required GSM MS processing chain for TCH/FS DL includes the step of Rx
80 DTX handler between the output of GSM 05.03 channel decoder and the input of
81 GSM 06.10 speech decoder; the old chain of fc-tch2fr followed by libgsm
82 decoding omitted this critical step and thus produced very unkind-on-ears
83 sounds.
84
85 * gsmefr-dlcap-dec has been written as a bold attempt to replicate the complete
86 Rx DTX handler and speech decoder (the part of TCH DL processing chain that
87 sits past the a_dd_0 buffer) as they are implemented inside TI's DSP. Such a
88 feat won't be possible for FR1 codec (other than by a Herculean effort of full
89 static reversing of the DSP ROM) because there is no bit-exact definition of
90 FR1 Rx DTX functions in GSM specs, but for EFR there is a bit-exact reference
91 implementation from ETSI. *If* TI's DSP matches this bit-exact reference
92 (there are some aspects of Rx DTX handling where this bit-exact reference is
93 considered to be an example rather than normative, see GSM 06.61), then there
94 is a chance we could replicate TI's DSP chain externally - but only if we can
95 figure out exactly how the bits of a_dd_0[0] drive the logic of their Rx DTX
96 handler. The Mother's plan is to capture the DSP's decoded speech output from
97 MCSI on an FCDEV3B using a small FPGA board with a PCM-to-UART logic function,
98 while simultaneously capturing TCH DL bits in the a_dd_0 buffer, then run
99 gsmefr-dlcap-dec on the captured TCH DL booty and see if we can replicate the
100 DSP's end output - but until then, this gsmefr-dlcap-dec program should be
101 treated as an unfinished experiment in progress.
102
103 * In the case of FR1 codec, there is no prescribed bit-exact definition for the
104 Rx DTX handler (GSM 06.11, 06.12 and 06.31 specs define general requirements,
105 but aren't bit-exact in most aspects), and the way in which we (Themyscira
106 Wireless) have implemented our FR1 Rx DTX handler (libgsmfrp in the present
107 package) perfectly matches our gsmx binary file format for good vs bad frames.
108 Therefore, in the case of FR1 codec there is nothing to be gained by skipping
109 gsmx and calling library functions directly, and thus there is no FR1
110 counterpart to gsmefr-dlcap-dec - just use gsmfr-dlcap-gsmx followed by
111 gsmfr-decode or gsmfr-decode-r.