FreeCalypso > hg > freecalypso-tools

annotate doc/Melody_E1 @ 422:c1aadfcd185f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
rvinterf client refactoring: libasync clients converted to use libinterf
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 28 Oct 2018 00:00:51 +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.