romdev-mcp 0.1.1

package/src/platforms/genesis/lib/sgdk/src/ext/minimusic/CHANGELOG.md

@@ -0,0 +1,31 @@
+# MiniMusic changelog
+
+## 2023-12-20: Version 1.10
+
+- (GitHub issue #12) Added a new function `MiniMusic_GetStatus` to query what the sound driver is doing. Currently it only reports if BGM is playing.
+- It seems the C API was still broken under C++ (oops).
+- Slowed down playback slightly to make it closer to 59.92Hz (NTSC refresh rate) than 60Hz, since it's more likely that you'll want the former instead.
+
+## 2023-12-07: Version 1.03
+
+- Fix C API which wasn't even *building* at all (goes to show how many people are using that API).
+
+## 2023-11-05
+
+- Added a very minimal sample program. Will need to update in the future with more sounds and a proper interface.
+- Changed the format of the subheadings in the changelog since not all of these are version bumps (sorry).
+
+## 2023-11-02: Version 1.02
+
+- (GitHub issue #10) Fixed sound effect priority not resetting when stopping music (or playing new music, which implicitly stops the previous one), which prevented further lower priority sound effects from playing until a higher priority one reset it again. Last patch had a similar bugfix for pausing.
+- Fixed an issue where `MuteFm` did not necessarily mute correctly FM channels 4 to 6 (and seemed to "work" by sheer coincidence only).
+
+## 2023-08-31: Version 1.01
+
+- Added `CHANGELOG.md` (this file).
+- (GitHub issue #9) Fixed PSG channels not muting when pausing.
+- (GitHub issue #8) Fixed sound effect priority not resetting when pausing, which prevented further lower priority sound effects from playing until a higher priority one reset it again.
+
+## 2023-08-26: Version 1.00
+
+- Initial release.

package/src/platforms/genesis/lib/sgdk/src/ext/minimusic/LICENSE.txt

@@ -0,0 +1,17 @@
+© 2023 Javier Degirolmo
+
+This software is provided 'as-is', without any express or implied
+warranty.  In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not
+   claim that you wrote the original software. If you use this software
+   in a product, an acknowledgment in the product documentation would be
+   appreciated but is not required.
+2. Altered source versions must be plainly marked as such, and must not be
+   misrepresented as being the original software.
+3. This notice may not be removed or altered from any source distribution.

package/src/platforms/genesis/lib/sgdk/src/ext/minimusic/README.md

@@ -0,0 +1,18 @@
+# MiniMusic
+
+Version 1.10
+
+A tiny Z80 sound driver for Mega Drive that runs entirely off Z80 RAM and doesn't access the cartridge slot. This may be useful if you want to play sound while writing back to cartridge Flash, or if you simply want to keep things tiny.
+
+This driver is under the zlib license (see `LICENSE.txt`). You are *not* required to credit the author, just don't lie about it.
+
+## How to use
+
+* If using C: check `doc/api-c.md`
+* If using asm: check `doc/api-asm.md`
+
+The format for the sound data is documented in `doc/format.md`. A sample program (asm API only) is available in the `sample-asm` directory.
+
+## Github
+
+https://github.com/sikthehedgehog/minimusic

package/src/platforms/genesis/lib/sgdk/src/ext/minimusic/data.z80

@@ -0,0 +1,148 @@
+;*******************************************************************************
+; State for all tracks (see TRACK_* for format)
+;*******************************************************************************
+
+    macro UninitTrack
+    dw  DefaultEndBgm       ; TRACK_ADDR_* ("no loop" point)
+    dw  DefaultEndBgm       ; TRACK_LOOP_* ("no loop" point)
+    db  FLAGMASK_REFRESH    ; TRACK_FLAGS (set all the defaults)
+    db  $FF                 ; TRACK_WAIT (slowest wait possible)
+    ds  SIZEOF_TRACK-7
+    db  $C0                 ; TRACK_PAN (both speakers on)
+    endm
+
+TrackData:
+
+BgmTrackData:
+BgmTrackData_Fm1:       UninitTrack     ; BGM FM channel 1
+BgmTrackData_Fm2:       UninitTrack     ; BGM FM channel 2
+BgmTrackData_Fm3:       UninitTrack     ; BGM FM channel 3
+BgmTrackData_Fm4:       UninitTrack     ; BGM FM channel 4
+BgmTrackData_Fm5:       UninitTrack     ; BGM FM channel 5
+BgmTrackData_Fm6:       UninitTrack     ; BGM FM channel 6
+BgmTrackData_Psg1:      UninitTrack     ; BGM PSG channel 1
+BgmTrackData_Psg2:      UninitTrack     ; BGM PSG channel 2
+BgmTrackData_Psg3:      UninitTrack     ; BGM PSG channel 3
+BgmTrackData_Psg4:      UninitTrack     ; BGM PSG channel 4
+
+SfxTrackData:
+SfxTrackData_Fm5:       UninitTrack     ; SFX FM channel 5
+SfxTrackData_Fm6:       UninitTrack     ; SFX FM channel 6
+SfxTrackData_Psg3:      UninitTrack     ; SFX PSG channel 3
+SfxTrackData_Psg4:      UninitTrack     ; SFX PSG channel 4
+
+;*******************************************************************************
+; Table with the default state for a newly initialized track. It includes
+; everything except the start address (which is written manually during init)
+;*******************************************************************************
+
+TrackInitData:
+    dw  DefaultEndBgm       ; TRACK_LOOP_* ("no loop" point)
+    db  FLAGMASK_REFRESH    ; TRACK_FLAGS (refresh everything)
+    db  $01                 ; TRACK_WAIT (start immediately)
+    ds  SIZEOF_TRACK-7
+    db  $C0                 ; TRACK_PAN (both speakers on)
+
+;*******************************************************************************
+; State for all YM2612 channels (see FMCHAN_* for format)
+;*******************************************************************************
+
+FmChanData:
+FmChanData_Fm1: db $7F,$7F,$7F,$7F,0, 0,0,0, BgmTrackData_Fm1-TrackData
+FmChanData_Fm2: db $7F,$7F,$7F,$7F,0, 0,1,1, BgmTrackData_Fm2-TrackData
+FmChanData_Fm3: db $7F,$7F,$7F,$7F,0, 0,2,2, BgmTrackData_Fm3-TrackData
+FmChanData_Fm4: db $7F,$7F,$7F,$7F,0, 2,0,4, BgmTrackData_Fm4-TrackData
+FmChanData_Fm5: db $7F,$7F,$7F,$7F,0, 2,1,5, BgmTrackData_Fm5-TrackData
+FmChanData_Fm6: db $7F,$7F,$7F,$7F,0, 2,2,6, BgmTrackData_Fm6-TrackData
+
+;*******************************************************************************
+; State for all PSG channels (see PSGCHAN_* for format)
+;*******************************************************************************
+
+PsgChanData:
+PsgChanData_Psg1: db $00,$00,$FF,$FF,$FF,$FF, $00,ADSR_RELEASE, $80, BgmTrackData_Psg1-TrackData
+PsgChanData_Psg2: db $00,$00,$FF,$FF,$FF,$FF, $00,ADSR_RELEASE, $A0, BgmTrackData_Psg2-TrackData
+PsgChanData_Psg3: db $00,$00,$FF,$FF,$FF,$FF, $00,ADSR_RELEASE, $C0, BgmTrackData_Psg3-TrackData
+PsgChanData_Psg4: db $00,$00,$FF,$FF,$FF,$FF, $00,ADSR_RELEASE, $E0, BgmTrackData_Psg4-TrackData
+
+;*******************************************************************************
+; SFX priority of every allocatable channel
+; 0 means channel unused by SFX. Other values mean channel used by SFX, with
+; higher values being higher priority.
+;*******************************************************************************
+
+SfxPriority:
+    db 0,0,0,0
+
+;*******************************************************************************
+; YM2612 and PSG frequency values corresponding to each semitone in an octave.
+;-------------------------------------------------------------------------------
+; note: PSG frequency values are multiplied by 2 because the code that scales
+; it to the intended octave overshoots by one octave.
+;*******************************************************************************
+
+FmFreqTable:
+    dw  644, 681, 722, 765
+    dw  810, 858, 910, 964
+    dw  1021, 1081, 1146, 1214
+
+PsgFreqTable:
+    dw  851*2, 803*2, 758*2, 715*2
+    dw  675*2, 637*2, 601*2, 568*2
+    dw  536*2, 506*2, 477*2, 450*2
+
+;*******************************************************************************
+; InstrumentTLMask
+; List of bitmasks indicating which slots' TL are affected during attentuation
+; computation for each algorithm.
+;-------------------------------------------------------------------------------
+; bit 0 = set if S1's TL is affected
+; bit 1 = set if S3's TL is affected
+; bit 2 = set if S2's TL is affected
+; bit 3 = set if S4's TL is affected
+;*******************************************************************************
+
+InstrumentTLMask:
+    db      $08,$08,$08,$08,$0C,$0E,$0E,$0F
+
+;*******************************************************************************
+; DefaultEndBgm, DefaultEndSfx
+;
+; If a track never sets the main loop point and executes OP_END, it will be
+; sent here instead (the default main loop point is here). This is how we
+; implement a track coming to a stop when no loop point is set. In the case of
+; SFX, it also tells it to return the channel back to BGM control.
+;*******************************************************************************
+
+DefaultEndSfx:
+    db      OP_ENDSFX                   ; Return channel to SFX
+    
+    db      OP_INSTRUMENT,0             ; Set instrument 0 to mute the channel
+                                          ; directly with the key-off below.
+                                          ; Note that it will be still updated
+                                          ; despite returning the channel back
+                                          ; because remapping happens before
+                                          ; this but hardware updates happen
+                                          ; after this.
+    ; fallthrough...
+
+DefaultEndBgm:
+    db      OP_KEYOFF                   ; Stop the current note
+    db      OP_END                      ; Keep stuck here
+
+;*******************************************************************************
+; NullInstrument
+; An instrument used to mute channels. It tries to decay the ADSR envelope as
+; quickly as possible, while also being reusable for both FM and PSG. It's
+; assigned to instrument #0 in tracks.
+;*******************************************************************************
+
+NullInstrument:
+    db      $00                         ; Algorithm
+    db      $00,$00,$FF,$FF             ; MUL and DT
+    db      $FF,$FF,$00,$7F             ; TL
+    db      $1F,$1F,$1F,$1F             ; AR and KS
+    db      $1F,$1F,$1F,$1F             ; DR and AM
+    db      $1F,$1F,$1F,$1F             ; SR
+    db      $0F,$0F,$0F,$0F             ; RR and SL
+    db      $00,$00,$00,$00             ; SSG-EG

package/src/platforms/genesis/lib/sgdk/src/ext/minimusic/define.z80

@@ -0,0 +1,173 @@
+;*******************************************************************************
+; Addresses for the fields in the header for the sound data
+;*******************************************************************************
+
+NumBgm:             equ $0800   ; Number of BGM IDs (max = 127?)
+NumSfx:             equ $0801   ; Number of SFX IDs (max = 127?)
+BgmList:            equ $0802   ; Pointer to BGM list
+SfxList:            equ $0804   ; Pointer to SFX list
+InstrumentList:     equ $0806   ; Pointer to instrument list
+
+;*******************************************************************************
+; Hardware port addresses
+;*******************************************************************************
+
+YmAddr1:            equ $4000   ; YM2612 bank 1 address port
+YmData1:            equ $4001   ; YM2612 bank 1 data port
+YmAddr2:            equ $4002   ; YM2612 bank 2 address port
+YmData2:            equ $4003   ; YM2612 bank 2 data port
+
+PsgPort:            equ $7F11   ; PSG port
+
+BankPort:           equ $6001   ; Bank switching port (actually $6000 but this
+                                  ; lets us write 1 to the bottom bit by reusing
+                                  ; the L register since the port responds to
+                                  ; the whole $60xx range)
+
+;*******************************************************************************
+; State kept for each track
+;*******************************************************************************
+
+TRACK_ADDR_LO:          equ 0   ; Current address
+TRACK_ADDR_HI:          equ 1
+TRACK_LOOP_LO:          equ 2   ; Main loop address
+TRACK_LOOP_HI:          equ 3
+TRACK_FLAGS:            equ 4   ; Hardware refresh flags (see FLAG_*)
+TRACK_WAIT:             equ 5   ; Ticks to wait before resuming
+TRACK_RET_LO:           equ 6   ; Return address for subroutines
+TRACK_RET_HI:           equ 7
+TRACK_SUBCOUNT:         equ 8   ; Sub-loop iteration count
+TRACK_SUBADDR_LO:       equ 9   ; Sub-loop address
+TRACK_SUBADDR_HI:       equ 10
+TRACK_NOTELEN:          equ 11  ; Ticks that next key-on/off will last
+TRACK_INSTRUMENT:       equ 12  ; Current instrument ID
+TRACK_PITCH:            equ 13  ; Current pitch (in semitones)
+TRACK_TRANSPOSE:        equ 14  ; Current transpose (in semitones)
+TRACK_VOLUME:           equ 15  ; Current attenutaion (in -0.75dB steps)
+TRACK_PAN:              equ 16  ; Bit 7: left channel, bit 6: right channel
+
+SIZEOF_TRACK:           equ 17  ; Size of the state for one track
+
+NUM_BGMTRACKS:          equ 10  ; Number of tracks we keep track of
+NUM_SFXTRACKS:          equ 4
+NUM_TRACKS:             equ NUM_BGMTRACKS+NUM_SFXTRACKS
+
+;*******************************************************************************
+; Track flags (see TRACK_FLAGS) used to keep track of when a change in the
+; track state needs to be reflected in the hardware.
+;*******************************************************************************
+
+FLAG_KEYOFF:            equ 1   ; Issue key-off
+FLAG_KEYON:             equ 2   ; Issue key-on
+FLAG_CANCELKEY:         equ 0   ; Ignore the above two
+FLAG_INSTRUMENT:        equ 4   ; Load new instrument values
+FLAG_PITCH:             equ 5   ; Update channel frequency
+FLAG_VOLUME:            equ 6   ; Update channel attenuation
+FLAG_PAN:               equ 7   ; Update channel panning
+
+FLAGMASK_REFRESH:       equ $F2 ; Write this value to force a channel refresh
+
+;*******************************************************************************
+; State kept for each FM channel
+;*******************************************************************************
+
+FMCHAN_TL_S1:           equ 0   ; Instrument TL for slot S1
+FMCHAN_TL_S3:           equ 1   ; Instrument TL for slot S3
+FMCHAN_TL_S2:           equ 2   ; Instrument TL for slot S2
+FMCHAN_TL_S4:           equ 3   ; Instrument TL for slot S4
+FMCHAN_TLMASK:          equ 4   ; Mask of which TL values to update
+FMCHAN_PORT:            equ 5   ; Lower byte of port address to access
+FMCHAN_BASE:            equ 6   ; Register number offset for this channel
+FMCHAN_KEY:             equ 7   ; Bit pattern to use for key-off/on
+FMCHAN_TRACK:           equ 8   ; Pointer to track state (offset)
+
+SIZEOF_FMCHAN:          equ 9   ; Size of the state for one FM channel
+NUM_FMCHAN:             equ 6   ; Number of FM channels
+
+;*******************************************************************************
+; State kept for each PSG channel
+;*******************************************************************************
+
+PSGCHAN_TL:             equ 0   ; Total level (AR → DR transition)
+PSGCHAN_SL:             equ 1   ; Sustain level (DR → SR transition)
+PSGCHAN_AR:             equ 2   ; Attack date
+PSGCHAN_DR:             equ 3   ; Decay rate
+PSGCHAN_SR:             equ 4   ; Sustain rate
+PSGCHAN_RR:             equ 5   ; Release rate
+PSGCHAN_LEVEL:          equ 6   ; Current ADSR level
+PSGCHAN_PHASE:          equ 7   ; Current ADSR phase (see ADSR_*)
+PSGCHAN_BITS:           equ 8   ; Bitmask for commands for this channel
+PSGCHAN_TRACK:          equ 9   ; Pointer to track state (offset)
+
+SIZEOF_PSGCHAN:         equ 10  ; Size of the state for one PSG channel
+NUM_PSGCHAN:            equ 4   ; Number of PSG channels
+
+;*******************************************************************************
+; Possible phases for an ADSR envelope (see PSGCHAN_PHASE)
+;*******************************************************************************
+
+ADSR_ATTACK:            equ 0   ; Attack phase
+ADSR_DECAY:             equ 2   ; Decay phase
+ADSR_SUSTAIN:           equ 4   ; Sustain phase
+ADSR_RELEASE:           equ 6   ; Release phase
+
+;*******************************************************************************
+; Track opcode numbers
+;*******************************************************************************
+
+OP_KEYOFF:              equ $60     ; Key-off
+OP_CANCELKEY:           equ $61     ; Cancel next key
+OP_LOOP:                equ $62     ; Start of main loop
+OP_END:                 equ $63     ; End of main loop
+OP_SUBLOOP:             equ $64     ; Start of sub-loop
+OP_SUBEND:              equ $65     ; End of sub-loop
+OP_CALL_B:              equ $66     ; Call to subroutine (8-bit offset)
+OP_CALL_W:              equ $67     ; Call to subroutine (16-bit offset)
+OP_RETURN:              equ $68     ; Return from subroutine
+OP_INSTRUMENT:          equ $69     ; Set instrument
+OP_TRANSP_ABS:          equ $6A     ; Set transpose (absolute)
+OP_TRANSP_REL:          equ $6B     ; Set transpose (relative)
+OP_VOLUME_ABS:          equ $6C     ; Set attenuation (absolute)
+OP_VOLUME_REL:          equ $6D     ; Set attenuation (relative)
+OP_PAN:                 equ $6E     ; Set panning
+OP_NOISE:               equ $6E     ; Set PSG noise mode
+
+OP_ENDSFX:              equ $6F     ; [internal] Return channel to BGM
+
+;*******************************************************************************
+; 68000 special command numbers
+;*******************************************************************************
+
+FIRST_CMD:              equ $FD     ; Lowest command number
+
+CMD_UNPAUSE:            equ $FD     ; Resume music
+CMD_PAUSE:              equ $FE     ; Pause music
+CMD_STOP:               equ $FF     ; Stop music
+
+;*******************************************************************************
+; YM2612 register numbers
+;*******************************************************************************
+
+YMREG_TIMERA_HI:        equ $24     ; Timer A frequency (bits 9-2)
+YMREG_TIMERA_LO:        equ $25     ; Timer A frequency (bits 1-0)
+YMREG_TIMERB:           equ $26     ; Timer B frequency
+YMREG_MODE:             equ $27     ; Timer control and ch3 mode
+YMREG_KEY:              equ $28     ; Key-on/off control
+
+YMREG_MUL:              equ $30     ; MUL and DT
+YMREG_TL:               equ $40     ; TL
+YMREG_AR:               equ $50     ; AR and KS
+YMREG_DR:               equ $60     ; DR and AM
+YMREG_SR:               equ $70     ; SR
+YMREG_RR:               equ $80     ; RR and SL
+YMREG_SSGEG:            equ $90     ; SSG-EG
+
+YMREG_FREQ_LO:          equ $A0     ; Frequency (low byte)
+YMREG_FREQ_HI:          equ $A4     ; Frequency (high byte)
+YMREG_ALGO:             equ $B0     ; Algorithm and feedback
+YMREG_PAN:              equ $B4     ; Pan, PMS and AMS
+
+YMACK_NONE:             equ $0F     ; Don't acknowledge timers
+YMACK_TIMERA:           equ $1F     ; Acknowledge timer A
+YMACK_TIMERB:           equ $2F     ; Acknowledge timer B
+YMACK_BOTH:             equ $3F     ; Acknowledge both timers

package/src/platforms/genesis/lib/sgdk/src/ext/minimusic/doc/api-c.md

@@ -0,0 +1,80 @@
+# C API for MiniMusic
+
+## Adding MiniMusic to your game
+
+You need to add the following files from the `api-c` directory into your program:
+
+* `minimus.c` is the API code proper
+* `minimus.h` is the API header file
+* `minimusb.inc` is the Z80 program
+
+Whenever you need to call a MiniMusic function, make sure to have the following declaration at the beginning of that file:
+
+```
+#include "minimus.h"
+```
+
+## Initialization
+
+To initialize the sound driver, you need to call `minimusic_init`. You can pass your sound data (up to 6KB) by passing a pointer to it and its size as arguments.
+
+```
+minimusic_init(&sound_data, sizeof(sound_data));
+```
+
+Check `doc/format.md` for the format of the sound data (and remember it has to fit within 6144 bytes). This includes all the tracks as well as the instruments.
+
+## Playing music
+
+You can play music or sound effects using the `minimusic_send_cmd` function. Pass the sound number as argument:
+
+```
+minimusic_send_cmd(1);
+```
+
+Passing 0 does nothing.
+
+The "sound number" starts at 1 and depends on how many music and sound effects you have. If you have e.g. five music and ten sound effects, then music numbers range from 1 to 5 and sound effect numbers range from 6 to 15.
+
+## Special commands
+
+A few special values can be passed to `minimusic_send_cmd` instead of a BGM or SFX number:
+
+* 255: stop music
+* 254: pause playback
+* 253: resume playback
+
+When pausing, all current sound effects will be stopped, but you will be able to play new sound effects *after* it's paused (if you want to play a pause jingle, make sure you do it after sending the pause command!).
+
+## DMA and I/O port accesses
+
+While MiniMusic does not access the cartridge slot, it *does* access the 68000 bus (to use the PSG), so you still need to guard against hardware bugs when using DMA or the I/O ports.
+
+To prevent this, request the Z80 bus before starting DMA or accessing the I/O port, and release the bus afterwards. You don't need to wait for the Z80 to release the bus, this is just to make sure the Z80 doesn't interfere. MiniMusic provides two inline functions to do this:
+
+```
+// any other setup needed here
+MINIMUSIC_Z80_GUARD_BEGIN();
+// start DMA or read pads here
+MINIMUSIC_Z80_GUARD_END();
+```
+
+Note: only the command that triggers DMA needs to be guarded like this (you don't need to guard around other DMA registers).
+
+## Check if music is playing
+
+You can check if music is still playing by calling the `minimusic_get_status` function. Mask (AND) it against the value `MINIMUSIC_STATUS_BGM`, and if it isn't 0 then music is currently playing:
+
+```
+if (minimusic_get_status() & MINIMUSIC_STATUS_BGM) {
+    // Music is playing...
+} else {
+    // Music not playing...
+}
+```
+
+Note that it will report music as *still* playing if it's paused. It only returns false when:
+
+* Music has stopped on its own (all tracks reached the end without looping).
+* Music has been interrupted by sending a stop (255) command.
+* No music has ever played to begin with.  

package/src/platforms/genesis/lib/sgdk/src/ext/minimusic/doc/format.md

@@ -0,0 +1,132 @@
+# MiniMusic sound data format
+
+This document describes the format of the data that's loaded in Z80 RAM for use by the sound driver. The following notes apply:
+
+* Numbers starting with `$` are hexadecimal.
+* All the data must fit in 6144 bytes (6KB).
+* All 16-bit values are little endian (first low byte, then high byte).
+* Data will be placed starting from Z80 address `$800` (all pointers must be adjusted accordingly).
+
+The only thing that needs to be at a specific address is the main header (see below), which must be at the very beginning. You can place everything else anywhere within that 6KB space (`$800` to `$1FFF`).
+
+## Main header
+
+The overall header for all the sound data is located at `$800` in Z80 RAM (i.e. the first eight bytes of the sound data) and is as follows:
+
+* **1 byte:** number of music
+* **1 byte:** number of sound effects
+* **2 bytes:** pointer to music list
+* **2 bytes:** pointer to sound effect list
+* **2 bytes:** pointer to instrument list
+
+Each of the three lists is a list of 16-bit pointers.
+
+# Music and sound effect data
+
+## Music header
+
+* **1 byte:** number of FM tracks (from 0 to 6)
+* **2 bytes × number of FM tracks:** pointers to each FM track
+* **1 byte:** number of PSG tracks (from 0 to 4)
+* **2 bytes × number of PSG tracks:** pointers to each PSG track
+
+FM channels are assigned from channel 1  to 6, in order. Sound effects are allowed to take over channels 5 and 6, so allocate the less important instruments there.
+
+PSG channels are assigned from channel 1 to 4: square, square, square, noise. If you need to use noise in music, you have to allocate all four channels. Sound effects are allowed to take over channels 3 and 4.
+
+## Sound effect header
+
+* **1 byte:** flags (see below)
+* **2 bytes (if used):** pointer to FM channel 6 track
+* **2 bytes (if used):** pointer to FM channel 5 track
+* **2 bytes (if used):** pointer to PSG channel 3 track
+* **2 bytes (if used):** pointer to PSG noise track
+
+The first byte indicates two things. The lower nibble (bits 3-0) indicates which channels are used:
+
+* **Bit 0:** uses FM channel 5
+* **Bit 1:** uses FM channel 6
+* **Bit 2:** uses PSG channel 3
+* **Bit 3:** uses PSG noise
+
+The upper nibble (bits 7-4) are the SFX priority, from 0 (lowest) to 15 (highest). When a SFX is already using a channel and we want to play a new one, it will be replaced if the new SFX has same or higher priority.
+
+Multiple sound effects can play at the same time if they use different channels.
+
+## Track data
+
+Each "track" corresponds to a hardware channel and consists of a list of "opcodes", each of which indicate an action such as key-on, change the note length, change the volume, etc.
+
+The following opcodes are available:
+
+* **`$80` to `$FF`: set note length.** Sets the wait duration for any following key-on/off. Substract 127 to get the number of ticks to wait (from `$80` = 1 tick to `$FF` = 128 ticks).
+* **`$00` to `$5F`: key-on.** It starts a new note and waits for the current note length. The pitch is given by the byte itself, in semitones (from `$00` = C1 to `$5F` = B8).
+* **`$60`: key-off.** It stops the current note and waits for the current note length.
+* **`$61`: cancel next key.** It removes the key part of the next key-on/off. For key-on, this changes the pitch and inserts a wait. For key-off, this only inserts the wait.
+* **`$62`: start of main loop.**
+* **`$63`: end of main loop.** Returns back to the main loop point (see above), or if it hasn't been set, it stops the track here.
+* **`$64 nn`: start of sub-loop.** `nn` is the number of times to play this loop. Sub-loops can't be nested (you can't have a sub-loop inside another sub-loop).
+* **`$65`: end of sub-loop.** If there are any iterations left it returns to the sub-loop point (see above), otherwise it continues forwards.
+* **`$66 nn` or `$67 nn nn`: call to subroutine.** For `$66` the offset is 8-bit (sign extended), for `$67` the offset is 16-bit (little endian). The offset is counted from the end of the opcode. Subroutine calls can't be nested (you can't call to a subroutine from another subroutine).
+* **`$68`: return from subroutine.** It continues where the last call left off.
+* **`$69 nn`: set instrument.** `nn` is the instrument ID.
+* **`$6A nn` or `$6B nn`: set transpose** (pitch offset), measured in semitones (in two's complement). It takes effect on the next key-on. `$6A` is absolute (`nn` is used as-is), `$6B` is relative (`nn` is added to the current transpose).
+* **`$6C nn` or `$6D nn`: set attenuation** (volume), measured in -0.75dB steps. `$6C` is absolute (`nn` is used as-is), `$6D` is relative (`nn` is added to the current attenuation, in two's complement)
+* **`$6E nn`: set panning.** `nn` bit 7 = left channel on, bit 6 = right channel on, bits 5-0 should be 0. Ignored for PSG channels.
+
+## PSG noise channel
+
+PSG noise channel may be used on its own or together with PSG channel 3. When entering notes with the PSG noise channel, rather than using semitones use these values:
+
+- `$00`: periodic noise, high pitch
+- `$01`: periodic noise, medium pitch
+- `$02`: periodic noise, low pitch
+- `$03`: periodic noise, channel 3
+- `$04`: white noise, high pitch
+- `$05`: white noise, medium pitch
+- `$06`: white noise, low pitch
+- `$07`: white noise, channel 3
+
+When using `$03` or `$07`, the pitch comes from the PSG channel 3 track. You should also mute PSG channel 3, however by default instrument 0 is loaded which is already mute (so it only matters if you're already using another instrument).
+
+# Instrument data
+
+The instrument list is a list of 16-bit pointers with the Z80 addresses of every instrument. The list starts counting from instrument number 1, _not_ 0.
+
+## FM instrument format
+
+FM instruments use the same format as EIF (Echo Instrument Format). It consists of 29 bytes with the values of YM2612 registers as-is, in the following order:
+
+* Register `$B0` (algorithm and feedback)
+* Registers `$30`, `$34`, `$38`, `$3C` (MUL and DT)
+* Registers `$40`, `$44`, `$48`, `$4C` (TL)
+* Registers `$50`, `$54`, `$58`, `$5C` (AR and KS)
+* Registers `$60`, `$64`, `$68`, `$6C` (DR and AMON)
+* Registers `$70`, `$74`, `$78`, `$7C` (SR)
+* Registers `$80`, `$84`, `$88`, `$8C` (RR and SL)
+* Registers `$90`, `$94`, `$98`, `$9C` (SSG-EG)
+
+Any unused bits must be left as 0.
+
+## PSG instrument format
+
+A PSG instrument consists of 6 bytes:
+
+* TL (total level)
+* SL (sustain level)
+* AR (attack rate)
+* DR (decay rate)
+* SR (sustain rate)
+* RR (release rate)
+
+TL, SL, AR, DR, SR, RR all mean the same thing as for FM instruments. TL and SL are measured as the threshold level, in 0.125dB steps (note: this is volume, *not* attenuation). AR, DR, SR, RR are also measured in 0.125dB steps, this amount is added or substracted every time the envelope ticks.
+
+A flat PSG envelope would be:
+
+```
+FF 00 FF 00 00 FF
+```
+
+## Instrument number 0
+
+Instrument number 0 is reserved for the "null" instrument, which is used to mute the channel. You can't redefine this instrument (it isn't included in the list), but tracks are allowed to use it.

package/src/platforms/genesis/lib/sgdk/src/ext/minimusic/doc/teradrive.md

@@ -0,0 +1,33 @@
+# MiniMusic on Teradrive
+
+**Disclaimer:** these are only observations. Use of MiniMusic on a Teradrive is *not* officially supported (outside of its Mega Drive compatibility).
+
+## Available Z80 RAM
+
+MiniMusic is normally limited to 6KB of sound data. This limit comes from the fact that Z80 RAM on Mega Drive is 8KB, and the first 2KB are reserved for the sound program, leaving 6KB to use for data.
+
+Teradrive however has 16KB of Z80 RAM. This means that 14KB should be available for data. MiniMusic should be able to use all 14KB of data just fine, only bear into mind that it's going to be a *very* narrow part of your userbase.
+
+## Using MiniMusic from DOS
+
+In theory, MiniMusic could be run directly on the Z80 from DOS if you *really* know what you're doing.
+
+To initialize the sound driver:
+
+1. Copy the Z80 program to Z80 address `$0000` onwards
+2. Copy the sound data to Z80 address `$0800` onwards
+3. Reset and start running the Z80
+
+To send a command:
+
+1. Pause the Z80
+2. If Z80 address `$0000` = 0 then write command there, resume Z80 and quit
+3. If Z80 address `$0001` = 0 then write command there, resume Z80 and quit
+4. If Z80 address `$0002` = 0 then write command there, resume Z80 and quit
+5. Let the Z80 run for some time and retry from step 1 (or give up and fail if you don't want to risk the CPU being stuck for a long time)
+
+Additionally, you can implement `MiniMusic_GetStatus` this way (the value you read from Z80 RAM will be the value the function returns):
+
+1. Pause the Z80
+2. Read Z80 address `$0003`
+3. Resume the Z80