superctr / mdsdrv

Sound driver for Sega Mega Drive

MDSDRV

A sound driver for Sega Mega Drive/Genesis.

Features

• Runs on the 68000 with the Z80 controlling PCM playback.
• 16 monophonic tracks that can be used for BGM or sound effects. Each track can be assigned to a channel with 4 levels of priority.
• Can use any combination of FM, PSG and PCM sound sources.
• FM3 special mode:
  • Can assign each or a pair of FM3 operators to one or more separate tracks with volume control.
• PCM playback modes:
  • 2 channel PCM playback at ~17.5 kHz with volume control
  • 3 channel PCM playback at ~13.3 kHz with volume control
  • Samples can play at 8 different sampling rates independent of the mixing rate
• Compact sequence format
  • Sound data can be compiled from MML files using ctrmml
• Various effects supported:
  • PSG volume envelopes
  • Pitch envelopes
  • Portamento
  • Fade in/out
  • Song volume and tempo control
• Macro tables
  • Allows for channel parameters and registers to be modified automatically as a note is playing.
• Equal temperament scale with 256 steps per semitone, allowing for easy detune or pitch slide effects.
• Unencumbered source code
• Fully position-independent code - supports any assembler or toolchain by including the binary blob.
• Uses approximately 1 kb (1024 bytes) of RAM.
• Integration with SGDK

Upcoming features

• System C2 support is currently in the experimental c2 branch.

How to use

Feel free to join the Discord server if you have any questions or feedback.

Composing sound data

mmlgui provides an easy way to compose music and sound effects using Music Macro Language (MML).

For information on the MML dialect, see here.

Compiling sound data

The mdslink tool of ctrmml is capable of building the sound data files (mdsseq.bin and mdspcm.bin).

# creates 'mdsseq.bin' and 'mdspcm.bin'
mdslink -o mdsseq.bin mdspcm.bin mymusic.mml ...

Sound data files can be in MML (Music Macro Language) or MDS formats. For information on the MDS binary format, see mdsseq.md.

Building MDSDRV

All required tools for building are already in the repository, you just need to run build.bat. These are Windows executables, so for other operating systems, wine is required.

# creates `main.bin` (test ROM) and `mdsdrv.bin` (sound driver blob)
wine /c build.bat

To quickly generate a ROM (in Windows) with a single song, you can drag and drop a .MDS or .MML file into "quickrom.bat"

Using MDSDRV

Once compiled, using MDSDRV should be as easy as including the binary files (mdsdrv.bin, mdsseq.bin, mdspcm.bin) in your project, and calling the correct addresses inside the mdsdrv.bin blob.

File listing

• main.bin is the sound test ROM. It is built from main.68k.
• out/mdsdrv.bin is the sound driver binary. It is built from blob.68k.
• out/mdsseq.bin is the compiled sequence data. It is built from music and sound effect files using mdslink.
• out/mdspcm.bin contains PCM sample data. It is also built using mdslink.

SGDK test project

• See sample/sgdk.

If the SGDK environment variables are set, calling build.bat should automatically build the SGDK test program.

Interfaces

• See api.md

Sound data reference

• See mdsseq.md

Precautions when using DMA

• See dma.md

The Z80 code has a protection mechanism against reading ROM during DMA transfers. Please read dma.md for information how to use it.

Copyright

© 2019-2022 Ian Karlsson.

MDSDRV is licensed under the terms of the zlib license.

Other programs included in this repository

mdslink is part of ctrmml and is licensed under the terms of the GPLv2. But all code is written by me and I give myself permission to use it here :).

asm68k is owned by SN Systems and is non-free. However it was last released 25 years ago. I hope to move away from using it soon. The code does however currently still use a lot of specific directives, and I prefer its listing outputs for debugging... Please bear with me as I try to find a good replacement.

sjasmplus is licensed under the zlib license. The version included in this repository has been downloaded from the Github repository.

salvador is released under the zlib license. The version included in this repository has been compiled from the source code in the Github repository.

Special thanks

• Sik: for making suggestions and giving inspiration for the Z80 driver.
• Yuzo Koshiro: For creating the MUCOM88 driver which was an inspiration to this project.
• All beta testers.

mdsdrv's Issues

[PCM] Or together panning bits for FM6 and PCM channels

FM LFO support

LFO delay can still be supported, and reuse memory from macro tables when the latter is not in use

FM support

The following FM features must be implemented:

• Key on and off
• Pitch calculation and write
• Volume calculation and write
• Channel LFO and panning flags
• Global LFO parameters (can be set with the fmreg command)
• FM3 special mode (#13 )
• DAC enable/disable (#4 )

Starting a new song causes unwanted FM sounds

When starting a new song (and not completely stopping the previous one before), there is noise generated by the FM channels.

This is caused by the FM envelope generator not being completely muted before loading a new instrument. To fix, either we mute FM channels or set the RR to max on all operators by default after starting a new song

Optimization ideas

• Currently I measured the runtime to 10 lines if 4 FM channels are active but not updated
• Trigger priority calculation based on channel allocation/deallocation rather than always doing it on each frame.
• Skip pitch calculation routine when not needed. I think checking a bitmask of the following new flags:
  • pitch envelope active. Set by new note, cleared if pitch envelope is finished or not active.
  • portamento active. Set by new note, cleared if portamento is completed
  • pitch update triggered by new note, dtn or trs commands

PCM support

PSG/PCM shared volume conversion

Make a function, to convert FM volume (-0.75 db steps) to the PSG/PCM native value (-2db steps) if bit 7 of the track volume is cleared.

This function could also handle accumulating the fadeout and global volume (#5).

Replace asm68k with a free alternative

asm68k originally came from the leaked Psy-Q Sega Saturn SDK and is an old proprietary assembler that has not been maintained in 25 years. It is also Windows-only, although it does work with Wine.

For Windows users I would like an alternative that can be either easily installed or included in the repo.

Currently, MDSDRV uses a few features which may or may not be specific to asm68k, including equr statements and some fancy expressions that might not work in other assemblers.

Suggested alternatives:
https://github.com/asmotor/asmotor - Is free software (GPLv3) and is currently maintained. It has an equs directive which can replace equr. Not sure about Windows support? -> It cannot output listing files, which makes debugging much harder.

[PCM] smarter DMA protection

Read vcounter after each buffer run, and during the idle loop.
If there is less than n samples before vblank, set z_min_buffer to the lowest possible value to ensure we don't enter a new buffer run before or at the vblank.

Based on my calculations, we should stop buffering at 28~35 before vblank. The vblank will last for 32~42 samples (NTSC) or 75~100 (PAL V28) or 61~82 (PAL V30).

The vcounter should not be read during vblank as it requires a 68k bus request (and hence, it will cause the Z80 to be halted by the VDP if DMA is in progress)

Global volume and fadeout

• Global/track volume modifier and fadeout for each channel. Preferably the levels should be equal between FM and PSG (may need a table to convert global volume values to PSG volumes)

I might consider only supporting fade in/out for the music tracks only. That will save 6 words of RAM for a feature that probably won't be needed.

Global volume can be a single word containing two byte values. One for PSG/PCM attenuated and one for FM. Fade and volume change routine converts FM value to PSG/PCM only once.

Z80 PCM driver

It looks like I am writing a Z80 PCM against better advice. The goal of the new Z80 driver is to offload some tasks from the 68k to improve CPU load and smoother PCM playback (=no need to stop Z80 for longer periods of time)

• 68k sends key on/off commands to Z80 Not needed
• 68k sends frequency commands to Z80. Z80 to convert the tone number+fraction to F-num.
• DAC playback

Advanced features (No need to implement, could be nice to have?)

• 68k sends volume commands to Z80. Z80 calculates actual volume given FM parameters?
• 68k sends instrument data to Z80.

Z80 could write instrument data, however it would not be very useful unless a full command queue is implemented. The 68k instrument loading routine is already very tight.

FM3 support

Implement support for FM channel 3 mode.

Since the PCM driver is stable for now, it might be time to do this.

[PCM] Expose PCM driver mode and pitch adjustment in sequence format

Drum mode

• Support drum mode (note events call a subroutine similar to the pat command)

[PCM] Support all PCM driver modes (2ch or 3ch mixing)

Currently the 2 channel mixing mode is supported by the 68000 code. First channel is always on track F (track id 5), Second channel should be on track K (track id 10).

Third channel once implemented will use track L (id 11), maybe fallback to use second channel when 2 channel mixing is used.

Macro table

Since it's annoying to manually insert effects (especially those that alter the state while a note is playing) in MML, a macro table can be used to automatically insert effects while a note is playing.

The macro table could use the same MML command as the pan envelope, alternatively a new event type is added in ctrmml.

The binary format of a macro table is as follows:

commands:
 0x00-0x3f - special commands
 0x40-0x7f - assign variable
 0x80-0xff - delay (frames - 0x7f)

special commands:
 0x00 - end macro table
 0x01 - jump
 0x02 - add to variable
 0x03 - set panning (mask with 0xc0)
 0x04 - set lfo parameters (mask with 0x3f)
 0x05 - write to FM chip common area (fmreg)
 0x06 - write to FM chip, offset to current port/channel (fmcreg)

The variables should map to internal track state, however to preserve backwards-compatibility in future versions, an internal lookup table should be used. The lookup table can also contain a bitmask representing update flags that must be updated.

Macro table should be handled after the instrument update, and before updating volume. Updating instruments through macro tables may not be supported (it would still require extra work in the MML compiler to remap the instruments in each table).

RAM needed (total 4 bytes)

 (w) macro table pointer
 (b) macro table position
 (b) macro table "restart on keyon" flag (bit7)/delay time

the "restart on keyon" flag must be handled by the key on handler (specific for psg/pcm/fm). I will create a macro for this though.

With this I will remove support for LFO delay. This can be implemented using macro table instead.

topic addition for better community reach

Hey,
for better reach of the community, I would like to suggest to add the following topic to the repository: motorola-68000

How to do this

Template ROM

Build a template ROM that can be used by tools to generate a test ROM without needing an assembler to build the sound driver and tester program.

To generate a test ROM, take the template ROM, append a pointer table followed by the mdsbin and mdsseq files.

example pointer table format:

long: "DATA" - magic bytes to determine that a valid table has been appended
long: pointer to sequence data
long: pointer to PCM data
word: song # to auto-play (0 to disable)
word: song count
long: pointer to song 1 title....
long: song 1 length?
long: pointer to song 2 title....
long: song 2 length...

.MDS file linker

To make files generated by ctrmml playable on MDSDRV, the generated files must be linked to generate a coherent data bank. This tool will probably be in the ctrmml codebase.

PSG support

The following PSG features must be implemented:

• Key on and off (using volume envelope)
• Pitch calculation and write
• Volume calculation and write (#14)
• Volume envelope
• Noise frequency mode (with noise taking priority over PSG3 = PSG3 must always be muted if noise is active)

Currently only "native" volume levels are supported. Supporting 7-bit volume won't be done until global volume levels (issue #5) is implemented, as the logic will be depending on that. (And ctrmml does not currently support that either)

Allocating new channel on a track does not automatically stop previous channel

Example: play a song that allocates FM0 for a track, then play another song that allocates PSG1.

Expected result: FM0 should be stopped
Actual result: FM0 is not stopped

A solution can be to always wait one frame before starting a track (or request slot) if another is occupying the track slot.