# HG changeset patch # User Mychaela Falconia # Date 1503723025 0 # Node ID 796c659b747cd8a23c7c7a3fae4140e65973867c # Parent 97d6d593ffc680428175cec8feaa9998be2a943a doc/Audio-mode-config written diff -r 97d6d593ffc6 -r 796c659b747c doc/Audio-mode-config --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Audio-mode-config Sat Aug 26 04:50:25 2017 +0000 @@ -0,0 +1,189 @@ +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 a loudspeaker (as opposed to a piezo buzzer) to +play ringtones and uses the Calypso DSP to generate those ringtone melodies, +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 +revelant 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. + +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 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. + +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 0, 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. + +* The numbers given on fir and aec lines are 16-bit values that go directly into + the DSP; the former are FIR coefficients and the latter are bit masks. They + can be given as either decimal or hexadecimal with 0x prefix in the ASCII + input to tiaud-compile.