summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/ymfm/GeneralInfo.md
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/ymfm/GeneralInfo.md')
-rw-r--r--3rdparty/ymfm/GeneralInfo.md282
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).