fMSX Documentation

# fMSX
version 3.0

### by Marat Fayzullin

# Contents

- New in This Version
- History
- Introduction
- fMSX Ports
- Registered Users
- What is Included
- Keyboard Assignments
- Command Line Options
- Frequently Asked Questions
- Thanks to...

# New in This Version

As I now have six seven (!) different emulators to maintain in addition to my academic studies, I expect you, people, to look for bugs and fix them if possible. Please, submit your fixes and bug reports!

- Added transparent support for GZIPped disk images as disks. You can now pass .GZ file names in `-diska/-diskb` command line options.
- Added transparent support for directories as disks (thanks to Miguel Colom). You can now pass directory names in `-diska/-diskb` command line options. Changes to such disks will not be saved for safety reasons.
- Added DirectDraw-based full screen mode to fMSX-Windows. Press [ALT]+[ENTER] to switch in and out of the full screen mode. Use it with caution, as DirectDraw is notoriously unstable.
- Added a full-fledged debugger to fMSX-Windows. Press [F11] to invoke the debugger.
- Fixed several bugs in MIDI implementations that made some games silent when logging soundtrack or using MIDI output in fMSX-Windows.
- Better adapted fMSX-MSDOS to 320x200 VGA screen.
- "Sync to VBlanks" option is now default in fMSX-MSDOS.

# History

## New in fMSX 2.8

- Fixed initial envelope volume in `AY8910.c`, thanks to Koichi Nishida.
- Fixed a problem with 8kB/16kB cartridges failing to execute in the MSX1 mode.
- When guessing a MegaROM mapper type, fMSX now tries to look at a data file `CARTS.CRC` containing pairs of cartridge CRCs and mapper types.
- Added support for the third cartridge slot. You can now give up to three cartridge names on the command line and three `-rom` options.
- Cartridges are now inserted into slots 1:X (A), 2:X (B), and 3:0 (C). The `RS232.ROM` has been moved to slot 3:3.
- Added support for the 64kB Panasonic FM-PAC cartridge with 8kB SRAM (`-rom 7`).
- fMSX loads files `FMPAC.ROM`, `MSXDOS2.ROM`, and `PAINTER.ROM` automatically, as long as they are in the program directory and there is an empty cartridge slot available.
- Added support for ASCII/8kB cartridges with 8kB SRAM (Xanadu, Royal Blood). Please, inform me if this has broken support for any "normal" ASCII/8kB cartridges.
- Added support for ASCII/16kB cartridges with 2kB SRAM (Hydlide 2). Please, inform me if this has broken support for any "normal" ASCII/16kB cartridges.
- All battery-backed SRAM save files have now got `.SAV` extension. For example, `GameMaster2.rom` will produce a SRAM file named `GameMaster2.sav`.
- Added reporting of bad memory writes with `-verbose 8`.
- The R-Type cartridge and its variants are supported by the ASCII/16kB MegaROM mapper (`-rom 5`).
- HAL's Hole In One Special cartridge is supported by the GENERIC/16kB MegaROM mapper (`-rom 1`).
- Konami's Majutsushi (aka Mah Jong 2 or RC765) cartridge is supported by the GENERIC/8kB MegaROM mapper (`-rom 0`), although the D/A audio circuit emulation is not implemented.
- Added fast-forwarding option (`[F9]`) and moved fixed font switch to a different key (`[CONTROL]-[F9]`).
- Changed `[F6],[F9],[F10]` assignments in fMSX-Windows to comply with other fMSX ports.
- Added `Options` menu to fMSX-Windows.
- fMSX-FreeBSD now compiles without changes on FreeBSD 5.x (FreeBSD 4.x users may have to change the location of the `soundcart.h`).
- Fixed sound in fMSX-FreeBSD by increasing the number of sound fragments from 8 to 64. If any of FreeBSD developers are reading this, could you explain why this is needed?

## New in fMSX 2.7

- Switched to the latest version of the OpenWatcom C/C++ compiler.
- The infamous Windows problem with spaces in directory names seems to be fixed by using a newer compiler.
- Made some arrays "const" to facilitate porting to run-from-ROM platforms (cellphones, PDAs, etc.).
- Joystick problems in fMSX-Windows are fixed.
- Descreased the default sound volume in fMSX-Unix.
- Increased the default wave synthesis frequency to 44.1kHz.
- Minor fixes to the Unix sound drivers.
- Removed MIDI volume control from Windows sound drivers.
- Added TV raster effect to fMSX-Windows.

## New in fMSX 2.6

- Added separate (and correct) emulation for the i8255 PPI chip.
- Added masking to lower bits of video table addresses.
- Added timing and other fixes to the Z80 core (courtesy of Omar Cornut).
- Fixed line coincidence and VBlank handling (thanks to Vincent van Dam).
- Save state (.STA) file format has changed.
- Fixed a bug that messed up screen table addresses when restoring state.
- Fixed a bug that left dummy memory page dirty when loading GZIPped ROMs.
- Fixed a -home option bug on Solaris (thanks to Eric Boon).
- Fixed fMSX-Unix to allow it to have an application icon under WindowMaker.

## New in fMSX 2.5

- Added emulation state saving and loading.
- Added support for GZIPped ROM files and state file.
- Changed keyboard handler in fMSX-Unix. Hopefully, the key assignments should now be more natural.
- Added sound on/off switch to fMSX-Unix and fMSX-MSDOS.
- Keyboard assignments changed everywhere.

## New in fMSX 2.4

- Small fix to the DI instruction.
- Small fix to the HALT instruction.
- Added -sync option to fMSX-MSDOS on public request.
- Fixed PHYDIO DiskROM call (4010h) to return the number of remaining sectors in register B (thanks, Maarten!).
- Fixed ASCII mappers to prevent memory corruption when switching ROM pages in disconnected slots.
- Fixed palette to span to true white.
- Added SetWave() call to the sound API.
- SCC emulation now makes use of waveforms via SetWave().
- SCC gets silenced when 0 frequency is written (thanks, Maarten!).
- Fixed SCC+ emulation.
- Vertical screen adjustment is only computed once, when refresh starts.
- Moved picture 10 pixels down when the screen is 192 pixels high.
- Removed unused SprCol variable.
- Added wave synthesis sound to fMSX-Windows.
- Fixed fMSX-MSDOS to restore palette when exiting the debugger.

## New in fMSX 2.3

- Now, when you buy fMSX-Windows, you also fMSX-MSDOS.
- Added modular FM-PAC (aka YM2413 aka OPLL) emulation.
- FM-PAC soundtrack can be logged into a MIDI file.
- Sound and MIDI logging APIs have been integrated and rewritten to accomodate MIDI instruments, dynamic instrument changes, drum usage, etc.
- Added PAL/NTSC switch on a bit in VDP[9] (thanks, Alex!).
- Added support for the overscan (Mantra demos and games run now).
- Added sprite support to SCREEN3 (no idea why it was not there).
- Added support for YJK (SCREEN12) and YAE (SCREEN10/11) screens.
- Added separate handling for IE0 and IE1 IRQs (Xevious, etc.).
- Added masking of Character Table address (SourceOfPower demo runs now).
- Fixed Z80 interrupt handling after EI (thanks, Maarten!).
- IE0 and IE1 IRQs are now reset when disabled.
- IE0 IRQ is now set when enabled.
- Palette sequencer now resets when writing to VDP[16].
- Fixed mapper #1 to support generic 16kB-paged MegaROMs (HoleInOneSpecial).
- Fixed cartridge loader to correctly load MegaROMs with "AB" signature in the last 16kB page (R-Type).
- Mappers #0 and #1 are now renamed to Generic/8kB and Generic/16kB.
- Fixed mapper #3 to have hardwired ROM at addresses 4000h-5FFFh (thanks, Sean!).
- Added mapper #6 that corresponds to the Konami GameMaster2 cartridge with SRAM (thanks again, Sean!).
- Added key click and motor relay click emulation via Drum() call.
- Major rewrite of the sound drivers and sound logging system.
- Added mouse emulation to fMSX-MSDOS.
- Added border emulation via VGA border to fMSX-MSDOS.
- Added built-in debugger to fMSX-MSDOS (F11).
- Fixed static palette in fMSX-MSDOS.
- Fixed fMSX-Unix to work in 24BPP and 32BPP modes.
- Added static palette to fMSX-Unix.
- Minor fixes to fMSX-Unix makefile.
- fMSX-Windows now runs in 16BPP HiColor mode.
- Changed Setup Panel in fMSX-Windows.
- HPeriod and VPeriod scrollbars are gone from fMSX-Windows as timing control is done automatically.
- PAL and NTSC buttons are gone from fMSX-Windows as PAL/NTSC switch is done automatically.

## New in fMSX 2.2

- Interrupt system rewritten.
- Mapper management rewritten.
- Keyboard assignments changed again. Check the documentation!
- Made a new MSDOS port of fMSX (still in development).
- Integrated modular AY8910 emulation.
- Integrated modular SCC emulation.
- Integrated SndUnix/SndWin/SndMSDOS sound drivers.
- Sound track is now logged to MIDI files.
- Added a table of I/O handler functions to Z80 core for easy expansion.
- Added ability to load flat (no mapper) 64kB ROMs.
- Added automatic MegaROM mapper guessing (-rom 6).
- Added standard PAL/NTSC timings.
- Added V9958 version flag in MSX2+ mode (VDP S1).
- Added correct emulation of HR/VR flags (VDP S2).
- Fixed border color in SCREEN8 (VDP R7).
- Fixed blinking frequency in TEXT80 (VDP R13).
- Added ADJUST register emulation (VDP R18).
- Added V9938 character scrolling to SCREEN0 and TEXT80 (VDP R23).
- Added scrolling to SCREEN1, SCREEN2, and SCREEN3 (VDP R23).
- Fixed scrolling bug in SCREEN6 and SCREEN7 (VDP R23).
- Made left/right borders 9/7 pixels in SCREEN0 and TEXT80.
- Added -home option to tell fMSX where to find system ROMs.
- Added -auto option for auto fire on pressing SPACE.
- Fixed information printed on -help.
- Fixed crash in fMSX-Windows when switching from 8kB to 16kB MegaROMs.
- Fixed trash in MSX2 logo in fMSX-Windows that appeared after reset.
- Better resizing in fMSX-Windows Setup panel.

## New in fMSX 2.1

- New fMSX-Windows available. Buy it now !
- Rewritten V9938 graphical operations support.
- Rewritten initialization sequence.
- Improved real-time clock emulation.
- Fixed a problem with color sprites (Zanac-Ex, Aleste).
- Fixed problems with memory allocation.
- Fixed mouse offset in fMSX-Unix/X.
- Extended documentation, added more questions to FAQ.
- Reduced window size in Unix/X to speed up updates.
- fMSX-Unix now supports 16bpp and 32bpp Xservers for sure.
- Added speed throttling to fMSX-Unix (see -sync).
- fMSX-Unix runs in a resizable window now.
- Fixed IPC key allocation bug in fMSX-Unix.
- Many small fixes to the code.

  ## New in fMSX 2.0b

  - Major code rewrite!
  - Line-by-line screen updates implemented
  - Standard modular Z80 emulation
  - Support for 16bit and 32bit X11 screens (possibly 24bit)
  - Support for KANJI.ROM
  - Mouse support
  - Joystick support
  - Multiple bug fixes
  - Multiple new bugs (look for them!)

  ## New in fMSX 1.5

  - More stable split screen (Zanac-Ex no longer blinks)
  - RAM mapper fixed again (Designer+ works now)
  - V9938 SRCH command fixed
  - MSXDOS2.ROM support
  - PAINTER.ROM support
  - FMPAC.ROM support
  - .PSG file format is updated
  - Serial port support is not yet implemented

  # Introduction

  fMSX is an emulator of MSX, MSX2, and MSX2+ home computers. You can always get the latest fMSX source code and support files from

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

  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. fMSX source code is open for everyone to see but it is not in public domain. If your company intends to use MSX software in its products and you consider licensing fMSX source code from me, please, email me.

  MSX is an old Z80-based family of home computers which appeared in 1982 as an attempt to establish a single standard in home computing similar to VHS in video. They were popular in Asian (Korea, Japan) and South American (Brazil, Chile) countries as well as in Europe (Netherlands, France, Spain) and former Soviet Union, but they are virtually unknown in USA. Although MSX standard quietly died to year 1988, the world got to see MSX2, MSX2+, and TurboR extensions of the standard.

  The MSX standard has been designed by a Japanese company called ASCII in cooperation with Microsoft, which provided a firmware version of its 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 USA appears to be an early SpectraVideo machine.

  In spite of its sad history, MSX is a very nice computer, especially good for education, which is clearly indicated by an example of the Soviet Union. Russian Ministry of Education bought hundreds of MSXes (and later MSX2s) grouped into "computerized classroom systems" of 10-16 machines connected with a simple network. Entire 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 3 channels of melodic sound, a noise channel, volume envelopes, and two general purpose parallel IO ports which MSX uses for joysticks and some other things. Due to their hardware architecture, MSX machines were perfectly suitable for games and there is a lot of good games either written for or ported to them.

  # fMSX Ports

  There are versions of fMSX for Amiga, Macintosh, IBM PC (both MSDOS and Windows), Unix, and other systems. If you would like to port fMSX to another system or make changes to the fMSX's code, please, contact me by email or some other means. Note that fMSX source code is freely distributable but it is not in public domain. You cannot use it for commercial purposes unless you contact me to arrange the conditions of such usage. Feel free to look at existing drivers as well as other code.

  # Registered Users

  If you have registered fMSX-Windows/MSDOS, please do not give your copies to anybody. And I do mean anybody. There was a couple of cases when registered users gave my programs away to their friends, relatives, or just "KeWl" characters on the Net, and then I found programs pirated, put onto WWW pages, and even posted to USENET newsgroups. If I find your personalized copies of fMSX-Windows/MSDOS 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.

  # What is Included

  ## Source Code Distribution

    This distribution includes complete portable C sources for fMSX and screen/keyboard drivers for Unix/X. fMSX-Unix has been tested on many different Unix flavors. The included sources should be sufficient to port fMSX to any more or less advanced computer system, while Unix/X drivers can be used as an example for the system-dependent part of the port.

  ## Windows/MSDOS Distribution

    This distribution includes ports of fMSX to the Microsoft's Windows and MSDOS operating systems. It is available from me, Marat Fayzullin, for $35US. This fee ensures that you get the latest full versions of fMSX-Windows and fMSX-MSDOS with no limitations. You will also get free updates via email as long as fMSX-Windows and fMSX-MSDOS are being updated. For more information about this distribution, take a look at

    http://www.komkon.org/fms/fMSX/fMSXWindows.html

    fMSX-Windows is a 32bit application which runs under all versions of Windows starting with Windows 95. It is compiled with Borland C++ Builder and needs DirectX for full screen operation. Fast computer and a video card that accelerates GDI image blitting are strongly recommended.

    fMSX-MSDOS is also a 32bit application that uses DOS4GW.EXE extender (included) to run. It accesses PC hardware directly and therefore may not be compatible with some versions of Windows.

    There is also another Windows port of fMSX available from Teturo Tokuyama. It is free but not up-to-date and lacks many features.

    If you want me to continue developing fMSX and would like to receive the full versions of fMSX-Windows and fMSX-MSDOS, please, register them by one of the following methods:

    ORDER ON THE WEB
      Tell your WWW browser to go to

      http://www.digibuy.com/cgi-bin/order.html?296825+92971118912

      and use the online form to register fMSX-Windows. You can pay with a credit card. They take MasterCard, Visa, Amex, or Discover. The software will be emailed to you as soon as I receive the notification from DigiBuy.

    ORDER BY PHONE
      Call one of the following numbers in US:

               1-800-242-4775 (extension 15247)
               1-713-524-6394 (extension 15247)

      and refer to product #15247 (fMSX-Windows). This service is provided by DigiBuy. You can pay them with a credit card. Don't forget to give them your email address. The software will be emailed to you as soon as I receive the notification from DigiBuy.

    ORDER BY MAIL
      Send $35US in cash, money order, or a US bank check to:

               Marat Fayzullin
               3030 Southview Road
               Ellicott City, MD 21042
               USA

      Don't forget to include your email address and mention that you want fMSX-Windows, as I'm selling several other products as well. The software will be emailed to you as soon as I receive the money.

  # Keyboard Assignments

        [Control]       - CONTROL
        [Alt]           - GRAPH
        [Insert]        - INSERT
        [Delete]        - DELETE
        [Home]          - HOME/CLS
        [End]           - SELECT
        [PageUp]        - STOP/BREAK
        [PageDown]      - COUNTRY
        [F6]            - Turn spacebar autofire on/off
        [F7]            - Load emulation state from .STA file
        [CONTROL]+[F7]  - Save emulation state to .STA file
        [F8]            - Change disk in drive A:
        [CONTROL]+[F8]  - Change disk in drive B:
        [F9]            - Fast-forward emulation
        [CONTROL]+[F9]  - Turn fixed font on/off
        [F10]           - Turn sound on/off
        [CONTROL]+[F10] - Turn soundtrack logging on/off
        [F11]           - Go to the built-in debugger
        [F12]           - Quit emulation

      in fMSX-Unix:
        [LAlt]          - Joystick A button
        [LControl]      - Joystick B button
        [RShift]        - CAPS LOCK
        [LShift]        - SHIFT

      in fMSX-Windows:
        [CapsLock]      - CAPS LOCK
        [Shift]         - SHIFT
        [CONTROL]+[F6]  - Simulate TV raster
        [CONTROL]+[F11] - Reset emulation

      in fMSX-MSDOS:
        [CapsLock]      - CAPS LOCK
        [Shift]         - SHIFT
        [CONTROL]+[F11] - Make a screen snapshot (SNAPxxxx.GIF)

  # Command Line Options

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

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

        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
        -hperiod <period>   - Minimal number of CPU cycles per HBlank [228]
        -vperiod <period>   - Minimal number of CPU cycles per VBlank [59736]
        -uperiod <period>   - Number of VBlanks per screen update [2]
        -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,8]
                              (three -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

        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 SOUND:
        -sound [<quality>]  - Sound emulation quality [44100]
                              0 - Off                1 - Adlib (MSDOS)
                              Values >8191 are treated as wave synthesis
                              frequencies.
        -nosound            - Same as '-sound 0'

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

        With #define UNIX:
        -sync <frequency>   - Sync screen updates to <frequency> [-nosync]
        -nosync             - Do not sync screen updates [-nosync]
        -static/-nostatic   - Use static color palette [-nostatic]
        -saver/-nosaver     - Save/don't save CPU when inactive [-saver]
        -scale <factor>     - Scale window by <factor> [1]

        With #define MSDOS:
        -vsync              - Sync screen updates to VBlank [-nosync]
        -sync <frequency>   - Sync screen updates to <frequency> [-nosync]
                              (<frequency> must be in 20Hz..100Hz range)
        -nosync             - Do not sync screen updates [-nosync]
        -static/-nostatic   - Use static color palette [-nostatic]
        -240/-200           - Use non-standard 256x240 mode [-200]

  # Frequently Asked Questions

  1. Where do I get MSX software?
     Go to http://www.komkon.org/fms/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 can be loaded into fMSX. There are "small" cartridge ROMs of 8kB, 16kB, or 32kB, and the MegaROMs, which can be 128kB, 256kB and even 512kB. MegaROMs require a special MegaROM mapper feature of fMSX that can be adjusted with `-rom` options.

  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)
         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.
         GMASTER2.RAM - Battery-backed static memory (SRAM) that comes with the
                        Konami GameMaster2 cartridge. This file gets overwritten on
                        exit if SRAM has been changed.

  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 disks 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. Why is the emulator so slow on my PC?
     Because your PC is too slow to run the emulator. The faster your machine is, the faster it will run. On slow machines, you can try speeding things up by increasing `-uperiod` value to 3..6. This value controls how frequently fMSX updates the display. In the fMSX-Windows, the same function is performed by the "Update x ..." slider in the Setup Panel. Additionally, if you run Windows in the TrueColor (24bpp or 32bpp) mode, try switching it into HiColor (16bpp) mode. This will speed up other applications as well.

  10. Emulator is too fast on my PC!
      When fMSX was created, I didn't expect that computers would become too fast for it :). Nevertheless, if fMSX-Unix is too fast on your computer, you can synchronize it to any given frequency using `-sync` option. You would usually want to do `-sync 25 -uperiod 2` which means "perform every second screen update and synchronize updates to 25Hz". The `-sync` option can also be used in fMSX-MSDOS, but as it disables task switching in Windows, you may want to use the `-vsync` option instead. In the fMSX-Windows, you can simply go to the Setup Panel and use "Sync to..." and "Update x ..." sliders to control the emulation speed.

  11. 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:
      - When booting MSX, press `[CTRL]+[DEL]` keys to switch off the second disk drive.
      - Before running a program, type `POKE &hFFFF,&hAA` to set MSX memory manager into the mode expected by most loaders.

  12. 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.

  13. 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.

  14. 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.

  15. 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 `-noshm` option to disable the usage of shared memory.

  16. 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 at

      http://www.math.utwente.nl/~metselaa/msx/X-drivers.html

  17. I start the fMSX-Unix, but the window stays black.
      Some other X11 application took over all available colors so that fMSX emulation could not allocate any for itself. Check if you run XV, Netscape, or something similar and quit these applications.

  18. I get distorted colors in fMSX-Windows.
      You are probably running Windows in an 8bit mode. In this mode, only 256 colors are accessible, and some of them are taken by other programs. Therefore, the system is trying to pick the closest possible colors, which do not always look right. Switch Windows into 16bit or 24bit modes for the right colors.

  # 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 (fms [AT] cs umd /DOT/ edu)