Driver:MSX

The MSX standard was created by ASCII and Microsoft. Computers for this standard were created by several manufacturers such as Daewoo, Panasonic, Philips, Sanyo, Sony, and Yamaha. There were four generations of MSX computers:

• MSX
• MSX2
• MSX2+
• MSX Turbo-R

When there is no auto booting software inserted the MSX systems boot into MSX-BASIC. From BASIC software can be loaded from cassette or floppy.

Software was mainly released on cartridges, cassettes and floppy disks.

Firmware

Some systems came with firmware which can include functionality like a calendar or a word processor. Most of these firmwares can be disabled either by configuration that is saved in the MSX computer itself or through a configuration switch (available through the MAME Tab menu).

Cartridge

Almost all MSX systems have at least one cartridge slot, most machines have two cartridge slots and some even more than two.

These cartridge slots can be used to insert a cartridge holding software or to extend the functionality of the system by adding a floppy interface for example.

To load the software just mount the software in the cartridge slot (cart1, cart2, etc) and start the emulation. The software should start automatically.

Some examples:

• Play the game Gradius: mame hx10 -cart1 gradius
• Add a floppy disk drive: mame hx10 -cart1 fsfd1
• Play Gradius 2 as a penguin: mame nms8245 -cart1 gradius2 -cart2 pengadv

Extra cartridge slots

Some extensions make more cartridge slots available in a system. For instance by using a slot expander or a Hudson Bee Card adaptor.

The hx10 normally has only one cartridge slot, -cart1. By inserting a BeePack a new cartridge slot, -cart2, becomes available. On base systems that have two cartridge slots the new cartridge slot would be -cart3.

By extending the system with a slot expander, four additional cartridge slots become available. The system cannot be indefinitely expanded like this. The MSX system only knows primary slots and sub-slots. A primary slot can be expanded to 4 sub-slots, but these sub-slots cannot again be expanded.

Almost all cartridge slots are available as primary slots making systems easily expandable.

Some examples:

• Play the game Gradius inserted in a slot expander: mame hx10 -cartslot1 slotexp -cart2 gradius

Cassette

Software on cassette must loaded through BASIC. Software can be stored on a cassette in 3 ways:

• Tokenised Basic

- This format is stored by using the CSAVE command and can be loaded by using the CLOAD command. There is no command to start the software after it has been loaded, so a RUN command is needed once loading completes.

• ASCII Basic

- This format is stored by using the SAVE command and can be loaded by using the LOAD"CAS:" or LOAD"CAS:filename" command or started automatically by using the RUN"CAS:" or RUN"CAS:filename" command.

• Binary code

- This format can be loaded and executed by using the BLOAD"CAS:",R or BLOAD"CAS:filename",R command.

The LOAD/RUN/BLOAD commands need the "CAS:" device identifier on systems that have a floppy disk, otherwise they would try to load the software from floppy.

The entries in the software lists should already have information on which instruction(s) to use for running the software.

Sound

MSX-AUDIO

The MSX-AUDIO extensions are cartridge based extensions around a Yamaha Y8950 sound chip. There were 3 releases that implement this extension:

• Panasonic FS-CA1
• Philips NMS-1205
• Toshiba HX-MU900

These extensions can be mounted by these example command lines:

• mame hx10 -cart1 fsca1
• mame hx10 -cart1 nms1205
• mame hx10 -cart1 hxmu900

The built-in software on these extensions can be bypassed by keeping the ESC key pressed during booting.

TODO: Midi

MSX-MUSIC

The MSX-MUSIC extension involves a Yamaha ym2413 sound chip and an extension for MSX-BASIC to play music through this sound chip.

The MSX-MUSIC extension is built into several MSX2+ and the MSX Turbo-R computers. Panasonic released the FM-Pac which is a cartridge version of MSX-MUSIC and included additional SRAM which could be used as storage by several games. Cartridge versions by other manufacturers did not include this SRAM functionality.

The MSX-MUSIC extension is supported by a lot of later software released for the MSX2 and MSX2+ systems.

The Panasonic FM-Pac can be mounted using command line switches similar to these:

• -cart1 fmpac
• -cart2 fmpac

Yamaha SFG

TODO

SCC

Quite some later games by Konami were released with an additional sound chip called the SCC (k051649) on the cartridge. This greatly enhanced the audio capabilities for these popular games.

There are several (home-brew) titles that support the SCC sound chip. The reason for this is that quite some people modified their SCC games so the sound chip could be used for 'backups', combined with the popularity of Konami games this quickly led to home-brew development against the SCC chips. MAME does not have support for these kinds of hacks.

Konami released two games (Snatcher and SD-Snatcher) on floppy with a separate cartridge containing an SCC chip (k052539) and additional RAM. To start software that wants to use an SCC just mount the cartridge from one of these software titles using any of these command line switches:

• -cart1 snatcher or -cart2 snatcher
• -cart1 sdsnatch or -cart2 sdsnatch

Some home-brew titles have been coded against the way the SCC was accessed by the original games but this may not always be compatible with the way the cartridges for Snatcher and SD-Snatcher should be used. This can lead to failure of the software to detect the SCC chips.

Other

TODO

Floppy

The most common format used is the 3.5" floppy disk. However, there was also some software released on 5.25" floppy disks.

To use a 5.25" floppy disk, an external floppy interface (avdpf550, cdx2, ddx30d, or ddx30) must be inserted in a cartridge slot. Example:

• mame hx10 -cart1 cdx2 -flop1 amazonia

Most software released on floppies will start automatically. Regular software could be stored on floppy in 2 ways:

• Basic

- This format is stored by using the SAVE command and can be loaded by using the LOAD"filename" or LOAD"A:filename" command or started automatically by using the RUN"filename" or RUN"CAS:filename" command.

• Binary code

- This format can be loaded and executed by using the BLOAD"filename",R or BLOAD"A:filename",R command.

By default the files will be loaded from the A: drive. If you want to load a file from a specific (logical) device then the filename can be prefixed with the device specification. For instance RUN"B:start.bas".

MSX-DOS2

MSX-DOS2 adds support for directories and management of memory in memory mappers. The software consists of a cartridge and a floppy containing the MSX-DOS2 environment. The minimum system requirement for MSX-DOS2 is an MSX2 machine.

Quite some Japanese MSX2 computers came with no or a memory mapper too small for MSX-DOS2. This was overcome by adding extra memory in the MSX-DOS2 cartridge in some releases. The MSX system can access this memory through sub-slots in the cartridge. This memory becomes inaccessible when the cartridge is mounted in a cartridge slot that is itself in a sub-slot. This is rare, most cartridge slots are primary slots, but when using a slot expander this situation can occur.

Since the MSX2 computers released in Europe had enough memory installed to run MSX-DOS2 the European release has no additional memory installed in the cartridge.

Currently supported variants:

• msxdos2j (Japan, 256KB RAM)
• msxdos2j_128 (Japan, 128KB RAM)
• msxdos2j_0 (Japan, no extra RAM)
• msxdos2e (Europe, no extra RAM)

Hudson Bee Card

The Hudson Bee Card was a small credit card sized medium. They were cheaper to produce than regular cartridges, and are similar to the HuCards used for the NEC PC-Engine and the MyCards used for the Sega Master System. The Bee Card looks similar to but is not compatible with the Astron SoftCard.

To use a Bee Card on an MSX Computer the Hudson BeePack card reader needs to be inserted in a cartridge slot. To mount the BeePack on an MSX system add -cartslot1 beepack to the command line. Doing so will make a new cartridge interface available to mount the Bee Card software.

The hx10 computer only has 1 cartridge slot so the new cartridge interface will be named cart2. On a machine with 2 cartridge slots, like nms8245, the new cartridge interface will be named cart3.

Some full command line examples:

• mame hx10 -cartslot1 beepack -cart2 bombmnsp
• mame nms8245 -cartslot1 beepack -cart3 bombmnsp
• mame nms8245 -cartslot2 beepack -cart3 bombmnsp

Astron SoftCard

The Electric Software Astron SoftCard was a small credit card sized medium. They were cheaper to produce than regular cartridges. The Astron SoftCard looks similar to but is not compatible with the Hudson Bee Card.

To use an Astron SoftCard on an MSX Computer the Astron SoftCard Adaptor needs to be inserted in a cartridge slot. To mount the SoftCard Adaptor on an MSX system add -cartslot1 softcard to the command line. Doing so will make a new cartridge interface available to mount the SoftCard software.

The hx10 computer only has 1 cartridge slot so the new cartridge interface will be named cart2. On a machine with 2 cartridge slots, like nms8245, the new cartridge interface will be named cart3.

A full command line examples:

• mame hx10 -cartslot1 softcard -cart2 wreck
• mame nms8245 -cartslot1 softcard -cart3 wreck
• mame nms8245 -cartslot2 softcard -cart3 wreck

Harddisk

IDE

Not supported yet.

Sunrise IDE

Sunrise released 2 version of their IDE interface one with a regular IDE connector and one with CF Card slots. Apart from the connectors the internal hardware, and firmware, functions the same way.

The interface cartridge contains a Flash ROM which holds the firmware. This Flash ROM can be written from the MSX itself with a special tool, IDEFLOAD.

The MSX system uses FAT12 so hard disk partitions are limited to max 32MB. MSX-DOS2 is built into the firmware.

Initialising a hard disk

To create a 64MB harddisk image for multiple partitions using chdman:

• chdman createhd -ss 512 -chs 1015,8,16 -c none -o ide.chd

Start the emulation:

• mame nms8245 -cartslot1 sunrise_ataide -flop1 sunride -hard1 ide.chd

During boot sequence the Sunrise IDE firmware will display information regarding the firmware version and the drives found, if any.

Since the harddisk image is still empty a dummy drive A will have been created and drive B will have be for accessing the floppy disk. To initialise the hard disk start the FDISK310 program.

Press the A key to autogenerate a partition table. Press a key to dismiss the information text at the bottom of the screen

Press the W key to write the partition table and the Y key to confirm. Press a key to dismiss the information text at the bottom of the screen.

Press the I key to initialise the partitions and the Y key to confirm. Press a key to dismiss the information text of the bottom of the screen.

Press the D key to display the partition table.

Use the cursor keys to move to the first partition and press the B key to allow the MSX to boot from this partition. Press the Q key to go back to the main screen. Then press the W and Y keys to write the partition table again.

Reset the MSX.

Since the partitions have been initialised but contain no data yet this will boot into MSX-Basic. The above created CHD contains 2 partitions, which will have been assigned drive letters A and B. The floppy drive will have been assigned the drive letter C. Copy the contents to the hard disk by issuing the command COPY"C:*.*"TO"A:*.*".

Reset the MSX again and it will now boot from the first partition, drive A, of the hard disk.

Updating the firmware

Imagine we want to write the 2.40 version of the firmware to the flash rom. Start the emulation as follows: mame nms8245 -cartslot1 sunrise_ataide -flop1 sunride240 -hard1 ide.chd.

To write a new firmware to the flash rom the IDE interface must not be in use. To do this start the emulation while pressing the INS key. Start the flashing program by entering: IDEFLOAD IDE240.DAT.

Choose the interface to flash and press ENTER.

The flash process will take a while to erase the flash and write the blocks.

When the system is rebooted it should now display the updated version of the firmware.

Note: Different firmware versions can be selected when starting the emulation. But since the Flash ROM contents are saved to MAME's nvram folder, the relevant nvram file needs to be removed before the selected firmware version gets activated.

SCSI

The MSX system uses FAT12 so hard disk partitions are limited to max 32MB. MSX-DOS2 is required to use directories.

To create a 20MB harddisk image using chdman:

• chdman createhd -ss 512 -chs 615,4,16 -c none -o msx_scsi_20mb.hdd

Start the emulation:

• mame nms8245 -cart1 msxdos2e -cart2 nov15966 -hard msx_scsi_20mb.hdd -flop1 nov15964

Once booted execute the following actions:

• Enter the command CD HDDUTILS
• Enter the command NFDISK
• Press INS (Insert) key to create a new partition
• Set the requested partition size (for a single 20MB partition enter the number 19.217)
• Press W, Y(es), and ESC.
• 
• Press any key and the system will reboot into MSX-BASIC because there is no MSX-DOS(2) on the hard disk yet.
• In MSX-BASIC enter the command COPY"B:"TO"A:". This will copy the base MSX-DOS2 files to the hard disk.
• The installation is now complete and the hard disk can be used as you please. If the system is rebooted or the emulation restarted then the system will boot from the hard disk.

When you are used to working with other Microsoft systems then drive A: is usually assigned to the floppy disk. In this case, however, A: is the hard disk and B: is the first floppy disk.

MegaSCSI

The MegaSCSI cartridge is different from other interface cartridges. Instead of ROM it has battery backed RAM. This battery backed RAM needs to be initialised with a disk interface code and a hard disk driver. The hard disk interface code will be copied from the disk interface code and patched with the hard disk interface code.

The MSX system uses FAT16 so hard disk partitions are limited to max 32MB. MSX-DOS2 is required to use directories.

To create a 20MB harddisk image using chdman:

• chdman createhd -ss 512 -chs 615,4,16 -c none -o msx_megascsi_20mb.hdd

The installation process is as follows:

• Start the emulation without MSX-DOS2: mame nms8245 -cart2 megascsi -flop1 megascsi -hard1 msx_megascsi_20mb.hdd
• Setup the cartridge ram disk: ERAMDISK /S2
• Restart the emulation with MSX-DOS2: mame nms8245 -cart1 msxdos2e -cart2 megascsi -flop1 megascsi -hard1 msx_megascsi_20mb.hdd
• This will boot into MSX-DOS2 from the B: drive (the floppy).
• Make a copy of the disk interface rom by executing the command: KSAVER KERNEL.KRN
• Install the hard disk interface code by executing the command: MGINST KERNEL.KRN /S2
• Reset the system. This will boot into MSX-DOS2 from the A: drive (the ram disk).
• This is not mandatory but useful to keep the utilities available. Copy the contents of the floppy to the ram disk by executing the command: COPY B: A:. After this the emulation can be started without the -flop1 megascsi part from the command line: mame nms8245 -cart1 msxdos2e -cart2 megascsi -hard1 msx_megascsi_20mb.hdd
• Setup the hard disk by executing the command: ESET
  • 
  • Press E(asy setup)
  • 
  • Press C (Connect drive)
  • Press N (drives) followed by 2
  • Move to the first 'no connection' line, press cursor right, and use cursor up/down to select 'ID0 HD SEAGATE ST225N', press cursor left.
  • Press S (setup) and Y
  • 
  • Press ESC
  • Press Q(uit)
• Reset the system
• The hard disk will now be available as drive B:

If you want to redo this initialisation process remember to remove the megascsi.nv file from the system's folder in the MAME nvram folder.

Since the MegaSCSI's RAM contents are saved in the nvram folder, the MegaSCSI will appear to be uninitialised when starting emulation of a different MSX system and you will have to re-do the initialisation process. You can copy the existing megascsi.nv file to this other MSX system's nvram folder but this is not guaranteed to work due to the copying of the internal disk interface code.

The /S2 switches in the commands above are to select slot #2 as the location of the MEGA-SCSI cartridge. On the selected machine -cart2 happens to be in MSX slot #2. On other systems this may be different.

MegaSCSI with CD-ROM

This will show how to make a CD-ROM's contents available to the MSX through the MegaSCSI.

• Start the emulation with mame nms8245 -cart1 msxdos2e -cart2 megascsi -hard1 msx_megascsi_20mb.hdd -cartslot2:mega_scsi:scsi:3 cdrom -cdrom MCCM_Millennium_CD1.iso
• Make the CD-ROM available to the MSX through the ESET utility:
  • Press E(asy setup)
  • Press C (Connect drive)
  • Press N (drives) followed by 3
  • Make third line says "C: ID3 CD Sony CDU76S"
  • Press S (setup) and Y
  • 
  • Press Q(uit)
• Reset the system
• Run the command MSXCDEX
• The contents of the CD-ROM drive will now be available as drive C: *

MIDI

TODO

Other hardware

TODO

Franky

Franky is an extension cartridge containing an SMS VDP chip. It can be used to playback sounds through the sound part of the SMS VDP chip and to run patched SG-1000 or SMS software.

A tool like SofaSMS can be used to patch and start SMS software on this cartridge. This tool needs to run under MSX-DOS2 and requires quite some memory to patch and run the software.

The procedure to set up the disk image is as follows:

• Pick a bootable MSX-DOS2 disk image and name it sofasms.dsk.
• Inject the SofaSMS files in the disk image:
  • floptool flopwrite msx pc_fat sofasms.dsk path/to/SSMS.TXT SSMS.TXT
  • floptool flopwrite msx pc_fat sofasms.dsk path/to/SSMS.INI SSMS.INI
  • floptool flopwrite msx pc_fat sofasms.dsk path/to/SSMS.COM SSMS.COM
• Inject the SMS file you want to run in the disk image:
  • floptool flopwrite msx pc_fat sofasms.dsk path/to/software.sms SOFTWARE.SMS

We will have to start the emulation with a Franky cartridge, MSX-DOS2, a large memory mapper, and an FM-Pac for SMS software that uses FM. So the command line becomes quite long:

• mame nms8245 -cartslot1 franky -cartslot2 slotexp -cartslot2:slotexp:cartslot1 mm1024k -cart4 msxdos2e -cart5 fmpac -flop1 path/to/sofasms.dsk
• From the MSX-DOS2 prompt execute: SSMS SOFTWARE.SMS /RH1

This will work for quite some SMS software, but not all. Some titles may require other switches to start the SSMS tool, see the SofaSMS documentation for more information.

Popolon Musical Memory Mapper

The Popolon Musical Memory Mapper is a 1MB memory mapper with an additional SN76489AN sound chip.

The tool SG1000 allows an SG-1000 software title to be run directly on the MSX.

The procedure to set up the disk image is as follows:

• Pick a bootable MSX-DOS disk image and name it sg1000.dsk.
• Inject the SG1000 files in the disk image:
  • floptool flopwrite msx pc_fat sg1000.dsk path/to/SG1000.COM SG1000.COM
  • floptool flopwrite msx pc_fat sg1000.dsk path/to/SG1000.DAT SG1000.DAT
  • floptool flopwrite msx pc_fat sg1000.dsk path/to/SG1000F.DAT SG1000F.DAT
• Inject the SMS file you want to run in the disk image:
  • floptool flopwrite msx pc_fat sg1000.dsk path/to/software.rom SOFTWARE.ROM

And then run the emulation:

• mame nms8245 -cartslot1 mmm -flop1 path/to/sg1000.dsk
• From the MSX-DOS prompt execute: SG1000 SOFTWARE.ROM