FreeCalypso > hg > freecalypso-tools
comparison doc/Melody_E1 @ 180:e50c3aa1152a
doc/Melody_E1 written
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Mon, 27 Mar 2017 21:38:45 +0000 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
179:da02ce0ac815 | 180:e50c3aa1152a |
---|---|
1 Generating ringtone melodies through the Calypso DSP | |
2 ==================================================== | |
3 | |
4 The DSP in the Calypso and other GSM DBB chips from TI includes a built-in | |
5 capability for generating ringtone melodies to be played through a loudspeaker | |
6 driven by the ABB, without using an external melody generator chip. More | |
7 specifically, the DSP in question supports two flavors of internal melody | |
8 generation, called Melody E1 and Melody E2 - although it is unclear whether | |
9 Melody E2 is implemented in the DSP ROM or in the DSP code patches downloaded | |
10 by TI's firmwares. | |
11 | |
12 The Melody E1 mechanism produces simple polyphonic melodies with up to 8 | |
13 simultaneous notes; these melodies consist of simple sine waves generated by | |
14 the DSP as commanded by the bits read from the melody file as explained below. | |
15 Melody E2 is a more complex mechanism for producing melodies (also polyphonic | |
16 with up to 8 simultaneous notes) using the sounds of specific instruments, | |
17 rather than simple sine waves, but we currently lack the bits required in order | |
18 to understand or exercise it, hence our current focus is on the simpler Melody | |
19 E1 mechanism. | |
20 | |
21 How these melodies are played | |
22 ============================= | |
23 | |
24 TI's RiViera Audio Service firmware component provides a front-end to the | |
25 various audio services provided by the lower-level DSP+L1 combo. In the case | |
26 of Melody E1 and Melody E2 features, the combination of the DSP and TI's | |
27 ARM-side L1 code effectively defines the format of the melody bits themselves, | |
28 but the RiViera Audio Service takes care of reading these bits from FFS and | |
29 feeding them to L1. | |
30 | |
31 To play an E1 format melody, the UI code needs to call audio_melody_E1_start(); | |
32 one of the arguments to this API function is the FFS absolute pathname of the | |
33 melody file. The API function will open this file and pass the open file | |
34 descriptor along with other parameters in the message posted to the Audio task; | |
35 the latter task will prefetch the first buffer-full of melody bits from the file | |
36 and then post an MMI_MELODY0_START_REQ message to the L1A task. The Melody E1 | |
37 handler in L1A will set up some preliminaries and fire up the Melody E1 L1S | |
38 task, and the latter will then pass the melody bits to the DSP at appropriate | |
39 times. | |
40 | |
41 Melody E1 file format | |
42 ===================== | |
43 | |
44 We have found a rather terse and not particularly thorough description of the | |
45 Melody E1 bit format on pages 160 through 163 of this PDF document: | |
46 | |
47 https://www.freecalypso.org/LoCosto-docs/PSL1DOC/L1/L1M_AS001_1.pdf | |
48 | |
49 This description is not complete enough to enable proper understanding or | |
50 implementation, but by combining it with a study of the L1A and L1S code that | |
51 reads these bits and passes most of them to the DSP, we have reconstructed a | |
52 somewhat more complete picture. | |
53 | |
54 The format is word-oriented, i.e., the basic unit of data in a Melody E1 file | |
55 is the 16-bit word. Most of these words are passed to the DSP for final | |
56 interpretation inside the latter, hence we won't be able to have a 100% certain | |
57 understanding of what happens there unless we can find the source for the DSP | |
58 ROM code or expend a Herculean effort to reverse-engineer it, but some of the | |
59 words are interpreted and acted upon by the ARM-side L1 firmware code, which we | |
60 have source-reconstructed already. When these words are written in a disk or | |
61 FFS file, the byte order is little-endian, as it is ARM code that reads these | |
62 16-bit words from a byte-oriented source. | |
63 | |
64 The very first word in a Melody E1 file gives the global list of oscillators | |
65 used by this melody; this word is read by the L1A code before the L1S task is | |
66 fired up. The presence of this word is not documented at all in the terse | |
67 description given in L1M_AS001_1.pdf, and our attempts at producing our own E1 | |
68 melodies were going nowhere until we discovered that this word is needed through | |
69 the study of our reconstructed TCS211 L1 code. This initial word corresponds | |
70 to the osc-set line in our ASCII format. | |
71 | |
72 After the initial word giving the global oscillator set, the melody file | |
73 consists of what we shall call time blocks. Each time block begins with a time | |
74 descriptor word which is interpreted and acted upon by ARM L1S code, followed | |
75 by 0 to 8 oscillator descriptors which are loaded into DSP API words. These | |
76 words are described in TI's document, so we are just going to supplement that | |
77 description wherever we have discovered something to the contrary. | |
78 | |
79 The lower byte of the time descriptor word tells the L1S task how long it should | |
80 wait before loading the following oscillator descriptors into the DSP. It | |
81 appears that TI's intent was for this time value to be measured in 20 ms audio | |
82 frames, but what the ARM L1S code actually does is multiply the given time value | |
83 by 4 and use the result as the number of TDMA frames to count - the L1S code | |
84 executes on every TDMA frame. 13 TDMA frames equal 60 ms, thus 4 TDMA frames | |
85 do not exactly equal 20 ms, but come a little short. It is not clear whether | |
86 the melody files generated by TI and/or their customers account for this | |
87 discrepancy or not. In any case, the time value given in the file needs to be | |
88 non-zero - putting a zero in there will cause the L1S counter to be set to 65535 | |
89 TDMA frames (a 16-bit unsigned counter loaded with 0 and decremented by one), | |
90 which is probably not what you want. | |
91 | |
92 The upper byte of the time descriptor word is a bit mask indicating which DSP | |
93 oscillators are to be loaded at this time. This bit mask byte can be zero, in | |
94 which case the time block consists of just the time descriptor word. However, | |
95 the L1S code does absolutely nothing to the DSP in this case, hence an empty | |
96 (no oscillators) time block is indistinguishable from adding the time to the | |
97 following non-empty block. But the largest time value that can fit in the byte | |
98 is 255, hence empty time blocks can be used to produce larger time deltas. | |
99 A time descriptor with zeros in both upper and lower bytes indicates the end of | |
100 the melody; this terminator is required. | |
101 | |
102 Now we come to the interesting part: the oscillator descriptors that are loaded | |
103 into the DSP to cause the actual melody generation to occur. The DSP's NDB API | |
104 page contains 4 words for each of the 8 oscillators, and these NDB API words are | |
105 where the oscillator descriptor words from the melody file ultimately go. | |
106 | |
107 Please refer to the description of the ml_load1 and ml_load2 bits on page 162 | |
108 of TI's L1M_AS001_1.pdf document. Now here is what the L1S code actually does: | |
109 first it loads 2 words from the file buffer into the DSP's NDB page - yes, | |
110 directly into there. Then it does the following logic (code simplified from | |
111 the actual into more readable pseudocode): | |
112 | |
113 load_size = 0; | |
114 if (word1 & ml_load1) | |
115 load_size++; | |
116 if (word1 & ml_load2) | |
117 load_size++; | |
118 if (load_size) | |
119 load load_size words at word2 address in the DSP's NDB page | |
120 | |
121 This logic is peculiar: what happens if ml_load2 is set but not ml_load1? The | |
122 result will be that the word meant to be word3 (the envelope word) will get | |
123 loaded into the word2 location in the DSP's NDB page. Unless the DSP actually | |
124 checks the ml_load bits and expects the envelope word in the word2 location in | |
125 this case, which I highly doubt, this L1S behaviour looks like a bug to me - so | |
126 don't use the word3 present but not word2 combination in your melodies. | |
127 | |
128 It appears that these ml_load1 and ml_load2 bits are only checked by the L1S | |
129 code and ignored by the DSP. I say so because when I tried creating a melody | |
130 in which word2 and word3 were always omitted, the result was bogus. It appears | |
131 that the first time a given oscillator is loaded, all 4 words must always be | |
132 given, otherwise the DSP will act on whatever garbage happens to be in those | |
133 NDB API words from before. When the same oscillator is subsequently reloaded, | |
134 omitting word2 and/or word3 will cause that word's previous value to be reused. | |
135 | |
136 A few notes regarding some bits in word0: | |
137 | |
138 ml_synchro (bit 0): the L1S code ORs a 1 into this bit in the NDB API word | |
139 after it has loaded all of the words. It thus seems more correct to me to put | |
140 a 0 in this bit in the files, so that the DSP sees the new descriptor when it | |
141 is complete - but of course we can never know for sure without knowing what | |
142 actually happens inside the DSP. | |
143 | |
144 ml_directF: both common sense and the TSM30 source (which uses the Melody E1 | |
145 feature of the DSP in that old Calypso version) suggest that ml_directF is | |
146 bit 1, ml_square1 is bit 2 and ml_square2 is bit 3, i.e., it appears that the | |
147 table on page 161 of L1M_AS001_1.pdf is wrong in this regard. Also note the | |
148 order in which the fields are described on page 162 of the same PDF document. | |
149 | |
150 This is where our current knowledge ends. Until we either obtain a copy of the | |
151 source for the DSP ROM or painstakingly reverse-engineer it, all we can do is | |
152 look at the few existing examples of E1-format melodies we can find (see below) | |
153 and experiment with putting different values in the various fields based on the | |
154 description in the L1M_AS001_1.pdf document. | |
155 | |
156 Examples of E1-format melodies | |
157 ============================== | |
158 | |
159 We've been very fortunate to discover that the legendary TSM30 phone appears to | |
160 have used the Melody E1 feature, and that there are a bunch of E1-format | |
161 melodies embedded in the famous TSM30 source from HispaPhreak. I have extracted | |
162 these melodies, played them through the earpiece speaker on a Pirelli DP-L10 | |
163 phone running FreeCalypso Magnetite (our own FCDEV3B with a loudspeaker that we | |
164 can actually use has not been built yet as of this writing), and found some of | |
165 them to be quite pleasant-sounding. These extracted TSM30 melodies can be found | |
166 here: | |
167 | |
168 ftp://ftp.freecalypso.org/pub/GSM/ringtone/tsm30-melody-e1.tar.gz | |
169 | |
170 I also found a couple of melodies in our TCS211 reference semi-src under | |
171 chipsetsw/services/Audio/tests; these two melodies illustrate how one can load | |
172 word2 and word3 the first time and then omit them afterward when reloading the | |
173 same oscillator. (All of the TSM30 melodies always load all 4 words in every | |
174 oscillator descriptor.) | |
175 | |
176 Our own ASCII format for E1 melodies | |
177 ==================================== | |
178 | |
179 In this FreeCalypso host tools package we have a utility for decoding existing | |
180 Melody E1 binary bits into an amenable-to-study ASCII format, as well as a | |
181 utility for generating new E1-format binary melodies from an ASCII text source | |
182 in the same format. The ASCII format is of our own invention, and consists of | |
183 numeric fields which map directly to the various bit fields in the DSP+fw's | |
184 binary format. | |
185 | |
186 Our ASCII format for E1 melodies consists of 3 parts: an osc-set global header | |
187 line, a sequence of time blocks, and an end line. The noteworthy aspects are: | |
188 | |
189 * Each time block is given as a time line followed by 0 or more osc lines. | |
190 This lines must follow in direct succession without intervening blank or | |
191 comment lines, and each time block must end with a blank line. | |
192 | |
193 * The end marker line is mandatory; having the ASCII file just end without it | |
194 is an error. | |
195 | |
196 Please see the source code for fc-e1decode and fc-e1gen for the rest. | |
197 | |
198 Some words regarding Melody E2 | |
199 ============================== | |
200 | |
201 E1-format melodies are self-contained: if you have a valid binary melody file | |
202 in E1 format from whatever source, you can play it through the DSP of any | |
203 Calypso device that runs our TCS211-based Magnetite firmware. But it is not so | |
204 simple with Melody E2. In order to play a melody in E2 format, one needs not | |
205 only the melody file itself, but also the set of *.mwa (instrument wave) files | |
206 corresponding to the set of instruments used by that melody. It appears that | |
207 the melody group at TI had produced as many as 48 different instrument wave | |
208 tables: see the list in the non-production | |
209 #if (AUDIO_SIMULATION) || (AUDIO_L1_STANDALONE) | |
210 section of the Cust_audio_melody_E2_load_instrument() function in l1audio_cust.c | |
211 in both TSM30 and LoCosto/Peek sources. (The LoCosto version lists 48 | |
212 instruments whereas the much earlier TSM30 version lists only 40 of them, thus | |
213 the list must have been added to over the course of TI history.) A given E2 | |
214 melody selects a subset of 1 to 8 instruments out of the larger set to be used | |
215 in that melody, and these selected instrument waves are loaded into the DSP's | |
216 API RAM before the actual play of the melody itself. | |
217 | |
218 Unfortunately all we have are the *.mwa file _names_ for the 48 Melody E2 | |
219 instruments that apparently existed at TI once upon a time, but not any of the | |
220 actual bits. The TSM30 source uses only Melody E1, not E2, thus we do not | |
221 currently have any source from which we can take any E2-format melody examples | |
222 or E2 instrument wave tables for TI's DSP. We also don't have any documentation | |
223 for any of these bits, and analysis of the Melody E2 code in L1 shows that it is | |
224 significantly different from E1. The code in TCS211 L1 that reads Melody E2 | |
225 file bits is not of much help for making our own E2 melodies, as all of the real | |
226 magic happens in the DSP, not on the ARM side. | |
227 | |
228 Thus our FreeCalypso hardware+firmware combination is capable of playing both E1 | |
229 and E2 melodies, but we won't be able to exercise the latter capability until | |
230 and unless someone finds a surviving copy of some existing E2 melodies along | |
231 with the *.mwa instrument wave files they require, whether it is the same | |
232 instrument set as listed in the non-production section of l1audio_cust.c or a | |
233 different one. But if someone does obtain a set of such melody bit files, our | |
234 FreeCalypso devices running FreeCalypso firmware are ready to play them. |