| 1 |
# ymfm |
| 2 |
|
| 3 |
<div style='text-align:center;margin:auto'> |
| 4 |
<img src='https://aarongiles.com/img/icon-ymfm.png' width='128px'> |
| 5 |
</div> |
| 6 |
|
| 7 |
[ymfm](https://github.com/aaronsgiles/ymfm) is a collection of BSD-licensed Yamaha FM sound cores (OPM, OPN, OPL, and others), written by [Aaron Giles](https://aarongiles.com) |
| 8 |
|
| 9 |
## Supported environments |
| 10 |
|
| 11 |
This code should compile cleanly in any environment that has C++14 support. |
| 12 |
It has been tested on gcc, clang, and Microsoft Visual C++ 2019. |
| 13 |
|
| 14 |
## Supported chip families |
| 15 |
|
| 16 |
Currently, support is present for the following chips (organized by header file): |
| 17 |
|
| 18 |
* ymfm_misc.h: |
| 19 |
* YM2149 (SSG) [1983: MSX; Atari ST] |
| 20 |
* ymfm_opm.h: |
| 21 |
* YM2151 (OPM) [1983: Sharp X1, X68000; MSX; synths: DX21, DX27, DX100] |
| 22 |
* YM2164 (OPP) [1985: FB-01 MIDI Expander; IBM Music Feature Card; MSX; synths: Korg DS-8, 707] |
| 23 |
* ymfm_opn.h: |
| 24 |
* YM2203 (OPN) [1984: NEC PC-88, PC-98, NEC PC-6001mkII SR, PC-6601 SR] |
| 25 |
* YM2608 (OPNA) [1985: NEC PC-88, PC-98] |
| 26 |
* YM2610 (OPNB) [1987: Neo Geo] |
| 27 |
* YM2610B (OPNB2) |
| 28 |
* YM2612 (OPN2) [1988: Sega Mega Drive/Genesis; FM Towns] |
| 29 |
* YM3438 (OPN2C) |
| 30 |
* YMF276 (OPN2L) |
| 31 |
* YMF288 (OPN3L) [1995: NEC PC-98] |
| 32 |
* ymfm_opl.h: |
| 33 |
* YM3526 (OPL) [1984: C64 SFX Sound Expander] |
| 34 |
* Y8950 (MSX-Audio) [1984: MSX] |
| 35 |
* YM3812 (OPL2) [1985: AdLib, Sound Blaster; synths: some Portasound keyboards] |
| 36 |
* YMF262 (OPL3) [1988: Sound Blaster Pro 2.0, SB16] |
| 37 |
* YMF289B (OPL3L) |
| 38 |
* YMF278B (OPL4) [1993: MSX Moonsound cartridge] |
| 39 |
* YM2413 (OPLL) [1986: Sega Master System, Mark III; MSX; synths: Portasound PSS-140, PSS-170, PSS-270] |
| 40 |
* YM2423 (OPLL-X) |
| 41 |
* YMF281 (OPLLP) |
| 42 |
* DS1001 (Konami 053982/VRC7) [1991: Famicom cartridge Lagrange Point] |
| 43 |
* ymfm_opq.h: |
| 44 |
* YM3806 (OPQ) [synths: PSR-60/70] |
| 45 |
* ymfm_opz.h: |
| 46 |
* YM2414 (OPZ) [1987: synths: TX81Z, DX11, YS200; Korg Z3 guitar synth] |
| 47 |
|
| 48 |
There are some obviously-related chips that also are on my horizon but have no implementation as yet: |
| 49 |
|
| 50 |
* YMW-258-F 'GEW8' (aka Sega 315-5560 aka Sega Multi-PCM) |
| 51 |
* YMF271 (OPX) |
| 52 |
* YM21280 (OPS) / YM21290 (EGS) [synths: DX7, DX1, DX5, DX9, TX7, TX216, TX416, TX816] |
| 53 |
* OPK? |
| 54 |
|
| 55 |
## History |
| 56 |
|
| 57 |
These cores were originally written during the summer and fall of 2020 as part of the [MAME](https://mamedev.org/) project. |
| 58 |
As such, their design started off heavily based on how MAME works. |
| 59 |
|
| 60 |
The OPM/OPN cores first appeared in MAME 0.230. |
| 61 |
The OPL cores were added in MAME 0.231. |
| 62 |
A further rewrite to abstract MAME dependencies is planned for MAME 0.232. |
| 63 |
|
| 64 |
The goal was threefold: |
| 65 |
1. provide BSD-licensed emulation cores that are more compatible with MAME's core licensing |
| 66 |
1. modernize and unify the code around a common implementation of shared features |
| 67 |
1. improve accuracy where possible based on discoveries made by others |
| 68 |
|
| 69 |
## Accuracy |
| 70 |
|
| 71 |
The goal of these cores is not 100% digital accuracy. |
| 72 |
To achieve that would require full emulation of the pipelines, which would make the code extremely difficult to comprehend. |
| 73 |
It would also make it much harder to share common implementations of features, or to add support for less well-known chip types. |
| 74 |
If you want that level of accuracy, there are [several](https://github.com/nukeykt/Nuked-OPN2) [decap-based](https://github.com/nukeykt/Nuked-OPM) [emulation cores](https://github.com/nukeykt/Nuked-OPLL) out there. |
| 75 |
|
| 76 |
Instead, the main goals are: |
| 77 |
1. Extremely high (audibly indistinguishable) accuracy |
| 78 |
1. Reasonable performance |
| 79 |
1. Clean design with readable code |
| 80 |
1. Clear documentation of the various chips |
| 81 |
|
| 82 |
## General approach |
| 83 |
|
| 84 |
Check out the [examples directory](https://github.com/aaronsgiles/ymfm/tree/main/examples) for some example usage patterns. |
| 85 |
I'm not a big fan of makefiles for simple things, so instructions on how to compile each example are provided at the top. |
| 86 |
|
| 87 |
# IMPORTANT |
| 88 |
|
| 89 |
As of May 2021, the interface to these is still a bit in flux. |
| 90 |
Be prepared when syncing with upstream to make some adjustments. |
| 91 |
|
| 92 |
### Clocking |
| 93 |
|
| 94 |
The general philosophy of the emulators provided here is that they are clock-independent. |
| 95 |
Much like the actual chips, you (the consumer) control the clock; the chips themselves have no idea what time it is. |
| 96 |
They just tick forward each time you ask them to. |
| 97 |
|
| 98 |
The way you move things along is via the `generate()` function, which ticks the internal system forward one or more samples, and writes out an array out chip-specific `output_data`. |
| 99 |
But what, exactly, is a "sample", and how long is it? |
| 100 |
|
| 101 |
This is where the external clock comes in. |
| 102 |
Most of the Yamaha chips are externally clocked in the MHz range. |
| 103 |
They then divide that clock by a factor (sometimes dynamically controllable), and then the internal operators are pipelined to further divide the clock. |
| 104 |
|
| 105 |
For example, the YM2151 internally divides the clock by 2, and has 32 operators to iterate through. |
| 106 |
Thus, for a nominal input lock of 3.58MHz, you end up at around a 55.9kHz sample rate. |
| 107 |
Fortunately, all the chip implementations can compute this for you; just pass the raw external clock value to the `sample_rate()` method and it will hand you back the output sample rate you want. |
| 108 |
|
| 109 |
Then call `generate()` that many times per second to output the results. |
| 110 |
|
| 111 |
But what if I want to output at a "normal" rate, like 44.1kHz? |
| 112 |
Sorry, you'll have to rate convert as needed. |
| 113 |
|
| 114 |
### Reading and Writing |
| 115 |
|
| 116 |
To read or write to the chips, you can call the `read()` and `write()` methods. |
| 117 |
The offset provided corresponds to the addressing input lines in a (hopefully) logical way. |
| 118 |
|
| 119 |
For reads, almost all chips have a status register, which you can read via `read_status()`. |
| 120 |
Some chips have a data port that can be read via `read_data()`. |
| 121 |
And chips with extended addressing may also have `read_status_hi()` and `read_data_hi()`. |
| 122 |
|
| 123 |
For writes, almost all chips have an address register and a data register, and so you can reliably count on there being a `write_address()` and `write_data()` method as well. |
| 124 |
If the chip supports extended addressing, it may also have `write_address_hi()` and `write_data_hi()`. |
| 125 |
|