--- a/doc/Audio-mode-config	Fri Jul 30 01:37:42 2021 +0000
+++ b/doc/Audio-mode-config	Fri Jul 30 05:21:19 2021 +0000
@@ -52,9 +52,10 @@
 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.
+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
@@ -94,6 +95,58 @@
 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
 ===========================
 
@@ -123,6 +176,11 @@
 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
@@ -144,7 +202,11 @@
 * 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.
+* 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
 ===========================================
@@ -183,7 +245,25 @@
   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.
+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.