Debian Codegraph @

BambooTracker/chip/ymfm/GeneralInfo.md

raw
1 # ymfm: One FM core to rule them all
2
3 The ymfm emulator ws written from the ground-up using the analysis and deduction by Nemesis as a starting point, particularly in [this thread](https://gendev.spritesmind.net/forum/viewtopic.php?f=24&t=386).
4
5 The core assumption is that these details apply to all FM variants unless otherwise proven incorrect.
6
7 The fine details of this implementation have also been cross-checked against Nemesis' implementation in his [Exodus emulator](https://www.exodusemulator.com/), as well as Alexey Khokholov's ["Nuked" implementations](https://github.com/nukeykt/Nuked-OPN2) based off die shots.
8
9 Operator and channel summing/mixing code for OPM and OPN is largely based off of research done by [David Viens](https://twitter.com/plgDavid) and Hubert Lamontagne.
10
11 ## Families
12
13 The Yamaha FM chips can be broadly categoried into families:
14
15 * OPM (YM2151)
16 * OPP (YM2164)
17 * OPN (YM2203)
18 * OPNA/OPNB/OPN2 (YM2608, YM2610, YM2610B, YM2612, YM3438, YMF276, YMF288)
19 * OPL (YM3526)
20 * OPL2 (YM3812)
21 * OPLL (YM2413, YM2423, YMF281, DS1001, and others)
22 * OPL3 (YMF262, YMF289B)
23 * OPL4 (YMF278)
24
25 Additionally, several lesser-documented variants exist exclusively in the employ of Yamaha synthesizers:
26
27 * OPQ (YM3608)
28 * OPZ (YM2414)
29
30 All of these families are very closely related, and the ymfm engine is designed to be universal to work across all of
31 these families.
32
33 Of course, each variant has its own register maps, features, and implementation details which need to be sorted out.
34 Thus, each significant variant listed above is represented by a register class.
35 The register class contains:
36
37 * constants describing core parameters and features
38 * mappers between operators and channels
39 * generic fetchers that return normalized values across families
40 * family-specific implementations of LFO and phase calculations
41
42 ## Family History
43
44 This history outlines the progress of adding/removing features across the three main families (OPM, OPN, OPL):
45
46 OPM started it all off, featuring:
47 * 8 FM channels, 4 operators each
48 * LFO and noise support
49 * Stereo output
50
51 OPM -> OPN changes:
52 * Reduced to 3 FM channels, 4 operators each
53 * Removed LFO and noise support
54 * Mono output
55 * Integrated AY-8910 compatible PSG
56 * Added SSG-EG envelope mode
57 * Added multi-frequency mode: ch. 3 operators can have separate frequencies
58 * Software controlled clock divider
59
60 OPN -> OPNA changes:
61 * Increased to 6 FM channels, 4 operators each
62 * Added back (a cut-down) LFO
63 * Stereo output again
64 * Removed software controlled divider on later versions (OPNB/OPN2)
65 * Removed PSG on OPN2 models
66
67 OPNA -> OPL changes:
68 * Increased to 9 FM channels, but only 2 operators each
69 * Even more simplified LFO
70 * Mono output
71 * Removed PSG
72 * Removed SSG-EG envelope modes
73 * Removed multi-frequency modes
74 * Fixed clock divider
75 * Built-in ryhthm generation
76
77 OPL -> OPL2 changes:
78 * Added 4 selectable waveforms
79
80 OPL2 -> OPLL changes:
81 * Vastly simplified register map
82 * 15 built-in instruments, plus built-in rhythm instruments
83 * 1 user-controlled instrument
84
85 OPL2 -> OPL3 changes:
86 * Increased to 18 FM channels, 2 operators each
87 * 4 output channels
88 * Increased to 8 selectable waveforms
89 * 6 channels can be configured to use 4 operators
90
91 ## Channels and Operators
92
93 The polyphony of a given chip is determined by the number of channels it supports.
94 This number ranges from as low as 3 to as high as 18.
95 Each channel has either 2 or 4 operators that can be combined in a myriad of ways.
96 On most chips the number of operators per channel is fixed; however, some later OPL chips allow this to be toggled between 2 and 4 at runtime.
97
98 The base ymfm engine class maintains an array of channels and operators, while the relationship between the two is described by the register class.
99
100 ## Registers
101
102 Registers on the Yamaha chips are generally write-only, and can be divided into three distinct categories:
103
104 * system-wide registers
105 * channel-specific registers
106 * operator-specific registers
107
108 For maximum flexibility, most parameters can be configured at the operator level, with channel-level registers controlling details such as how to combine the operators into the final output.
109 System-wide registers are used to control chip-wide modes and manage onboard timer functions.
110
111 Note that since registers are write-only, some ymfm register classes will use "holes" in the register space to store additional values that may be needed.
112
113 ## Attenuation
114
115 Most of the computations of the FM engines are done in terms of attenuation, and thus are logarithmic in nature.
116 The maximum resolution used internally is 12 bits, as returned by the sin table:
117
118 Bit | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
119 ----|----|----|----|----|----|----|-----|------|-------|--------|---------|---------
120 dB | -96| -48| -24| -12| -6| -3| -1.5| -0.75| -0.375| -0.1875| -0.09375| -0.046875
121
122 The envelope generator internally uses 10 bits:
123
124 Bit | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
125 ----|----|----|----|----|----|-----|------|-------|--------|---------|
126 dB | -48| -24| -12| -6| -3| -1.5| -0.75| -0.375| -0.1875| -0.09375|
127
128 Total level for operators is usually represented by 7 bits:
129
130 Bit | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
131 ----|----|----|----|----|----|-----|------|
132 dB | -48| -24| -12| -6| -3| -1.5| -0.75|
133
134 Sustain level in the envelope generator is usually represented by 4 bits:
135
136 Bit | 3 | 2 | 1 | 0 |
137 ----|----|----|----|----|
138 dB | -24| -12| -6| -3|
139
140 ## Status and Timers
141
142 Generically, all chips (except OPLL) support two timers that can be programmed to fire and signal IRQs.
143 These timers also set bits in the status register.
144 The behavior of these bits is shared across all implementations, even if the exact bit positions shift (this is controlled by constants in the registers class).
145
146 In addition, several chips incorporate ADPCM decoders which also may set bits in the same status register.
147 For this reason, it is possible to control various bits in the status register via the `set_reset_status()` function directly.
148 Any active bits that are set and which are not masked (mask is controlled by `set_irq_mask()`), lead to an IRQ being signalled.
149
150 Thus, it is possible for the chip-specific implementations to set the mask and control the status register bits such that IRQs are signalled via the same mechanism as timer signals.
151
152 In addition, the OPM and OPN families have a "busy" flag, which is set after each write, indicating that another write should not be performed.
153 Historically, the duration of this flag was constant and had nothing to do with the internals of the chip.
154 However, since the details can potentially vary chip-to-chip, it is the chip's responsibility to insert the busy flag into the status before returning it to the caller.
155
156 ## Clocking
157
158 Each of the Yamaha chips works by cycling through all operators one at a time.
159 Thus, the effective output rate of the chips is related to the input clock divided by the number of operators.
160 In addition, the input clock is prescaled by an amount.
161 Generally, this is a fixed value, though some early OPN chips allow this to be selected at runtime from a small
162 number of values.
163
164 ## Channel Frequencies
165
166 One major difference between OPM and later families is in how frequencies are specified.
167 OPM specifies frequency via a 3-bit 'block' (aka octave), combined with a 4-bit 'key code' (note number) and a 6-bit 'key fraction'.
168 The key code and fraction are converted on the chip into an x.11 fixed-point value and then shifted by the block to produce the final step value for the phase.
169
170 Later families, on the other hand, specify frequencies via a 3-bit 'block' just as on OPM, but combined with a 9-12-bit 'frequency number' or 'fnum', which is directly shifted by the block to produce the step value.
171 So essentially, later chips make the user do the conversion from note value to phase increment, while OPM is programmed in a more 'musical' way, specifying notes and cents.
172
173 Internally, this is abstracted away into a 'block_freq' value, which is a 16-bit value containing the block and frequency info concatenated together as follows:
174
175 * OPM: `[3-bit block]:[4-bit keycode]:[6-bit fraction] = 13 bits total`
176
177 * OPZ: `[3-bit block]:[12-bit fnum] = 15 bits total`
178 * OPN: `[3-bit block]:[11-bit fnum] 0 = 15 bits total`
179 * OPL: `[3-bit block]:[10-bit fnum]:00 = 15 bits total`
180 * OPLL: `[3-bit block]:[ 9-bit fnum]:000 = 15 bits total`
181
182 The register classes handle the raw format directly and convert it into a phase increment which can be used by the generic engine.
183
184 ## Low Frequency Oscillator (LFO)
185
186 The LFO engines are different in several key ways.
187 The OPM LFO engine is fairly intricate.
188 It has a 4.4 floating-point rate which allows for a huge range of frequencies, and can select between four different waveforms (sawtooth, square, triangle, or noise).
189 Separate 7-bit depth controls for AM and PM control the amount of modulation applied in each case.
190 This global LFO value is then further controlled at the channel level by a 2-bit AM sensitivity and a 3-bit PM sensitivity, and each operator has a 1-bit AM on/off switch.
191
192 For OPN the LFO engine was removed entirely, but a limited version was put back in OPNA and later chips.
193 This stripped-down version offered only a 3-bit rate setting (versus the 4.4 floating-point rate in OPN), and no
194 global depth control.
195 It did bring back the channel-level sensitivity controls and the operator-level on/off control.
196
197 For OPL, the LFO is simplified again, with AM and PM running at fixed frequencies, and simple enable flags at the operator level for each controlling their application.
198
199 ## Differences Between Families
200
201 The table below provides some high level functional differences between the differnet families:
202
203 subfamily: | OPM | OPN | OPNA | OPL | OPL2 | OPLL | OPL3 |
204 ------------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|
205 outputs: | 2 | 1 | 2 | 1 | 1 | 1 | 4 |
206 channels: | 8 | 3 | 6 | 9 | 9 | 9 | 18 |
207 operators: | 32 | 12 | 24 | 18 | 18 | 18 | 36 |
208 waveforms: | 1 | 1 | 1 | 1 | 4 | 2 | 8 |
209 instruments: | no | no | no | yes | yes | yes | yes |
210 ryhthm: | no | no | no | no | no | yes | no |
211 dynamic ops: | no | no | no | no | no | no | yes |
212 prescale: | 2 | 2/3/6 | 2/3/6 | 4 | 4 | 4 | 8 |
213 EG divider: | 3 | 3 | 3 | 1 | 1 | 1 | 1 |
214 EG DP: | no | no | no | no | no | yes | no |
215 EG SSG: | no | yes | yes | no | no | no | no |
216 mod delay: | no | no | no | yes | yes | yes? | no |
217 CSM: | yes | ch 2 | ch 2 | yes | yes | yes | no |
218 LFO: | yes | no | yes | yes | yes | yes | yes |
219 noise: | yes | no | no | no | no | no | no |
220
221 * Outputs represents the number of output channels: 1=mono, 2=stereo, 4=stereo+.
222 * Channels represents the number of independent FM channels.
223 * Operators represents the number of operators, or "slots" which are assembled into the channels.
224 * Waveforms represents the number of different sine-derived waveforms available.
225 * Instruments indicates whether the family has built-in instruments.
226 * Rhythm indicates whether the family has a built-in rhythm
227 * Dynamic ops indicates whether it is possible to switch between 2-operator and 4-operator modes dynamically.
228 * Prescale specifies the default clock divider; some chips allow this to be controlled via register writes.
229 * EG divider represents the divider applied to the envelope generator clock.
230 * EG DP indicates whether the envelope generator includes a DP (depress?) phase at the beginning of each key on.
231 * SSG EG indicates whether the envelope generator has SSG-style support.
232 * Mod delay indicates whether the connection to the first modulator's input is delayed by 1 sample.
233 * CSM indicates whether CSM mode is supported, triggered by timer A.
234 * LFO indicates whether LFO is supported.
235 * Noise indicates whether one of the operators can be replaced with a noise source.
236
237 ## Chip Specifics
238
239 While OPM is its own thing, the OPN and OPL families have quite a few specific
240 implementations, with many differing details beyond the core FM parts. Here are
241 some details on the OPN family:
242
243 chip ID: | YM2203 | YM2608 | YMF288 | YM2610 | YM2610B | YM2612 | YM3438 | YMF276 |
244 ---------:|:------:|:------:|:------:|:------:|:-------:|:------:|:------:|:------:|
245 aka: | OPN | OPNA | OPN3L | OPNB | OPNB2 | OPN2 | OPN2C | OPN2L |
246 FM: | 3 | 6 | 6 | 4 | 6 | 6 | 6 | 6 |
247 AY-8910: | 3 | 1 | 1 | 1 | 1 | - | - | - |
248 ADPCM-A: | - | 6 int | 6 int | 6 ext | 6 ext | - | - | - |
249 ADPCM-B: | - | 1 ext | - | 1 ext | 1 ext | - | - | - |
250 DAC: | no | no | no | no | no | yes | yes | yes |
251 output: | 10.3fp | 16-bit | 16-bit | 16-bit | 16-bit | 9-bit | 9-bit | 16-bit |
252 summing: | adder | adder | adder | adder | adder | muxer | muxer | adder |
253
254 * FM represents the number of FM channels available.
255 * AY-8910 represents the number of AY-8910-compatible outputs.
256 * ADPCM-A represents the number of internal/external ADPCM-A channels present.
257 * ADPCM-B represents the number of internal/external ADPCM-B channels present.
258 * DAC indicates if a directly-accessible DAC output exists, replacing one channel.
259 * Output indicates the output format to the final DAC.
260 * Summing indicates whether channels are added or time divided in the output.
261
262 OPL has a similar trove of chip variants:
263
264 chip ID: | YM3526 | Y8950 | YM3812 | YM2413 | YMF262 | YMF289B | YMF278B |
265 ------------:|:------:|:-------:|:------:|:------:|:------:|:-------:|:-------:|
266 aka: | OPL |MSX-AUDIO| OPL2 | OPLL | OPL3 | OPL3L | OPL4 |
267 FM: | 9 | 9 | 9 | 9 | 18 | 18 | 18 |
268 ADPCM-B: | - | 1 ext | - | - | - | - | - |
269 wavetable: | - | - | - | - | - | - | 24 |
270 instruments: | no | no | no | yes | no | no | no |
271 output: | 10.3fp | 10.3fp | 10.3fp | 9-bit | 16-bit | 16-bit | 16-bit |
272 summing: | adder | adder | adder | muxer | adder | adder | adder |
273
274 * FM represents the number of FM channels available.
275 * ADPCM-B represents the number of external ADPCM-B channels present.
276 * Wavetable indicates the number of wavetable channels present.
277 * Instruments indicates that the chip has built-in instrument selection.
278 * Output indicates the output format to the final DAC.
279 * Summing indicates whether channels are added or time divided in the output.
280
281 There are several close variants of the YM2413 with different sets of built-in instruments.
282 These include the YM2423, YMF281, and DS1001 (aka Konami VRC7).