Debian Codegraph @

BambooTracker/chip/ymfm/ymfm.h

raw
1 // BSD 3-Clause License
2 //
3 // Copyright (c) 2021, Aaron Giles
4 // All rights reserved.
5 //
6 // Redistribution and use in source and binary forms, with or without
7 // modification, are permitted provided that the following conditions are met:
8 //
9 // 1. Redistributions of source code must retain the above copyright notice, this
10 // list of conditions and the following disclaimer.
11 //
12 // 2. Redistributions in binary form must reproduce the above copyright notice,
13 // this list of conditions and the following disclaimer in the documentation
14 // and/or other materials provided with the distribution.
15 //
16 // 3. Neither the name of the copyright holder nor the names of its
17 // contributors may be used to endorse or promote products derived from
18 // this software without specific prior written permission.
19 //
20 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23 // DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24 // FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 // DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26 // SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27 // CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28 // OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
31 #ifndef YMFM_H
32 #define YMFM_H
33
34 #pragma once
35
36 #if defined(_MSC_VER) && !defined(_CRT_SECURE_NO_WARNINGS)
37 #define _CRT_SECURE_NO_WARNINGS
38 #endif
39
40 #include <cassert>
41 #include <cstdint>
42 #include <cstdio>
43 #include <cstring>
44 #include <algorithm>
45 #include <memory>
46 #include <string>
47 #include <vector>
48
49 namespace ymfm
50 {
51
52 //*********************************************************
53 // DEBUGGING
54 //*********************************************************
55
56 class debug
57 {
58 public:
59 // masks to help isolate specific channels
60 static constexpr uint32_t GLOBAL_FM_CHANNEL_MASK = 0xffffffff;
61 static constexpr uint32_t GLOBAL_ADPCM_A_CHANNEL_MASK = 0xffffffff;
62 static constexpr uint32_t GLOBAL_ADPCM_B_CHANNEL_MASK = 0xffffffff;
63 static constexpr uint32_t GLOBAL_PCM_CHANNEL_MASK = 0xffffffff;
64
65 // types of logging
66 static constexpr bool LOG_FM_WRITES = false;
67 static constexpr bool LOG_KEYON_EVENTS = false;
68 static constexpr bool LOG_UNEXPECTED_READ_WRITES = false;
69
70 // helpers to write based on the log type
71 template<typename... Params> static void log_fm_write(Params &&... args) { if (LOG_FM_WRITES) log(args...); }
72 template<typename... Params> static void log_keyon(Params &&... args) { if (LOG_KEYON_EVENTS) log(args...); }
73 template<typename... Params> static void log_unexpected_read_write(Params &&... args) { if (LOG_UNEXPECTED_READ_WRITES) log(args...); }
74
75 // downstream helper to output log data; defaults to printf
76 template<typename... Params> static void log(Params &&... args) { printf(args...); }
77 };
78
79
80
81 //*********************************************************
82 // GLOBAL HELPERS
83 //*********************************************************
84
85 //-------------------------------------------------
86 // bitfield - extract a bitfield from the given
87 // value, starting at bit 'start' for a length of
88 // 'length' bits
89 //-------------------------------------------------
90
91 inline uint32_t bitfield(uint32_t value, int start, int length = 1)
92 {
93 return (value >> start) & ((1 << length) - 1);
94 }
95
96
97 //-------------------------------------------------
98 // clamp - clamp between the minimum and maximum
99 // values provided
100 //-------------------------------------------------
101
102 inline int32_t clamp(int32_t value, int32_t minval, int32_t maxval)
103 {
104 if (value < minval)
105 return minval;
106 if (value > maxval)
107 return maxval;
108 return value;
109 }
110
111
112 //-------------------------------------------------
113 // array_size - return the size of an array
114 //-------------------------------------------------
115
116 template<typename ArrayType, int ArraySize>
117 constexpr uint32_t array_size(ArrayType (&/*array*/)[ArraySize])
118 {
119 return ArraySize;
120 }
121
122
123 //-------------------------------------------------
124 // count_leading_zeros - return the number of
125 // leading zeros in a 32-bit value; CPU-optimized
126 // versions for various architectures are included
127 // below
128 //-------------------------------------------------
129
130 #if defined(__GNUC__)
131
132 inline uint8_t count_leading_zeros(uint32_t value)
133 {
134 if (value == 0)
135 return 32;
136 return __builtin_clz(value);
137 }
138
139 #elif defined(_MSC_VER)
140
141 inline uint8_t count_leading_zeros(uint32_t value)
142 {
143 unsigned long index;
144 return _BitScanReverse(&index, value) ? uint8_t(31U - index) : 32U;
145 }
146
147 #else
148
149 inline uint8_t count_leading_zeros(uint32_t value)
150 {
151 if (value == 0)
152 return 32;
153 uint8_t count;
154 for (count = 0; int32_t(value) >= 0; count++)
155 value <<= 1;
156 return count;
157 }
158
159 #endif
160
161
162 // Many of the Yamaha FM chips emit a floating-point value, which is sent to
163 // a DAC for processing. The exact format of this floating-point value is
164 // documented below. This description only makes sense if the "internal"
165 // format treats sign as 1=positive and 0=negative, so the helpers below
166 // presume that.
167 //
168 // Internal OPx data 16-bit signed data Exp Sign Mantissa
169 // ================= ================= === ==== ========
170 // 1 1xxxxxxxx------ -> 0 1xxxxxxxx------ -> 111 1 1xxxxxxx
171 // 1 01xxxxxxxx----- -> 0 01xxxxxxxx----- -> 110 1 1xxxxxxx
172 // 1 001xxxxxxxx---- -> 0 001xxxxxxxx---- -> 101 1 1xxxxxxx
173 // 1 0001xxxxxxxx--- -> 0 0001xxxxxxxx--- -> 100 1 1xxxxxxx
174 // 1 00001xxxxxxxx-- -> 0 00001xxxxxxxx-- -> 011 1 1xxxxxxx
175 // 1 000001xxxxxxxx- -> 0 000001xxxxxxxx- -> 010 1 1xxxxxxx
176 // 1 000000xxxxxxxxx -> 0 000000xxxxxxxxx -> 001 1 xxxxxxxx
177 // 0 111111xxxxxxxxx -> 1 111111xxxxxxxxx -> 001 0 xxxxxxxx
178 // 0 111110xxxxxxxx- -> 1 111110xxxxxxxx- -> 010 0 0xxxxxxx
179 // 0 11110xxxxxxxx-- -> 1 11110xxxxxxxx-- -> 011 0 0xxxxxxx
180 // 0 1110xxxxxxxx--- -> 1 1110xxxxxxxx--- -> 100 0 0xxxxxxx
181 // 0 110xxxxxxxx---- -> 1 110xxxxxxxx---- -> 101 0 0xxxxxxx
182 // 0 10xxxxxxxx----- -> 1 10xxxxxxxx----- -> 110 0 0xxxxxxx
183 // 0 0xxxxxxxx------ -> 1 0xxxxxxxx------ -> 111 0 0xxxxxxx
184
185 //-------------------------------------------------
186 // encode_fp - given a 32-bit signed input value
187 // convert it to a signed 3.10 floating-point
188 // value
189 //-------------------------------------------------
190
191 inline int16_t encode_fp(int32_t value)
192 {
193 // handle overflows first
194 if (value < -32768)
195 return (7 << 10) | 0x000;
196 if (value > 32767)
197 return (7 << 10) | 0x3ff;
198
199 // we need to count the number of leading sign bits after the sign
200 // we can use count_leading_zeros if we invert negative values
201 int32_t scanvalue = value ^ (int32_t(value) >> 31);
202
203 // exponent is related to the number of leading bits starting from bit 14
204 int exponent = 7 - count_leading_zeros(scanvalue << 17);
205
206 // smallest exponent value allowed is 1
207 exponent = std::max(exponent, 1);
208
209 // mantissa
210 int32_t mantissa = value >> (exponent - 1);
211
212 // assemble into final form, inverting the sign
213 return ((exponent << 10) | (mantissa & 0x3ff)) ^ 0x200;
214 }
215
216
217 //-------------------------------------------------
218 // decode_fp - given a 3.10 floating-point value,
219 // convert it to a signed 16-bit value
220 //-------------------------------------------------
221
222 inline int16_t decode_fp(int16_t value)
223 {
224 // invert the sign and the exponent
225 value ^= 0x1e00;
226
227 // shift mantissa up to 16 bits then apply inverted exponent
228 return int16_t(value << 6) >> bitfield(value, 10, 3);
229 }
230
231
232 //-------------------------------------------------
233 // roundtrip_fp - compute the result of a round
234 // trip through the encode/decode process above
235 //-------------------------------------------------
236
237 inline int16_t roundtrip_fp(int32_t value)
238 {
239 // handle overflows first
240 if (value < -32768)
241 return -32768;
242 if (value > 32767)
243 return 32767;
244
245 // we need to count the number of leading sign bits after the sign
246 // we can use count_leading_zeros if we invert negative values
247 int32_t scanvalue = value ^ (int32_t(value) >> 31);
248
249 // exponent is related to the number of leading bits starting from bit 14
250 int exponent = 7 - count_leading_zeros(scanvalue << 17);
251
252 // smallest exponent value allowed is 1
253 exponent = std::max(exponent, 1);
254
255 // apply the shift back and forth to zero out bits that are lost
256 exponent -= 1;
257 return (value >> exponent) << exponent;
258 }
259
260
261
262 //*********************************************************
263 // HELPER CLASSES
264 //*********************************************************
265
266 // various envelope states
267 enum envelope_state : uint32_t
268 {
269 EG_DEPRESS = 0, // OPLL only; set EG_HAS_DEPRESS to enable
270 EG_ATTACK = 1,
271 EG_DECAY = 2,
272 EG_SUSTAIN = 3,
273 EG_RELEASE = 4,
274 EG_REVERB = 5, // OPQ/OPZ only; set EG_HAS_REVERB to enable
275 EG_STATES = 6
276 };
277
278 // external I/O access classes
279 enum access_class : uint32_t
280 {
281 ACCESS_IO = 0,
282 ACCESS_ADPCM_A,
283 ACCESS_ADPCM_B,
284 ACCESS_PCM,
285 ACCESS_CLASSES
286 };
287
288
289
290 //*********************************************************
291 // HELPER CLASSES
292 //*********************************************************
293
294 // ======================> ymfm_output
295
296 // struct containing an array of output values
297 template<int NumOutputs>
298 struct ymfm_output
299 {
300 // clear all outputs to 0
301 ymfm_output &clear()
302 {
303 for (uint32_t index = 0; index < NumOutputs; index++)
304 data[index] = 0;
305 return *this;
306 }
307
308 // clamp all outputs to a 16-bit signed value
309 ymfm_output &clamp16()
310 {
311 for (uint32_t index = 0; index < NumOutputs; index++)
312 data[index] = clamp(data[index], -32768, 32767);
313 return *this;
314 }
315
316 // run each output value through the floating-point processor
317 ymfm_output &roundtrip_fp()
318 {
319 for (uint32_t index = 0; index < NumOutputs; index++)
320 data[index] = ymfm::roundtrip_fp(data[index]);
321 return *this;
322 }
323
324 // internal state
325 int32_t data[NumOutputs];
326 };
327
328
329 // ======================> ymfm_wavfile
330
331 // this class is a debugging helper that accumulates data and writes it to wav files
332 template<int _Channels>
333 class ymfm_wavfile
334 {
335 public:
336 // construction
337 ymfm_wavfile(uint32_t samplerate = 44100) :
338 m_samplerate(samplerate)
339 {
340 }
341
342 // configuration
343 ymfm_wavfile &set_index(uint32_t index) { m_index = index; return *this; }
344 ymfm_wavfile &set_samplerate(uint32_t samplerate) { m_samplerate = samplerate; return *this; }
345
346 // destruction
347 ~ymfm_wavfile()
348 {
349 if (!m_buffer.empty())
350 {
351 // create file
352 char name[20];
353 sprintf(name, "wavlog-%02d.wav", m_index);
354 FILE *out = fopen(name, "wb");
355
356 // make the wav file header
357 uint8_t header[44];
358 std::memcpy(&header[0], "RIFF", 4);
359 *(uint32_t *)&header[4] = m_buffer.size() * 2 + 44 - 8;
360 std::memcpy(&header[8], "WAVE", 4);
361 std::memcpy(&header[12], "fmt ", 4);
362 *(uint32_t *)&header[16] = 16;
363 *(uint16_t *)&header[20] = 1;
364 *(uint16_t *)&header[22] = _Channels;
365 *(uint32_t *)&header[24] = m_samplerate;
366 *(uint32_t *)&header[28] = m_samplerate * 2 * _Channels;
367 *(uint16_t *)&header[32] = 2 * _Channels;
368 *(uint16_t *)&header[34] = 16;
369 std::memcpy(&header[36], "data", 4);
370 *(uint32_t *)&header[40] = m_buffer.size() * 2 + 44 - 44;
371
372 // write header then data
373 fwrite(&header[0], 1, sizeof(header), out);
374 fwrite(&m_buffer[0], 2, m_buffer.size(), out);
375 fclose(out);
376 }
377 }
378
379 // add data to the file
380 template<int _Outputs>
381 void add(ymfm_output<_Outputs> output)
382 {
383 int16_t sum[_Channels] = { 0 };
384 for (int index = 0; index < _Outputs; index++)
385 sum[index % _Channels] += output.data[index];
386 for (int index = 0; index < _Channels; index++)
387 m_buffer.push_back(sum[index]);
388 }
389
390 // add data to the file, using a reference
391 template<int _Outputs>
392 void add(ymfm_output<_Outputs> output, ymfm_output<_Outputs> const &ref)
393 {
394 int16_t sum[_Channels] = { 0 };
395 for (int index = 0; index < _Outputs; index++)
396 sum[index % _Channels] += output.data[index] - ref.data[index];
397 for (int index = 0; index < _Channels; index++)
398 m_buffer.push_back(sum[index]);
399 }
400
401 private:
402 // internal state
403 uint32_t m_index;
404 uint32_t m_samplerate;
405 std::vector<int16_t> m_buffer;
406 };
407
408
409 // ======================> ymfm_saved_state
410
411 // this class contains a managed vector of bytes that is used to save and
412 // restore state
413 class ymfm_saved_state
414 {
415 public:
416 // construction
417 ymfm_saved_state(std::vector<uint8_t> &buffer, bool saving) :
418 m_buffer(buffer),
419 m_offset(saving ? -1 : 0)
420 {
421 if (saving)
422 buffer.resize(0);
423 }
424
425 // are we saving or restoring?
426 bool saving() const { return (m_offset < 0); }
427
428 // generic save/restore
429 template<typename DataType>
430 void save_restore(DataType &data)
431 {
432 if (saving())
433 save(data);
434 else
435 restore(data);
436 }
437
438 public:
439 // save data to the buffer
440 void save(bool &data) { write(data ? 1 : 0); }
441 void save(int8_t &data) { write(data); }
442 void save(uint8_t &data) { write(data); }
443 void save(int16_t &data) { write(uint8_t(data)).write(data >> 8); }
444 void save(uint16_t &data) { write(uint8_t(data)).write(data >> 8); }
445 void save(int32_t &data) { write(data).write(data >> 8).write(data >> 16).write(data >> 24); }
446 void save(uint32_t &data) { write(data).write(data >> 8).write(data >> 16).write(data >> 24); }
447 void save(envelope_state &data) { write(uint8_t(data)); }
448 template<typename DataType, int Count>
449 void save(DataType (&data)[Count]) { for (uint32_t index = 0; index < Count; index++) save(data[index]); }
450
451 // restore data from the buffer
452 void restore(bool &data) { data = read() ? true : false; }
453 void restore(int8_t &data) { data = read(); }
454 void restore(uint8_t &data) { data = read(); }
455 void restore(int16_t &data) { data = read(); data |= read() << 8; }
456 void restore(uint16_t &data) { data = read(); data |= read() << 8; }
457 void restore(int32_t &data) { data = read(); data |= read() << 8; data |= read() << 16; data |= read() << 24; }
458 void restore(uint32_t &data) { data = read(); data |= read() << 8; data |= read() << 16; data |= read() << 24; }
459 void restore(envelope_state &data) { data = envelope_state(read()); }
460 template<typename DataType, int Count>
461 void restore(DataType (&data)[Count]) { for (uint32_t index = 0; index < Count; index++) restore(data[index]); }
462
463 // internal helper
464 ymfm_saved_state &write(uint8_t data) { m_buffer.push_back(data); return *this; }
465 uint8_t read() { return (m_offset < int32_t(m_buffer.size())) ? m_buffer[m_offset++] : 0; }
466
467 // internal state
468 std::vector<uint8_t> &m_buffer;
469 int32_t m_offset;
470 };
471
472
473
474 //*********************************************************
475 // INTERFACE CLASSES
476 //*********************************************************
477
478 // ======================> ymfm_engine_callbacks
479
480 // this class represents functions in the engine that the ymfm_interface
481 // needs to be able to call; it is represented here as a separate interface
482 // that is independent of the actual engine implementation
483 class ymfm_engine_callbacks
484 {
485 public:
486 // timer callback; called by the interface when a timer fires
487 virtual void engine_timer_expired(uint32_t tnum) = 0;
488
489 // check interrupts; called by the interface after synchronization
490 virtual void engine_check_interrupts() = 0;
491
492 // mode register write; called by the interface after synchronization
493 virtual void engine_mode_write(uint8_t data) = 0;
494 };
495
496
497 // ======================> ymfm_interface
498
499 // this class represents the interface between the fm_engine and the outside
500 // world; it provides hooks for timers, synchronization, and I/O
501 class ymfm_interface
502 {
503 // the engine is our friend
504 template<typename RegisterType> friend class fm_engine_base;
505
506 public:
507 // the following functions must be implemented by any derived classes; the
508 // default implementations are sufficient for some minimal operation, but will
509 // likely need to be overridden to integrate with the outside world; they are
510 // all prefixed with ymfm_ to reduce the likelihood of namespace collisions
511
512 //
513 // timing and synchronizaton
514 //
515
516 // the chip implementation calls this when a write happens to the mode
517 // register, which could affect timers and interrupts; our responsibility
518 // is to ensure the system is up to date before calling the engine's
519 // engine_mode_write() method
520 virtual void ymfm_sync_mode_write(uint8_t data) { m_engine->engine_mode_write(data); }
521
522 // the chip implementation calls this when the chip's status has changed,
523 // which may affect the interrupt state; our responsibility is to ensure
524 // the system is up to date before calling the engine's
525 // engine_check_interrupts() method
526 virtual void ymfm_sync_check_interrupts() { m_engine->engine_check_interrupts(); }
527
528 // the chip implementation calls this when one of the two internal timers
529 // has changed state; our responsibility is to arrange to call the engine's
530 // engine_timer_expired() method after the provided number of clocks; if
531 // duration_in_clocks is negative, we should cancel any outstanding timers
532 virtual void ymfm_set_timer(uint32_t /*tnum*/, int32_t /*duration_in_clocks*/) { }
533
534 // the chip implementation calls this to indicate that the chip should be
535 // considered in a busy state until the given number of clocks has passed;
536 // our responsibility is to compute and remember the ending time based on
537 // the chip's clock for later checking
538 virtual void ymfm_set_busy_end(uint32_t /*clocks*/) { }
539
540 // the chip implementation calls this to see if the chip is still currently
541 // is a busy state, as specified by a previous call to ymfm_set_busy_end();
542 // our responsibility is to compare the current time against the previously
543 // noted busy end time and return true if we haven't yet passed it
544 virtual bool ymfm_is_busy() { return false; }
545
546 //
547 // I/O functions
548 //
549
550 // the chip implementation calls this when the state of the IRQ signal has
551 // changed due to a status change; our responsibility is to respond as
552 // needed to the change in IRQ state, signaling any consumers
553 virtual void ymfm_update_irq(bool /*asserted*/) { }
554
555 // the chip implementation calls this whenever data is read from outside
556 // of the chip; our responsibility is to provide the data requested
557 virtual uint8_t ymfm_external_read(access_class /*type*/, uint32_t /*address*/) { return 0; }
558
559 // the chip implementation calls this whenever data is written outside
560 // of the chip; our responsibility is to pass the written data on to any consumers
561 virtual void ymfm_external_write(access_class /*type*/, uint32_t /*address*/, uint8_t /*data*/) { }
562
563 protected:
564 // pointer to engine callbacks -- this is set directly by the engine at
565 // construction time
566 ymfm_engine_callbacks *m_engine;
567 };
568
569 }
570
571 #endif // YMFM_H