--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Melody_E1	Mon Mar 27 21:38:45 2017 +0000
@@ -0,0 +1,234 @@
+Generating ringtone melodies through the Calypso DSP
+====================================================
+
+The DSP in the Calypso and other GSM DBB chips from TI includes a built-in
+capability for generating ringtone melodies to be played through a loudspeaker
+driven by the ABB, without using an external melody generator chip.  More
+specifically, the DSP in question supports two flavors of internal melody
+generation, called Melody E1 and Melody E2 - although it is unclear whether
+Melody E2 is implemented in the DSP ROM or in the DSP code patches downloaded
+by TI's firmwares.
+
+The Melody E1 mechanism produces simple polyphonic melodies with up to 8
+simultaneous notes; these melodies consist of simple sine waves generated by
+the DSP as commanded by the bits read from the melody file as explained below.
+Melody E2 is a more complex mechanism for producing melodies (also polyphonic
+with up to 8 simultaneous notes) using the sounds of specific instruments,
+rather than simple sine waves, but we currently lack the bits required in order
+to understand or exercise it, hence our current focus is on the simpler Melody
+E1 mechanism.
+
+How these melodies are played
+=============================
+
+TI's RiViera Audio Service firmware component provides a front-end to the
+various audio services provided by the lower-level DSP+L1 combo.  In the case
+of Melody E1 and Melody E2 features, the combination of the DSP and TI's
+ARM-side L1 code effectively defines the format of the melody bits themselves,
+but the RiViera Audio Service takes care of reading these bits from FFS and
+feeding them to L1.
+
+To play an E1 format melody, the UI code needs to call audio_melody_E1_start();
+one of the arguments to this API function is the FFS absolute pathname of the
+melody file.  The API function will open this file and pass the open file
+descriptor along with other parameters in the message posted to the Audio task;
+the latter task will prefetch the first buffer-full of melody bits from the file
+and then post an MMI_MELODY0_START_REQ message to the L1A task.  The Melody E1
+handler in L1A will set up some preliminaries and fire up the Melody E1 L1S
+task, and the latter will then pass the melody bits to the DSP at appropriate
+times.
+
+Melody E1 file format
+=====================
+
+We have found a rather terse and not particularly thorough description of the
+Melody E1 bit format on pages 160 through 163 of this PDF document:
+
+https://www.freecalypso.org/LoCosto-docs/PSL1DOC/L1/L1M_AS001_1.pdf
+
+This description is not complete enough to enable proper understanding or
+implementation, but by combining it with a study of the L1A and L1S code that
+reads these bits and passes most of them to the DSP, we have reconstructed a
+somewhat more complete picture.
+
+The format is word-oriented, i.e., the basic unit of data in a Melody E1 file
+is the 16-bit word.  Most of these words are passed to the DSP for final
+interpretation inside the latter, hence we won't be able to have a 100% certain
+understanding of what happens there unless we can find the source for the DSP
+ROM code or expend a Herculean effort to reverse-engineer it, but some of the
+words are interpreted and acted upon by the ARM-side L1 firmware code, which we
+have source-reconstructed already.  When these words are written in a disk or
+FFS file, the byte order is little-endian, as it is ARM code that reads these
+16-bit words from a byte-oriented source.
+
+The very first word in a Melody E1 file gives the global list of oscillators
+used by this melody; this word is read by the L1A code before the L1S task is
+fired up.  The presence of this word is not documented at all in the terse
+description given in L1M_AS001_1.pdf, and our attempts at producing our own E1
+melodies were going nowhere until we discovered that this word is needed through
+the study of our reconstructed TCS211 L1 code.  This initial word corresponds
+to the osc-set line in our ASCII format.
+
+After the initial word giving the global oscillator set, the melody file
+consists of what we shall call time blocks.  Each time block begins with a time
+descriptor word which is interpreted and acted upon by ARM L1S code, followed
+by 0 to 8 oscillator descriptors which are loaded into DSP API words.  These
+words are described in TI's document, so we are just going to supplement that
+description wherever we have discovered something to the contrary.
+
+The lower byte of the time descriptor word tells the L1S task how long it should
+wait before loading the following oscillator descriptors into the DSP.  It
+appears that TI's intent was for this time value to be measured in 20 ms audio
+frames, but what the ARM L1S code actually does is multiply the given time value
+by 4 and use the result as the number of TDMA frames to count - the L1S code
+executes on every TDMA frame.  13 TDMA frames equal 60 ms, thus 4 TDMA frames
+do not exactly equal 20 ms, but come a little short.  It is not clear whether
+the melody files generated by TI and/or their customers account for this
+discrepancy or not.  In any case, the time value given in the file needs to be
+non-zero - putting a zero in there will cause the L1S counter to be set to 65535
+TDMA frames (a 16-bit unsigned counter loaded with 0 and decremented by one),
+which is probably not what you want.
+
+The upper byte of the time descriptor word is a bit mask indicating which DSP
+oscillators are to be loaded at this time.  This bit mask byte can be zero, in
+which case the time block consists of just the time descriptor word.  However,
+the L1S code does absolutely nothing to the DSP in this case, hence an empty
+(no oscillators) time block is indistinguishable from adding the time to the
+following non-empty block.  But the largest time value that can fit in the byte
+is 255, hence empty time blocks can be used to produce larger time deltas.
+A time descriptor with zeros in both upper and lower bytes indicates the end of
+the melody; this terminator is required.
+
+Now we come to the interesting part: the oscillator descriptors that are loaded
+into the DSP to cause the actual melody generation to occur.  The DSP's NDB API
+page contains 4 words for each of the 8 oscillators, and these NDB API words are
+where the oscillator descriptor words from the melody file ultimately go.
+
+Please refer to the description of the ml_load1 and ml_load2 bits on page 162
+of TI's L1M_AS001_1.pdf document.  Now here is what the L1S code actually does:
+first it loads 2 words from the file buffer into the DSP's NDB page - yes,
+directly into there.  Then it does the following logic (code simplified from
+the actual into more readable pseudocode):
+
+	load_size = 0;
+	if (word1 & ml_load1)
+		load_size++;
+	if (word1 & ml_load2)
+		load_size++;
+	if (load_size)
+		load load_size words at word2 address in the DSP's NDB page
+
+This logic is peculiar: what happens if ml_load2 is set but not ml_load1?  The
+result will be that the word meant to be word3 (the envelope word) will get
+loaded into the word2 location in the DSP's NDB page.  Unless the DSP actually
+checks the ml_load bits and expects the envelope word in the word2 location in
+this case, which I highly doubt, this L1S behaviour looks like a bug to me - so
+don't use the word3 present but not word2 combination in your melodies.
+
+It appears that these ml_load1 and ml_load2 bits are only checked by the L1S
+code and ignored by the DSP.  I say so because when I tried creating a melody
+in which word2 and word3 were always omitted, the result was bogus.  It appears
+that the first time a given oscillator is loaded, all 4 words must always be
+given, otherwise the DSP will act on whatever garbage happens to be in those
+NDB API words from before.  When the same oscillator is subsequently reloaded,
+omitting word2 and/or word3 will cause that word's previous value to be reused.
+
+A few notes regarding some bits in word0:
+
+ml_synchro (bit 0): the L1S code ORs a 1 into this bit in the NDB API word
+after it has loaded all of the words.  It thus seems more correct to me to put
+a 0 in this bit in the files, so that the DSP sees the new descriptor when it
+is complete - but of course we can never know for sure without knowing what
+actually happens inside the DSP.
+
+ml_directF: both common sense and the TSM30 source (which uses the Melody E1
+feature of the DSP in that old Calypso version) suggest that ml_directF is
+bit 1, ml_square1 is bit 2 and ml_square2 is bit 3, i.e., it appears that the
+table on page 161 of L1M_AS001_1.pdf is wrong in this regard.  Also note the
+order in which the fields are described on page 162 of the same PDF document.
+
+This is where our current knowledge ends.  Until we either obtain a copy of the
+source for the DSP ROM or painstakingly reverse-engineer it, all we can do is
+look at the few existing examples of E1-format melodies we can find (see below)
+and experiment with putting different values in the various fields based on the
+description in the L1M_AS001_1.pdf document.
+
+Examples of E1-format melodies
+==============================
+
+We've been very fortunate to discover that the legendary TSM30 phone appears to
+have used the Melody E1 feature, and that there are a bunch of E1-format
+melodies embedded in the famous TSM30 source from HispaPhreak.  I have extracted
+these melodies, played them through the earpiece speaker on a Pirelli DP-L10
+phone running FreeCalypso Magnetite (our own FCDEV3B with a loudspeaker that we
+can actually use has not been built yet as of this writing), and found some of
+them to be quite pleasant-sounding.  These extracted TSM30 melodies can be found
+here:
+
+ftp://ftp.freecalypso.org/pub/GSM/ringtone/tsm30-melody-e1.tar.gz
+
+I also found a couple of melodies in our TCS211 reference semi-src under
+chipsetsw/services/Audio/tests; these two melodies illustrate how one can load
+word2 and word3 the first time and then omit them afterward when reloading the
+same oscillator.  (All of the TSM30 melodies always load all 4 words in every
+oscillator descriptor.)
+
+Our own ASCII format for E1 melodies
+====================================
+
+In this FreeCalypso host tools package we have a utility for decoding existing
+Melody E1 binary bits into an amenable-to-study ASCII format, as well as a
+utility for generating new E1-format binary melodies from an ASCII text source
+in the same format.  The ASCII format is of our own invention, and consists of
+numeric fields which map directly to the various bit fields in the DSP+fw's
+binary format.
+
+Our ASCII format for E1 melodies consists of 3 parts: an osc-set global header
+line, a sequence of time blocks, and an end line.  The noteworthy aspects are:
+
+* Each time block is given as a time line followed by 0 or more osc lines.
+  This lines must follow in direct succession without intervening blank or
+  comment lines, and each time block must end with a blank line.
+
+* The end marker line is mandatory; having the ASCII file just end without it
+  is an error.
+
+Please see the source code for fc-e1decode and fc-e1gen for the rest.
+
+Some words regarding Melody E2
+==============================
+
+E1-format melodies are self-contained: if you have a valid binary melody file
+in E1 format from whatever source, you can play it through the DSP of any
+Calypso device that runs our TCS211-based Magnetite firmware.  But it is not so
+simple with Melody E2.  In order to play a melody in E2 format, one needs not
+only the melody file itself, but also the set of *.mwa (instrument wave) files
+corresponding to the set of instruments used by that melody.  It appears that
+the melody group at TI had produced as many as 48 different instrument wave
+tables: see the list in the non-production
+	#if (AUDIO_SIMULATION) || (AUDIO_L1_STANDALONE)
+section of the Cust_audio_melody_E2_load_instrument() function in l1audio_cust.c
+in both TSM30 and LoCosto/Peek sources.  (The LoCosto version lists 48
+instruments whereas the much earlier TSM30 version lists only 40 of them, thus
+the list must have been added to over the course of TI history.)  A given E2
+melody selects a subset of 1 to 8 instruments out of the larger set to be used
+in that melody, and these selected instrument waves are loaded into the DSP's
+API RAM before the actual play of the melody itself.
+
+Unfortunately all we have are the *.mwa file _names_ for the 48 Melody E2
+instruments that apparently existed at TI once upon a time, but not any of the
+actual bits.  The TSM30 source uses only Melody E1, not E2, thus we do not
+currently have any source from which we can take any E2-format melody examples
+or E2 instrument wave tables for TI's DSP.  We also don't have any documentation
+for any of these bits, and analysis of the Melody E2 code in L1 shows that it is
+significantly different from E1.  The code in TCS211 L1 that reads Melody E2
+file bits is not of much help for making our own E2 melodies, as all of the real
+magic happens in the DSP, not on the ARM side.
+
+Thus our FreeCalypso hardware+firmware combination is capable of playing both E1
+and E2 melodies, but we won't be able to exercise the latter capability until
+and unless someone finds a surviving copy of some existing E2 melodies along
+with the *.mwa instrument wave files they require, whether it is the same
+instrument set as listed in the non-production section of l1audio_cust.c or a
+different one.  But if someone does obtain a set of such melody bit files, our
+FreeCalypso devices running FreeCalypso firmware are ready to play them.