Debian Codegraph @

BambooTracker/chip/ymfm/README.md

raw
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