# HG changeset patch # User Mychaela Falconia # Date 1490650725 0 # Node ID e50c3aa1152aa7ad5185222bdc264b1bdf62b2d7 # Parent da02ce0ac8157fa9071fd08c210fe7298a111835 doc/Melody_E1 written diff -r da02ce0ac815 -r e50c3aa1152a doc/Melody_E1 --- /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.