FreeCalypso > hg > freecalypso-tools

comparison doc/Audio-mode-config @ 245:796c659b747c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Audio-mode-config written
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 26 Aug 2017 04:50:25 +0000
parents
children b5b148ef63da
comparison
equal deleted inserted replaced
244:97d6d593ffc6 245:796c659b747c
1 There exist a number of tunable settings in the Iota ABB (the chip that performs
2 A-to-D and D-to-A conversion for the voice path) and in the Calypso DSP which
3 in TI's firmware architecture are meant to be configured through the audio mode
4 facility of the RiViera Audio Service. The ABB settings grouped under the audio
5 mode are as follows:
6
7 * The selection of which analog interface pins the downlink audio should be
8 sent to: EARN&EARP (earpiece), AUXON&AUXOP (auxiliary) or HSO (headset).
9
10 * The selection of which analog interface pins the uplink audio should be taken
11 from: MICIN&MICIP (main microphone), AUXI (auxiliary input) or HSMICP
12 (headset microphone).
13
14 * The selection of AUXI input levels when this analog input is in use for the
15 voice uplink.
16
17 * Analog gains for the uplink, the downlink and the analog sidetone from the
18 uplink input to the downlink output.
19
20 * Selection of a special filter bypass mode for the voice downlink.
21
22 * The selection of MICBIAS (or HSMICBIAS) voltage between 2.0 V and 2.5 V.
23
24 The DSP voice path settings grouped under the audio mode are as follows:
25
26 * The selection of the digital voice path as being between GSM and the ABB (the
27 default for analog voice interfaces), between GSM and MCSI (the external
28 digital voice interface) or between MCSI and the ABB (non-GSM operation).
29
30 * FIR filter coefficients for the voice uplink and for the voice downlink.
31
32 * Enabling/disabling and configuration of the Acoustic Echo Cancellation (AEC)
33 mechanism.
34
35 The firmware paradigm for working with all of the above settings is as follows:
36
37 * In a lab environment, each of the listed settings can be independently tweaked
38 and read back through ETM packets over the RVTMUX debug serial interface; the
39 corresponding fc-tmsh commands (matching TI's original Windows-based TMSH)
40 are auw for writing individual audio parameters and aur for reading them back.
41
42 * In end-use operation, TI's intent as realized in the firmware design is that
43 all of the listed audio settings will only be changed as a group, loaded from
44 audio mode configuration files in FFS.
45
46 Each audio mode configuration needs to be assigned a name between 1 and 9
47 characters long, and for each named configuration there are two files in FFS:
48
49 /aud/modename.cfg is the main configuration file
50 /aud/modename.vol is the corresponding volume setting file
51
52 This paradigm is a good fit for "dumbphone" handsets in which there usually
53 will be several different voice audio configurations for classic handheld
54 operation, for the hands-free loudspeaker mode, for operation with a wired
55 headset, and if the phone uses a loudspeaker (as opposed to a piezo buzzer) to
56 play ringtones and uses the Calypso DSP to generate those ringtone melodies,
57 there will also need to be an output-only audio configuration for ringing.
58
59 How do the audio mode config files under /aud come into being? It appears that
60 TI's original intent was that a configuration would be manually constructed on
61 a test device via TMSH auw commands, saved in the FFS of that test device with
62 the aus command, then read out of that test device FFS in binary form and
63 reuploaded as an opaque blob to all devices on the production line. One can do
64 the same procedure with our fc-tmsh and fc-fsio which fully replicate the
65 revelant functionality of TI's original TMSH (to the best of our knowledge),
66 but in FreeCalypso we have an alternate way which fits better with our UNIX
67 philosophy: we have created our own ASCII text format for representing all of
68 the content in TI's /aud/*.cfg binary files and tiaud-* utilities for compiling
69 TI's binary cfg files from our ASCII source format, disassembling a *.cfg file
70 read out of FFS into the same ASCII format, and creating the required *.vol
71 companion files, which are also binary.
72
73 A note about volume settings: the Iota ABB has two variable gain controls in
74 the voice downlink path: the main "volume" gain in rather coarse 6 dB steps
75 (the choices being 0 dB, -6 dB, -12 dB, -18 dB, -24 dB and mute) and a finer
76 "calibration" gain in 1 dB steps between -6 and +6 dB. It appears that TI's
77 intent was that only the coarse volume control in 6 dB steps is to be visible
78 to the user, with just 5 possible non-mute volume levels, and that the finer
79 gain control be set at the factory in the audio mode config files for each mode
80 as some form of calibration. Pirelli DP-L10 significantly deviates from this
81 model by providing 10 non-mute volume levels to the user with 2 dB or 3 dB steps
82 between them by changing both VOLCTL and VDLPG fields in the VBDCTRL register,
83 but at the present time we have no plans to make a similar drastic change in
84 FreeCalypso.
85
86 Another noteworthy feature of the audio mode system with respect to volume
87 control is that there is a separate *.vol file that stores the current volume
88 setting for each mode. In a "dumbphone" handset firmware built according to
89 TI's paradigm, the /aud/*.cfg files will be written once on the factory
90 production line and only read afterward, but whenever the user turns the volume
91 up or down in the UI, the *.vol file _corresponding to the current mode_ will
92 be updated by the running fw. Thus the fw would maintain a separate notion of
93 the current volume for ringing, for the earpiece speaker, for the hands-free
94 loudspeaker and for the wired headset, something which Pirelli's fw very
95 notoriously fails to do.
96
97 Default audio configuration
98 ===========================
99
100 The default audio config set in the Iota ABB registers and in the DSP when no
101 named audio mode config has been loaded with the audio_mode_load() API call
102 (accessible via AT@AUL or via fc-tmsh aul command) is as follows, in the syntax
103 which our tiaud-compile utility accepts as input and which our tiaud-decomp
104 utility emits as output:
105
106 voice-path 0
107 mic default {
108 gain 3
109 output-bias 0
110 fir 0 0x4000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
111 fir 8 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
112 fir 16 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
113 fir 24 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
114 }
115 speaker ear+aux {
116 gain 0
117 audio-filter 0
118 fir 0 0x4000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
119 fir 8 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
120 fir 16 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
121 fir 24 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
122 }
123 sidetone -5
124 aec 0 0 0 0 0
125
126 The meaning is as follows:
127
128 * voice-path is the DSP digital voice path setting, 0 means the standard
129 configuration with the voice channel going between GSM and the local analog
130 voice hardware attached to the ABB.
131
132 * The default microphone input is used for the voice uplink (MICIN&MICIP pins),
133 whereas the voice downlink is presented on both EARN&EARP and AUXON&AUXOP
134 pins, i.e., both "ear" and "aux" VDL amplifiers are enabled.
135
136 * The microphone gain is 3 dB, the fine gain adjustment in the voice downlink
137 path is 0 dB, and the sidetone gain is -5 dB.
138
139 * output-bias 0 under mic means that the MICBIAS voltage is set to 2.0 V.
140
141 * audio-filter 0 under speaker means that the VFBYP bit in the VBCTRL1 register
142 is NOT set, i.e., the normal configuration.
143
144 * DSP FIR filters do nothing, as coefficient 0 is set to unity and all other
145 coefficients are set to zero.
146
147 * The AEC mechanism in the DSP is disabled.
148
149 Creating your own audio mode configurations
150 ===========================================
151
152 The input to our tiaud-compile utility can contain every setting shown in the
153 default case above, or any desired subset thereof. For any settings not given
154 in the input, the defaults from the above will be used, except that
155 tiaud-compile's current default for the speaker mode is just ear rather than
156 ear+aux. (It is a default which you should NOT depend on; set it explicitly if
157 it matters!) A few notes:
158
159 * For all settings given as numbers, the number given in the ASCII input is the
160 number that goes into TI's binary structure, without any transformation, even
161 in those cases where the result is counter-intuitive, such as "audio-filter 0"
162 meaning that the filter is *enabled*.
163
164 * The 3 possible mode keywords for the mic mode are default, aux and headset,
165 corresponding to MICIN&MICIP, AUXI and HSMICP analog inputs, respectively.
166
167 * The 5 possible mode keywords for the speaker mode are ear, aux, headset,
168 buzzer and ear+aux. The buzzer speaker mode exists only on TI's Nausica ABB
169 predating Iota, i.e., it won't work on any of the Calypso+Iota+Rita devices
170 built or supported by FreeCalypso, but our tiaud-compile and tiaud-decomp
171 utilities support it because it is nominally supported by TI's RiViera Audio
172 Service and its binary data structure for audio mode configuration.
173
174 * When mic is set to aux, an additional mic setting called extra-gain becomes
175 available. If extra-gain is set to 0, the AUXI gain will be set to 28.2 dB,
176 if extra-gain is set to 0, the AUXI gain will be set to 4.6 dB; all other
177 values will be considered invalid by the firmware.
178
179 * Each of the two FIR filters in the DSP (one for uplink, one for downlink) has
180 a total of 31 coefficients, numbered 0 through 30, inclusive. In the ASCII
181 input to tiaud-compile you can put each coefficient on its own fir line, put
182 all 31 coefficients on the same line, or group them in any other way you like.
183 The grouping used in the tiaud-decomp output has been chosen for line length
184 reasons.
185
186 * The numbers given on fir and aec lines are 16-bit values that go directly into
187 the DSP; the former are FIR coefficients and the latter are bit masks. They
188 can be given as either decimal or hexadecimal with 0x prefix in the ASCII
189 input to tiaud-compile.