FreeCalypso > hg > gsm-codec-lib

annotate doc/Calypso-TCH-downlink @ 178:5fe0b3eb35c1

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