********************************************************************************
                                    uBee512

            An emulator for all Microbee Z80 FDD and ROM based models.

                        Copyright (C) 2007  Stewart Kay

For contact details please see the 'Contact' section at the end of this file.
********************************************************************************

Distribution License
====================
The GPL in this distribution applies only to the uBee512 sources, the
binaries produced from it and the associated documentation.  The SDL and
makez80 packages carry their own respective licenses.  The GPL does not
apply to any other parts of the distribution unless clearly stated.  Other
files and utility programs that are not GPL may form part of this
distribution but these are not required to be able to use the uBee512
emulator.

uBee512 GPL
-----------
uBee512 - An emulator for the Microbee Z80 FDD and ROM based models. 
Copyright (C) 2007  Stewart Kay

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

uBee512 Tools License
---------------------
Any software tools that may be supplied that are not third party are
"Freeware".  the software comes with absolutely no warranties and are to be
used at your own risk.  The code is provided "as-is".

Third party software
====================
- Multi-Z80 CPU emulator by Neil Bradley (neil@synthcom.com)

- Simple DirectMedia Layer library by Sam Lantinga et al.
  http://www.libsdl.org/

Overview
========
Welcome to the uBee512 Microbee emulator. This project is a fork of the
nanowasp v0.22 project and was started on the 5th June 2007.

uBee512 is an emulator for all Microbee Z80 FDD and ROM based models. It
supports full Premium and Standard graphics, sound, tape, serial, printer,
Real Time Clock (RTC), and key board emulation.  The extra DRAM 256 and 512
emulation models allows other third party operating systems to be used.  The
Telerm 256TC model is also emulated.

The program is command line driven and provides various options.  A GUI
interface is to be introduced in the future. The current development has
concentrated on emulation before tackling graphical user interfaces.

You can get the packages from here:
https://sourceforge.net/projects/ubee512/

Objective
---------
The objective of the emulator is to emulate all Z80 Microbee computer models
and to run existing software that works on a real Microbee and to support
all the standard and later the optional peripherals.

Platforms
---------
The source should be able to be built and run under most platforms that
supports SDL.  The Fastest code execution should occur on machines that
support an 80386 CPU as it can use the emitted assembly language file
produced from makez80.

There appears to be a problem in the 'endiness' used in some places in the
makez80 output and so the emitted C version is unlikely to work on little
endian hardware.  This will be looked at a later time.

Currently the supported platforms that have been tested on i386 and x86_64
hardware using the assembly language MZ80 include the following:

- win32 Athlon XP 1.8GHz (2200+) 512Mb DRAM and Windows 2000.

- Linux Athlon AMD64 dual core (3800+) 2Gb DRAM and Fedora core 6 using the
  32 bit version. 

- FreeBSD Athlon AMD64 dual core (3800+) FreeBSD 6.2 using the 32 bit version.

Features
--------
New for this release:
* Now emulates all Microbee Z80 FDD and ROM based models!
* Teleterm 256TC model emulation added.
* Real Time Clock (RTC) emulation added.
* Added 'rtc' directory, each model emulated has it's own RTC RAM image
  saved to this directory.
* Each FDD model now has a preferred default boot disk image file name.  If
  not found then will try to use 'boot.dsk'.
* Every FDD model now has a preferred default boot ROM image name.  If not
  found then will try to use 'rom1.bin' except for 56K and 256TC models.
* p256 and 256K (64K to 256K DRAM upgrade) model emulations added.
* Confirmation exit and reset windows added for Unices.
* Added --rtc option.  RTC is default for 256TC, and all models with 256K or
  more memory.
* Added --nodisk option to force 256TC boot ROM Menu to appear.
* The '.dsk' image should now be fully implemented.
* Microbee LINE FEED moved from KP_ENTER to PAGEUP, BREAK from KP_PLUS to
  PAUSE/BREAK and F1 (tape) to HOME keys.  This is for consistency with the
  Teleterm 256TC keys emulation.
* Z80 PIO emulation improvements.
* APC model name changed to 56K.

Overall features:
* Full Premium (Alpha+) model graphics support. 32K PCG, 8K Screen, 8K
  Colour and 8K Attribute RAM.
* Premium (Alpha+) emulation of the hardware inverse and flashing video
  defined in attribute RAM.
* Teleterm 256TC emulation.
* 56/64/128/256/512K RAM/DRAM emulation.
* ROM based (tape only) models emulation.
* Specific disk emulations for 512K, 256K, 128K, and 64K models using
  Premium/Standard graphics, and the 56K RAM model.
* Selectable display aspect ratios 2:1 and 1:1
* Speaker sound emulation.
* PIO with interrupts emulated.
* RS232 Serial communications for TX/RX.
* Parallel printer output to file(s) options.
* Tape in and Tape out from/to wave files.
* Real Time Clock (RTC) emulation.
* Fully mapped 6545 and 256TC keyboard, emulates all keys correctly and key
  repeating works at correct speed.
* All 6545 cursor modes supported.
* Screen is resized to suit the current 6545 registers.
* Various disk images supported and has read/write capability for drives A-D.
* Speed execution accuracy and regulation is excellent and very fast in
  turbo mode and even faster if specifying the XTAL frequency to a high
  value.
* Default speed of emulation is 3.375 MHz but the target frequency can also
  be specified as a command line option.
* CRTC for the VBLANK status is much improved, important for key repeat
  speed and many games.
* Optional colour and monochrome monitor types: colour, green, amber, white
  and black.
* Standard Microbee emulation option for backwards compatibility.  (i.e. No
  Premium graphics)
* Full screen mode.
* Emulator 'hacking' options.

Premium emulation
-----------------
Premium Microbees were released standard with 16K of PCG and 2K each of
screen, attribute and colour RAM but was able to be expanded to 32K PCG and
8K each for the other three.  As emulated RAM is cheap you get the full
amount.

Part of the Premium's new graphics was support for hardware flashing of
video and inverse video.  Both of these have been emulated.

Colour support is also part of the Premium series and this too is emulated
and is also available when running in standard model colour mode.  You have
a choice of monitor types to view the output on.

256TC emulation
---------------
The Teleterm 256TC model is emulated.  This has emulation for both the later
internal keyboard and 6545 keys. The external keyboard option is not
supported.  The Real Time Clock (RTC) is emulated.

This model has been developed and tested using the 256TC ROM built in
diagnostics. The system has been tested to boot a 128K operating system but
no actual 256TC system has been tested, I am optimistic it should work
though.

Sound emulation
---------------
Sound emulation works very well on the machines used for testing.  I have
not had a chance to test on Windows Vista.  Your mileage may vary in this
area depending on your host hardware, operating system and drivers.

Be aware that running in turbo mode option with sound can cause the sound
buffer to become full quite quickly and sound could become very distorted
and broken up.

The sound quality is also very dependent on the system timer granularity.
See the 'Speed performance' section for more information.

Z80 PIO emulation
-----------------
The Z80 PIO is emulated,  it also is able to generate maskable interrupts.
This allows printing (strobe signal) and serial interrupts to occur.  The
Microbee is able to generate interrupts on any port B bit, currently serial
RX, 256TC keys, and RTC interrupts are emulated.

RS232 Serial emulation
----------------------
RS232 Serial emulation for RX and TX is implemented.  This should work for
polled or interrupt driven code.  The serial uses the host's RS232 ports.

Printer emulation
-----------------
Parallel printer emulation (Z80 PIO port A) under interrupts is implemented. 
The printer output is directed to files.

Real Time Clock (RTC)
---------------------
The RTC is emulated,  it uses the host's system time.  The MC146818 RTC was
designed to keep time and date for the years 1900-1999 only.  The system
software around for the Microbee is typically not Y2K compliant.  Usually the
'19' is just hard code in for the year part and the year '2007' would be
displayed as '19:7' on a Microbee today.  The ':' is the next character
after the '9'.

On a real Microbee the dates will now be incorrect because we have past the
year '1999', the emulator does not emulate this Microbee limitation, the
purists will say that being an emulator it should reproduce exactly the
same result and they have a point.  At a later time this may be added as an
option.  Currently the date and time is taken from the host system so the
date will always be correct (except the year) and is not user settable.  The
':' problem is partially addressed by subtraction 100 from the year to
produce the year '1907'.  If the Microbee application only displays the last
2 digits everything will look correct.

Don't rely on any Microbee applications that may use of the date for any
calculations.

Speed performance
----------------- 
Emulation speed is excellent when targeting 3.375 MHz, the speed is
consistent and smooth on all programs tested.  This is the default when
starting the emulator.

In turbo mode the speed is very fast especially under Windows 2000 (other
windows not tested yet) and a 1.8 GHz Athlon XP (2200+).  The sound is still
played at the normal rate.

The Turbo mode is great if you do not need Z80 CPU and sound to stay in sync
or need time delays to be accurate.  Great for editing and testing, etc.

On my development machine, an Athlon AMD64 dual core (3800+) and Fedora core
6 installed with the 32 bit version I was able to run 4 x uBee512 emulators
at the same time with audio and speed all appearing to work at 3.375 MHz,
More instances were possible but the audio showed signs of breaking up.  I
don't know what the performance is like under Windows for this many
instances.

Even faster speed is possible by specifying the XTAL frequency to be
emulated as a command line option.  On the hardware mentioned above, 200+ MHz
of Z80 speed was achieved. The frame rate is reduced at these speeds so the
screen does not refresh as quick but this is all dependent on you host
platform's capability.  Reducing the XTAL frequency down improves the frame
rate.

The speed accuracy (and the sound quality) depends on the granularity of the
system timer.  You need to have a 1mS resolution.  If your resolution is
10mS you can expect the speed to be about 30% slower and the sound will
break up.  This was the case when testing on an older FreeBSD platform.  I
have been informed that the timer can be changed to 1mS on FreeBSD but this
was not tried.  Later testing on a FreeBSD 6.2 system gave the expected
results as this has 1mS resolution by default.

Z80 Operating systems
---------------------
The following operating systems have been tested and are known to work:

* CIAB
* Microbee 128K
* PJB v1.2 and 512K v2.0a pre-release

Z80 Application software
------------------------
Too numerous to mention it all, but essentially all system support programs
and 3rd party software work except for disk formatting programs.

All machine code games I have tried have worked well.

For Microworld basic programs the list is very long,  there are some very
good graphics and sound affects programs to be had.

Applications for the Premium like 'Simply Write' appear to work well with
out any problems.  I have also tested other Premium graphics programs and
the results has been very good.

For some good samples of Standard and Premium software search through the
MBUG archive located here:

http://www.retroarchive.org/cpm/cdrom/MBUG/
http://z80cpu.eu/mirrors/oldcomputers.dyndns.org/cdrom/cpm/mbug/
http://microbee.no-ip.com/uploads/Software/MBUG

(look in the CAT files) for clare1.mwb clareX.mwb, etc, QUIX-2.COM.

Other Microbee and generic CP/M software can be found here:
http://z80cpu.eu/mirrors/oldcomputers.dyndns.org/cdrom/cpm/beehive/
http://z80cpu.eu/mirrors/oldcomputers.dyndns.org/cdrom/cpm/simtel/cpmug/
http://www.retroarchive.org/cpm/cdrom/SIMTEL/CPMUG/

Software distributions
======================
The latest source and binary distributions are available from:
https://sourceforge.net/projects/ubee512/

The "n.n.n" is the version number:

ubee512-n.n.n.tar.gz     : Source files
ubee512-n.n.n-win32.exe  : Binary installer for Windows
ubee512-n.n.n-win32.zip  : Binary files in ZIP format for Windows

Building from sources
=====================
The information provided here is for a Linux build environment, the win32
port of the emulator is cross compiled from here:

You will need to have a GCC build environment set up for the native build
and if you want to cross compile you will also need mingw and install the
SDL libraries for mingw.

To compile for FreeBSD you need to be on a FreeBSD system.  You should check
the Makefile FreeBSD section to see if it is correct for your version.  The
current set up is for v6.2

On unices generally, it appears that you must have a minimum KDE
installation for SDL to work.

The Makefile does the job but it lacks some dependencies and portability,  I
hope to improve on this later.  If you make any changes to any header files
or the Makefile do a 'make clean' before compiling.
 
Untar the source distribution into a normal user work area logged in as
a standard user.

$ tar -xzf ubee512-n.n.n.tar.gz    (n.n.n is the version number)
$ cd ubee512-n.n.n/src

$ make linux

If you want to cross compile the windows version:
$ make win

If you have compile problems:
Open up the Makefile in a text editor and check the requirements section. 
You will need to make sure the xCINC and xCLIB for each target is correct
for your system.

Install the files
-----------------
As root:
# make install

or if you use sudo (ubuntu) you could use:
$ sudo make install

Un-install the files
--------------------
As root:
# make uninstall

Installation
============
WINDOWS
-------
The binary installer or the binary ZIP distribution file may be used.

The emulator may be installed to any location you want,  if installing to a
systems area then you may need to have administration rights to install and
run the program.

EXE file
--------
1. If you have a previous installation that used the installer you should
   remove this first with the add/remove software found in the control
   panel.  This should not delete any files you have placed into the
   installed location but it is recommended that the files be backed up
   first anyway.
2. Run the installer and follow the directions.
3. Copy the required disk images to the installed program directory
   ubee512\disks\
4. Copy the required ROM images (see ROM IMAGES below)
5. Optional is to place tape wave files in ubee512\tapes\

ZIP file
--------
1. Unzip the windows binary distribution to location you wish to use.  If
   you have a previous installation then you can just unzip over the top of
   the other.
2. Copy the required disk images to the installed program directory
   ubee512\disks\
3. Copy the required ROM images (see ROM IMAGES below)
4. Optional is to place tape wave files in ubee512\tapes\
5. You can create a desktop link to the emulator with some options if you
   don't want to run from a command line.

If running from a cmd prompt from any location you will need to add a path
for the system to find ubee512.

UNICES (Linux/FreeBSD)
----------------------
1. If you have not built and installed the package you need to do that
   first, see the section 'Building from sources'.
2. Make sure you are logged in as a normal user.
3. Run the ubee512 emulator.  The first time this occurs some directories
   will be created in your home account.  It will then exit.
4. Copy the required disk images to you home path,  normally this is located
   here: /home/username/.ubee512/disks/
5. Copy the required ROM images (see ROM IMAGES below)
6. Optional is to place tape wave files in .ubee512/tapes/

ROM IMAGES
----------
ROMs may be subject to copyright,  the ROMs you choose and whether you are
entitled to use any copyrighted ROMs can not be answered here.  If you own a
Microbee computer that already has these ROMs you may be entitled to make
images from them or use a convenient image source.

The ROMs required will depend on what model you are trying to emulate. Disk
emulation will require a boot ROM and tape based models will require Basic
ROMs and possibly other support ROMs.

Copy all required ROMs to the following locations:

Windows:
Installed location\ubee512\roms\

Unices:
Your home location/.ubee512/roms/

Sources
-------
Some ROMs can be found here or at similar mirrored sites.  A library utility
is required to extract the '.lbr' files:

Several library extraction tools to work under CP/M can be found on some
MBUGnnn.ARC disk archives.

A library extraction tool (lbrate) and an unarchiving tool for arc files
(nomarch) is available for Unices here:
http://rus.members.beeb.net/index.html

mbeepc85.zip, mbeepc.zip, mbee.zip, mbee56.zip
http://www.emunews.eu/mess.htm

Boot ROMs:
http://z80cpu.eu/mirrors/oldcomputers.dyndns.org/cdrom/cpm/beehive/os/bootroms.lbr

Premium ROMs:
http://z80cpu.eu/mirrors/oldcomputers.dyndns.org/cdrom/cpm/beehive/os/premroms.lbr

Miscellaneous ROMs:
http://z80cpu.eu/mirrors/oldcomputers.dyndns.org/cdrom/cpm/beehive/os/miscroms.lbr

Character ROM
------------- 
Regardless of what model is being emulated a character ROM image is
required. 'charrom.bin' is the character ROM.  It needs two font sizes for
3.375 MHz models so requires a 3.375 MHz model Microbee 4K ROM image.  If
emulating the 2MHz Microbee model a 2K character ROM could be used.

MODELS
------
Specific emulation for all Z80 Microbees models is supported, this includes
both floppy disk and tape based machines.

Known problems
--------------
* There may be problems with the 'pc' and 'pc85' models displaying a mosaic
  of coloured characters on the display in BASIC.  I have not determined the
  cause of this as yet as I do not know what the correct versions of BASIC
  are for these two models.  The problem does not appear if forcing the
  model to monochrome mode with the -mw option.

* A Telcom v3.2.1 ROM was found not to initialise correctly,  Telcom v1.1
  and v1.2 do appear to work correctly though.  This may not be an emulator
  problem.

* The bn60.rom, a Premium graphical 128K boot ROM will not boot the disk.
  This may not be an emulator problem.

Non Emulator problems
---------------------
* Some 'boot.dsk' images may be set to read only and will fail to open in
  the emulator.  Check the file attributes and make sure the file is not set
  as read only.

* A 256TC tc256r12.bin ROM image appears to be defective.  Use the
  alternative ROM image shown in the 256TC model section below.

Testing
-------
The '56k' model has only been tested for ROM booting into monitor mode using
the --mmode option.  Booting a 56k CP/M system disk has not been tried
although the CIAB system disk does boot and appear to work correctly.  Also
does not have the memory write protect (manually operated switch) feature
implemented yet so can not be made to look like a Basic model.

The '256TC' model has been developed and tested using the 256TC ROM built in
diagnostics. Serial reports failure but does actually work.  The Printer
port passes if a --print=myfile.prn is specified on the command line.  The
system has been tested to boot a 128K operating system but a 256TC system
has not been tested, I am fairly optimistic it should work though.

Special options
---------------
The 256TC model can be forced to boot into menu mode by specifying the
'--nodisk' option. This reports no disk for initial disk checks and so the
menu should appear, further booting (F1) or resetting should then detect the
disk.

The '--mmode' option forces the return of a series of 'M' keys (6545) when
the emulator is started.  This is used for jumping directly into the ROM's
Monitor mode on FDD models.

Model emulation
---------------
The model to be emulated is specified as an option on the command line with:

--model=type

The models (type) that are emulated are:

256tc - Teleterm 256TC, 256K DRAM FDD
p512k - Premium, 512K DRAM FDD
512k  - Standard, 512K DRAM FDD
p256k - Premium, 256K DRAM FDD (64K Premium to 256K upgrade)
256k  - Standard, 256K DRAM FDD (64K CIAB to 256K upgrade)
p128k - Premium, 128K DRAM FDD
128k  - Standard, 128K DRAM FDD (SBC)
p64k  - Premium, 64K DRAM FDD
64k   - Standard, 64K DRAM FDD (CIAB)
56k   - APC 56K RAM, FDD (Advanced Personal Computer)
ppc85 - Premium, PC85 32K Tape
pc85  - Standard, PC85 32K Tape
pc    - PC 32K Tape (Personal Communicator)
ic    - IC 32K Tape
2mhz  - First model and kits, 32K Tape

The p512k model is emulated if no option is specified.

Each model uses a particular boot or BASIC ROM(s),  other ROMs are optional,
all the ROMs must be located in the ubee512/roms directory.  If the default
model boot ROM image can not be opened the emulator will attempt to open the
fall-back image 'rom1.bin' except for the 56K and 256TC models.

BASIC ROMs for the pc, ic and 2mhz models may be one ROM image or ROM part
images. The emulator will try to use the first ROM file in the list, if this
is not found then ROM parts will be used.

Each FDD model has a default boot disk image name,  the default image must
be located in the ubee512/disks directory.  If the default model boot disk
image can not be opened the emulator will attempt to open the fall-back
image 'boot.dsk' or the user may specify what image should be used.
 
Models: 256tc                                 Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: 256TC.ROM                         16K  BIOSNEW2.DAT (v1.15)
                                              16K  tc256r12.bin (does not work)
extra ROMs: rom2.bin (optional)               16K
            rom3.bin (optional)                8K
boot image: 256tc.dsk

Models: p512k                                 Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: P512K.ROM                         16K  bn54.rom, bn56.rom, bn60.rom
extra ROMs: rom2.bin (optional)               16K
            rom3.bin (optional)                8K
boot image: p512k.dsk

Models: 512k                                  Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: 512K.ROM                          16K  bn54.rom, bn56.rom
extra ROMs: rom2.bin (optional)               16K
            rom3.bin (optional)                8K
boot image: 512k.dsk

Models: p128k (SBC)                           Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: P128K.ROM                         16K  bn54.rom, bn56.rom, bn60.rom
extra ROMs: rom2.bin (optional)               16K
            rom3.bin (optional)                8K
boot image: p128k.dsk

Models: 128k (SBC)                            Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: 128K.ROM                          16K  bn54.rom, bn56.rom
extra ROMs: rom2.bin (optional)               16K
            rom3.bin (optional)                8K
boot image: 128k.dsk

Models: p256k (64K to 256K Upgrade)           Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: P256K.ROM                         16K  bn54.rom, bn56.rom ?
extra ROMs: rom2.bin (optional)               16K
            rom3.bin (optional)                8K
boot image: p256k.dsk

Models: 256k (64K to 256K Upgrade)            Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: 256K.ROM                          16K  bn54.rom, bn56.rom ?
extra ROMs: rom2.bin (optional)               16K
            rom3.bin (optional)                8K
boot image: 256k.dsk

Models: p64k (CIAB)                           Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: P64K.ROM                          16K  bn54.rom, bn56.rom ?
extra ROMs: rom2.bin (optional)               16K
            rom3.bin (optional)                8K
boot image: p64k.dsk

Models: 64k (CIAB)                            Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: 64K.ROM                           16K  bn54.rom, bn56.rom ?
extra ROMs: rom2.bin (optional)               16K
            rom3.bin (optional)                8K
boot image: 64k.dsk

Models: 56k (APC)                             Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: 56K.ROM                            4K  56kb.rom
                                               4K  dreamdisk2.18.1_E0.bin
boot image: 56k.dsk

Models: ppc85                                 Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
BASIC ROMs: PREM-A.ROM                        16K  PREM-A.ROM v5.29e (banked)
            PREM-B.ROM                         8K  PREM-B.ROM v5.29e
   Net ROM: PREM_NETWORK.ROM                  16K  telc321.rom ?
  PAK0 ROM: PREM-C.ROM   (Wordbee)            16K  PREM-C.ROM
  PAK1 ROM: PREM-E.ROM   (Basic help)         16K  PREM-E.ROM
  PAK2 ROM: PREM-F.ROM   (Busycalc/PC85 Menu) 16K  PREM-F.ROM
  PAK3 ROM: PREM-G.ROM   (Graphics/Database)  16K  PREM-G.ROM
  PAK4 ROM: PREMVTEX.ROM (Vidotex)            16K  PREM-PREMVTEXT.ROM
  PAK5 ROM: PREM-I.ROM   (Shell)              16K  PREM-I.ROM
  PAKx ROM: PREM_PAK6.ROM - PREM_PAK7.ROM     16K

Models: pc85                                  Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
BASIC ROMs: PC85_BASIC.ROM                    16K  ?
   Net ROM: PC85_NETWORK.ROM (8K)             16K  telc321.rom ?
  PAKx ROM: PC85_PAK0.ROM - PC85_PAK7.ROM     16K  ?

Models: pc                                    Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
BASIC ROMs: PC_BASIC.ROM or                   16K  5.22e ?
            PC_BASIC_A.ROM +                   8K
            PC_BASIC_B.ROM                     8K
   Net ROM: PC_NETWORK.ROM                     4K  telc11.rom
  PAK0 ROM: PC_EDASM.ROM (Editor Assembler)    8K  edasm.rom
  PAK1 ROM: PC_WBEE.ROM (Wordbee)              8K  wbee12.rom
  PAKx ROM: PC_PAK2.ROM - PC_PAK7.ROM          8K

Models: ic                                    Max  Possible Versions/ROMs
-------------------------------------------------------------------------------  
BASIC ROMs: IC_BASIC.ROM or                   16K  ?
            IC_BASIC_A.ROM                     8K
            IC_BASIC_B.ROM                     8K
   Net ROM: IC_NETWORK.ROM                     4K  telc11.rom
  PAK0 ROM: IC_WBEE.ROM (Wordbee)              8K  wbee12.rom
  PAKx ROM: IC_PAK1.ROM - IC_PAK7.ROM          8K

Models: 2mhz                                  Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
BASIC ROMs: 2MHZ_BASIC.ROM or                 16K  5.10, 5.11
            2MHZ_BASIC_A.ROM +                 4K
            2MHZ_BASIC_B.ROM +                 4K
            2MHZ_BASIC_C.ROM +                 4K
            2MHZ_BASIC_D.ROM                   4K 
   Net ROM: 2MHZ_NETWORK.ROM                   4K  telc11.rom
  PAK0 ROM: 2MHZ_PAK0.ROM                      8K  edasm.rom

Linking to ROM or disk image files
----------------------------------
Under unices the preferred method is to create a soft link to the targeted
ROM or disk image file.  This way only one copy of the ROM/disk image is
required if used by more than one model:

example, create a soft link called PC_EDASM.ROM to edasm.rom
$ ln -s edasm.rom PC_EDASM.ROM 

Under Windows 2000 and later soft links for NTFS file systems can be created
with a junction.  There are free tools about to do this.

The alternative to creating a soft link is to copy each ROM image to the
model name for the ROM:

example, copy edasm.rom to PC_EDASM.ROM
>copy edasm.rom PC_EDASM.ROM

Using the uBee512 Emulator
==========================
KEYBOARD
--------
All keys are mapped to their respective locations,  this includes the arrow
keys that appeared on the Premium series.  Some keys do not appear on an IBM
keyboard and these have been remapped as follows:

LINEFEED: PAGEUP
   BREAK: PAUSE/BREAK
   RESET: PAGEDOWN

Other functionality:
 Exit the emulator: END
Full screen toggle: ALT+ENTER
  Tape reset/start: HOME

A confirmation window should appear when pressing the exit or reset keys.

Pressing the ESC key with the PAGEDOWN key (ESC+RESET) will bypass prompting
the user for any confirmation.

DISPLAY
-------
The display supports two display ratios of 2:1 and 1:1,  by default this is
now set to 2:1.  The 2:1 display ratio is a much improved ratio than what
was provided in versions prior to 1.4.0.

When using an 80x24 display mode the 2:1 ratio is very close to a 4:3
monitor aspect ratio.

In BASIC the 64x16 display is not quite as good but still much better than
the 1:1 ratio.

If the display size is 40 characters wide the 1:1 display ratio is enforced.
This keeps Microbee applications like Videotex to the correct aspect ratio.

If the older ratio is preferred then a --aspect=1 option can be specified on
the command line.

DISK IMAGE FILES
----------------
The emulator currently supports the following types of disk images:

WARNING !!!!!: Some of these formats have not been tested,  in particular
are the '.DS80' and '.DS82' images.  Please first test with a copy of your
image.  If reading is successful from all areas of the image then writing
should be fine.  The main issue of concern here is the disk image
specifications and not so much the actual read/write functions.

'.DSK'
CPCEMU Disk image format,  this should work on all standard Microbee disks
including the 3.5" Modular disk format but only Microbee DS DD 40T disks
have been tested to work at this stage.  Other non Microbee formats may also
work.

'.IMG' or '.NW'
Raw image files in nanowasp v0.22 format, 40T DS DD
The format of this image is: S0-T0..T39, S1-T0..T39

'.DIP' 
Disk Image Plus format.  This is currently under development and is subject
to change and may not be used in the future.

The following raw disk image formats have been introduced to allow easy
creation of images commonly used by the Microbee.  The names also help to
identify what disk can be used in which drive to suit the Microbee OS.

The sectors are in sequential order starting from 1 (or 1 and 21 for DS80) 
The format of the singled sided images is: S0-T0, S0-T1, S0-T2, ...
The format of the double sided images is: S0-T0, S1,T0, S0-T1, S1-T1 ...

'.DS40' or '.D40'
Microbee 40T DS DD raw disk image (SBC)

'.SS80' or '.S80'
Microbee 80T SS DD raw disk image (CIAB)

'.DS80' or '.D80'
Microbee 80T DS DD raw disk image (Modular)

'.DS82' or '.D82'
Microbee 80T DS DD raw disk image (Dreamdisk)

'.DS84' or '.D84'
Microbee 80T DS DD raw disk image (PJB)

All disks are recognised by their file name extension,  and is not case
sensitive. A mixture of any of these disk types are allowed for drives A-D.

A disk image containing an operating system is required for drive A.

Disk images may be obtained from http://microbee.no-ip.com

The images used are specified using the '-a, -b, -c, -d' command line
options when invoking the emulator.

If no image is specified for drive 'A' then boot.dsk will be booted.

You must only specify the image type that the OS knows about for each drive.
If you want to use an image of a different size/format for a particular
drive then you must use that OS's set up program to change the drive set up.

Floppy to image software
------------------------
If you want to convert your floppy disks to disk images then this site is
definitely worth a look:

http://www.classiccmp.org/dunfield/img/index.htm

I used the "ImageDisk 1.17" software successfully on a 386 to generate a
DS40 disk image then converted to a raw disk image format, one of the
programs provided tests the FDC capabilities of the host PC.

There are also other disk conversion tools available from the web site.

TAPE PORT IN/OUT
----------------
Tape out to a wave file using the --tapeo option and tape input from a wave
file using the --tapei option have been provided.

A new directory name of 'tapes' will be created in the installation and is
the default location for tape wave files.

The wave file format currently being used is documented further on.  The
format (the default format) may change in the future, compatibility between
different Microbee emulators on the file format will make life easier for
all concerned.  uBee512 currently saves and loads one format type.  The only
flexibility on creating wave files is the ability to set the sample frequency
desired.  Loading of wave files has more flexibility in that the data
element size, channels, etc. can have values other than 8 bit data and mono.

The files produced by uBee512 should be very accurate as regards the timing
as this is directly controlled by the Z80 cycle counters.  It will not make
any difference what the speed of emulation is for the accuracy, but the tape
writes and reads are much faster if emulating at high speed rates.  So if
you a bunch of wave files containing programs that you want to load and save
to disk then high speed mode is the way to go.

Tape sample frequency
---------------------
The tape output sample frequency can be specified using the --tapesamp
option. Currently the default sample frequency is 22050 Hz but this may
change in the future.

Tape volume level
-----------------
The tape output volume level can be specified using the --tapevol option.
The default volume level is 16.

Loading on a Microbee
---------------------
The intention is to have the wave files produced by uBee512 to be loadable
by a real Microbee with the blue tape plug (yellow on later models ?)
connected to your PC speaker output socket and the wave file played back. 
This has not been tested at this stage.

Wave files from cassette
------------------------
The intention is also that DGOS and Kansas City Standard (KCS) format
cassette tapes can be recorded to a wave file (by other software) and then
loaded back into the emulator.  This also has not been tested.  The software
used must be able to write the format being used by uBee512 or converted
afterwards.

There is a conversion tool for Windows,  make a copy of your original as it
overwrites when converting:

http://www.lightlink.com/tjweber/StripWav/StripWav.html

Limited testing
---------------
Testing so far has been limited to saving to wave files using uBee512 then
loading back into uBee512.  As I do not have a Microbee computer I am unable
to test compatibility for real hardware.  I would appreciate any one who
could do this testing and let me know the results.

Saving data to tape
-------------------
Data will be written to the wave file whenever the tape out port changes
state. (As tape data is written to in normal usage)

IMPORTANT: The wave file is closed and finalised when exiting the emulator.
You must exit the emulator to use the file you created.  You can then start
the emulator again using the file as an input.

An example of how to use the tape out feature:

A:>basic

First load a '.MWB' file from disk:
>load "myfile"

Save the file to the tape device at 300 baud:
>csave "file1"

Save the file to the tape device at 1200 baud:
>csavef "file2"

Any single wave file can hold as many tape saves as required. A 5 second
quiet period is placed in the wave file between each csave or csavef
command.

Loading data from tape
----------------------
To load data from tape requires that an extra step be taken.  After issuing
a cload command in basic you need to press the HOME key.  This is required
because the emulator has no idea when a PIO port B read is made what the
intention was as there are other input bits on this port too.

When there is no more data left to be pulled out of the wave file you will
need to press the HOME key again to reset the file to the beginning and
allow the data to be accessed.

The HOME key may be pressed at any time to reset the file to the
beginning, but don't press it during a cload operation.

An example of how to use the tape in feature:

A:>basic

Load a file from tape:
>cload

!!!!! PRESS THE HOME KEY NOW !!!!!

After a few seconds you should see something like:
file1  B *

>cload
file2  B *

You can also specify the file you want to load from the wave file:

Press the HOME key to reset the wave stream.

>cload "file2"
file1  B
file2  B *

Consult the BASIC manual for all the tape commands.

Compressing wave files
----------------------
As the the wave files produced by uBee512 are made up of square waves and
not sinusoidal data the amount of compression that can be achieved is
extremely large, 98% may be typical on a 22 KHz file.

RS232 SERIAL COMMUNICATIONS
---------------------------
RS232 serial communications under interrupts are emulated.  The emulation
makes use of the host PC's RS232 ports so connection to a Microbee computer,
another emulator, terminal, modem or a serial printer should now be
possible.  USB-SERIAL Virtual com port devices have also been tested to
work.

The emulation is for the original Microbee PIO software generated serial
routines.  Baud rates up to 19200 have been tested successfully in both
directions.

The optional Z80 SCC serial IC is not currently emulated.

The options associated with the RS232 serial emulation are:
--coms, --baud, --baudrx, --baudtx, --datab and --stopb 

It is important that a baud rate is specified to match the baud rate you are
using in the Microbee application.  By default this is 300 baud if you don't
tell it otherwise.  If you have problems then check the baud rate settings
and also that you are using the correct com ports.

Requirements
------------
You must pass options on the command line that will match the baud rate,
number of data and stop bits used by the application under the emulator. 
The defaults are 300 baud, 8 data, 1 stop bit.  To enable the serial
emulation option you must specify the serial communications port to be used
on the host PC.

Null-modem emulator 
-------------------
Communication ports can be emulated in Unices and Windows.  For Windows
there is the com0com project:

http://com0com.sourceforge.net/

Testing
-------
Testing involved connecting two serial ports together on my development
platform with a cross over cable:

D9 (F)       D9 (F)
------       ------
RX   2       3 TX
TX   3       2 RX
GND  5       5 GND
RTS  7       8 CTS
CTS  8       7 RTS

7/8 bit data and 1/2 stop bits were tested to work successfully.

Using serial under a Unix style of OS will require that you have access
rights to serial devices.  Typically this involves adding the user in
question to the group associated with the serial device.

The testing that follows used two instances of uBee512 and command lines
with the baud rate adjusted accordingly.

The following tests were conducted at the default speed of 3.375 MHz.  Much
faster file transfer (about x2.5) was able to be achieved using the turbo
mode option but setting a high CPU clock rate will most likely slow things
down because of the way the PIO interrupts work and also time out errors are
likely to occur.

The OS you boot is up to you, the example below boots the 'boot.dsk' from
the default location.

Drive B - 'testdisk.dsk' is a freshly made DS40 disk containing E5 hex in
all sectors.  You could also use a copy of another disk image and erase all
the files on it, the examples shown below will expect to find it in the
default location for disk images.

On Linux:
$ ubee512 -mw -b testdisk.dsk --coms=/dev/ttyS0 --baud=19200
$ ubee512 -mw -b testdisk.dsk --coms=/dev/ttyS1 --baud=19200

On Windows:
> ubee512 -mw -b testdisk.dsk --coms=1 --baud=19200
> ubee512 -mw -b testdisk.dsk --coms=2 --baud=19200

The -mw option is used to enable white monochrome monitor mode as the status
line is very difficult to read in colour.

Telcom v2.0
-----------
Set the baud rate to 19200 for TX and RX for both emulated Telcoms:
>baud 19k

Enter Full duplex terminal mode on each Telcom:
>f

What you type on one Telcom should appear on the other.

Press CTRL+ESC to get back to the main menu on each Telcom.

To send files set one of the Telcoms to receive:
>rec

The other to send a file:
>send myfile.ext

After 5-10 seconds you should notice something happening on the top status
line.

I don't know if v2.0 of Telcom is buggy but I received some inconsistent
results when using it for file transfers.  The later version 2.4 appears to
work perfectly.

Telcom v2.4
-----------
You will need to erase 'testdisk.dsk' before starting.

This version was supplied with the Premium series Microbee.  Telcom and the
CP/M OS worked very well as compared to v2.0 at a speed of 19200 baud for
both Terminal and File transfer mode.

The following file transfer test was made:

Test platform : AMD64 +3800 dual core 2Gb + Fedora Core 6, x86 release.
Emulation     : 3.375 MHz
Baud rate TX  : 19k
Baud rate RX  : 19k
Data bits     : 8
Stop bits     : 1
Parity        : none
Handshaking   : none
Amount sent   : 356Kb
Time taken    : 00:12:16 (H:M:S)
Files from    : all from 400K disk boot image A:
Files to      : 400K DS40 disk image on drive B:
File count    : 43
Retries       : none noted
Errors        : 0

Sender side:
Start Telcom (press '6' from the shell)

Set baud rate to 19200:
>19k

Send the files from drive A:
>send *.*

Receiver side:
We want the files to be transferred to drive B: so exit the shell (press '0'
then 'y' to confirm) then log on to drive B:

>b:

Start Telcom:
>telcom

Set baud rate to 19200:
>19k

Receive the files:
>rec

PC to PC File Transfer
----------------------
The above Telcom v2.4 test was repeated with very similar results between my
two development PCs, One running Fedora Core 6 (FC6) and the other Windows
2000.  Each was running uBee512.  The FC6 side used a USB-SERIAL virtual
serial port and Windows a standard coms port.

Redirection in MicroWorld BASIC
-------------------------------
Connect a communications port to a communications port on the same or
another PC and start the emulator up with 1200 baud communications.

On Linux:
$ ubee512 --coms=/dev/ttyS0 --baud=1200

On Windows:
> ubee512 --coms=1 --baud=1200

Start Basic and redirect the input to come from the serial port (1200 baud)
in addition to the keyboard.  This example used Basic v6.30.  I found v6.23
to be very slow for this example.

>in# 5 on

On the PC with the other communications port run some terminal software at
the same baud rate.  Anything you type in the terminal will be sent to the
emulator's serial port, you can run commands or copy and paste MWB text
files into the terminal.

To turn the redirection off from the serial port enter:
in# 5 off

Output redirection is also possible using "out# 5 on" or "out# 5" if only
the serial port is to be used for output.

I found that using both input and output redirection at the same time did
not work and produced garbled characters. Don't know if this is an emulator
issue or normal.

Break signal
------------
This is emulated for TX but not tested.  I don't know if any Microbee
software ever used this signal.

Unknowns
--------
The emulator may work with Bee modems, this may require that different baud
rates are selectable for TX and RX ?, I have no experience with these type
of modems.

Other Issues
------------
It does not appear that serial cards found on i386 type hardware support
different board rates for the TX and RX direction on the same port, but this
may be available on a full RS232 implementation, so currently you can only
set one baud rate for both directions.  A later release will address this
issue by using 2 separate independent serial ports and a simple adaptor
circuit.

For now you can ignore the --baudtx and --baudrx options and just use the
--baud option to set the baud rate for both directions.

Still to do
-----------
Starnet networking capability.  Need further information on how PIO port B
bit 7 works. (or may even work as is ?)

PARALLEL PRINTER
----------------
Printer emulation on port A of the PIO is emulated under interrupts.
Currently the printer output can be directed to file(s) in one or two
formats.  You can use both formats at the same time if desired.

A new directory name of 'printer' will be created in the installation and is
the default location for printer files.

The options associated with the printer emulation are:
--print, and --printa

Normally the --print would be used,  the --printa option is used to generate
an ASCII decimal file so the actual values can easily be seen.  Both options
can be used together with different file names if required.

Examples
--------
This example will boot the default disk and send printer output to the
default print directory:

>ubee512 --print=myprint.prn

The examples that follow assume that the default printer is the parallel
device.

CP/M redirection
----------------
Once in CP/M go to the command line.

To send all console output to the printer:
Press ^P

Send some stuff to the console and printer:
dir a:

Type a file:
type textfile.txt p

Turn off printing output:
Press ^P

This output will not go to the printer file:
dir a:

Basic
-----
Start BASIC and load a MWB file from tape or disk then 'llist' to the printer
device, this is a simple method that can be used to convert files to text
format:

>load "prog1"
>llist
>load "prog2"
>llist
>load "prog3"
>llist

prog1, prog2, and prog3 will all be concatenated together in the printer
file.

Exit the emulator and look in myprint.prn

The file may then be printed from the host system using the appropriate
software.

EMULATION HACKING
-----------------
The Microbee was very popular with hardware hackers,  so why not have some
emulator hacking capabilities ?  The options below can be used to experiment
with the inside workings of uBee512:

-f, --frate=fps
-t, --turbo
-x, --xtal=frequency 
--vblank=method
--sound=method

A useful combination that prevents multiple keys being produced in quick
succession when running in turbo mode is to use:

-t --vblank=1

This will only work if the keyboard scanning code in the application uses
the VBLANK status of the 6545.  If the key scanning code relies on software
delays then it will not make any difference.

This will also control the speed of any games that rely on the VBLANK
status and play these at the correct rate.

Speed execution information
---------------------------
An explanation of how uBee512 controls Z80 speed execution is needed here
before progressing any further:

By default a frame rate of 30 FPS and a CPU clock frequency of 3375000 Hz is
used to determine how many cycles of Z80 code are executed in one block:

cycles = clock / framerate

A real Microbee would execute these cycles in this amount of time:

time = cycles / clock

After these cycles have executed some house keeping duties are carried out,
i.e. screen updates, key checks, etc.  The time taken to execute the cycles
and the house keeping duties is measured (timex), so we now know what time
it took and what time it should take (time).  We can now calculate the delay
that is required from these two values:

delay = time - timex

This delay is used to make the emulator run at the stated clock rate.  Turbo
mode simply disables inserting this delay, this then results in the emulator
running as fast as possible.

As the speed is made higher a state will eventually be reached where timex
will be larger than time.  The delay value will go negative and will not be
used.  This state is where the emulator can no longer regulate the execution
speed and will result in the frame rate reducing, essentially it will behave
as if in turbo mode.

Much faster execution is possible by increasing the cycles value and running
in turbo mode.  you can do this by specifying the frame rate with the
--frate option.  By making the frame rate smaller you end up with a higher
cycle value.  The higher cycle value results in the emulator spending more
time executing Z80 code and less time doing house keeping duties.  If the
cycle value is too high it will result in slow updating of the display.

Now that is known how things work the options can be used to play with the
speed.

Some speed options
------------------
A value of 200 MHz causes the screen to update quite slowly so may at first
appear to be slow but it is actually executing code very quickly:

--xtal=200.0

Another approach if you want speed is to specify a frame rate value and drop
it into turbo mode, whenever turbo mode is used the frame rate no longer holds
true, it simply determines how many Z80 cycles are executed in one frame.

The example shown below will execute 3375000/10 Z80 cycles per frame with no
additional delays thrown in, the --vblank option is just used to stop keys
exploding out under basic or CP/M:

-t --frate=10 --vblank=1

COMMAND LINE OPTIONS
--------------------
Usage: ubee512 [options]

-a, --image_a=file      Image file path & filename for floppy drive A
-b, --image_b=file      Image file path & filename for floppy drive B
-c, --image_c=file      Image file path & filename for floppy drive C
-d, --image_d=file      Image file path & filename for floppy drive D

                        If you specify a path as part of the image name then
                        it will be accessed from that area.  If only an
                        image name is specified the emulator will look for
                        it here:

                        Windows:
                        installed location\ubee512\disks\

                        Unices:
                        your home path/.ubee512/disks/

                        Hint: if you want to access an image in the current
                        directory you need to force it using the following
                        method:

                        Windows:
                        ubee512 -a .\myimage.dsk

                        Unices:
                        ubee512 -a ./myimage.dsk

--aspect=n              Set the display aspect, n=1 is 1:1,  default aspect
                        2:1 (n=2),  n may be set to 1 or 2.  1:1 scaling
                        may be enforced for some CRTC6545 display sizes'.

--baud=rate             Set serial communications baud rate for both TX and
                        RX.  A value from 1 to 19200 is allowed.  Default
                        rate is 300 baud.  If Individual baud rates are
                        required for TX and RX then use the --baudtx and
                        --baudrx options instead.  This value must match the
                        Microbee serial application's value.

--baudtx=rate           Set serial communications baud rate for TX only.  A
                        value from 1 to 19200 is allowed.  Default rate is
                        300 baud.  This value must match the Microbee serial
                        application's value.

--baudrx=rate           Set serial communications baud rate for RX only.  A
                        value from 1 to 19200 is allowed.  Default rate is
                        300 baud. This value must match the Microbee serial
                        application's value.

--coms=port             Serial communications port for emulation of RS232.
                        On Unices specify a device, on Windows specify the
                        com port number.  No serial communications will be
                        emulated if this option is not specified.

--conio                 Switches on verbose console output for Windows port.
                        By default only fatal errors and some option's output
                        is sent to the console.

--datab=bits            Set serial communications number of data bits.  A
                        value from 5 to 8 is allowed.  Default value is 8
                        data bits.  This value must match the Microbee
                        serial application's value.

--frate=fps             Frame rate,  the default is 30 FPS,  an integer value
                        between 1 and 1,000,000 is allowed.  This option is
                        intended for 'hacking' and code development use.

-f, --fullscreen        Start in full screen mode (use ALT+ENTER to toggle).

-h, --help, --usage     Display help information on command line usage.

--mmode                 Forces the return of the 'M' key once when the
                        emulator is started.  This is used for jumping
                        directly into the ROM's Monitor mode.

--model=type            Model type, if this option is not specified the p512k
                        model is emulated.  The 'p' denotes a Premium
                        variation in a model.  The following models are
                        supported: 256tc, p512k, 512k, p256k, 256k, p128k,
                        128k, p64k, 64k, 56k, ppc85, pc85, pc, ic, and 2mhz.

-m, --monitor=type      Monitor type, if this option is not specified a
                        colour monitor is the default. <type> may be one
                        of the following:

                        a : amber monitor
                        g : green monitor
                        w : white monitor, white foreground on black
                            background
                        b : black monitor, black foreground on white
                            background
                        c : colour monitor

                        Note: This option by itself does not force the
                        emulation into a standard model Microbee, it's use
                        simply determines what sort of monitor is connected
                        to the emulated Microbee, be it a standard or
                        Premium model.  If you want to force the Premium
                        graphics 'off' you must uses the -s<col> option.  If
                        <col> = m then this option can then further set
                        the desired monochrome colour.

--nodisk                Force no disks initially,  used to start some boot
                        ROMs in menu mode.

--pcg=n                 Premium model option that sets size of PCG RAM to be
                        emulated.  n may be 16 or 32.  Standard premium
                        models are 16K.  Default is 32K.

--print=file            Printer output to file,  the output is not modified.
                        The location of the file follows the same rule as
                        used for the drive image options except default
                        directory is 'printer'.

--printa=file           Printer output to file,  the output is converted to
                        ASCII decimal. The location of the file follows the
                        same rule as used for the drive image options except
                        default directory is 'printer'.

--rtc=n                 Real Time Clock (RTC) emulation. n=1 to enable, n=0
                        to disable.  The following models use RTC by
                        default: 256tc, p512k, 512k, p256k, 256k.

--sound=method          Determine the method used for sound,  the default
                        method is 'prop':

                           off : sound is turned off
                          prop : sound is proportional to XTAL frequency
                        normal : sound rate forced as if 3.375 MHz XTAL

-s, --standard=col      Standard graphics Microbee emulation,  turn off
                        the Premium (alpha+) graphics and use a standard
                        green monitor. The <col> specifier allows for
                        standard monochrome or colour support:

                        c : standard Microbee with colour
                        m : standard Microbee with Green monochrome

                        If using this option with the 'm' parameter then the
                        -m<mode> option can also be specified to select the
                        monochrome colour that is preferred.

--stopb=bits            Set serial communications number of stop bits.  A
                        value from 1 to 2 is allowed.  Default value is 1
                        data bits.  This value must match the Microbee
                        serial application's value for TX.

--tapei=file            Tape input from a WAV file.  The location of the file
                        follows the same rule as used for the drive image
                        options except default directory is 'tapes'.

--tapeo=file            Tape output to a WAV file.  The location of the file
                        follows the same rule as used for the drive image
                        options except default directory is 'tapes'.

--tapesamp=frequency    Tape output sample frequency in Hz.  Default is
                        22050 Hz.

--tapevol=level         Tape output wave file volume level.  A level of 0 to
                        127 is allowed. (default level is 16)

-t, --turbo             Turbo mode, executes Z80 code as fast as possible.
                        Without this option the emulation attempts to keep
                        Z80 CPU execution to match the XTAL value.  This
                        option is intended for 'hacking' and code development
                        use.  There are much faster methods if more speed is
                        required. (see the README file)

--vblank=method         Vertical blanking method to be employed. This is
                        only intended for 'hacking' when experimenting with
                        turbo mode and/or high XTAL speeds.  It is not
                        required or even recommended to be used if 3.375 MHz
                        or 2 MHz emulation is desired.

                        0 : 50 Hz VBLANK rate derived from Z80 cycles and is
                            proportional to the XTAL frequency.
                        1 : 50 Hz VBLANK rate derived from the host timer.

                        When running in turbo mode then setting the <method>
                        equal to 1 will ensure that a VBLANK rate of 50Hz
                        will be used.  Without this, key repeating may be
                        too fast.

--vdu=n                 Premium model option that sets size of VDU RAM to be
                        emulated.  n may be 2 or 8.  The VDU RAM size
                        determines the number of screen, attribute and colour
                        RAM banks.  Standard premium models are 2K.  Default
                        value is 2K.

--version               Obtain the version number.

--vol=level             Set the sound volume level.  A level of 0 to 127 is
                        allowed. (default level is 16)

-x, --xtal=frequency    Set the Z80 clock frequency for emulation in MHz.
                        Standard emulation frequencies are 3.375 and 2.0
                        MHz.  All other frequencies are classed as 'hacking'.
                        3.375 MHz is the default clock frequency.  Frequency
                        is entered as a floating point number.

                        The highest frequency possible is determined by the
                        host platform.  As the value increases to the point
                        where uBee512 can no longer regulate the Z80
                        execution rate the frame rate will decrease (slower
                        screen update periods).

-z, --debug             Debugging output (for development purposes only)
                        writes to a log file.

Some sample command lines
-------------------------
Show the help information on command line usage.
>ubee512 -h

Boot the boot.dsk image found in the default location.
>ubee512

Boot the boot.dsk image found in the path specified. Use forward
slashes on unices.
>ubee512 -a \path\otherboot.dsk

Boot a 128K system with A and B images
>ubee512 -a myboot128k.dsk -b mydisk-ds40.dsk

For 'micro defender' game we must use a monochrome monitor.  The '-mw' is
for white on a black background.
>ubee512 -mw -a mybootdisk.dsk

Boot the default boot image in full screen mode.
>ubee512 -f

Boot the default boot image in turbo and full screen mode.
>ubee512 -t -f

Boot the default boot image with the sound off.
>ubee512 --sound=off

Boot the default boot image with the sound volume set to level 10.
>ubee512 --vol=10

Boot the default boot image with a Z80 clock frequency set to 2 MHz.
>ubee512 --xtal=2

Boot the default boot image, use a tape input wave file
>ubee512 --tapei=mytape.wav

Specifications
==============
WAVE FILE FORMAT
----------------
uBee512 uses The Canonical WAVE File Format.

Here are some links about it:
http://www.lightlink.com/tjweber/StripWav/Canon.html

I used this as my reference material:
http://ccrma.stanford.edu/courses/422/projects/WaveFormat/

Files created by uBee512 are:
- PCM: 1 (no compression)
- Channels: Mono (single channel)
- Sample rate: can be specified using --tapesamp option
- Bits per sample: 8

Files read by uBee512 must conform to:
- PCM: 1 (no compression)
- Channels: specification dependent (only the first channel data is used)
- Sample rate: specification dependent
- Bits per sample: 8, 16 or 32

Frequently Asked Questions (FAQ)
================================
Q: I have a "boot.dsk" image in the correct location but the emulator
   reports something like (Windows example): fdc_loaddisk: Unable to open
   c:\Program files\ubee512\disks\boot.dsk
A: This is most likely caused by the "boot.dsk" file set as read only.  This
   file must be writeable.  In Windows explorer right click on the file and
   select the properties option, then uncheck the Read-only flag.

Q: How often can I expect to see new releases ?
A: As this project is quite new and currently under fairly heavy development
   expect releases every 14-28 days or less, but this may vary due to any
   problems that may be encountered along the way and also other
   commitments.

   Bug fix releases will normally only occur if I believe it has a large
   impact on the performance of the software so may be held over to the next
   minor or major release version.

Q: When I use the turbo mode option, pressing a key causes multiple keys to
   be displayed in very quick succession.
A: Use the --vblank=1 option when using the turbo mode option.

Q: It's a bit of chore having to type in long command lines with the options
   I desire, how can this be made easier ?
A: Create a batch file(s) in Windows or script file under Unices that
   contains your favourite start up methods.  Alternatively create desktop
   links with the command options included.

Q: Will there be a Graphical User Interface (GUI) for uBee512 ?
A: Yes, this is planned to be added later.  The main focus at present is to
   emulate most of the Microbee hardware features, but not to the extent
   that it holds up a GUI development.  A GUI will allow hot-plugging of
   various disk images, wave files (for tape) amongst other things.

Acknowledgements
================ 
1. Thanks to the nanowasp v0.22 release by David G. Churchill. This project
   was forked from it.

2. Thanks to the http://microbee.no-ip.com web site.  This site provided the
   various documentation I needed to make this project happen.

3. Thanks to Neil Bradley (Multi-Z80 CPU emulator) for allowing me to make
   some code changes to makez80.c to add an undocumented instruction.

4. Thanks to Malcolm Kay for his assistance and for building and testing the
   FreeBSD port.

Links
=====
- http://microbee.no-ip.com web site.  This site provides a lot of useful
  information for Microbee users.
- http://z80cpu.eu/mirrors/oldcomputers.dyndns.org/cdrom/cpm
- http://www.digitalresearch.biz/CPM.HTM
- http://www.classiccmp.org/dunfield/
- http://www.seasip.demon.co.uk/Cpm/index.html
- http://www.znode51.de/indexe.htm

Contact
=======
If you have any new feature suggestions, bug reports, etc. then please send
an email to: ubee512@gmail.com

For bug reports please provide the following information:
1) Version number of the uBee512 emulator.
2) The platform it was running on, for example if running on Windows then
   state if W95, W98, Me, W2000, XP, Vista, etc.  Same for Linux, state the
   actual Linux distribution used and version.
3) SDL version used if known.
4) What uBee512 distribution package was used for the installation.
5) Path used for the installation.
6) Command line start up options used (cut and paste if possible)
7) Description of the problem.

Enjoy!

Stewart
(uBee on the http://microbee.no-ip.com site)
