diff options
Diffstat (limited to '3rdparty/ymfm/GeneralInfo.md')
-rw-r--r-- | 3rdparty/ymfm/GeneralInfo.md | 282 |
1 files changed, 282 insertions, 0 deletions
diff --git a/3rdparty/ymfm/GeneralInfo.md b/3rdparty/ymfm/GeneralInfo.md new file mode 100644 index 00000000000..52cdbf5e81b --- /dev/null +++ b/3rdparty/ymfm/GeneralInfo.md @@ -0,0 +1,282 @@ +# ymfm: One FM core to rule them all + +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). + +The core assumption is that these details apply to all FM variants unless otherwise proven incorrect. + +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. + +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. + +## Families + +The Yamaha FM chips can be broadly categoried into families: + +* OPM (YM2151) + * OPP (YM2164) +* OPN (YM2203) + * OPNA/OPNB/OPN2 (YM2608, YM2610, YM2610B, YM2612, YM3438, YMF276, YMF288) +* OPL (YM3526) + * OPL2 (YM3812) + * OPLL (YM2413, YM2423, YMF281, DS1001, and others) + * OPL3 (YMF262, YMF289B) + * OPL4 (YMF278) + +Additionally, several lesser-documented variants exist exclusively in the employ of Yamaha synthesizers: + +* OPQ (YM3608) +* OPZ (YM2414) + +All of these families are very closely related, and the ymfm engine is designed to be universal to work across all of +these families. + +Of course, each variant has its own register maps, features, and implementation details which need to be sorted out. +Thus, each significant variant listed above is represented by a register class. +The register class contains: + +* constants describing core parameters and features +* mappers between operators and channels +* generic fetchers that return normalized values across families +* family-specific implementations of LFO and phase calculations + +## Family History + +This history outlines the progress of adding/removing features across the three main families (OPM, OPN, OPL): + +OPM started it all off, featuring: +* 8 FM channels, 4 operators each +* LFO and noise support +* Stereo output + +OPM -> OPN changes: +* Reduced to 3 FM channels, 4 operators each +* Removed LFO and noise support +* Mono output +* Integrated AY-8910 compatible PSG +* Added SSG-EG envelope mode +* Added multi-frequency mode: ch. 3 operators can have separate frequencies +* Software controlled clock divider + +OPN -> OPNA changes: +* Increased to 6 FM channels, 4 operators each +* Added back (a cut-down) LFO +* Stereo output again +* Removed software controlled divider on later versions (OPNB/OPN2) +* Removed PSG on OPN2 models + +OPNA -> OPL changes: +* Increased to 9 FM channels, but only 2 operators each +* Even more simplified LFO +* Mono output +* Removed PSG +* Removed SSG-EG envelope modes +* Removed multi-frequency modes +* Fixed clock divider +* Built-in ryhthm generation + +OPL -> OPL2 changes: +* Added 4 selectable waveforms + +OPL2 -> OPLL changes: +* Vastly simplified register map +* 15 built-in instruments, plus built-in rhythm instruments +* 1 user-controlled instrument + +OPL2 -> OPL3 changes: +* Increased to 18 FM channels, 2 operators each +* 4 output channels +* Increased to 8 selectable waveforms +* 6 channels can be configured to use 4 operators + +## Channels and Operators + +The polyphony of a given chip is determined by the number of channels it supports. +This number ranges from as low as 3 to as high as 18. +Each channel has either 2 or 4 operators that can be combined in a myriad of ways. +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. + +The base ymfm engine class maintains an array of channels and operators, while the relationship between the two is described by the register class. + +## Registers + +Registers on the Yamaha chips are generally write-only, and can be divided into three distinct categories: + +* system-wide registers +* channel-specific registers +* operator-specific registers + +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. +System-wide registers are used to control chip-wide modes and manage onboard timer functions. + +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. + +## Attenuation + +Most of the computations of the FM engines are done in terms of attenuation, and thus are logarithmic in nature. +The maximum resolution used internally is 12 bits, as returned by the sin table: + +Bit | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 +----|----|----|----|----|----|----|-----|------|-------|--------|---------|--------- + dB | -96| -48| -24| -12| -6| -3| -1.5| -0.75| -0.375| -0.1875| -0.09375| -0.046875 + +The envelope generator internally uses 10 bits: + +Bit | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +----|----|----|----|----|----|-----|------|-------|--------|---------| + dB | -48| -24| -12| -6| -3| -1.5| -0.75| -0.375| -0.1875| -0.09375| + +Total level for operators is usually represented by 7 bits: + +Bit | 6 | 5 | 4 | 3 | 2 | 1 | 0 | +----|----|----|----|----|----|-----|------| + dB | -48| -24| -12| -6| -3| -1.5| -0.75| + +Sustain level in the envelope generator is usually represented by 4 bits: + +Bit | 3 | 2 | 1 | 0 | +----|----|----|----|----| + dB | -24| -12| -6| -3| + +## Status and Timers + +Generically, all chips (except OPLL) support two timers that can be programmed to fire and signal IRQs. +These timers also set bits in the status register. +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). + +In addition, several chips incorporate ADPCM decoders which also may set bits in the same status register. +For this reason, it is possible to control various bits in the status register via the `set_reset_status()` function directly. +Any active bits that are set and which are not masked (mask is controlled by `set_irq_mask()`), lead to an IRQ being signalled. + +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. + +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. +Historically, the duration of this flag was constant and had nothing to do with the internals of the chip. +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. + +## Clocking + +Each of the Yamaha chips works by cycling through all operators one at a time. +Thus, the effective output rate of the chips is related to the input clock divided by the number of operators. +In addition, the input clock is prescaled by an amount. +Generally, this is a fixed value, though some early OPN chips allow this to be selected at runtime from a small +number of values. + +## Channel Frequencies + +One major difference between OPM and later families is in how frequencies are specified. +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'. +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. + +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. +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. + +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: + +* OPM: `[3-bit block]:[4-bit keycode]:[6-bit fraction] = 13 bits total` + +* OPZ: `[3-bit block]:[12-bit fnum] = 15 bits total` +* OPN: `[3-bit block]:[11-bit fnum] 0 = 15 bits total` +* OPL: `[3-bit block]:[10-bit fnum]:00 = 15 bits total` +* OPLL: `[3-bit block]:[ 9-bit fnum]:000 = 15 bits total` + +The register classes handle the raw format directly and convert it into a phase increment which can be used by the generic engine. + +## Low Frequency Oscillator (LFO) + +The LFO engines are different in several key ways. +The OPM LFO engine is fairly intricate. +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). +Separate 7-bit depth controls for AM and PM control the amount of modulation applied in each case. +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. + +For OPN the LFO engine was removed entirely, but a limited version was put back in OPNA and later chips. +This stripped-down version offered only a 3-bit rate setting (versus the 4.4 floating-point rate in OPN), and no +global depth control. +It did bring back the channel-level sensitivity controls and the operator-level on/off control. + +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. + +## Differences Between Families + +The table below provides some high level functional differences between the differnet families: + +subfamily: | OPM | OPN | OPNA | OPL | OPL2 | OPLL | OPL3 | +------------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:| +outputs: | 2 | 1 | 2 | 1 | 1 | 1 | 4 | +channels: | 8 | 3 | 6 | 9 | 9 | 9 | 18 | +operators: | 32 | 12 | 24 | 18 | 18 | 18 | 36 | +waveforms: | 1 | 1 | 1 | 1 | 4 | 2 | 8 | +instruments: | no | no | no | yes | yes | yes | yes | +ryhthm: | no | no | no | no | no | yes | no | +dynamic ops: | no | no | no | no | no | no | yes | +prescale: | 2 | 2/3/6 | 2/3/6 | 4 | 4 | 4 | 8 | +EG divider: | 3 | 3 | 3 | 1 | 1 | 1 | 1 | +EG DP: | no | no | no | no | no | yes | no | +EG SSG: | no | yes | yes | no | no | no | no | +mod delay: | no | no | no | yes | yes | yes? | no | +CSM: | yes | ch 2 | ch 2 | yes | yes | yes | no | +LFO: | yes | no | yes | yes | yes | yes | yes | +noise: | yes | no | no | no | no | no | no | + +* Outputs represents the number of output channels: 1=mono, 2=stereo, 4=stereo+. +* Channels represents the number of independent FM channels. +* Operators represents the number of operators, or "slots" which are assembled into the channels. +* Waveforms represents the number of different sine-derived waveforms available. +* Instruments indicates whether the family has built-in instruments. +* Rhythm indicates whether the family has a built-in rhythm +* Dynamic ops indicates whether it is possible to switch between 2-operator and 4-operator modes dynamically. +* Prescale specifies the default clock divider; some chips allow this to be controlled via register writes. +* EG divider represents the divider applied to the envelope generator clock. +* EG DP indicates whether the envelope generator includes a DP (depress?) phase at the beginning of each key on. +* SSG EG indicates whether the envelope generator has SSG-style support. +* Mod delay indicates whether the connection to the first modulator's input is delayed by 1 sample. +* CSM indicates whether CSM mode is supported, triggered by timer A. +* LFO indicates whether LFO is supported. +* Noise indicates whether one of the operators can be replaced with a noise source. + +## Chip Specifics + +While OPM is its own thing, the OPN and OPL families have quite a few specific +implementations, with many differing details beyond the core FM parts. Here are +some details on the OPN family: + +chip ID: | YM2203 | YM2608 | YMF288 | YM2610 | YM2610B | YM2612 | YM3438 | YMF276 | +---------:|:------:|:------:|:------:|:------:|:-------:|:------:|:------:|:------:| +aka: | OPN | OPNA | OPN3L | OPNB | OPNB2 | OPN2 | OPN2C | OPN2L | +FM: | 3 | 6 | 6 | 4 | 6 | 6 | 6 | 6 | +AY-8910: | 3 | 1 | 1 | 1 | 1 | - | - | - | +ADPCM-A: | - | 6 int | 6 int | 6 ext | 6 ext | - | - | - | +ADPCM-B: | - | 1 ext | - | 1 ext | 1 ext | - | - | - | +DAC: | no | no | no | no | no | yes | yes | yes | +output: | 10.3fp | 16-bit | 16-bit | 16-bit | 16-bit | 9-bit | 9-bit | 16-bit | +summing: | adder | adder | adder | adder | adder | muxer | muxer | adder | + +* FM represents the number of FM channels available. +* AY-8910 represents the number of AY-8910-compatible outputs. +* ADPCM-A represents the number of internal/external ADPCM-A channels present. +* ADPCM-B represents the number of internal/external ADPCM-B channels present. +* DAC indicates if a directly-accessible DAC output exists, replacing one channel. +* Output indicates the output format to the final DAC. +* Summing indicates whether channels are added or time divided in the output. + +OPL has a similar trove of chip variants: + +chip ID: | YM3526 | Y8950 | YM3812 | YM2413 | YMF262 | YMF289B | YMF278B | +------------:|:------:|:-------:|:------:|:------:|:------:|:-------:|:-------:| +aka: | OPL |MSX-AUDIO| OPL2 | OPLL | OPL3 | OPL3L | OPL4 | +FM: | 9 | 9 | 9 | 9 | 18 | 18 | 18 | +ADPCM-B: | - | 1 ext | - | - | - | - | - | +wavetable: | - | - | - | - | - | - | 24 | +instruments: | no | no | no | yes | no | no | no | +output: | 10.3fp | 10.3fp | 10.3fp | 9-bit | 16-bit | 16-bit | 16-bit | +summing: | adder | adder | adder | muxer | adder | adder | adder | + +* FM represents the number of FM channels available. +* ADPCM-B represents the number of external ADPCM-B channels present. +* Wavetable indicates the number of wavetable channels present. +* Instruments indicates that the chip has built-in instrument selection. +* Output indicates the output format to the final DAC. +* Summing indicates whether channels are added or time divided in the output. + +There are several close variants of the YM2413 with different sets of built-in instruments. +These include the YM2423, YMF281, and DS1001 (aka Konami VRC7). |