Debian Codegraph @

extern/ESFMu/esfm.h

raw
1 /*
2 * ESFMu: emulator for the ESS "ESFM" enhanced OPL3 clone
3 * Copyright (C) 2023 Kagamiin~
4 *
5 * ESFMu is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU Lesser General Public License as
7 * published by the Free Software Foundation, either version 2.1
8 * of the License, or (at your option) any later version.
9 *
10 * ESFMu is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public License
16 * along with ESFMu. If not, see <https://www.gnu.org/licenses/>.
17 */
18
19 /*
20 * ESFMu wouldn't have been possible without the hard work and dedication of
21 * the retro computer hardware research and preservation community.
22 *
23 * I'd like to thank:
24 * - Nuke.YKT
25 * Developer of Nuked OPL3, which was the basis for ESFMu's code and
26 * also a great learning resource on Yamaha FM synthesis for myself.
27 * Nuke.YKT also gives shoutouts on behalf of Nuked OPL3 to:
28 * - MAME Development Team(Jarek Burczynski, Tatsuyuki Satoh):
29 * Feedback and Rhythm part calculation information.
30 * - forums.submarine.org.uk(carbon14, opl3):
31 * Tremolo and phase generator calculation information.
32 * - OPLx decapsulated(Matthew Gambrell, Olli Niemitalo):
33 * OPL2 ROMs.
34 * - siliconpr0n.org(John McMaster, digshadow):
35 * YMF262 and VRC VII decaps and die shots.
36 * - rainwarrior
37 * For performing the initial research on ESFM drivers and documenting
38 * ESS's patent on native mode operator organization.
39 * - jwt27
40 * For kickstarting the ESFM research project and compiling rainwarrior's
41 * findings and more in an accessible document ("ESFM Demystified").
42 * - pachuco/CatButts
43 * For documenting ESS's patent on ESFM's feedback implementation, which
44 * was vital in getting ESFMu's sound output to be accurate.
45 * - And everybody who helped out with real hardware testing
46 */
47
48 #include <stddef.h>
49 #include <stdint.h>
50
51 #ifdef __cplusplus
52 extern "C" {
53 #endif
54
55 typedef struct _esfm_slot esfm_slot;
56 typedef struct _esfm_slot_internal esfm_slot_internal;
57 typedef struct _esfm_channel esfm_channel;
58 typedef struct _esfm_chip esfm_chip;
59
60
61 void ESFM_init (esfm_chip *chip, uint8_t fast);
62 void ESFM_write_reg (esfm_chip *chip, uint16_t address, uint8_t data);
63 void ESFM_write_reg_buffered (esfm_chip *chip, uint16_t address, uint8_t data);
64 void ESFM_write_reg_buffered_fast (esfm_chip *chip, uint16_t address, uint8_t data);
65 void ESFM_write_port (esfm_chip *chip, uint8_t offset, uint8_t data);
66 uint8_t ESFM_readback_reg (esfm_chip *chip, uint16_t address);
67 uint8_t ESFM_read_port (esfm_chip *chip, uint8_t offset);
68 void ESFM_generate(esfm_chip *chip, int16_t *buf);
69 void ESFM_generate_stream(esfm_chip *chip, int16_t *sndptr, uint32_t num_samples);
70 int16_t ESFM_get_channel_output_native(esfm_chip *chip, int channel_idx);
71
72
73 // These are fake types just for syntax sugar.
74 // Beware of their underlying types when reading/writing to them.
75 typedef uint8_t flag;
76 typedef uint8_t uint2;
77 typedef uint8_t uint3;
78 typedef uint8_t uint4;
79 typedef uint8_t uint5;
80 typedef uint8_t uint6;
81 typedef uint8_t uint8;
82 typedef uint16_t uint9;
83 typedef uint16_t uint10;
84 typedef uint16_t uint11;
85 typedef uint16_t uint12;
86 typedef uint16_t uint16;
87 typedef uint32_t uint19;
88 typedef uint32_t uint23;
89 typedef uint32_t uint32;
90 typedef uint64_t uint36;
91
92 typedef int16_t int13;
93 typedef int16_t int14;
94 typedef int16_t int16;
95 typedef int32_t int32;
96
97 enum eg_states
98 {
99 EG_ATTACK,
100 EG_DECAY,
101 EG_SUSTAIN,
102 EG_RELEASE
103 };
104
105
106 typedef struct _esfm_write_buf
107 {
108 uint64_t timestamp;
109 uint16_t address;
110 uint8_t data;
111 flag valid;
112
113 } esfm_write_buf;
114
115 typedef struct _emu_slot_channel_mapping
116 {
117 int channel_idx;
118 int slot_idx;
119
120 } emu_slot_channel_mapping;
121
122 typedef struct _esfm_slot_internal
123 {
124 uint9 eg_position;
125 uint9 eg_ksl_offset;
126 uint10 eg_output;
127
128 uint4 keyscale;
129
130 int13 output;
131 int13 emu_output_enable;
132 int13 emu_mod_enable;
133 int13 feedback_buf;
134 int13 *mod_input;
135
136 uint19 phase_acc;
137 uint10 phase_out;
138 flag phase_reset;
139 flag *key_on;
140 flag key_on_gate;
141
142 uint2 eg_state;
143 flag eg_delay_run;
144 flag eg_delay_transitioned_10;
145 flag eg_delay_transitioned_10_gate;
146 flag eg_delay_transitioned_01;
147 flag eg_delay_transitioned_01_gate;
148 uint16 eg_delay_counter;
149 uint16 eg_delay_counter_compare;
150
151 uint16 fb_out0;
152 uint16 fb_out1;
153 } esfm_slot_internal;
154
155 struct _esfm_slot
156 {
157 // Metadata
158 esfm_channel *channel;
159 esfm_chip *chip;
160 uint2 slot_idx;
161
162 // Register data
163 int13 out_enable[2];
164 uint10 f_num;
165 uint3 block;
166 uint3 output_level;
167 // a.k.a. feedback level in emu mode
168 uint3 mod_in_level;
169
170 uint6 t_level;
171 uint4 mult;
172 uint3 waveform;
173 // Only for 4th slot
174 uint2 rhy_noise;
175
176 uint4 attack_rate;
177 uint4 decay_rate;
178 uint4 sustain_lvl;
179 uint4 release_rate;
180
181 flag tremolo_en;
182 flag tremolo_deep;
183 flag vibrato_en;
184 flag vibrato_deep;
185 flag emu_connection_typ;
186 flag env_sustaining;
187 flag ksr;
188 uint2 ksl;
189 uint3 env_delay;
190 // overlaps with env_delay bit 0
191 // TODO: check if emu mode only uses this, or if it actually overwrites the channel field used by native mode
192 flag emu_key_on;
193
194 // Internal state
195 esfm_slot_internal in;
196 };
197
198 struct _esfm_channel
199 {
200 esfm_chip *chip;
201 esfm_slot slots[4];
202 uint5 channel_idx;
203 int16 output[2];
204 flag key_on;
205 flag emu_mode_4op_enable;
206 // Only for 17th and 18th channels
207 flag key_on_2;
208 flag emu_mode_4op_enable_2;
209 };
210
211 #define ESFM_WRITEBUF_SIZE 1024
212 #define ESFM_WRITEBUF_DELAY 2
213
214 struct _esfm_chip
215 {
216 esfm_channel channels[18];
217 int32 output_accm[2];
218 uint_fast16_t addr_latch;
219
220 flag emu_wavesel_enable;
221 flag emu_newmode;
222 flag native_mode;
223
224 flag keyscale_mode;
225
226 // Global state
227 uint36 eg_timer;
228 uint10 global_timer;
229 uint8 eg_clocks;
230 flag eg_tick;
231 flag eg_timer_overflow;
232 uint8 tremolo;
233 uint8 tremolo_pos;
234 uint8 vibrato_pos;
235 uint23 lfsr;
236
237 flag rm_hh_bit2;
238 flag rm_hh_bit3;
239 flag rm_hh_bit7;
240 flag rm_hh_bit8;
241 flag rm_tc_bit3;
242 flag rm_tc_bit5;
243
244 // 0xbd register in emulation mode, exposed in 0x4bd in native mode
245 // ("bass drum" register)
246 uint8 emu_rhy_mode_flags;
247
248 flag emu_vibrato_deep;
249 flag emu_tremolo_deep;
250
251 uint8 timer_reload[2];
252 uint8 timer_counter[2];
253 flag timer_enable[2];
254 flag timer_mask[2];
255 flag timer_overflow[2];
256 flag irq_bit;
257
258 // Halts the envelope generators from advancing.
259 flag test_bit_eg_halt;
260 /*
261 * Activates some sort of waveform test mode that amplifies the output volume greatly
262 * and continuously shifts the waveform table downwards, possibly also outputting the
263 * waveform's derivative? (it's so weird!)
264 */
265 flag test_bit_distort;
266 // Appears to attenuate the output by about 3 dB.
267 flag test_bit_attenuate;
268 // Resets all phase generators and holds them in the reset state while this bit is set.
269 flag test_bit_phase_stop_reset;
270
271 esfm_write_buf write_buf[ESFM_WRITEBUF_SIZE];
272 size_t write_buf_start;
273 size_t write_buf_end;
274 uint64_t write_buf_timestamp;
275
276 flag fast_mode;
277 };
278
279 #ifdef __cplusplus
280 }
281 #endif