            ---------------------------------------------------------
                           C A T O R C I O   1 . 0    
             Acorn Master Compact/Olivetti Prodest PC 128 S emulator
            ---------------------------------------------------------


1. Description
2. Disclaimer
3. Setting up and using Catorcio
4. What's emulated and what's not
5. History
6. Contacting the author


 1. DESCRIPTION
----------------

  Catorcio is a DOS-based program that emulates the Acorn Master Compact, known
in Italy as the Olivetti Prodest PC 128 S.
The emulator is written in 80x86 real mode ASM and thus it's very fast and small
(the executable file is less than 18KB). It is based on my "65SC12 Emulator"
available with full source code at Robert Schmidt's "The BBC Lives!" site
(http://www.nvg.ntnu.no/bbc) under the Emulators section, together with Catorcio
itself and many other BBC emulators (thank you Robert!)
It features a simple text-mode interface for its configuration, while the
emulation is carried out in graphic mode (EGA compatible).


 2. DISCLAIMER
---------------

  Catorcio is shareware. If you use it for more than 30 days, you must register
by paying 15 US$ to the author. Remember that the author spent many hours
writing and debugging this software! See below for instructions on how to
contact the author.
Catorcio is supplied as-is; the author WILL NOT be held responsible for ANY
damages that may occur as a direct or indirect result of using Catorcio.
The author will not be held responsible for damages resulting from the loss of
business or productivity due to the use of Catorcio.
You are encouraged to use and distribute Catorcio; please contact the author if
you want to distribute Catorcio on shareware CDROMs/collections.


 3. SETTING UP AND USING CATORCIO
----------------------------------

  Catorcio needs a mimimum set up before being usable.
First of all, unzip CATORCIO.ZIP in a suitable directory (since you are reading
this doc file, you probably already did), using the -d switch to create the
required directory structure.
Then, you need a copy of the original Acorn Master Compact ROMs.

Note that Acorn still hold their rights on the ROMs, so if you haven't got a
real Acorn Master Compact or Olivetti Prodest PC 128 S it is illegal to have
copies of the ROMs.

You need the following ROMs:

 * MOS 5.10
 * BBC BASIC 4
 * ADFS 2.10
 * UTILS 1.0

The ROMs must reside in a "ROMS" subdirectory of the directory in which you
installed the emulator, along with the "EEPROM" 128 bytes file that holds the
contents of the Master Compact's internal configuration EEPROM (Electrically
Erasable Programmable Read Only Memory).

The MOS must reside in a 16 kB (16384 bytes) file named OS.ROM.
The other ROMs can have any name but the extension must be .ROx, where x is a
hexadecimal digit representing the paged ROM bank where it must be loaded.

The default Acorn Master Compact comes with ADFS in bank 13 (D hexadecimal),
BBC BASIC in bank 14 (hex E) and Utils in bank 15 (hex F).
The ADFS and BASIC can be loaded in any bank, while the Utils ROM must be
mandatorily loaded in bank 15 due to the privileged way in which it's treated
by the MOS.
Note that banks 4, 5, 6, 7 are occupied by the sideway RAM and cannot be used
by paged ROMs.
Any other files with an extension different from .ROx are ignored by Catorcio.

Once set up, use of Catorcio is simple. After a presentation screen, the program
displays the main menu. A function in the main menu is selected by pressing
the appropriate key among the ones listed below. The program will display
appropriate messages at the bottom of the screen.
Here is a list and a brief explanation of the available options.
 
 I: Instruction timing ON/OFF
This function controls the timing of instructions. If timing is off, the
emulator just runs at maximum speed. With timing enabled, the emulator tries to
execute instructions at the speed a real 65C12 would execute them. Note that a
80486dx-66 runs the emulator approximately 1.2 times faster than a real Acorn
Master Compact: thereby, with today's computers there should'nt be any problems
in running the emulator at full speed.
For more information about how timing is performed, see the technical notes
below.

 L: Log file ON/OFF
The emulator can create a 65C12EM.LOG file (in the current directory) containing
the history of executed instructions and the values of the registers for every
instruction. This key allows the user to enable or disable the log file feature.
Note that with today's computers it's impossible to achieve full speed with log
file on (it requires a disk transfer rate greater than 20 MB/s!)
Maybe in the (not so far) future... :-)

 S: Start emulation
This function starts the instruction emulation. The emulated processor will
start executing the instruction in the memory location &FFFC.

 E: Exit program
The E key lets the user return back to DOS/Windows.

Once the emulation is started, you can go back to the main menu at any time by
pressing F11.
At that point the "Start emulation" menu item will be replaced by "Resume
emulation": pressing R will bring you back to the emulator, at the same point
where it was interrupted.

Please note that Catorcio can run fine under a Windows environment, although it
can be slowed down by other applications running at the same time.
The best thing to do is to run Catorcio in a clean DOS environment.

The keyboard mapping tries to resemble, whenever possible, the keyboard layout
of a real Master Compact; i.e. it's not the symbol you see on a key but its
position that determines what a key does.
For example, the key right to the "L" acts as ";" or "+" depending on the
status of the shift keys.
Note that it's impossible to treat all the keys in a positional way; the cursor
keys of the Master Compact are mapped on the cursor keys of the PC, and the
"Delete" and "Copy" are respectively the "Del" and "End" keys located above the
PC cursor keys. "F0" is the PC's "F10", "Shift-Lock" is mapped on the "Alt" key.
The "Break" key is the F12 key on the PC; note that the key combinations
involving Break work OK (although Shift-Break causes the emulated computer to
hang due to the lack of an emulated WD177x and floppy interface).

A common problem seems to be the contents of the EEPROM file not fulfilling the
consistency checks of the MOS; in this case, once the emulator is launched, the
MOS hangs displaying some apparently nonsense-ish graphics at the centre of the
screen.
This is the MOS writing a message in mode 7 while the emulator only supports a
mode 0 display. The message is "Options reset - Press BREAK to continue";
pressing F12 should in fact bring on the usual Master Compact startup messages.
If, after pressing F12, you still see only some nonsense (that changes when you 
type something anyway this time), it means that the MOS sets mode 7 as its
default startup mode; you must change this by (blindly) typing the following
(use the "-" key on the numeric keyboard as the "*"):

*CONFIGURE MODE 0

or

*CONFIGURE MODE 128

(shadow RAM is emulated, so you can use MODE 128 as well) to set video mode 0 
or mode 128 as the default startup mode. Note that this must be typed in upper
case. 
Restarting the emulator or pressing Ctrl-Break (Ctrl-F12 on the PC) will finally
(hopefully) bring on a meaningful Master Compact screen.

The ROMS\EEPROM file that comes with the emulator is configured for using MODE 0
as the default video mode with the UK version of the ROMs, so if you are using
the original Acorn Master Compact ROM set the emulator should run fine at the
first try.

If you have any problems/questions/bug reports, don't hesitate to contact me
(see below for how to do this).


 4. WHAT'S EMULATED AND WHAT'S NOT
-----------------------------------

  Catorcio is still in a prototypal stage; it currently emulates the minimum 
requested IC's that allow it to accept keyboard input and display screen output.
Here is a detailed list of what's emulated:

 * 65SC12, including timing.
 * A partial system VIA (6522) to allow the emulation of memory mapping, EEPROM,
   keyboard and IRQs.
 * Memory mapping and sideways/private RAM/ROM.
 * EEPROM (8572); it's contents are stored in the external file ROMS\EEPROM.
 * Keyboard; it even supports typematic settings within the Master, and doesn't 
   rely on the auto-repeat of the PC like all other emus I tried out :-)
 * A very basic mode 0 or 128 (no real 6845 or ULA emulation) without hardware
   scrolling.

What's not emulated yet:

 * The user VIA (6522)
 * The sound chip (SN76489A)
 * The disk interface (WD177x)
 * The cathode ray tube controller (6845)
 * The video ULA and hardware video scrolling mechanism
 * The serial port interface RS232
 * The Econet


 5. HISTORY
------------

  Version 1.0 - 24 August 1999
First publicly available release.

The latest version of Catorcio is available at Robert Schmidt's "The BBC lives!"
site (http://www.nvg.ntnu.no/bbc) under the Emulators section.


 6. CONTACTING THE AUTHOR
--------------------------

  For any problems, bug reports, or for including Catorcio in a shareware
CDROM/collection, feel free to contact me by e-mail or ordinary mail (the 
former is obviously faster and preferable):

conca@neworldfl.com

Carlo Concari
Loc. Parola, 115
43030 Parma
Italy
