FreeCalypso > hg > freecalypso-tools

annotate doc/Melody_E1 @ 926:6a0aa8d36d06

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