MSX-MUSIC programming
This page was last modified 18:20, 2 December 2021 by Bengalack. Based on work by Grauw and Gdx and others.

MSX-MUSIC is YM2413 aka OPLL implementation standard for MSX. This implementation can be found inside most MSX2+ computers and all MSX tR computers. It is also very popular as external cartridge among MSX2 users. There exists only few software that supports MSX-MUSIC on MSX1.

You may also want to check out music replayer routines

Contents

Detecting

Do a scan for the following strings in all slots and subslots in the following two passes:

  1. There is text "APRLOPLL" in the ROM an internal device at 4018h ~ 401Fh (also used by clone cartridges)
  2. There is text "OPLL" in the ROM an external device at 401Ch ~ 401Fh (Panasoft FM-PAC)

If the first is found, you can directly use the OPLL on the I/O ports. If the first is not found but the second is, then you need to first enable the I/O ports by setting the I/O enable flag at address #7FF6 (see below), or use the memory-mapped I/O.

The order of checks is important because if it is done in the wrong order, Panasoft FM-PAC will be playing simultaneously with the internal FM-PAC. This also means an internal (or clone cartridge) MSX-MUSIC takes precedence over a Panasoft FM-PAC.

Direct usage for internal device

I/O Port R/W Usage Wait (in μsec) Wait (as clock cycles)
#7C W Register Index 3.36 12
#7D W Register data 23.52 84

Direct usage for external device

I/O Port Address* R/W Usage Wait (in μsec) Wait (as clock cycles)
#7C 7FF4H W Register Index 3.36 12
#7D 7FF5H W Register data 23.52 84

(*) Access by memory addressing should be on all external MSX-MUSIC but all clones do not have this feature.

Note: If you want to activate the I/O ports, you need to set bit 0 of address #7FF6 in FM-PAC slot else OPLL chip will be available for use only trough memory I/O. To prevent two devices on same I/O ports it is not recommended to activate FM-PAC when there is internal MSX-MUSIC present.

PLEASE NOTE: Do not set the bit0 of #7FF6 if there is an "APRLOPLL" string. This will break compatibility with Panasonic MSX2+ computers! In Panasonic A1WX and A1WSX seting bit 0 in any address between #7FF0 and #7FFF will disable the MSX-MUSIC ROM completely.

If you use MSX-BASIC or FM-BIOS then no extra attention is needed because CALL MUSIC command and OPLINI routine will both automatically activate OPLL when needed. These routines will always search first for internal MSX-MUSIC (APRLOPLL) and then external (PAC2OPLL) and activate the external only if internal is not found.


FM-BIOS

Address Name Meaning Usage
#4110 WRTOPL Write to OPLL registers IN: A=Register, E=Data
#4113 INIOPL Initialize OPLL IN: HL=Work area (needs to be even address)
#4116 MSTART Start music IN: A=Repeat count 0-254 (0=infinite repeat) HL=Music address
#4119 MSTOP Stop music
#411C RDDATA Read instrument data IN: A=Instrument number (0-63), HL=8 byte buffer to output.
#411F OPLDRV Handle music data. Put in H.TIMI hook
#4122 TESTBGM LD A,(Workarea + #3A) Output: A=Playing status 0=Not playing
#5000 Statement handler CALL-command handler
#5003 Interrupt handler
#5006 Stop background music
#5009 Enable & reset OPLL


For BIOS music format, please look MSX Datapack chapter 3.3.4