FreeCalypso > hg > freecalypso-tools
view doc/Audio-mode-config @ 840:25a182bc031b
rvinterf/include/audio.h: create interface definitions
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sat, 31 Jul 2021 07:33:58 +0000 |
parents | 02d92d49c9f8 |
children | 6a0fcbca8ac7 |
line wrap: on
line source
There exist a number of tunable settings in the Iota ABB (the chip that performs A-to-D and D-to-A conversion for the voice path) and in the Calypso DSP which in TI's firmware architecture are meant to be configured through the audio mode facility of the RiViera Audio Service. The ABB settings grouped under the audio mode are as follows: * The selection of which analog interface pins the downlink audio should be sent to: EARN&EARP (earpiece), AUXON&AUXOP (auxiliary) or HSO (headset). * The selection of which analog interface pins the uplink audio should be taken from: MICIN&MICIP (main microphone), AUXI (auxiliary input) or HSMICP (headset microphone). * The selection of AUXI input levels when this analog input is in use for the voice uplink. * Analog gains for the uplink, the downlink and the analog sidetone from the uplink input to the downlink output. * Selection of a special filter bypass mode for the voice downlink. * The selection of MICBIAS (or HSMICBIAS) voltage between 2.0 V and 2.5 V. The DSP voice path settings grouped under the audio mode are as follows: * The selection of the digital voice path as being between GSM and the ABB (the default for analog voice interfaces), between GSM and MCSI (the external digital voice interface) or between MCSI and the ABB (non-GSM operation). * FIR filter coefficients for the voice uplink and for the voice downlink. * Enabling/disabling and configuration of the Acoustic Echo Cancellation (AEC) mechanism. The firmware paradigm for working with all of the above settings is as follows: * In a lab environment, each of the listed settings can be independently tweaked and read back through ETM packets over the RVTMUX debug serial interface; the corresponding fc-tmsh commands (matching TI's original Windows-based TMSH) are auw for writing individual audio parameters and aur for reading them back. * In end-use operation, TI's intent as realized in the firmware design is that all of the listed audio settings will only be changed as a group, loaded from audio mode configuration files in FFS. Each audio mode configuration needs to be assigned a name between 1 and 9 characters long, and for each named configuration there are two files in FFS: /aud/modename.cfg is the main configuration file /aud/modename.vol is the corresponding volume setting file This paradigm is a good fit for "dumbphone" handsets in which there usually will be several different voice audio configurations for classic handheld operation, for the hands-free loudspeaker mode, for operation with a wired headset, and if the phone uses its hands-free loudspeaker plus the Calypso DSP to play ringtones (as opposed to using a buzzer on BU/PWT or a ringtone player chip that drives the speaker bypassing the voice path), there will also need to be an output-only audio configuration for ringing. How do the audio mode config files under /aud come into being? It appears that TI's original intent was that a configuration would be manually constructed on a test device via TMSH auw commands, saved in the FFS of that test device with the aus command, then read out of that test device FFS in binary form and reuploaded as an opaque blob to all devices on the production line. One can do the same procedure with our fc-tmsh and fc-fsio which fully replicate the relevant functionality of TI's original TMSH (to the best of our knowledge), but in FreeCalypso we have an alternate way which fits better with our UNIX philosophy: we have created our own ASCII text format for representing all of the content in TI's /aud/*.cfg binary files and tiaud-* utilities for compiling TI's binary cfg files from our ASCII source format, disassembling a *.cfg file read out of FFS into the same ASCII format, and creating the required *.vol companion files, which are also binary. A note about volume settings: the Iota ABB has two variable gain controls in the voice downlink path: the main "volume" gain in rather coarse 6 dB steps (the choices being 0 dB, -6 dB, -12 dB, -18 dB, -24 dB and mute) and a finer "calibration" gain in 1 dB steps between -6 and +6 dB. It appears that TI's intent was that only the coarse volume control in 6 dB steps is to be visible to the user, with just 5 possible non-mute volume levels, and that the finer gain control be set at the factory in the audio mode config files for each mode as some form of calibration. Pirelli DP-L10 significantly deviates from this model by providing 10 non-mute volume levels to the user with 2 dB or 3 dB steps between them by changing both VOLCTL and VDLPG fields in the VBDCTRL register, but at the present time we have no plans to make a similar drastic change in FreeCalypso. Another noteworthy feature of the audio mode system with respect to volume control is that there is a separate *.vol file that stores the current volume setting for each mode. In a "dumbphone" handset firmware built according to TI's paradigm, the /aud/*.cfg files will be written once on the factory production line and only read afterward, but whenever the user turns the volume up or down in the UI, the *.vol file _corresponding to the current mode_ will be updated by the running fw. Thus the fw would maintain a separate notion of the current volume for ringing, for the earpiece speaker, for the hands-free loudspeaker and for the wired headset, something which Pirelli's fw very notoriously fails to do. Old vs. new AEC =============== One of the settings in the audio mode config structure underwent an evolutionary change within the span of history that is relevant to FreeCalypso - this setting is the configuration for AEC, the Acoustic Echo Cancellation functional block of the Calypso DSP. As TI's GSM DSPs evolved (before, during and after the Calypso era), their AEC implementation evolved along with the rest, and different evolutionary versions of AEC require different configuration and tuning parameters. When the audio mode facility was first implemented, the AEC block in TI's GSM DSPs of that time was controlled with a single 16-bit control word; the people in the SSA group who implemented RiViera Audio Service then decided to split different bits from this one DSP control word into 5 different parameter words, and the result was the "old" 5-word AEC config. But the version of AEC implemented in the DSP ROM in the Calypso silicon version we work with is slightly newer; this version corresponds to what TI's L1 code calls L1_NEW_AEC. However, the waters then got muddied: for reasons which we (FreeCalypso team) cannot understand (perhaps miscommunication between different groups at TI), TI's TCS211 reference firmware shipped with L1_NEW_AEC disabled (C preprocessor symbol set to 0 instead of 1), even though the underlying DSP AEC block (combination of ROM and official patches) is the "new" kind and not the "old" one. There are two fallouts from this software misconfiguration on TI's part: 1) If one takes stock TCS211 from TI or any derivative version in which this aspect is unchanged (all mokoN firmwares, and all FC firmwares up to Magnetite) and tries to enable AEC, the result will be a poor AEC configuration: the old echo level and long vs short settings do nothing on the new DSP, whereas the new tunable parameters will remain at their defaults with no way to tweak them. I (Mother Mychaela) can only guess that this situation is what Openmoko must have run into when they tried to get AEC working. 2) When someone downstream of TI figures out that L1_NEW_AEC needs to be changed from 0 to 1 and actually makes that change, like we did in our Tourmaline fw, the format and size of the audio mode binary structure change, and all old audio mode config files become invalid. Our FreeCalypso work is affected by point 2 above: we started working with audio mode config files in 2017, using the old AEC configuration, and only made the switch to L1_NEW_AEC in 2021. We now have two kinds of audio mode config binary files: the old kind that are 164 bytes long, and the new kind that are 176 bytes long. Our Tourmaline firmware has L1_NEW_AEC enabled, while Magnetite (our legacy backward compatiblity fw) has it disabled. To prevent loading of garbage into AEC config when an audio mode file of the wrong kind is loaded, we have implemented the following workaround in both Tourmaline and Magnetite: if the loaded mode config file has the wrong length, the AEC config is set to the default disabled state instead of whatever is in the mode file - loading an AEC config of the wrong format is not possible. Default audio configuration =========================== The default audio config set in the Iota ABB registers and in the DSP when no named audio mode config has been loaded with the audio_mode_load() API call (accessible via AT@AUL or via fc-tmsh aul command) is as follows, in the syntax which our tiaud-compile utility accepts as input and which our tiaud-decomp utility emits as output: voice-path 0 mic default { gain 3 output-bias 0 fir 0 0x4000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 fir 8 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 fir 16 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 fir 24 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 } speaker ear+aux { gain 0 audio-filter 0 fir 0 0x4000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 fir 8 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 fir 16 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 fir 24 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 } sidetone -5 aec 0 0 0 0 0 The above version is the one produced by Magnetite and earlier firmwares without L1_NEW_AEC; in the new Tourmaline version the last line changes to: aec-new 0 0 0x1 0x7FFF 0x1FFF 0x4000 0x32 0x1000 0x1000 0 0 0 The meaning is as follows: * voice-path is the DSP digital voice path setting, 0 means the standard configuration with the voice channel going between GSM and the local analog voice hardware attached to the ABB. * The default microphone input is used for the voice uplink (MICIN&MICIP pins), whereas the voice downlink is presented on both EARN&EARP and AUXON&AUXOP pins, i.e., both "ear" and "aux" VDL amplifiers are enabled. * The microphone gain is 3 dB, the fine gain adjustment in the voice downlink path is 0 dB, and the sidetone gain is -5 dB. * output-bias 0 under mic means that the MICBIAS voltage is set to 2.0 V. * audio-filter 0 under speaker means that the VFBYP bit in the VBCTRL1 register is NOT set, i.e., the normal configuration. * DSP FIR filters do nothing, as coefficient 0 is set to unity and all other coefficients are set to zero. * The AEC mechanism in the DSP is disabled, although the format of the bits that say so is different between old and new AEC versions. In the new version there are a number of tunable settings that only kick in when AEC is enabled; when AEC is disabled by default, these tunable knobs still have sensible defaults that aren't all zeros. Creating your own audio mode configurations =========================================== The input to our tiaud-compile utility can contain every setting shown in the default case above, or any desired subset thereof. For any settings not given in the input, the defaults from the above will be used, except that tiaud-compile's current default for the speaker mode is just ear rather than ear+aux. (It is a default which you should NOT depend on; set it explicitly if it matters!) A few notes: * For all settings given as numbers, the number given in the ASCII input is the number that goes into TI's binary structure, without any transformation, even in those cases where the result is counter-intuitive, such as "audio-filter 0" meaning that the filter is *enabled*. * The 3 possible mode keywords for the mic mode are default, aux and headset, corresponding to MICIN&MICIP, AUXI and HSMICP analog inputs, respectively. * The 5 possible mode keywords for the speaker mode are ear, aux, headset, buzzer and ear+aux. The buzzer speaker mode exists only on TI's Nausica ABB predating Iota, i.e., it won't work on any of the Calypso+Iota+Rita devices built or supported by FreeCalypso, but our tiaud-compile and tiaud-decomp utilities support it because it is nominally supported by TI's RiViera Audio Service and its binary data structure for audio mode configuration. * When mic is set to aux, an additional mic setting called extra-gain becomes available. If extra-gain is set to 0, the AUXI gain will be set to 28.2 dB, if extra-gain is set to 1, the AUXI gain will be set to 4.6 dB; all other values will be considered invalid by the firmware. * Each of the two FIR filters in the DSP (one for uplink, one for downlink) has a total of 31 coefficients, numbered 0 through 30, inclusive. In the ASCII input to tiaud-compile you can put each coefficient on its own fir line, put all 31 coefficients on the same line, or group them in any other way you like. The grouping used in the tiaud-decomp output has been chosen for line length reasons. aec vs aec-new in tiaud-compile input ===================================== tiaud-compile accepts both aec (old) and aec-new settings; aec must be followed by 5 numbers, aec-new must be followed by 12 numbers. Each number is a 16-bit value, and they go into the binary structure without further interpretation by tiaud-compile - instead the firmware is the entity that gives them meaning. Numbers without 0x prefix are interpreted as decimal. tiaud-compile will generate one type or the other of the binary output file, following these rules: * If an aec setting is given, a 164 byte file will be produced, with the 5 AEC words being the given ones. * If an aec-new setting is given, a 176 byte file will be produced, with the 12 AEC words being the given ones. * If neither setting is given, a 164 byte file will be produced, with the 5 AEC words of the old type being all zeros. Thanks to the modified audio mode loading code in our firmwares, these 164 byte mode files can still be used with current Tourmaline fw, with AEC set to its default disabled state.