

                        ******* fMSX *******
                 The Portable MSX/MSX2/MSX2+ Emulator
                             version 1.5

                         by Marat Fayzullin
                      
	             Acorn Port by David McEwen 
	                          
Introduction
------------

This is a port of Marat's MSX emulator. This is an excellent emulator, it 
basically provides a complete computer... This computer however has a great 
selection of games... from Aleste to VKiller - a sort of Castlevania.

**Please ensure that your machine can handle a definable 256 colour mode
and has at least 800k free**

What is MSX?
------------

  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 (Holland, France) 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 it. 
  In spite of its sad history, MSX is a very nice computer, especially
useful for educational purposes which is clearly indicated by 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 interconnected by a simple network. Entire generation of
programmers has grown up using these computers. 
  Hardware-wise, MSX represents a hybride of a Nintendo Entertainment
System and a generic CP/M-80 machine. Its heart is Z80 CPU working at
3.58MHz in the base model (frequency was doubled in TurboR). The video
subsystem is built around TI9918 or TI9928 VDP chip also used in Texas
Instruments' TI-99/4 computers. In the later MSX models this chip was
upgraded to V9938 (MSX2) and V9958 (MSX2+ and TurboR). The latest version
is V9990. The audio system is handled by AY-3-8910 chip by General
Electric, same as the one used in Sinclair ZXSpectrum128 audio. AY-3-8910
provides 3 channels of synthetized sound, noise generation, and two
general purpose parallel IO ports which are used for joysticks and some
other things in the MSX design. Due to their hardware structure, MSX
machines were perfectly suitable for games and there is a lot of good
games either written or ported to them. You can find more information
about MSX and remaining MSX fans at http://www.komkon.org/fms/MSX/


How do I use it ?
-----------------

There are various ways of using this machine, it depends on what you are 
using :

Rom Images:<.rom files>
	These should have dos extension stripped and be filetyped to MSXRom.
	Then you can just double click on them.

Disks Images:<.dsk files> 
	These should have dos extension stripped and be filetyped to MSXDsk.
	Then you drag them to the Options window into either the drive A or
	the drive B slot.
	
Tape Images:<.cas files>
	These should have dos extension stripped and be filetyped to MSXTap.
	Then you drag them to the Options window into the Tape slot.	
	 	
On the disks or tapes you may find files with extension .BIN,.OBJ or .GM
These are o-called BLOADable binary files. They can be run from MSX 
BASIC with 

                     BLOAD "filename",R

There may also be .COM files. These are MSX DOS command files.
Boot MSX DOS and run them from there.

As standard the Acorn port comes with the following Roms:
They are all stored in the !Fmsx.Roms directory. They don't need to be run
separately. They are loaded automatically when found.

MSX	     - Standard MSX BIOS and BASIC code
MSX2	     - MSX2 BIOS and BASIC code
MSX2EXT	     - MSX2 ExtROM containing system extensions
MSX2P        - MSX2+ BIOS and BASIC code
MSX2PEXT     - MSX2+ ExtROM containing system extensions
DISK         - MSX DiskROM containing BDOS and DISK BASIC (optional)
RS232        - RS232 BIOS and BASIC extensions (optional)
FMPAC        - FM-PAC BIOS and BASIC extensions (optional)
MSXDOS2      - MSXDOS2 system core (optional)
CMOS         - Non-volatile memory used in MSX2 and MSX2+. This file gets 
               rewritten on exit if non-volatile memory was changed.

This is an extra rom that can be found - just copy it into the Roms directory
stripping the dos extension
PAINTER      - Yamaha Painter, graphical editor found in Russian MSX
               machines from Yamaha (optional)
               

The recommended method of using the emulator is by the front end, however you can 
use the command line. Access of the emulator via the command line will be removed 
in the next main release... this is because it is nicer to integrate the front end 
and the emulator and will remove the possibility of huge command line calls, which
can occur. Also it will enable problems such as the dos extension one to be 
removed...
Currently there are 4 things that can't be done via the front end, they shouldn't 
cause any problems though. They are setting a file for printer output, serial 
output and soundoutput and also supplying a 2nd cartridge. 
Use -help option. It will tell fMSX to display all options available in
your version. Following are the currently available options:

  -verbose <level>    - Select debugging messages [1]
                        0 - Silent       1 - Startup messages
                        2 - V9938 ops    4 - Disk
                        8 - Memory      16 - Illegal Z80 ops
  -iperiod <period>   - Set internal interrupts period [6000ops]
  -uperiod <period>   - Number of interrupts per screen update [2]
  -help               - Print this help page
  -printer <filename> - Redirect printer output to file [stdout]
  -ram <pages>        - Number of 16kB RAM pages [4/8/8]
  -vram <pages>       - Number of 16kB VRAM pages [2/8/8]
  -msx1/-msx2/-msx2+  - Select MSX model [-msx1]
  -rom <type>         - Select MegaROM mapper types [0,0]
                        (two -rom options can be present)
                        0 - Konami 8kB    1 - Konami 16kB
                        2 - Konami5 8kB   3 - Konami4 8kB
                        4 - ASCII 8kB     5 - ASCII 16kB
  -diska <filename>   - Set disk image used for drive A: [DRIVEA.DSK]
  -diskb <filename>   - Set disk image used for drive B: [DRIVEB.DSK]
  -tape <filename>    - Set tape image file [off]
  -font <filename>    - Set fixed font for text modes [DEFAULT.FNT]
  -serial <filename>  - Redirect serial I/O to a file [stdin/stdout]
  -logsnd <filename>  - Write soundtrack to a file [off]

Once the emulator is running the keys are mapped to their Acorn equivalents.
So there is little or no difference to be spotted. There are a couple of keys 
yet to be mapped, but they are of little importance. They will of course be 
added in the next release.    
              
*FAQ*
----- 

Why are my Roms/Disk images not working ?
-------------------

Strip the Dos extension, if they still do not work, try downloading them
again. If they still do nothing try increasing the wimpslot to around 800k.
Another thing to try is altering the MegaROM type... this is a matter of trial and error.

If there is still no joy. Send the image to Marat and see if he can 
find a reason.

Where's the sound ?
-------------------

This is being worked on... the MSX has a complicated sound system that will
take a while to rejig to the Acorn setup, but it will work *eventually*

Do I need a special screen mode ?
---------------------------------

Nope the emulator runs happily in a 320 by 256 mode as the screen fits nicely. 
I could have it running in a 16 colour mode but that would require a more 
radical recoding, which is a bit of a pain.

Will you get it to run in the desktop ?
---------------------------------------

Possibly, really it would only be viable on a StrongARM, due to the code being 
mainly in C. It is not a priority at the moment, but if I can recode sections 
to provide more speed then we shall see... as it stands it is too slow

fMSX version 2.0 is due out soon will you be porting this ?
------------------------------------------------------------

As soon as the source is available I shall get to work. It has some speed up 
features in it that could help out in the quest for speed. It just depends on 
Uni work what the timescale will be, but it shouldn't take long, the machine 
is not very complex.

Will you be porting any other emulators ?
-----------------------------------------

Yes! - although aren't 2 ports enough?

I have some emulator source code residing on my hard drive ready to port!!
It is just a matter of tidying up the MSX and Coleco ones first... 



Copyright and Disclaimer
------------------------

This emulator is copyright Marat Fayzullin 1994-6, and the Acorn-specific
components are copyright David McEwen 1998. You may not attempt to pass off
any part of this work as your own, although you may distribute it freely as
long as you supply the complete archive (that is, all the files supplied to
you).

This software is supplied "as is". I make no claims about the reliability or
suitability for any purpose of this emulator, and any use of it is undertaken
at your own risk. No responsibility is taken for any failure of the software,
or for any loss or damage caused directly or indirectly by the software.

Whilst I will endeavour to help you if you have problems with this emulator,
no such support is guaranteed.

In the above "This emulator" refers to everything supplied within this
archive, which is specifically the !Fmsx application and all the files
contained within it, and also the documentation files (including the one you
are reading now).



COMMENTS
--------

Any comments about the emulator as such should go to Marat Fayzullin : 
email : fms@komkon.org
Website : http://www.komkon.org/fms

Any comments about the Acorn specific parts and please no inane emails giving 
me ways of making money etc... just useful constructive stuff please
email : dem95c@cs.nott.ac.uk
Website : http://www.cs.nott.ac.uk/~dem95c