fMSX
version 5.0

MSX Home Computer Emulator
by Marat Fayzullin

Contents

New in This Version

Introduction

fMSX is a program that emulates MSX, MSX2, and MSX2+ home computers. It runs the majority of MSX software and mimics most popular hardware extensions, such as SCC, OPLL, etc. You can always get the latest fMSX source code, binaries, and support files from

http://fms.komkon.org/fMSX/

fMSX has a very long history for a piece of software. It has been in continuous development since 1993, when I wrote the first version to run on Unix-based DEC Alpha workstations. Because fMSX is written in C, it is a very portable program. It can run on any sufficiently fast 32bit hardware platform, be it personal computer, PDA, videogame console, cell phone, set-top box, or a DVD player. There are fMSX versions for Unix, Windows, Macintosh, Symbian, MSDOS, Amiga, and many other platforms.

fMSX source code is open for everyone to see but it is not in public domain. You can look and learn from it, but you cannot change it or copy it without giving a credit to the original author and a few other conditions. If you would like to port fMSX to another platform or make changes to the code, please, contact me by email or some other means.

You cannot use fMSX source code for commercial purposes unless you contact me to arrange the conditions of such usage. If your company intends to use MSX software in its products and you are considering using fMSX source code, please, email me about licensing.

MSX is an old 8bit family of home computers created in 1982 as an attempt to establish a single standard in home computing similar to VHS in video. MSX computers have been popular in Asia (Korea, Japan) and South America (Brazil, Chile) as well as in Europe (Netherlands, France, Spain) and former Soviet Union, although they are virtually unknown in the USA. Although the MSX platform quietly died around 1988, the world got to see MSX2, MSX2+, and TurboR extensions of the MSX platform.

The MSX has been mainly designed by a Japanese company called ASCII in cooperation with Microsoft, who provided the firmware BASIC for the machine. There is a widespread rumor that "MSX" stands for "MicroSoft eXtended". MSX machines were produced by such giants as Sony, Yamaha, Panasonic, Toshiba, Daewoo, and Philips. The only MSX model ever sold in the US appears to be an early SpectraVideo machine though.

In spite of its short history, MSX is a very nice computer, especially good for education, as seen in an example of the Soviet Union. Soviet Ministry of Education bought hundreds of MSXes (and later MSX2s) grouped into "computerized classroom systems" of 10-16 machines connected with a simple network. A whole generation of programmers has grown up using these computers.

Hardware-wise, MSX represents a hybride of a videogame console and a generic CP/M-80 machine. Its heart is a Z80 CPU running at 3.58MHz in the base model. The clock frequency has been doubled in the TurboR. The video subsystem is built around a TI9918 or TI9928 VDP chip also used in Texas Instruments' TI-99/4 computers, ColecoVision, and Coleco Adam. In the late MSX models, this chip has been upgraded to V9938 (MSX2) and then to V9958 (MSX2+ and TurboR). The latest version of this chip is known as V9990. The audio system is handled by an AY-3-8910 chip from General Instruments, same as the one used in Sinclair ZX Spectrum 128. AY-3-8910 provides three channels of melodic sound, a noise channel, volume envelopes, and two general purpose parallel IO ports, which MSX uses for joysticks and a few other things. Due to their hardware architecture, MSX machines were perfectly suitable for games and there was a lot of good games either written for or ported to them.

fMSX Ports

Because fMSX is a very portable program, it can run on many different platforms: Unix, Macintosh, MSDOS, Windows, Symbian, PocketPC, Amiga, etc. The complete up-to-date list of fMSX ports is available at the fMSX distribution site. Following are the major ports:

fMSX-Windows

Starting December 2013, fMSX-Windows is free for everyone to use, in binary form. You can download it from the fMSX distribution site. Also see my other emulators for Windows.

fMSX-Android

fMSX-Android is available from the Google Play Store. You can download the full version or the feature-limited free demo. Also see my other emulators for Android.

fMSX-Unix

fMSX-Unix is available freely in the source code form from the fMSX distribution site.

fMSX-Linux

fMSX-Linux (ELF, GLIBC, X11) is compiled from the same source code as all other Unix versions. You can get it for free from the fMSX distribution site.

Registered Users

If you've registered fMSX-Windows, please do not give your copy to anybody. And I do mean anybody. There were cases when registered users gave fMSX away to their friends, relatives, or just some shady characters on the Net, and then I found it pirated, put onto the Web, and even posted to USENET newsgroups. If I find your personalized copy of fMSX being spread around, your registration gets automatically cancelled which means no support and no more updates.

I understand that the previous paragraph may sound threatening to some people, but this kind of piracy really hurts my profits and feelings. I've put a lot of effort into fMSX, and can only continue working on it if people do not try to cheat on me.

Keyboard Assignments

 
  [CONTROL]       - CONTROL (also: joystick FIRE-A button)
  [SHIFT]         - SHIFT (also: joystick FIRE-B button)
  [ALT]           - GRAPH (also: swap joysticks)
  [INSERT]        - INSERT
  [DELETE]        - DELETE
  [HOME]          - HOME/CLS
  [END]           - SELECT
  [PGUP]          - STOP/BREAK
  [PGDOWN]        - COUNTRY
  [F6]            - Load emulation state from .STA file
  [F7]            - Save emulation state to .STA file
  [F8]            - Rewind emulation back in time
  [F9]            - Fast-forward emulation
  [F10]           - Invoke built-in configuration menu
  [F11]           - Reset hardware
  [F12]           - Quit emulation
  [CONTROL]+[F8]  - Toggle scanlines on/off
  [ALT]+[F8]      - Toggle screen softening on/off
  [CONTROL]+[F10] - Go to the built-in debugger

Command Line Options

 
Usage: fmsx [-option1 [-option2...]] [filename1] [filename2]

  [filename1] = name of file to load as cartridge A
  [filename2] = name of file to load as cartridge B

  When compiled with #define ZLIB, fMSX will transparently
  uncompress singular GZIPped and PKZIPped files.

  [-option] =
  -verbose <level>    - Select debugging messages [1]
                        0 - Silent       1 - Startup messages
                        2 - V9938 ops    4 - Disk/Tape
                        8 - Memory      16 - Illegal Z80 ops 
  -skip <percent>     - Percentage of frames to skip [25]
  -pal/-ntsc          - Set PAL/NTSC HBlank/VBlank periods [NTSC]
  -help               - Print this help page
  -home <dirname>     - Set directory with system ROM files [off]
  -printer <filename> - Redirect printer output to file [stdout]
  -serial <filename>  - Redirect serial I/O to a file [stdin/stdout]
  -diska <filename>   - Set disk image used for drive A: [DRIVEA.DSK]
                        (multiple -diska options accepted)
  -diskb <filename>   - Set disk image used for drive B: [DRIVEB.DSK]
                        (multiple -diskb options accepted)
  -tape <filename>    - Set tape image file [off]
  -font <filename>    - Set fixed font for text modes [DEFAULT.FNT]
  -logsnd <filename>  - Set soundtrack log file [LOG.MID]
  -state <filename>   - Set emulation state save file [automatic]
  -auto/-noauto             - Use autofire on SPACE [off]
  -ram <pages>        - Number of 16kB RAM pages [4/8/8]
  -vram <pages>       - Number of 16kB VRAM pages [2/8/8]
  -rom <type>         - Select MegaROM mapper types [8,8]
                        (two -rom options accepted)
                        0 - Generic 8kB   1 - Generic 16kB (MSXDOS2)
                        2 - Konami5 8kB   3 - Konami4 8kB
                        4 - ASCII 8kB     5 - ASCII 16kB
                        6 - GameMaster2   7 - FMPAC
                        >7 - try guessing mapper type
  -msx1/-msx2/-msx2+  - Select MSX model [-msx2]
  -joy <type>         - Select joystick types [0,0]
                        (two -joy options accepted)
                        0 - No joystick
                        1 - Normal joystick
                        2 - Mouse in joystick mode
                        3 - Mouse in real mode
  -simbdos/-wd1793    - Simulate DiskROM disk access calls [-wd1793]
  -sound [<quality>]  - Sound emulation quality (Hz) [44100]
  -nosound            - Same as '-sound 0'
  -sync <frequency>   - Sync screen updates to <frequency> [60]
  -nosync             - Do not sync screen updates [-nosync]
  -static/-nostatic   - Use static color palette [-nostatic]
  -tv/-lcd/-raster    - Simulate TV scanlines or LCD raster [off]
  -soft/-eagle        - Scale display with 2xSaI or EAGLE [off]
  -epx/-scale2x       - Scale display with EPX or Scale2X [off]
  -cmy/-rgb           - Simulate CMY/RGB pixel raster [off]
  -mono/-sepia        - Simulate monochrome or sepia CRT [off]
  -green/-amber       - Simulate green or amber CRT [off]
  -4x3                - Force 4:3 television screen ratio [off]

  With #define DEBUG:
  -trap <address>     - Trap execution when PC reaches address [FFFFh]
                        (when keyword 'now' is used in place of the
                        <address>, execution will trap immediately)

  With #define MITSHM:
  -shm/-noshm         - Use MIT SHM extensions for X [-shm]

  With #define UNIX:
  -saver/-nosaver     - Save/don't save CPU when inactive [-saver]
  -scale <factor>     - Scale window by <factor> [2]

  With #define MSDOS:
  -vsync              - Sync screen updates to VBlank [-vsync]
  -480/-200           - Use 640x480 or 320x200 VGA mode [-200]

Frequently Asked Questions
  1. Where do I get MSX software?

    Go to http://fms.komkon.org/MSX/ and follow links from there.

  2. What do I do with .BAS,.GMB,.CRC,.LDR files?

    These are BASIC programs. You run them from MSX BASIC with

    RUN "filename"

  3. What do I do with .BIN,.OBJ,.GM files?

    These are binary files with programs, also known as BLOADable files. You can run them from MSX BASIC with

    BLOAD "filename",R

  4. What do I do with .COM files?

    These are MSXDOS command files. You can run them from MSXDOS by typing their names sans the .COM extension.

  5. What are the .ROM files?

    These are binary images of cartridge ROMs that you can load into fMSX. There are "small" cartridge ROMs of 8kB, 16kB, or 32kB, and the MegaROMs, which can be 128kB, 256kB and even 512kB.

  6. What are the .ROM files included with fMSX?

    Following .ROM files may not be normal cartridges, but they are used by fMSX: 

    MSX.ROM      - Standard MSX BIOS and BASIC code
MSX2.ROM     - MSX2 BIOS and BASIC code
MSX2EXT.ROM  - MSX2 ExtROM containing system extensions
MSX2P.ROM    - MSX2+ BIOS and BASIC code
MSX2PEXT.ROM - MSX2+ ExtROM containing system extensions
DISK.ROM     - MSX DiskROM containing BDOS and Disk BASIC (optional)
RS232.ROM    - RS232 BIOS and BASIC extensions (optional)
FMPAC.ROM    - FM-PAC BIOS and BASIC extensions (optional)
MSXDOS2.ROM  - MSXDOS2 system core (optional)
PAINTER.ROM  - Yamaha Painter, graphical editor found in Russian MSX
               machines from Yamaha (optional)
GMASTER.ROM  - Konami GameMaster, a game cheating tool (optional).
GMASTER2.ROM - Konami GameMaster2, a game cheating tool (optional).
KANJI.ROM    - ROM with Kanji character images (optional)
CMOS.ROM     - Non-volatile memory used in MSX2 and MSX2+. This file gets 
               overwritten on exit if non-volatile memory has been changed.
    Please note that not all of these may be included with your fMSX copy.

  7. How do I use disks with fMSX?

    fMSX includes disk support starting with version 0.9. If you have an earlier version, you cannot use disks. The following instructions assume that you have a version supporting disks.

    First, make sure that the DISK.ROM file containing MSX DiskROM is in the current directory. Then, use an MSDOS program called DCOPY.EXE to create disk images of your MSX disks:

    DCOPY <drive>: <filename>.DSK

    These images are just raw files with all disk blocks written in a sequence. They can also be created on a Unix machine with

    cp /dev/rfd0 <filename>.DSK

    or a similar command. If you have a 1.44MB HD floppy formatted on MSX for 720kB, don't forget to stick a piece of tape on the HD/DD indicator hole.

    After you have created disk image files, run fMSX in the following way:

    fmsx -diska <filename1>.DSK -diskb <filename2>.DSK

    where two image filenames will become your drives A: and B:. You can also have default disk images called DRIVEA.DSK and DRIVEB.DSK and located in the current directory.

  8. Is there an easier way to work with disk images?

    In fact, there is. Look at two programs that come with fMSX, called wrdsk and rddsk. The wrdsk program allows you to create a disk image and add files to it:

    wrdsk <filename>.DSK <file> <file> ...

    The rddsk program will read files from a given disk image:

    rddsk <filename>.DSK [-d <dir>] [<file> <file> ...]

  9. I can't get some BASIC programs to work with the emulator.

    Many MSX programs have BASIC loaders written for machines not quite compatible with each other. Other loaders expect the machine to have only one floppy disk drive and use the memory dedicated to the second drive. To make such programs work, perform two "magic passes" on fMSX before running a loader:

  10. I can't get some ROM images to work with the emulator.

    If the ROM image is bigger than 32kB, try using -rom <N> parameter with different <N>s (see fmsx -help for a complete list). If you still can't get ROM image to work, send it to me for analysis.

  11. Is it legal to spread cartridge ROMs?

    NO. Nobody seems to care though, mainly because there is no profit to be made from MSX software any longer. Nevertheless, be aware of the fact that by using commercial software you haven't bought you are commencing an act of piracy.

  12. When compiling fMSX-Unix, I get "undefined name" errors.

    This means that your linker cannot find the libraries necessary for the emulator (namely, libX11.a and libXext.a) or some additional libraries (like libsocket.a and libnsl.a) are required. Find these libraries in your system and modify the Makefile so that the final invocation of the C compiler has -L<path_to_libs> options. If you have no libXext.a library, try #undefining MITSHM option.

  13. When starting fMSX-Unix, I get X_ShmAttach error.

    You are probably trying to run the emulator on a remote Xterminal while it attempts to use shared memory for interfacing with X. Use the -noshm option to disable the shared memory usage.

  14. The emulation starts under Unix, but then I get X_PutImage error.

    Unix/X version of fMSX can currently be compiled for 8bit, 16bit, or 32bit Xterminals. Neither 1bit nor 4bit Xterminals will work with the drivers included into official fMSX distribution. Arnold Metselaar developed the drivers supporting any Xterminal. These drivers are available from the fMSX distribution site.

History

New in fMSX 4.9

New in fMSX 4.8

New in fMSX 4.7

New in fMSX 4.6

New in fMSX 4.5

New in fMSX 4.4

New in fMSX 4.3

New in fMSX 4.2

New in fMSX 4.0

New in fMSX 3.9

New in fMSX 3.8

New in fMSX 3.7

New in fMSX 3.5

New in fMSX 3.4

New in fMSX 3.3

New in fMSX 3.2

New in fMSX 3.1

New in fMSX 3.0

New in fMSX 2.8

New in fMSX 2.7

New in fMSX 2.6

New in fMSX 2.5

New in fMSX 2.4

New in fMSX 2.3

New in fMSX 2.2

New in fMSX 2.1

New in fMSX 2.0b

New in fMSX 1.5

Thanks to...
Hans Guijt [.NL]
Working on Amiga port, Hans has done a very good job in getting fMSX run fast on an Amiga. He rewrote the CPU emulation and the screen drivers in assembler, optimized the VDP emulation, wrote sound drivers, and added many more things making fMSX-Amiga the best, if not the fastest MSX emulator for this platform. Thanks, Hans (and yes, I do remember those .ROM files too ;)).

Igor Sharfmesser [.KZ] and Alex Krasivsky [.RU]
Igor and Alex have brought to life fMSX-MSDOS. The first version, including screen and keyboard drivers, was done by Igor. AdLib sound was added by Alex.

Teturo Tokuyama [.JP]
Teturo has done an excellent port of fMSX to Windows. As much as I hate Windows, I must admit that Teturo's fMSX-Win32 rules. Period.

Murakami Reki [.JP]
Murakami has written PC9801 port of fMSX. He is the guy whom you have to thank for the disk support in fMSX. If not for him, I would have never started implementing it :).

Marcel de Kogel [.NL]
Marcel wrote an excellent port of fMSX to MSDOS. His MSDOS version of fMSX was actually the first one that supported all fMSX features correctly. Marcel also provided invaluable help debugging and improving fMSX and other emulators.

Ville Hallik [.EE]
AY8910 and SCC chips emulation, written by Ville for Linux/FreeBSD /dev/dsp device, and SunOS /dev/audio, was the best fMSX sound emulation I have seen at the time. And, yes, it lets you play MSX games with sound on a Unix system! =:)

John Stiles [.US]
John took over the development of the Macintosh version of fMSX and managed to speed up the common part of display drivers used in the Unix/X, MSDOS, Windows, and Macintosh versions.

Paul Chapman [.CA]
Paul Chapman is the original author of fMSX-Macintosh. Although his port had bugs, it looked great and ran faster than the original MSX computer on an average PPC-based Macintosh of that time. As Paul was not able to continue developing fMSX-Macintosh, the development has been taken over by John Stiles.

Arnold Metselaar [.NL]
If you happen to have a non-standard X11 display, get Arnold's X11 drivers fixed to work for any screen depth. Arnold has also added to his drivers a lot of improvements that are not in the standard fMSX distribution. Make sure to check out his work.

Guenter Woigk [.DE]
Found a bug with offsets in Z80 commands using IX/IY registers.

Martial Benoit [.FR]
Explained how VDP deals with sprites and sent me copies of V9938 and WD2793 databooks (WOW! Thanks, Martial :)).

Sean Young [.NL]
For finally making it clear to me how GameMaster2 SRAM works and also for finding a bug in my Konami4 mapper emulation.

Alex Wulms [.NL]
Alex has written the most accurate emulation of the V9938 graphical operations to date. This emulation is now a part of fMSX. Also, Alex explained to me a lot of technical details of VDP operation. And he sent me a copy of the WD1793 databook :).

Maarten ter Huurne [.NL]
Maarten has done extensive bug-hunting on things that I would never consider to run (that is, demos :)). He also looks for glitches in games and doesn't rest until he gets to the source of a problem. Additionally, he has implemented MSX Serial I/O emulation that is slowly making its way into fMSX. And finally (as the stuff above were not enough) you can thank Maarten and Takamichi Suzukawa for the English translation of the Konami's Solid Snake cartridge!

Miguel Colom [.ES]
Miguel has come up with an idea and the code to use directories as if they were MSX disks.

...and to all other people who helped me with advice, information, and encouragment.

ENJOY THE EMULATOR AND LET US KEEP MSX ALIVE :)
© Copyright by Marat Fayzullin (marat [AT] komkon <DOT> org)