| 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). |