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

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

                     Copyright (C) 2007-2008  Stewart Kay

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

Distribution License
====================
The GPL in this distribution applies to the uBee512 sources, and the
binaries produced from it.  The SDL, LibDsk Mesa 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-2008  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
---------------------
These tools are "Freeware".  The software comes with absolutely no
warranties and are to be used at your own risk.  The code is provided
"as-is".

The source/scripts and binary code are allowed to be modified for personal
use only, these must not be used in any other projects in original or
modified form without written permission from the author.

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/

- LibDsk by John Elliott.  LibDsk is a library intended to give transparent
  access to floppy drives and to the "disc image files" used by emulators to
  represent floppy drives.
  http://www.seasip.demon.co.uk/Unix/LibDsk/

- Mesa 3-D graphics library.
  http://www.mesa3d.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), Joystick, CPU speed switching and key board
emulation.  The extra DRAM 256 and 512 emulation models allows other third
party operating systems to be used.  The 256TC Telecomputer and Teleterm
models are 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/

You could also create a freshmeat.net account and subscribe to my project to
be informed of new releases here:
http://freshmeat.net/projects/ubee512/

This README file is updated for each new release and may contain additional
examples and corrections.

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.

The 'C' version of MZ80 now works to limited a degree.  Some op-codes do not
appear to be executed correctly and timing that relies on cycle counts does
not work correctly. There are other differences in the way the 'C' and ASM
builds emulate instructions. For now the 'C' build of MZ80 remains
unsupported.

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 Ubuntu 8.04.1 Hardy
  using the 32 bit version.

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

Changes for this release
------------------------
New for this release:
* Ubuntu Debian binary package added to the distribution packages.
* Added OpenGL textured video rendering mode, SDL remains the default mode. 
  To use OpenGL mode specify '--video-type=gl' on the command line or set
  the required system's video type by changing the assignment inside the new
  sample configuration file.  See the README file if OpenGL results in a
  white display.
* The OpenGL mode permits 4:3 and other aspect ratios in a window, full
  screen and maximised modes fill completely.
* Added --gl-filter_fs, --gl-filter_max and --gl-filter_win options to
  select soft or sharp filtering modes in OpenGL mode.
* Added --gl-aspect-bee option to set the Microbee aspect ratio.
* Added --gl-aspect-mon option to override the monitor aspect ratio.
* Added --gl-max option to enable/disable maximised window on start up. This
  currently does not work for Windows. Maximised windows can be set after
  starting the emulator.
* Added --gl-vsync option to enable/disable vertical sync swap buffers every
  n'th retrace.
* Added --gl-winpct option to set the initial window width by percentage.
* Added --gl-winpix option to set the initial window width by pixels.
* Added EMUKEY+F hot key to toggle the current filter mode when in OpenGL
  mode.
* Added EMUKEY+KP1 to EMUKEY+KP9 hot keys to select 10-90% width windows
  when in OpenGL mode.
* Added EMUKEY+KP_PERIOD to use the Microbee's 6545 screen width for the
  window width when in OpenGL mode.
* Added window resize feature using mouse to set window size when in OpenGL
  mode.
* Added 'gl' parameter to the --video-type option to select OpenGL mode.
* Added internal variables that can be created and accessed using options.
* Added scripting language options for uBee512 configuration files.  The
  options relevant are described below:
* Added --varset and --varuset options to set and unset variables.
* Added --exit to allow emulation to exit during start up.
* Added --echo and --echoq to send string and/or variables to stdout.
* Added --if-end to terminate a test condition.
* Added --if-else to divert on a --if-test = false condition.
* Added --if-egt to test if string is equal to or greater than.
* Added --if-elt to test if string is equal to or less than.
* Added --if-eq to test if string is equal to.
* Added --if-gt to test if string is greater than.
* Added --if-lt to test if string is less than.
* Added --if-negt to test if string is not equal or greater than.
* Added --if-nelt to test if string is not equal or less than.
* Added --if-neq to test if string is not equal to.
* Added --if-ngt to test if string is not greater than.
* Added --if-nlt to test if string is not less than.
* Added --if-set to test if a variable has been set.
* Added --if-nset to test if a variable has not been set.
* Added --if-system to test for underlying system type.
* Added --if-true and --if-false to set the condition to true or false.
* Added --if-cmpmode to set the method used to compare values.
* Added preconfigured variables UBEE_VERSION, UBEE_HOST, UBEE_SYS_MAJOR and
  UBEE_SYS_MINOR to the existing UBEE512 (ubee512) variable.  These are all
  created using the --varset method so this also means they can be removed
  with --varuset.
* Added joystick C_WINI and C_WIND commands for increasing/decreasing window
  size.
* Added joystick C_GLFILT command for toggling of OpenGL filter mode, and
  C_VSIZE1 command for video resizing.
* Added joystick C_MWHEEL command to select mouse wheel association.
* Added +video and +options to the --modio option arguments.

Changes:
* Changed --snd-freqlow default to 20Hz to improve re-sync on quiet periods.
* Some improvements made to the audio holdoff code.
* Recoded the vdu_colcont_w() function to test RGB intensity bits and VDU
  PCG/colour RAM selection bits separately, this prevents a change in either
  leading to unnecessary time consuming updates.
* Changed version checking to skip a new version install if a later version
  ID string is found. This allows older version binaries to run without
  modifying the version ID. This will only work with emulator versions
  3.0.0 and onwards.
* Changes made to ubee512rc and games.ini.sample files making use of the
  new scripting language options added to this release.
* Comment lines in configuration files may now have leading white space.

Fixes:
* Fixed issue when changing screen sizes from within a Microbee program that
  could possibly cause the emulator to crash under certain circumstances.
* Added code to correctly handle double quoted command line arguments
  when using win32 before being processed by getopt_long().

uBee512 v3.0.1
Fixes:
* Fixed a bug when toggling full screen mode under Unices when using SDL
  video rendering failed to switch modes and would freeze.

Overall features
----------------
* Support for OpenGL and SDL video rendering.
* Scripting language for emulator start-up configuration.
* Configuration file(s) allows default settings and customised models to
  be defined.
* 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.
* Premium composite monochrome half intensity emulation.
* 256TC Telecomputer and Teleterm models emulation.
* Early colour circuit 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.
* Microbee joystick and joystick to key mappings.
* Real Time Clock (RTC) emulation.
* Fully mapped 6545 and 256TC/Teleterm 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.
* LibDsk and built in disk image formats supported.  read/write capability
  is available for drives A-D.
* Speed execution accuracy and regulation is excellent and very fast in
  turbo mode and even faster if specifying the clock 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,
  black and a user mode.
* Full screen mode.
* Emulator 'hacking' options.
* Z80 Debugging tools built in.
* Tools allowing files to be copied between the host system and CP/M.

Configuration file
------------------
The emulator is highly configurable,  the configuration file uses the same
options that are possible on the command line.  Customised sections can be
added making invoking the emulator with options much easier.  Command line
parameters can be used in addition if desired and more than one customised
section can be invoked from the same command line.

Other alternative customised configuration files may also be specified if
required.

Telecomputer (256TC) emulation
------------------------------
The 256TC model is emulated.  The external serial keyboard option is not
supported.  The Real Time Clock (RTC) is emulated.

Premium emulation
-----------------
Premium Microbees were released standard with 16K of PCG and 2 or 8K each of
screen, attribute and colour RAM (VDU) but was able to be expanded to 32K
PCG and the full 8K for VDU RAM.

There is emulation option to select 32K PCG RAM for emulation.

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

Colour video is also part of the Premium series and this too is emulated. 
You have a choice of monitor types to view the output on.

The full 8K of VDU RAM was not actually used as some Premium software would
not work correctly with it unless the programmer was fully aware of the
possibility of the extra 2K RAM banks being installed at a later date, some
machines were shipped with the full 8K for the screen, colour and attribute
RAM but configured to only use 2K for each (3 x 6K wasted).

The problem:
When programming the extra graphics capability of the Premium and selecting
one of the extra PCG banks then attempting to write to VDU RAM (i.e screen,
colour, attribute) would work fine for a machine set for 2K VDU RAM but if
the extra VDU RAM was installed and enabled the incorrect VDU bank would be
selected.

It was the responsibility of the programmer to select VDU bank 0 before
attempting any further access, but programmers were not doing this.  Problem
was that unless the programmer had a full 8K VDU RAM machine for development
the bug would not have been noticed.  If the Premiums were released with 8K
as standard from day one this problem would not have eventuated.

There is an option to use the full 8K VDU RAM and it will behave like a real
Premium with the same problems.

So what was the purpose of this extra VDU RAM then?  Not sure, except it
might have been possible to allow fast switching of displayed video frames
by pre-loading the RAM then adjusting the 6545 display address.

Teleterm emulation
------------------
This model has not been tested, the full technical information is not
currently available and ROM images are required.  The emulation is based on
what information is on hand and some guess work so it may or may not work. 
Some options have been added that will allow some ROM locations to use SRAM
instead, some of these may be required in addition to the model option. 

This model is reported to have 40K of SRAM and would appear to use the same
hardware as used by the Premium model with some changes to incorporate a
daughter board for the later keyboard.  It is not obvious where the extra 8K
SRAM is located but could have just used some banked PCG RAM, for this
reason 32K PCG RAM has been allocated for this model's emulation.  If the
extra 8K was achieved by using a PAK or other ROM location then some other
options in addition to selecting this model may be used to achieve correct
emulation.

Reference:
Online journal - issue 24, June 1986, pages 25-27.
Online journal - issue 27, September 1986, pages 18-20.

If anyone can help out with ECNS (additions in HWNB) concerning this model
or ROM images then please email me at the address contained in the 'Contact'
section at the end of this README file.

56K (APC model) emulation
-------------------------
This model does not have the memory write protect (manually operated switch)
feature implemented yet so can not be made to look like a Basic model.

Standard colour emulation
-------------------------
Colour emulation for standard models prior to the Premium and 256TC/Teleterm
model Microbees have been emulated.  The optional colour board circuitry,
the colour values and methods used is quite different to the later alpha+
colour models.

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/Teleterm keys, RTC, and VSYNC 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
appears to have been designed to keep time and date for the years 1901-2099
only.  It correctly adjusts for the leap year that does occur in 2000.  The
system software around for the Microbee is typically not Y2K compliant. 
Usually the '19' is just hard coded in for the year part and the year '2008'
would be displayed as '19:8' on a Microbee today.  The ':' is the next ASCII
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 subtracting 100 from the year to
produce the year '1908'.  If the Microbee application only displays the last
2 digits everything will look correct.

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

Joystick emulation
------------------
The standard Microbee joystick is emulated.  Any joystick that is supported
by SDL and has switch capability should be suitable. A cheap PC USB Game Pad
was used for development and works well.  The joystick buttons have default
configurations but may be configured as required.

Also supported are joystick to key and command mappings that allow games and
other programs to use joystick control, there are 256 sets that may be
configured, the first 26 of these are selectable from the keyboard using hot
keys.

PIO Port B bit 7 links
----------------------
The link settings that determines the signal to PIO port B bit 7 are
emulated, an option can be specified to select the required signal.

Speed performance
----------------- 
Emulation speed is excellent when targeting 3.375 and 2.0 MHz, the speed is
consistent and smooth on all programs tested.  Each model emulated uses the
standard CPU clock frequency designed for that model 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.

Even faster speed is possible by specifying the CPU clock frequency to be
emulated as a command line option.  On the hardware mentioned above, 200+
MHz and possibly as high as 1GHz 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 your host platform's capability.  Reducing the CPU clock
frequency down improves the frame rate.

Using banked CP/M operating systems may reduce the speed achievable as a
large amount of DRAM bank switching is used to access code in other banks
and is especially noticeable when doing nothing and only checking for keys. 
This is not an issue for a real Microbee but under emulation requires 32K of
RAM to be switched in and out every time the bank changes.  For this reason
non-banked CIAB and 56K CP/M systems do not use as much host CPU time.

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 Standard/Premium versions
* PJB v1.2 and 512K v2.0a pre-release
* PJB 512K v2.2P
* PJB 256TC v2.2P
* Microbee 256TC Telecomputer
* Microbee 56K CP/M

Z80 Application software
------------------------
Too numerous to mention it all, but essentially all system support programs
and 3rd party software work including 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://microbee.no-ip.com/uploads/Software/
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/

File paths and Variables
========================
BUILT-IN VARIABLES
------------------
uBee512 has internal variable support, variables may be created by the user,
some predefined variables are created at run time that may be accessed using
options.

Any internal variables may be redefined by using first using an --varuset
option followed by a --varset option.  Variables defined by the system takes
precedence.

The internally created variables are:

  UBEE512 or ubee512      Path to the ubee512 account.
  UBEE_VERSION            Emulator version.
  UBEE_HOST               Host system (UNIX or WIN).
  UBEE_SYS_MAJOR          On Unix systems this will be 'UNIX' On Windows
                          systems it contains one of the following:
                          win9x_me, nt4, nt5 or nt6.  Both systems will use
                          upper case for the variable value.
  UBEE_SYS_MINOR          On Unix systems this will be the value of the
                          uname.sysname member.  On Windows systems it contains
                          one of the following: w95, w98, me, nt4_ws,
                          nt4_server, w2000, xp, server_2003, or vista. Both
                          systems will use upper case for the variable value.

The @UBEE512@ variable allows scripts to be portable between systems and
should be used if portability is to be maintained. The configuration files
that come with the uBee512 distribution make use of this.

This variable is set to the uBee512 installed location in Windows or the
account location in Unices, typically it will have the following values:

Windows:
c:\Program Files\ubee512

Unices:
/home/username/.ubee512

This variable may be overridden by specifying an environment variable for it
as that is checked first.

Through out this documentation @UBEE512@ will be used to refer to the
account location.

ENVIRONMENT VARIABLES
---------------------
Environment variables may be used by parameters to options.  The variable
may be passed using the shells normal method, i.e. %VAR% in Windows and $VAR
in BASH (Unices), the shell in these cases will simply pass the variable
value through without uBee512 even knowing.  This method is fine for command
line usage but another method that is portable is possible by passing the
variable as @VAR@, this also allows the use of environment variables to be
used in configuration files.

PATH SLASH CHARACTERS
---------------------
Forward or back slashes may be used in file paths irrespective of the
program being run under Unices or Windows environments when slash conversion
is enabled. See --slashes option. Unices will see '\' as an escape sequence
when used on the command line and also when found in configuration files and
slash conversion is disabled.

FILES TO BE OPENED
------------------
Existing files will first be searched for in the current directory, if the
path is not found a second search in the default directory will take place.
For the second search the file path specified will be appended to the
default directory path.  The second search is not carried out if a '\',
'.\', or '..\' are the first characters of the path or a ':' character is
used under Windows.

FILES TO BE CREATED
-------------------
Files to be created will be placed into the default directory unless a path
to another location is specified by using a '\', '.\', or '..\' as the first
characters of the path or a ':' character is used under Windows.

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
ubee512_n.n.n_i386.deb   : Binary package for Ubuntu (Debian)

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.

LibDsk support is pre-set to be compiled in but can be disabled in the
Makefile if so desired.  To compile LibDsk support in will require libdsk.h
and libdsk.a files on the build system.

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-linux

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

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 including a USB
drive, 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 an existing installation then save the current libdskrc file
   if this has been customised.  This file if it exists will be found in the
   share directory.
2. 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.
3. Run the installer and follow the directions.
4. To access floppy drives on Windows 2000 and above requires a special
   floppy driver to be installed. This is available from here:
   http://simonowen.com/fdrawcmd/
5. Follow the install instructions under 'ALL SYSTEMS'.

ZIP file
--------
1. If you plan on installing over an existing installation then save the
   current libdskrc file if this has been customised.  This file if it
   exists will be found in the share directory.
2. Unzip the windows binary distribution to a location you wish to use.  If
   you have a previous installation then you can just unzip over the top of
   the other.
3. To access floppy drives on Windows 2000 and above requires a special
   floppy driver to be installed. This is available from here:
   http://simonowen.com/fdrawcmd/
4. You can create a desktop link to the emulator with some options if you
   don't want to run from a command line.
5. Follow the install instructions under 'ALL SYSTEMS'.

UBUNTU (DEBIAN)
---------------
The Ubuntu package has 'libdsk' statically linked into the binary package.
All other dependencies will be handled by the installer program.

1. Use a package installer of your choice:
   a) To use the dpkg installer: $sudo dpkg -i ubee512_n.n.n_i386.deb or
   b) From the desktop double click on the deb file from 'File browser'
2. Follow the install instructions under 'ALL SYSTEMS'.

UNICES FROM SOURCE (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. Follow the install instructions under 'ALL SYSTEMS'.

ALL SYSTEMS
-----------
1. Run the ubee512 emulator.  The first time this occurs a windows message
   (or text to stdout in Unix) will be displayed with some information. Some
   directories and files will be created in your home account.  It will then
   exit. (Windows will ask you to confirm first).
2. Copy the required disk images to the installed program directory
   @UBEE512@\disks\ (see DISK IMAGES below)
3. Copy the required ROM images (see ROM IMAGES below)
4. Optional is to place tape wave files in @UBEE512@\tapes\
5. A ubee512rc will have been created if no previous file by that name
   existed, this file may be edited to allow settings to be customised. 
   (see CONFIGURATION FILE below).  If you want to use OpenGL video
   rendering mode the option for the host system may need to be set.
6. If running from a console prompt from any location you will need to add a
   path for the system to find ubee512.

DIRECTORY AND FILE STRUCTURE
----------------------------
The following directories and files will be created in the home account when
uBee512 is run for the first time or when installing from the ZIP or
installer applications/scripts:

Directories:
disks           default location for disk images.
doc             documentation for uBee512, license information, etc.
files           default location for Microbee files.
images          contains uBee512 icons, etc.
printer         default location for printer output emulation.
roms            default location for ROMs.
rtc             used by uBee512 for storing RTC values per model.
tapes           default location for tapes in/out.
tools           contains support tools (may be empty on Unices)

Files:
ubee512_ver.id  contains the current version ID string.
ubee512rc       default configuration file.
disks.alias     default disk aliases file.
roms.alias      default ROMs aliases file.

Windows only:
configs         contains sample configuration files.
share           contains libdskrc disk definitions file.
ubee512.exe     uBee512 executable file.
SDL.dll         SDL Dynamic Link Library file.

Unices only:
.ubee512        ubee512 account in home directory.
.libdskrc       libdskrc disk definitions file in home directory.
/usr/local/bin/ contains ubee512 binary.
/usr/local/share/ubee512 contains default ubee512 configuration files,
documentation, tools source code, etc.

RUNNING FOR THE FIRST TIME
--------------------------
Each time uBee512 is run a check is made for the presence of the version
identification file (ubee512_ver.id) and the contents. If the ID version is
older than the current emulator running or if not found then a console
message will be displayed with information, the user should follow the
instructions before running the emulator again.

Older versions of the emulator (from v3.0.0) may co-exist if desired without
affecting the account or seeing the install message re-appearing.

Other files and directories will be created if not found. ubee512rc,
roms.alias, and disk.alias files will be created from default sample files
if these are not already found in the uBee512 directory.

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

I have cross compiled lbrate for win32 by changing the CC entry in the make
file from CC=GCC to CC=i386-mingw32-gcc then running i386_mingw32-strip on
it to reduce the size of the executable down.  It should also be possible to
compile under Windows and GCC without any changes necessary to the Makefile.

The cross compiled lbrate can be found here:
http://microbee.no-ip.com/uploads/software/Utilities/lbrate.exe

Various ROMs:
http://microbee.no-ip.com/uploads/Software/MICROBEE/ROMS/

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.

DISK IMAGES
-----------
Disks may be subject to copyright,  the disk images you choose and whether
you are entitled to use any copyrighted disk software can not be answered
here.  If you already own the original disks you may be entitled to make
images from them or use a convenient image source.

Copy all required disk images to the following locations:

Windows:
Installed location\ubee512\disks\

Unices:
Your home location/.ubee512/disks/

CP/M OS images
--------------
The Peter Broughton 512K CP/M system (ZCPR) can be found here and is in the
public domain:

http://microbee.no-ip.com/uploads/software/MICROBEE/OS/pjb-2.2p-17_05_1988.zip

The 1st image is bootable, unzip to your disks directory and use a
command like:

>ubee512 -a pjb1-ds84.dsk

CP/M tools images
-----------------
Included are some CP/M tools that are designed to only be run under the
uBee512 emulator.  The programs provided allow copying of files between the
host system and CP/M, there are also some other programs, see the TOOLS.TXT
and CHNGELOG.TXT document in the image for more information.  The images
will be placed into the 'disks' directory. For convenience I have provided
images for all the common Microbee formats:

ubee512_cpm_tools.ss80_
ubee512_cpm_tools.ds40_
ubee512_cpm_tools.ds80_
ubee512_cpm_tools.ds82_
ubee512_cpm_tools.ds84_

The underscore '_' character tells uBee512 that these files are not to be
written to, this will NOT apply if using the LibDsk driver to access the
files.  Don't remove this and don't place any other files into these images
as the images are replaced when installing the emulator.

Note the size of these images is smaller than what is expected for a raw
disk image and is normal.

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

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 - 256TC Telecomputer, 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)
tterm - Teleterm
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 model option is specified.

Model defaults
--------------
The table below shows the default values for each model.  Command line
options may be used to alter some of the emulation features.  The --model
option must always precede any other overriding options that may be used.

BOOT:
This is the address at where Z80 code will start to execute from.  There is
no option at present to change this value.

RAM:
This is the amount of DRAM/RAM emulated.  There is no option at present to
change this value.

PCG:
This is the amount of PCG RAM emulated.  The --pcg option can be used to
change the default value for Premium models.

VDU:
This is the amount of VDU RAM emulated.  The VDU RAM includes the screen,
attribute, and colour RAM banks for Premium emulation.  The --vdu option can
be used to change the default value for Premium models only.  By default the
VDU memory is 2K but 8K can be selected.  Setting to 8K can be problematic
and is not advised unless you understand the problems associated with it.

COL:
The colour value indicates the colour version used, 2 is the alpha+
(Premium) colour circuitry, 1 is the standard colour circuitry and no entry
is monochrome.  The standard colour circuit emulation can be enabled with
--col or --col-type and disabled with --mono.  These options only work with
standard models.  A monochrome monitor can be used on any model machine
using the -m or --monochrome option.  Two types of colour monitor may be
emulated for the standard colour models.  See the --col-type option for more
information.

HWF:
This is the hardware flashing/inverse video emulation supported by the
256TC/Teleterm and Premium models.  The 256TC has this as standard.  The
Premium models required some hardware changes to enable this feature to be
used.  The upgraded Premium disk models emulated have this enabled by
default.  The --hwflash option can be used to enable or disable this
emulation.  This setting has no affect on standard models.

MHI:
This is the monochrome half intensity video emulation supported by the
256TC/Teleterm and Premium models.  The 256TC has this as standard.  The
Premium models required some hardware changes to enable this feature to be
used.  The upgraded Premium disk models emulated have this enabled by
default.  The --hint option can be used to enable or disable this emulation. 
The setting has no affect on standard models.

LPEN:
This is the CRTC 6545 Light pen key encoding emulation that every model has
except for the 256TC and Teleterm.  The 256TC/Teleterm models can be forced
to allow this feature by using the --lpen option.

CLK:
This is the CPU clock speed change used by the 256TC and Peter Broughton
system.  When enabled the CPU clock can be switched between 3.375 and 6.750
MHz with software. The --speedsel=n option allows this feature to be enabled
or disabled.

PIOB7:
Link settings on the mother board determines what signal is applied to the
Z80 PIO port B bit 7.  3 of the 4 possibilities are emulated.  The 'net'
option is not emulated.

 piob7=rtc
   use the Real Time Clock (RTC) interrupt output.

 piob7=vsync
   use the Vertical sync signal.

 piob7=pup
   use the pull up resistor.

 piob7=net
   Not implemented.

RTC:
Determines if the Real Time Clock (RTC) emulation is used.  The --rtc=n
option allows this to be enabled or disabled.

PREMG:
Determines if the extra (Premium) graphics are emulated.  There is no option
at present to change this value.

CLOCK:
This is the CPU clock frequency in MHz.  The CPU clock can be altered by
using the -x, --clock=f or --xtal=f options.

Model Type   BOOT  RAM PCG VDU COL HWF MHI LPEN CLK PIOB7 RTC PREMG    CLOCK
-------------------------------------------------------------------------------
256tc disk  0x8000 256  16  2   2   Y   Y   -    Y   rtc   Y    Y   3.375/6.750
p512k disk  0x8000 512  32  2   2   Y   Y   Y    Y   rtc   Y    Y   3.375/6.750
512k  disk  0x8000 512   2  2   -   -   -   Y    Y   rtc   Y    -   3.375/6.750
p256k disk  0x8000 256  32  2   2   Y   Y   Y    Y   rtc   Y    Y   3.375/6.750
256k  disk  0x8000 256   2  2   -   -   -   Y    Y   rtc   Y    -   3.375/6.750
p128k disk  0x8000 128  16  2   2   -   -   Y    -   pup   -    Y   3.375
128k  disk  0x8000 128   2  2   -   -   -   Y    -   pup   -    -   3.375
p64k  disk  0x8000  64  16  2   2   -   -   Y    -   pup   -    Y   3.375
64k   disk  0x8000  64   2  2   -   -   -   Y    -   pup   -    -   3.375
56k   disk  0xE000  56   2  2   -   -   -   Y    -   pup   -    -   3.375
tterm tape  0x8000  32  32  2   2   -   -   -    -  vsync  -    Y   3.375
ppc85 tape  0x8000  32  16  2   2   -   -   Y    -  vsync  -    Y   3.375
pc85  tape  0x8000  32   2  2   1   -   -   Y    -  vsync  -    -   3.375
pc    tape  0x8000  32   2  2   1   -   -   Y    -  vsync  -    -   3.375
ic    tape  0x8000  32   2  2   -   -   -   Y    -   pup   -    -   3.375
2mhz  tape  0x8000  32   2  2   -   -   -   Y    -   pup   -    -   2.000

Known problems
--------------
* 256TC and BN60 BIOSs may not boot if a high CPU clock or frame rate is
  specified unless '--nodisk' is also used to first boot into the ROM's menu
  then press F1 key to boot from the disk.  This is not a problem when using
  the default CPU clock and frame rate values.

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.

* There are some defective ROM images:

  - A Telcom v3.2.1 ROM previously suspected as being faulty has now been
    proved to be so.  There is an alternative image for that ROM.  Since
    version 2.1.0 the emulator now checks the NETWORK ROM for known bad
    values and if a match is found applies a patch to the ROM image in
    memory.

  - A 256TC tc256r12.bin ROM is defective.  Use the alternative ROM images
    shown in the 256TC model section below.

Special options
---------------
The 256TC and Premium BN60.ROM 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 requirements
----------------------------
The information provided here applies when override options have not been
specified. The override options allow all the ROMs to be configured from the
command line or the configuration file.

Each model uses a particular boot or BASIC ROM(s),  other ROMs are optional,
all the ROMs must be located in the current or 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 current or 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' except for the 56K, 64K models, or the user may specify
what image should be used.

ROMs aliases
------------
From version 2.7.0 an optional ROMs alias file (roms.alias) is used, this
makes creating links or renaming files no longer necessary.  The roms.alias
file contains alias entries for all the ROM names shown below, by default
the file names substituted are the same names as used in previous versions
of the uBee512.  This method should work out of the box.

From version 2.7.0 the ROM names are more consistent,  the default ROMs
alias file will substitute back to the previous file names used.

See the roms.alias file for more information on how to use ROM aliases.

disk aliases
------------
From version 2.7.0 an optional disks alias file (disks.alias) is used, this
makes creating links or renaming files no longer necessary.  The disks.alias
file contains alias entries for all the disk names shown below.

The disk aliases also has the added advantage that any uBee512 disk image
type supported may be substituted.  The file extension of the substituted
file determines the image type.  The '.dsk' in the alias name is more for
reference purposes now.

See the disks.alias file for more information on how to use disks aliases.

Default model ROMs and disk images
----------------------------------

Model: 256tc                                  Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: 256TC.ROM                         16K  v1.15, v1.20
                                              16K  tc256r12.bin (is bad)
boot image: 256tc.dsk

Model: p512k                                  Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: P512K.ROM                         16K  bn54.rom, bn56.rom, bn60.rom
extra ROMs: P512K_2.ROM (optional)            16K
            P512K_3.ROM (optional)             8K
boot image: p512k.dsk

Model: 512k                                   Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: 512K.ROM                          16K  bn54.rom, bn56.rom
extra ROMs: 512K_2.ROM (optional)             16K
            512K_3.ROM (optional)              8K
boot image: 512k.dsk

Model: p256k (64K to 256K Upgrade)            Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: P256K.ROM                         16K  bn54.rom, bn56.rom, bn60.rom
extra ROMs: P256K_2.ROM (optional)            16K
            P256K_3.ROM (optional)             8K
boot image: p256k.dsk

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

Model: p128k (SBC)                            Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: P128K.ROM                         16K  bn54.rom, bn56.rom, bn60.rom
extra ROMs: P128K_2.ROM (optional)            16K
            P128K_3.ROM (optional)             8K
boot image: p128k.dsk

Model: 128k (SBC)                             Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: 128K.ROM                          16K  bn54.rom, bn56.rom ?
extra ROMs: 128K_2.ROM (optional)             16K
            128K_3.ROM (optional)              8K
boot image: 128k.dsk

Model: p64k (CIAB)                            Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: P64K.ROM                          16K  bn54.rom, bn56.rom
extra ROMs: P64K_2.ROM (optional)             16K
            P64K_3.ROM (optional)              8K
boot image: p64k.dsk

Model: 64k (CIAB)                             Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: 64K.ROM                           16K  bn54.rom, bn56.rom ?
extra ROMs: 64K_2.ROM (optional)              16K
            64K_3.ROM (optional)               8K
boot image: 64k.dsk

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

Model: tterm (Teleterm)                       Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
BASIC ROMs: TTERM_A.ROM                       16K  ?
            TTERM_B.ROM                        8K  ?
  PAK0 ROM: TTERM_C.ROM                       16K  ?
  PAK1 ROM: TTERM_E.ROM                       16K  ?
  PAK2 ROM: TTERM_F.ROM                       16K  ?
  PAK3 ROM: TTERM_G.ROM                       16K  ?
  PAK4 ROM: TTERM_H.ROM                       16K  ?
  PAK5 ROM: TTERM_I.ROM                       16K  ?
   Net ROM: TTERM_NETWORK.ROM                 16K  ?

Model: ppc85 (Premium PC85)                   Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
BASIC ROMs: PPC85_A.ROM                       16K  PREM-A.ROM v5.29e (banked)
            PPC85_B.ROM                        8K  PREM-B.ROM v5.29e
  PAK0 ROM: PPC85_PAK0.ROM                    16K  PREM-C.ROM v1.3 Wordbee
  PAK1 ROM: PPC85_PAK1.ROM                    16K  PREM-E.ROM Basic help
  PAK2 ROM: PPC85_PAK2.ROM                    16K  PREM-F.ROM BC III PC85 Menu
  PAK3 ROM: PPC85_PAK3.ROM                    16K  PREM-G.ROM Graphics/DB
  PAK4 ROM: PPC85_PAK4.ROM                    16K  PREM-PREMVTEXT.ROM v2.35
  PAK5 ROM: PPC85_PAK5.ROM                    16K  PREM-I.ROM Shell
  PAKx ROM: PPC85_PAK6.ROM - PPC85_PAK7.ROM    8K  External ROMs
   Net ROM: PPC85_NETWORK.ROM                 16K  TELC321.ROM v3.2.1

Model: pc85                                   Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
BASIC ROMs: PC85_BASIC.ROM or                 16K  5.25e, 5.24e?
            PC85_BASIC_A.ROM                   8K
            PC85_BASIC_B.ROM                   8K
  PAK0 ROM: PC85_PAK0.ROM                      8K  wbee12.rom ?
  PAK1 ROM: PC85_PAK1.ROM                      8k  ?
  PAK2 ROM: PC85_PAK2.ROM                      8K  ?
  PAK3 ROM: PC85_PAK3.ROM                      8K  ?
  PAK4 ROM: PC85_PAK4.ROM                      8K  ?
  PAK5 ROM: PC85_PAK5.ROM                      8K  ?
  PAKx ROM: PC85_PAK6.ROM - PC85_PAK7.ROM      8K  External ROMs
   Net ROM: PC85_NETWORK.ROM (8K)             16K  TELC321.ROM ?

Model: pc                                     Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
BASIC ROMs: PC_BASIC.ROM or                   16K  5.22e
            PC_BASIC_A.ROM +                   8K
            PC_BASIC_B.ROM                     8K
  PAK0 ROM: PC_WBEE.ROM                        8K  wbee12.rom
  PAK1 ROM: PC_PAK1.ROM                        8k  COMMAND file (Basic help)
  PAKx ROM: PC_PAK2.ROM - PC_PAK5.ROM          8K  Internal ROMs
  PAKx ROM: PC_PAK6.ROM - PC_PAK7.ROM          8K  External ROMs
   Net ROM: PC_NETWORK.ROM                     8K  Telcom v3.0, v3.1

Model: ic                                     Max  Possible Versions/ROMs
-------------------------------------------------------------------------------  
BASIC ROMs: IC_BASIC.ROM or                   16K  5.22e
            IC_BASIC_A.ROM +                   8K
            IC_BASIC_B.ROM                     8K
  PAK0 ROM: IC_WBEE.ROM                        8K  wbee12.rom
  PAKx ROM: IC_PAK1.ROM - IC_PAK7.ROM          8K  External ROMs
   Net ROM: IC_NETWORK.ROM                     4K  telc12.rom telc11.rom

Model: 2mhz                                   Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
BASIC ROMs: 2MHZ_BASIC.ROM or                 16K  5.10, 5.00
            2MHZ_BASIC_A.ROM +                 4K
            2MHZ_BASIC_B.ROM +                 4K
            2MHZ_BASIC_C.ROM +                 4K
            2MHZ_BASIC_D.ROM                   4K 
  PAK0 ROM: 2MHZ_PAK0.ROM                      8K  edasm.rom
  PAKx ROM: 2MHZ_PAK1.ROM - 2MHZ_PAK7.ROM      8K  External ROMs
   Net ROM: 2MHZ_NETWORK.ROM                   4K  Telcom v1.0

Notes
-----
* PC Series III
  The PC series III model was released with Version 3 of Telcom. This was
  the first 8K Network ROM developed from the v1.2 of Telcom.  There does
  not appear to be any Telcom v2.x ROMs.  Version 3 of Telcom included an
  improved machine code monitor, self test and calculator.

  A ROM was introduced providing help for BASIC commands and is termed
  the "COMMAND FILE ROM" located at PAK1.

  Reference: Online Issue 4 - September 1994 Page 36-37

CONFIGURATION FILE
------------------
The emulator is highly configurable, from version 3.0.0 the configuration
file supports a built in scripting language that is able to make decisions
based on the value of variables and so determine how the emulator should be
configured on start up.

The configuration file uses the same options that are possible on the
command line.  Customised sections can be added making invoking the emulator
with options much easier.  Command line parameters may be used in addition
and more than one customised section can be invoked from the same command
line.

A 'ubee512rc' text file (the default) is required to hold the configuration
script. The supplied 'ubee512rc.sample' file can be used as a template.  On
Windows installations this file will be found in the configs directory and
on Unices is normally found in:

/usr/local/share/ubee512/config

Alternative configuration files may also be used if the first option on the
command line is --config=my_config.

The default path for configuration files is @UBEE512@

File structure
--------------
- Comments lines are preceded by '#' or ';' and must be the first non-space
  character on the line. Blank lines are ignored.

- A definition name must be surrounded with square bracket characters '['
  and ']'. All lines below this are part of the definition until a new
  definition name or the end of file is reached.  A maximum of 5000
  definitions are allowed.

- A definition's contents can NOT reference any other definitions.  The
  command line options may include any number of references to definitions
  contained in the file and may be mixed with options.

- Values contained in the [global-start] and [global-end] sections are
  always referenced but their use is optional.  It is not the intention that
  these be used directly by the user.  The [global-start] section is applied
  before any command line options or customised sections are processed.  The
  [global_end] section allows options to override what resulted from a
  command line or a customised section.  i.e. the --model option sets
  default values and the [global-end] section can globally override the
  settings if this is required on a global basis.

- Names used for a definition section must be unique.  If any command line
  option parameters that contains a space before it matches the definition
  name then it will be treated as file definition instead.

- Double quotes '"' may be used around an entry causing it to be treated as
  one option/parameter. On Unices the backslash '\' character can be used to
  allow an escape sequence.  Wild cards will not be expanded.

- Options may be divided up and placed onto new lines to make for easier
  reading.

Listing the definitions
-----------------------
Use the --lcon or lconw option or use the 'listall' entry found in the
sample file to list all the definition names contained in the configuration
file.  A 'list' entry is also included that will list all entries except for
some early administration entries.

Examples
--------
A very simple ubee512rc file definition could consist of the following:

# Run a CIAB emulation with standard colour emulation.
[ciab-col]
--fullscreen
--model=64k
--col
-a ciabsyst.ss80

Then to run the 'ciab-col' definition enter:
>ubee512 ciab-col

To disable the full screen mode (toggle it off) enter:
>ubee512 ciab-col -f

This example adds a [com1] definition to the ubee512rc configure file:

# Set up some serial access @ 9600 baud (windows example)
[com1]
--coms=1 --baud=19200 --datab=8

Now we have a [ciab-col] and [com1] definition we could use the following
line that also defines an image for drive B:

>ubee512 ciab-col com1 -b workimage.ss80

The above line could all be defined as one definition but the example shows
how the configuration file and command line options can be combined.

Scripting language options
--------------------------
There are many options that can be used to test strings with the result
determining the execution path through the script. The language has the
typical 'if', 'else', 'end' structure.  Every '--if-x' test requires a
matching '--if-end' at some point, an '--if-else' does not require it.
Conditionals may be nested up to 1000 levels deep.

All conditional options must be used within a [section].  You can not
conditionally decide to make a section visible.

All the available conditional options are described in 'Conditional
processing' under the 'Command line options' section.

The following are some examples of typical conditional testing,  the
indentation helps to make the script easier to read.  While these examples
don't do anything useful it should show how one can make real use of the
language.

# [example1] This provides a way to enable a script section. To disable this
# section change '--if-true' to '--if-false'.

[example1]
--conio
--if-true
   --echo="The emulator version is: @UBEE_VERSION@"
   --echo="this will always be output"
   --echo="same with this"
--if-end
--exit=-1

# [example2] Some testing based on the host system in use.

[example2]
--if-system=win
  --conio
  --echo="We are on a Windows system."
  --echo="Major type: @UBEE_SYS_MAJOR@  Minor type: @UBEE_SYS_MINOR@"
--if-else
  --if-system=unix
     --echo="We are on a Unix system. The system is: @UBEE_SYS_MINOR@"
  --if-end
--if-end
--exit=-1

# [example3] Show how to set and unset variables and test values an test. 
# To test a variable value it must be enclosed by '@' characters.

[example3]
--conio
--varset="myvar1=Hello World"
--if-eq="@myvar@,Hello World"
   --echo="test 1 resulted in equals"
--if-else
   --echo="test 1 resulted in not equals"
--if-end

--varuset="myvar1"
--varset="myvar1=Hello Worlds"
--if-eq="@myvar@,Hello World"
   --echo="test 2 resulted in equals"
--if-else
   --echo="test 2 resulted in not equals"
--if-end
--exit=-1

Using the uBee512 Emulator
==========================
KEYBOARD
--------
Keyboard emulation of the CRTC6545 'Light pen' keys and the 256TC/Teleterm
internal keyboard is supported, both types can be used at the same time. 
The 256TC/Teleterm key emulation is only possible in the 256TC/Teleterm
models.

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:

Keys
----
256TC/Teleterm Models
  SELECT: PAGEUP

Standard/Premium Models
LINEFEED: PAGEUP
   RESET: PAGEDOWN
 SHIFT 0: SHIFT INSERT

All Models
   BREAK: PAUSE/BREAK

On a Microbee (not 256TC/Teleterm) no key is found above the '0' but there
is a ')' key on a PC keyboard so another method is required to return the
'SHIFT 0' combination as shown above.

Emulator control
----------------
     END: Exit the emulator             
PAGEDOWN: Reset the emulator

A confirmation window should appear when pressing the exit or reset keys. No
confirmation for exit will appear if a --exit-check=off has been specified
earlier.

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

Emulator commands (hot keys, and joystick commands)
---------------------------------------------------
The EMUKEY is the HOME or ALT keys.  The ALT key is not usable in the
256TC/Teleterm models unless the --lpen option is also specified.

The EMUKEY hot keys will repeat if held down.  The repeat rate may be
configured using --cmd-repeat1 and --cmd-repeat2 options.

Emulator command                 EMUKEY + KEY             Joystick commands
----------------                 ------------             ----------------- 
Full screen toggle               EMUKEY + ENTER           C_FSTOG
Tape rewind                      EMUKEY + T               C_TAPER
Dump memory (--dump=n)           EMUKEY + D               C_DMP
Dump memory (+ 0x0080)           EMUKEY + 1               C_DMPN1
Dump memory (+ 0x1000)           EMUKEY + 2               C_DMPN2
Dump memory (- 0x0080)           EMUKEY + 3               C_DMPB1
Dump memory (- 0x1000)           EMUKEY + 4               C_DMPB2
Dump memory   (repeat)           EMUKEY + 5               C_DMPREP
Register dump                    EMUKEY + R               C_DMPREG
Debug mode off                   EMUKEY + -               C_DBOFF
Debug mode on                    EMUKEY + =               C_DBON
Debug trace on/off               EMUKEY + \               C_DBTRA
Debug step                       EMUKEY + BS              C_DBST1
Debug step * 10                  EMUKEY + [               C_DBST10
Debug step * 20                  EMUKEY + ]               C_DBST20
Joystick disable                 EMUKEY + J + <0>         n/a
Joystick Microbee enable         EMUKEY + J + <1>         n/a
Joystick keys select/enable      EMUKEY + J + <K>         n/a
Sound mute toggle                EMUKEY + S               C_MUTE
Pause emulator on/off            EMUKEY + P               C_PAUSE
Volume up                        EMUKEY + UP              C_VOLU
Volume down                      EMUKEY + DOWN            C_VOLD
Mouse scroll wheel association   EMUKEY + W               C_MWHEEL
OpenGL Filter toggle             EMUKEY + F               C_GLFILT
OpenGL 10% window width          EMUKEY + KP1             n/a
OpenGL 20% window width          EMUKEY + KP2             n/a
OpenGL 30% window width          EMUKEY + KP3             n/a
OpenGL 40% window width          EMUKEY + KP4             n/a
OpenGL 50% window width          EMUKEY + KP5             n/a
OpenGL 60% window width          EMUKEY + KP6             n/a
OpenGL 70% window width          EMUKEY + KP7             n/a
OpenGL 80% window width          EMUKEY + KP8             n/a
OpenGL 90% window width          EMUKEY + KP9             n/a
OpenGL Microbee CRTC X width     EMUKEY + KP_PERIOD       n/a

MOUSE
-----
The mouse buttons provide the following functionality:

  LEFT BUTTON: Double click toggles full screen mode.
MIDDLE BUTTON: Reset the emulator.
 RIGHT BUTTON: Exit the emulator.

The mouse scroll wheel may be associated with various actions, see the
--mouse-wheel option for more information. The default association controls
the sound volume:

  WHEEL UP: Volume up
WHEEL DOWN: Volume down

If associated with the OpenGL display then the display may be resized:

  WHEEL UP: Increase OpenGL window size
WHEEL DOWN: Decrease OpenGL window size

The association may be changed at any time by using the EMUKEY + W hot key.

Window resizing in OpenGL mode may also be accomplished by dragging the
window's sides or corners.  After releasing, the Window will resize to the
width and the depth will be set according to the Monitor and Microbee aspect
ratio settings.

Maximised window toggling in OpenGL mode is supported. Note that on Windows
that full screen mode can only be toggled to when the window is not
currently maximised.

JOYSTICK
--------
Microbee joystick
-----------------
To use an SDL compatible joystick in the standard configuration simply
requires a --js=n option to be specified, n=0 for the first joystick, n=1
for the next, etc.  By default the joystick will be enabled but may be
enabled/disabled using the emulator's hot keys at any time.  The state of
the Microbee joystick emulation can be seen in the status bar.

Use the following options to change the standard assignments of each
Microbee joystick button:

  --js-up=n               Button number for 'up', default is 0
  --js-right=n            Button number for 'right', default is 1
  --js-down=n             Button number for 'down', default is 2
  --js-left=n             Button number for 'left', default is 3
  --js-fire=n             Button number for 'fire', default is 4
  --js-play1=n            Button number for 'player 1', default is 5
  --js-play2=n            Button number for 'player 2', default is 6
  --js-spare=n            Button number for 'spare', default is 7

The joystick should be enabled before running any program that uses it and
not after.

Analogue joysticks
------------------
Some joysticks may not have the ability to return X and Y direction movement
of a joystick as up, down, left and right button events, the analogue values
returned by these joysticks can be converted to look like simple buttons
using options.  The joystick may need to be switched to analogue mode for
this to work.

This feature will be enabled by default but does require the joystick to be
calibrated by the host system driver.  This should be carried out before
using the --js-axisl option.  Incorrect operation may result if the joystick
is not calibrated correctly.  The Joystick diagnostics described below can
be used to view the analogue values returned by the joystick.

The default button values returned for the movement direction are the same
as a digital joystick but may be changed if required.

Use the following options for analogue joysticks:

  --js-axis=x             Joystick axis mapping to buttons.  x=on to enable,
                          x=off to disable. Default is enabled.
  --js-axisb=n            Joystick axis buttons base number.  The axis button
                          offsets are 0=up, 1=right, 2=down and 3=left.  The
                          base number n is added to the offsets to generate a
                          button number. n may be any value from 0 to 124.
                          Default value is 0.
  --js-axisl=n            Determines the thresh hold level for button
                          detection.  n may be any value from 1 to 32767.
                          Default value is 3200.

Joystick keys
-------------
The joystick can also be used in key mapping mode,  for this each key (6545
keys only) that is required is assigned to a joystick button. 128 joystick
buttons per key set can be defined, there are 256 key sets available.  Once
the key sets have been configured the one required can be selected from the
keyboard using the emulator's hot keys.

To see what KEY names are available issue a --js-klist option,  the names
are not case sensitive.

Example:

Defining each button requires two options,  these must be used in the order
shown here, let's create a joystick key set that contains '[' for left, ']'
for right, 'q' for up, and 'a' for down movement.  These options should be
placed into your configuration file and given the entry [joy] (or whatever
you want to call it):

[joy]
--js=0

# set up, right, down and left movement keys
--js-kk=q       --js-kb=0
--js-kk=]       --js-kb=1
--js-kk=a       --js-kb=2
--js-kk=[       --js-kb=3
--js-kset=A

You could then use the above definition like so:
>ubee512 joy -a games_1.dsk

The last --js-kset option determines which key set is selected but may be
changed using the emulator's hot keys at any time:

To select this key set use: EMUKEY + J <A>

The status of joystick key set selection can be seen in the status bar.

See the ubee512rc.sample and games.ini.sample file for some predefined
joystick keys.

Joystick commands
-----------------
The joystick can also have joystick buttons mapped to emulator commands, the
same commands as used for EMUKEY hot keys are available.  The method used
for setting the associations is identical to the method of setting the
'Joystick keys' except 'C_TYPE' parameters are specified instead of a key. 
The mappings may contain any combination of commands and keys.

The commands will repeat if the joystick button is held down.  The repeat
rate may be configured using --cmd-repeat1 and --cmd-repeat2 options.

To view the available command names issue a --js-clist option,  the names
are not case sensitive.

Example:

[joy]
--js=0

# set up, right, down, left movement keys, FS toggle and Pause commands
--js-kk=q       --js-kb=0
--js-kk=]       --js-kb=1
--js-kk=a       --js-kb=2
--js-kk=[       --js-kb=3
--js-kk=C_FSTOG --js-kb=6
--js-kk=C_PAUSE --js-kb=7
--js-kset=A

See the games.ini.sample file for some predefined joystick keys.

Joystick diagnostics
--------------------
If you need to find out what buttons, etc. do on your joystick then run this
diagnostics command line and while viewing the standard console output press
buttons on the joystick:

>ubee512 --js=0 --modio=+joystick --conio

SOUND
-----
The emulation of sound is improving as uBee512 is developed further.  From
version 2.7.0 there has been some major improvements and options to
customise the performance.  A problem of a slow distorted sound that had
affected some Windows machines systems should now be resolved.  On my
testing platforms sound is excellent under Windows 2000 and Ubuntu Hardy.

One of the problems associated with sound emulation is keeping the Z80 CPU
emulation and sound generation speed tracking as close as possible to each
other.  If sound emulation runs to fast the sound can break up, if too slow
the sound lags behind what the CPU is doing and has to catch up.

There are a large number of sound options that can be used to fine tune the
sound performance, the default values work very well (for me) and it is
dependent on what system, hardware, the number of other applications running
at the same time, etc.  Some other processes running may have excessive CPU
time causing problems. Web browsers can be a problem when a page is
updating.

One of the best options to try is --snd-hq.  This option sets high quality
sound.  How well this works will be dependent on the host platform.  This is
not set by default so you need to specify the option, if this works well on
your system then you can add it the ubee512rc file in the global section.

See the 'COMMAND LINE OPTIONS' section for further information on this and
other sound options.

uBee512 prior to version 2.7.0 was actually using excessive CPU time
updating the SDL window when nothing needed to be updated.  The CPU time has
been greatly reduced when no display updating is occurring, keep in mind
that some Microbee programs are continuously writing repeated data to the
display memory so the CPU time will not show much improvement.

DISPLAY
-------
From version 3.0.0 OpenGL and SDL video rendering modes are both supported.
OpenGL is the preferred method as rendering is faster and alternative aspect
ratios are possible.  The default mode is SDL as the OpenGL mode may need
suitable drivers installed to work correctly.  The OpenGL mode can be
enabled by using an '--video-type=gl' option on the command line or by
setting this mode system by system in the configuration file.

OpenGL Rendering
----------------
OpenGL mode allows just about any aspect ratio to be achieved and full
screen mode is truly 'full screen'.  Windows may be resized in a number of
different ways.

As OpenGL handles the stretching to achieve the correct aspect ratio only
one line of Y axis data needs to be written to the display (SDL uses 2).
This speeds up screen writes especially when the display must be redrawn
completely.

Hardware and drivers
--------------------
To use OpenGL the video hardware driver must be able to support OpenGL and
will require suitable drivers to support this.  OpenGL is widely used in
Unix environments.  It is also supported on Windows systems but later
systems like XP and Vista no longer support OpenGL out of the box.  The
opengl32.dll file is supplied by the manufacturer's drivers for these later
systems. If you use OpenGL mode and end up with a white display then you
need to look at obtaining drivers and/or settings that support OpenGL.

On Windows systems there may be OpenGL controls found under the display
adapter's advanced section, if not check for the latest drivers supplied by
your video card manufacturer.  Some integrated or older video hardware do
not support OpenGL in hardware.

http://www.opengl.org/pipeline/article/vol003_9/

Using OpenGL
------------
All the available OpenGL options are described in detail in 'OpenGL
rendering' under the 'Command line options' section.

When OpenGL is used the window's default size will be 50% of the desktop
width.  The aspect ratio of the window will be determined by the current
desktop resolution and the Microbee's display aspect.

By default the Microbee (wanted) aspect ratio is 4:3 (1.333 to 1).  Monitor
aspect ratios for LCD types may be 5:4 or 4:3 and desktop resolutions should
be able to correctly identify these.  CRT monitors are typically 4:3 aspect
but may be using a non 4:3 resolution aspect.

Monitor aspect ratio
--------------------
The --gl-aspect-mon option can be used to change the aspect ratio of the
Monitor display. This option may be required if running a 4:3 CRT monitor
with non 4:3 display resolution.

Microbee aspect ratio
---------------------
The --gl-aspect-bee option can be used to change the aspect ratio of the
Microbee display.  This should only be used after achieving the correct
monitor aspect ratio.

Start up window size
--------------------
The display window may be set to any reasonable size by using options.  The
--gl-winpct and --gl-winpix options can be used to set the display width by
a percentage of the desktop width or by a set number of pixels.  the default
window size is 50% of the desktop width.

Filter options
--------------
Each display mode has a 'soft' and 'sharp' filter rendering method.
Depending on the resolution currently displayed one may look better than the
other.  Small windows tend to look better using the 'soft' mode.  The
default mode can be changed using the '--gl-filter-x' options provided for
each window mode.  The EMUKEY + F hot key can be used to toggle between the
two types for each window mode.

Windows resizing
----------------
The display window may be resized by stretching the window using the mouse,
the mouse scroll wheel, setting window sizes from 10-90% using hot keys,
setting the window size to the Microbee's current CRTC width value, and
toggling between normal and maximised windows.

See the 'KEYBOARD' and 'MOUSE' sections for more information.

Windows and Unix differences
----------------------------
On Unix systems the --gl-max option can be used to enter a maximised window
mode on start up.  This option does not currently work correctly on Windows
systems so is disabled for that system, maximised can be selected
afterwards.

Toggling between a full screen and a maximised window in Unix is possible
but not under Windows, under Windows you can only toggle between a normal
window and full screen so un-maximising the window is required before
toggling.

On Unix systems toggling between full screen and windows mode will place the
window in the top left corner of the display, on Windows systems the
original window position is re-instated correctly.

SDL Rendering
-------------
The display supports two display ratios of 2:1 and 1:1,  by default this is
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 other 1:1 ratio is preferred then a --aspect=1 option can be
specified on the command line.

STATUS INFORMATION (TITLE BAR)
------------------------------
The title bar is used to show various information during the running of the
emulator.  The information displayed by default is as follows:

uBee512-n.n.n P512K 3.375MHz 8N1:300 [M:P:Ti:To:JS:Jn] [vol nn%] [win nn%] D:

Argument     Description                                Displayed (default)
--------     -----------                                -------------------
+mute        Sound muted status                         M
+emuver      Emulator name and version                  uBee512-n.n.n
+model       Base model emulated                        model
+speed       CPU clock speed                            3.375MHz
+serial      Serial port set up if enabled              1N8:300
+print       Parallel printer enable                    P
+tape        Tape input/output state                    Ti:To
+joy         Joystick status                            JS:Jn
+d           Short drive access                         D:

Other optional status arguments:

Argument     Description                                Displayed (default)
--------     -----------                                -------------------
+emu         Emulator name                              uBee512
+ver         Emulator version                           n.n.n
+drive       Long drive access                          Drive D:
+model       Base model emulated                        model
+ram         Amount of RAM emulated                     nK
+sys         System name                                --sys=name
+title       Customised title                           --title=name
+vol         Always display volume level                [vol nn%]
+win         Always display window size                 [win nn%]

Non optional displayed values
-----------------------------
Paused

 A [PAUSED] will always be displayed when the emulator is issued a pause
 command.  No other values following this will be displayed until the paused
 state is turned off.

Debug

 A [DEBUG] will always be displayed when the emulator is in debug mode. If
 the emulator is in the paused state then the display will show [PAUSED]
 instead.

Persist values
--------------
Persist values are displayed until their timers expire. The display of the
value may be optional and may be able to configured to always be displayed.
The timer persist value used may also be configured using the --gui-persist
option.

Drive access
 
 This is displayed only if enabled.  A spinning wagon wheel will be
 displayed next to the drive letter during the persist period when the drive
 is accessed.

Volume level [vol nn%]

 This will always be displayed for any volume adjust command, the volume
 level may also be enabled to display all the time with '+vol'.

Window size [win nn%]

 This will always be displayed for any window size adjust action, the window
 size may also be enabled to display all the time with '+win'.

Control arguments
-----------------
+clear

 Clear all current status values, you need to use this when any of the
 default values are to be removed.

+left

 Force left hand justification.  Some window managers centre the title, if
 you want this forced left then this argument will attempt to do that.

Other related options
---------------------
--gui-persist=n
  
 Set the persist time in milliseconds for values that appear on the status
 line, default is 3000mS.

--spad=n

 Sets the number of spaces to be placed between each entry on the title bar. 
 The actual spacing achieved will be dependent on the title font used.
 Default value is 5 spaces.

--title=name

 Define the customised title name to be used when '+title' is used in the
 --status option.

Example
-------
--spad=10
--title="My title message"
--status=+clear+title+model+speed+print+tape+joy+d

The font and size of the text in the title bar is dependent on the
configuration of the Window manager being used.

DISK IMAGE FILES (ORIGINAL BUILT IN SUPPORT)
--------------------------------------------
The following describes the built in support for disk images.  It is
independent of LibDsk.

The emulator currently supports the following types of built-in disk images:

'.DSK'
CPCEMU Disk image format,  this should work on all standard Microbee disks
including the 3.5" Modular disk format.  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.

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 for non
256TC and 56K models.

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.

Dynamic image creation
----------------------
A RAW disk image may be created by uBee512 dynamically when starting the
emulator.  Currently this works for RAW disk images only, the image created
will overwrite any previous image by the same file name.

To make uBee512 create the image a '.temp' is appended to the file name.  The
emulator will a create file containing E5 hex.  The image created will not
be full size but will grow as needed.

After exiting the emulator the image will be available for use but it should
have the '.temp' part removed if the contents are to be kept or it will be
overwritten if specified again.

Example:
-b myimage.ds40.temp

Write protection
----------------
Disk images can be made write protected by adding a trailing underscore
character ('_') to the image name.

LIBDSK IMAGE AND FLOPPY ACCESS
-------------------------------
LibDsk is built into uBee512.  It provides the capability to access many
types of disk images, and floppy disks.  The emulator uses LibDsk in such a
way that allows even copy protected disks to be used successfully.

Native Microbee format programs for DS80 and DS40 disks that place side 0
into the physical side 1 sector headers are also able to be used by making
use of some of LibDsk's functions.

The full documentation for LibDsk can be found in the distribution files
here:

http://www.seasip.demon.co.uk/Unix/LibDsk/

The documentation presented here is only intended for use with the emulator.

To access floppy drives on Windows 2000 and above requires a special floppy
driver to be installed. This is available from here:

http://simonowen.com/fdrawcmd/

LibDsk image types
------------------
The following disc image file formats are supported by LibDsk:

dsk
---
Disc image in the DSK format used by CPCEMU.  The format of a .DSK file is
described in the CPCEMU documentation.

edsk
----
Disc image in the extended CPCEMU DSK format.

raw
---
Raw disc image - as produced by "dd if=/dev/fd0 of=image". On systems other
than Linux, DOS or Windows, this is also used to access the host system's
floppy drive.

logical
-------
Raw disc image in logical file system order.  Previous versions of LibDsk
could generate such images (for example, by using the now-deprecated
-logical option to dsktrans) but couldn't then write them back or use them
in emulators.

floppy
------
Host system's floppy drive (under Linux, DOS or Windows).

int25
-----
Hard drive partition under DOS. Also used for the floppy drive on Apricot
PCs.

ntwdm
-----
Enhanced floppy support under Windows 2000 and XP, using an additional
kernel-mode driver.

myz80
-----
MYZ80 hard drive image, which is nearly the same as "raw" but has a 256 byte
header.

cfi
---
Compressed floppy image, as produced by FDCOPY.COM under DOS. Its format is
described in cfi.html.

qm
--
Disc images created by Sydex's CopyQM. This is a read-only driver.

teledisk
--------
Disc images created by Sydex's TeleDisk.  This is a read-only driver.

nanowasp
--------
Disc image in the 400k Microbee format used by the v0.22 NanoWasp emulator.

apridisk
--------
Disc image in the format used by the ApriDisk utility. The format is
described in apridisk.html.

rcpmfs
------
Reverse CP/M file system. A directory is made to appear as a CP/M disk. This
is an experimental system and should be approached with caution.

remote
------
Remote LibDsk server, most likely at the other end of a serial line.

Using LibDsk to access floppy and disk images
---------------------------------------------
The supplied libdskrc file located in the ubee512 share directory for
Windows and in the user's home path for Unices (.libdskrc) contains formats
specific to the Microbee.  You may add additional formats to this file.  The
LibDsk documentation describes the structure for definitions.

Microbee native format programs placed side 0 into the sector headers on
physical side 1 of double sided disks.  These and other similar disks can be
accessed correctly by using the --side1as0 option.  This option will also
determine what method the internal write track will use. 'ds40' and 'ds80'
formats will automatically use the --side1as0 option.  if the DS40 and DS80
disks used do not have the side 1 issue then disk formats 'ds401' and
'ds801' must be used instead.  Disks created using these last two formats
will also read/write correctly on a Microbee.

The following options are for use with LibDsk (see COMMAND LINE OPTIONS
for more information):

--dstep         Informs LibDsk the next Disk drives option uses double
                stepping to support 48tpi DD disks in a 96tpi DD drive. This
                option must precede each Disk drive option when LibDsk is
                required.

--dstep-hd      Same use as the --dstep option except this is for 48tpi DD
                disks in 96tpi HD drives.

--format=type   Determines the disk format type when using LibDsk.

--lformat       Lists all the LibDsk built in and additional disk formats
                that are available.

--ltype         Lists all the LibDsk driver types that are available.

--side1as0      Informs LibDsk the next Disk drives option uses a disk that
                has physical side one sectors containing 0 in the sector
                headers.

--type=driver   Determines what LibDsk driver will be used for the next Disk
                drives option.

--psec          Determines if sector probing is used for the next Disk drives
                option.

Examples:

Boot from a floppy disk (Native Microbee formatted) that has a system on it:

  Windows 98/Me:
    >ubee512 --type=floppy --format=ds80 -a A:

  Windows 2000/XP/Vista:
    >ubee512 --type=ntwdm --format=ds80 -a A:

  Unices:
    $ ubee512 --type=floppy --format=ds80 -a /dev/fd0

Boot from a disk image and make the emulator's drive B: use the floppy drive:

  Windows 98/Me:
    >ubee512 -a bootimage.ds80 --type=floppy --format=ds80 -b A:

  Windows 2000/XP/Vista:
    >ubee512 -a bootimage.ds80 --type=ntwdm --format=ds80 -b A:

  Unices:
    $ ubee512 -a bootimage.ds80 --type=floppy --format=ds80 -b /dev/fd0

Boot a copy protected disk (or EDSK image):

  Windows 98/Me:
    Does not appear to be possible on this system.

  Windows 2000/XP/Vista:
    >ubee512 --type=ntwdm --format=ss80 --psec -a A:
    >ubee512 --type=edsk --format=ss80 --psec -a bootimage.edsk

  Unices:
    $ ubee512 --type=floppy --format=ss80 --psec -a /dev/fd0
    $ ubee512 --type=edsk --format=ss80 --psec -a bootimage.edsk

Boot from a Teledisk disk image

  Windows W98/Me/2000/XP/Vista:
    >ubee512 --type=tele --format=ds80 -a bootimage.td0

  Unices:
    $ ubee512 --type=tele --format=ds80 -a bootimage.td0

An absolute path must be specified for LibDsk images.  It will not
automatically check the disks directory as is done with the built in image
support.

Formatting a floppy disk
------------------------
If you want to use High density 3.5" media then read the section concerning
this below before preceding any further.

The standard Microbee format programs should work from within the emulator.
The format method for double sided disks depends on if the --side1as0 option
or one of the disk formats that selects this automatically is used.  Using
'ds40' or 'ds80' will create formatted disks with the side 1 sector header
issue.  'ds401' and 'ds801' will use the current physical side for the side
value.

Examples:

  Windows 98/Me:
    Not tested

  Windows 2000/XP/Vista:
    >ubee512 -a bootdisk.ds80 --type=ntwdm --format=ds80 -b A:

  Unices:
    $ ubee512 -a bootdisk.ds80 --type=floppy --format=ds80 -b /dev/fd0

The options below can be added to the above command lines to view the output
of the system formatting program:

--conio --modio=+fdc_wtd+fdc_wth

LibDsk tools
------------
This section contains some examples of some very useful tools found in
LibDsk.  See the LibDsk documentation for further information on how to use
these.

In all the example commands shown it would be beneficial to add an extra
option of '-retry 5' so that the programs don't exit on a single bad error.

Any command example that ends with the backslash '\' means the rest of the
command is on the next line and may need to be removed.

dskform
-------
Floppy or image file formatter for emulated machines.

At present it can't replicate the Microbee side 1 issue or format DS80 disks
to have sectors 1-10 on the system tracks.  If the disk is not going to be
used as a system disk this limitation should not present a problem.

Apart from the DS80 problems it should be able to be used for formatting all
the Microbee disks contained in the liddskrc file.

Examples:

Format a floppy disk for the PJB DS84 format

  Windows 98/Me:
    Not tested

  Windows 2000/XP/Vista:
    >dskform --type=ntwdm --format=ds84 A:

  Unices:
    $ dskform --type=floppy --format=ds84 /dev/fd0

dsktrans
--------
Copies from one floppy or image file to another.

Examples:

This will copy a disk image to a floppy disk. The process also formats
the disk at the same time.

  Windows 98/Me:
    Not tested

  Windows 2000/XP/Vista:
    >dsktrans -itype raw -otype ntwdm -format ds84 diskimage.ds84 A:
    >dsktrans -itype dsk -otype ntwdm -format ds84 diskimage.dsk A:
    >dsktrans -itype edsk -otype ntwdm -format ds84 diskimage.edsk A:

  Unices:
    $ dsktrans -itype raw -otype floppy -format ds84 diskimage.ds84 /dev/fd0
    $ dsktrans -itype dsk -otype floppy -format ds84 diskimage.dsk /dev/fd0
    $ dsktrans -itype edsk -otype floppy -format ds84 diskimage.edsk /dev/fd0

This will create a disk image from a floppy disk.

  Windows 98/Me:
    Not tested

  Windows 2000/XP/Vista:
    >dsktrans -itype ntwdm -otype raw -format ds84 A: diskimage.ds84
    >dsktrans -itype ntwdm -otype dsk -format ds84 A: diskimage.dsk
    >dsktrans -itype ntwdm -otype edsk -format ds84 A: diskimage.edsk

  Unices:
    $ dsktrans -itype floppy -otype raw -format ds84 /dev/fd0 diskimage.ds84
    $ dsktrans -itype floppy -otype dsk -format ds84 /dev/fd0 diskimage.dsk
    $ dsktrans -itype floppy -otype edsk -format ds84 /dev/fd0 diskimage.edsk

dskdump
-------
Sector-level copy from one floppy or image file to another.

This will create an EDSK image from a SS80 floppy disk that contains
different numbers of sectors per track and sector sizes. i.e. A copy protected
disk.

  Windows 98/Me:
    Not tested

  Windows 2000/XP/Vista:
    >dskdump -itype ntwdm -otype edsk -iside 0 -format ss80 A: diskimage.edsk

  Unices:
    $ dskdump -itype floppy -otype edsk -iside 0 -format ss80 /dev/fd0 \
    diskimage.edsk

UNICES FLOPPY ACCESS
--------------------
This method is largely obsolete if LibDsk is built into the emulator. Please
see the 'LIBDSK IMAGE AND FLOPPY ACCESS' section if LibDsk is available.

10 sector per track (s/t) Microbee floppies that have been formatted with
the native format utilities may not be accessible using the existing device
definitions.  Disks that have the side 1 format issue, unusual sector
numbering, and the other unknowns can make this difficult.  It has been
found that 10 s/t double density disks can be formatted on a Linux or other
Unix hosts that will work in the emulator and the Microbee.

All standard Microbee formats should work except for the DS80 formats as
these have sectors that commence from 21 instead of 1 for the data tracks. 
There may be a method to create a Unix floppy device that will work, though.

To access a floppy disk instead of a 'disk image' we simply specify the
floppy device.  On Linux floppy drive 0 is normally /dev/fd0.  There are
other pre-configured devices that can be used that will match the floppy
media.  In the case of 10 s/t DS82 and DS84 Microbee formats I use:

/dev/fd0u800

You will need to have read/write permission as a normal user for the device.
If there are no suitable preconfigured devices already on your system then
you will need to create one.

Formatting a compatible floppy
------------------------------
If you want to use High density 3.5" media then read the section concerning
this below before preceding any further.

To format the disk as a user in fd0 place a non-write protected floppy disk
into the drive then enter:

$ fdformat /dev/fd0u800

The formatted disk will contain F6s and not the familiar E5s as used by
CP/M.  To use the disk in CP/M the directory entries will first need to be
filled with E5's

One way to achieve this is to create a disk image using my disk image tools
and call the image 'formatted.ds84'.  The newly created image will contain
all E5s.  Then use 'dd' as follows:

$ dd if=formatted.ds84 of=/dev/fd0u800

ATTENTION !!!: Use extreme care when using 'dd', and DO NOT run as root.
If used incorrectly unrecoverable loss of data could result.

Creating a compatible floppy disk from a disk image
---------------------------------------------------
Creating a compatible floppy from a raw disk image is straight forward under
Linux. A DS84 image can be created with:

$ dd if=myimage.ds84 of=/dev/fd0u800 

This will only work with standard raw disk images.

ATTENTION !!!: Use extreme care when using 'dd', and DO NOT run as root.
If used incorrectly unrecoverable loss of data could result.

Creating a disk image from a compatible floppy
----------------------------------------------
Creating a disk image from the compatible floppy is straight forward under
Linux. A DS84 image can be created with:

$ dd if=/dev/fd0u800 of=myimage.ds84 bs=512 count=1600

or just:

$ dd if=/dev/fd0u800 of=myimage.ds84

ATTENTION !!!: Use extreme care when using 'dd', and DO NOT run as root.
If used incorrectly unrecoverable loss of data could result.

Using the floppy disk
---------------------
To invoke this and boot from a floppy disk I use something like this:

$ ubee512 -a /dev/fd0u800/.ds84

Note that only raw formats are supported.  You can't use '.DSK' formats
directly on floppy disks!

A mix of direct floppy access and disk images can be used if desired.

As the read/write to floppies is being handled by the system, disk caching
will be noticeable on reads.

Don't change floppy disks while the emulator is running.  There is no
support for this at present.  You will have to exit the emulator first
before changing the disk then run the emulator again.

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.

Included in this distribution is documentation describing how to use this
package to create Microbee disk images.  See 'microbee_disk_to_image.txt'

LibDsk also has some excellent tools for conversion between floppy disks and
images.  Software sources and Windows binaries are available here:

http://www.seasip.demon.co.uk/Unix/LibDsk/

Teledisk by Sydex (Shareware) is widely available on the internet and can be
used to create TD0 images readable by LibDsk.

Other useful tools are Anadisk and CopyQM by Sydex.

Imagetools
----------
I have created some software tools for manipulating raw and 'DSK' images.
The tools that come with LibDsk can do most of what these can do but still
have some usefulness.  The distribution can be obtained here:

http://microbee.no-ip.com/uploads/Software/Imagetools/

USING 1.44MB 3.5" HD DISKS AS DD
--------------------------------
It is possible to make use of modern 3.5" High Density disks and make these
look like double density instead.

The top left hole (looking from disk front) found on HD disks informs the
drive what media type is being used.  The drive can be tricked into thinking
the disk is a normal double density disk by covering this hole up.  On a
Microbee that has an old double density only drive it makes no difference.

You can find plenty of talk about this subject on the net about whether it
means unreliable data retention, High density media may require larger write
signals and the drives adjust this according to the media inserted. By
covering up the HD hole we are affectively telling the drive to use DD
signals on a HD disk. I would not rely on data being retained for long
periods but I also don't rely on floppy disks full stop.

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 and volume level 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 wave files produced by uBee512 can be be loaded by a real Microbee with
the red tape plug connected to your PC's speaker on your amplifier/speakers
and the wave file played back.

To do this a mono to stereo adaptor should be used to avoid shorting out the
other audio channel from the PC's amplifier output.  It won't matter what
channel is used for the audio take off.  A replacement load resistor of 100
Ohms also is required.  The unused channel may also require a loading
resistor to keep the PC amplifier stable.

MICROEBEE          PC AUDIO OUT
---------          ------------
 
                   o L (UNUSED)     <--+ (Recommended for unused channel)
                                       |
TAPE-IN  o----+----o R                 |
              |                        |
              /                        / 
              \ 100 Ohms               \ 100 Ohms
              /                        /
              \                        \
              |                        |
     0V  o----+----o COMMON         <--+ 


Wave files from cassette
------------------------
The intention is 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.  The software used must be able to write the format
being used by uBee512 or converted afterwards.

Conversion tools for Windows:

http://www.beethink.com/AudioConverter.htm
http://www.lightlink.com/tjweber/StripWav/StripWav.html

If using the last one make a copy of your original as it overwrites when
converting.

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 EMUKEY+T keys.  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 EMUKEY+T keys again to reset the file to the beginning and
allow the data to be accessed.

The EMUKEY+T keys 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 EMUKEY+T KEYS 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 EMUKEY+T keys 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 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 -b testdisk.dsk --coms=/dev/ttyS0 --baud=19200
$ ubee512 -b testdisk.dsk --coms=/dev/ttyS1 --baud=19200

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

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,  set the list device to
use the parallel port then 'llist' to the printer device, this is a simple
method that can be used to convert files to text format:

>outl#1

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

Copy a file to the host system
------------------------------
A binary or text file can be copied to the host system using the CP/M
pip.com command.  In the case of binary files do not copy more than 1 file
at a time unless you want concatenated binaries.

When copying a binary file, the '[o]' is essential otherwise the first ^Z
byte encountered will terminate the copy:

>pip lpt:=filename.com[o]

Copy a text file that has the typical ^Z character as end of file marker:

>pip lpt:=filename.txt

VSYNC
-----
The VSYNC signal can be used to feed PIO port B bit 7,  this can be selected
by using the --piob7=vsync option, The PIO emulation allows for interrupts
for this signal.

Example
-------
This was used as a primitive method to keep time on tape based models.  This
can be demonstrated using the ROM based Telcom.  This example used Basic
5.22e and Telcom v1.2.

>ubee512 --model=ic --piob7=vsync

In Basic start Telcom:
>net

Set the alarm time:
>alarm 0001

Turn the clock on:
>clock on

Now wait for the time to reach 0001 to hear the alarm.  The alarm will stop
after 1 minute.

Exit Telcom to get back to Basic by pressing the ENTER key.

Type in:
>1 LIST
>2 GOTO 1

>run

This should show the clock still being updated in the top right of the
screen and the alarm sounding if active.

Press the BREAK or ^C keys to exit the Basic program loop.

DEBUGGING TOOLS
---------------
The emulator has built in debugging tools, these consist of command line
options and EMUKEYs. These have been introduced to aid in the development of
the emulator but should also prove to be valuable for application debugging
too.

Too view the output of the debugging tools a console will need to be
viewable.  In Windows the --conio option must be used or the output will
be sent to stdout.txt instead.

Z80 code debugging
------------------
Debugging mode can be started from the command line or started and stopped
during the running of the emulator.

Z80 Instructions can be single stepped with EMUKEY+BS, stepped 10 or 20
instructions at a time with EMUKEY+[ and EMUKEY+] or continuous trace mode
using EMUKEY+\ to turn on and off.  The Debugging mode can be switched off
with EMUKEY+- and switched on with EMUKEY+=.  The stepping and trace
commands will automatically switch on debugging mode.

During debugging break points will be checked and tracing and code execution
will be halted.  The user can then use the step or trace keys from that
point.

What is displayed in step and trace mode is determined by command line
options.  By default the disassembly fits in an 80 column wide display. 
Only the PC, Z80 Flags and registers AF, BC, DE, and HL are seen.  Other
registers and stack pointer contents can be viewed by using the appropriate
--debug options.  The instruction counter can also be made viewable.

Note: The emulation of the EI instruction appears to execute the instruction
following it so the disassembly of the following instruction is never seen. 
The register values shown next to the EI disassembly is the result of the
instruction that followed it.

Break points
------------
Break points will be monitored only when debug mode is enabled. Break points
are are specified on the command line.  There are two types, --bp=addr and
--bpc=count.

--bp sets a Z80 address where a break point will occur.  You can specify as
many --bp break points as you require.  After a break point is detected the
code execution is halted and the break point is cleared.

--bpc allows setting a break point at a particular instruction count.  Only
one value can be set at a time.

Example:
--bp=0x8000 --bp=0x100

Module IO debugging
-------------------
The result of I/O operations can be viewed and logged using the --modio
option.  This option can take parameters that determines which modules or
parts within a module should be reported.  It can also perform some other
tasks.

Examples:
--modio=+paknet+pioa+piob+piocont

--modio=+log+paknet+pioa+piob+piocont

The last example also sends the output to a log file.  WARNING: Logging can
produce extremely large files in a short period of time, be careful when
using it.

Peripheral register debugging
-----------------------------
The register contents of peripheral devices (including the Z80) can be view
by pressing the EMUKEY+R keys.  What is displayed is determined by the
--regs option.

Example:
--regs=+crtc+rtc+z80

Memory dump debugging
---------------------
The Z80 memory map contents can be dumped by pressing one of the EMUKEY+DUMP
keys. The dump keys supported are:

--dump=n    EMUKEY + D
+ 0x0080    EMUKEY + 1
+ 0x1000    EMUKEY + 2
- 0x0080    EMUKEY + 3
- 0x1000    EMUKEY + 4
repeat      EMUKEY + 5

The initial address is set to 0 unless a --dump=addr option is specified on
the command line to change the default value.

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, --clock, --xtal=f
--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 50 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 the execution speed is understood 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:

--clock=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]

 Control related:

  --alias-disks=x         Enables/disables checking for ROM aliases in the
                          roms.alias file. x=on to enable, x=off to disable.
                          Default is enabled.

  --alias-roms=x          Enables/disables checking for disk aliases in the
                          disks.alias file. x=on to enable, x=off to disable.
                          Default is enabled.

  --args-error=options    Clears an option error detection flag.  Arguments
                          commence with a '-' character to disable a flag.
                          Additional arguments may be declared in the same
                          --args-error option.

                          The arguments supported are:
                          -unknown - disable non-recognised argument error.

  --config=file           Allows an alternative configuration file to be used
                          or if file='none' then no configuration file will be
                          used.  This option if used must be the first option
                          declared on the command line.  The default file used
                          for configuration is 'ubee512rc' and must be located
                          in the ubee512 directory.

  --cmd-repeat1=n         Set the first delay period in milliseconds to be
                          used for repeated emulator commands. Normally these
                          are activated with EMUKEY and joystick buttons
                          mapped to commands. Default value is 500mS.
  --cmd-repeat2=n         Same as --cmd-repeat1 except this value determines
                          the delay period to be used after the first period.
                          Default value is 50mS.

  --dclick=n              Set the double click speed for mouse button events.
                          n may be 100-3000 milliseconds, default is 300mS.

  --exit=x                Forces the emulator to exit. This option is intended
                          to be used inside start up scripts when a condition
                          is not met.  x is the exit status value.

  --exit-check=x          Enables/disables exit checking. if enabled the user
                          must confirm before exiting the emulator. x=on to
                          enable, x=off to disable. Default is enabled.

  --gui-persist=n         Set the persist time in milliseconds for values that
                          appear on the status line, default is 3000mS.

  --lockfix-win32=x       Enables/disables LOCK key code fix for Win32. This
                          option has been provided in case it needs to be
                          disabled. x=on to enable, x=off to disable. Default
                          is enabled.

  --lockfix-x11=x         Enables/disables LOCK key code fix for x11. This
                          option has been provided in case it needs to be
                          enabled (possibly on some x11 set-ups). x=on to
                          enable, x=off to disable. Default is disabled.

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

  --mouse-wheel=x         Set the action associated with mouse wheel scrolling
                          The default is 'vol', the association can also be
                          changed with the EMUKEY+W hot key.

                          The arguments supported are:
                          none : no association (does nothing).
                           vol : adjust application volume level.
                           win : resize windows display when in OpenGL mode.

  --nodisk                Set no disks flag,  use to start some boot ROMs in
                          menu mode.  This flag will be cleared when any key
                          is pressed.

  --slashes=x             Conversion of path slashes to host format. x=on to
                          enable, x=off to to disable.  Default is enabled.

  --spad=n                Sets the number of spaces to be placed between each
                          status entry on the title bar.  The actual spacing
                          achieved will be dependent on the title font used.
                          Default value is 2 spaces.

  --status=options        Status configuration for title bar.  Arguments
                          commence with a '+' character. Additional arguments
                          may be declared in the same --status option.

                          The arguments supported are:
                          +clear - clear all current status arguments.
                          +d - show short drive access.
                          +drive - show long drive access.
                          +emu - show emulator name.
                          +emuver - show emulator name and version.
                          +joy - show joystick status.
                          +left - force left hand justification.
                          +model - show base model emulated.
                          +mute - show the sound mute state.
                          +print - show parallel printer enable.
                          +ram - show amount of RAM emulated.
                          +serial - show serial port set up if enabled.
                          +speed - show CPU clock speed.
                          +sys - show system name.
                          +tape - show tape input/output state.
                          +title - show customised title.
                          +ver - show emulator version.
                          +vol - always show volume level.
                          +win - always show window size.

  --title=name            Define the customised title name to be used when
                          '+title' is used in the --status option.

  --varset=var=val        Set a uBee512 built in environment variable.
                          var contains the variable name and val the value to
                          be assigned separated by '='. i.e. myvar=myvalue.
  --varuset=var           Un-set (remove) a uBee512 built in environment
                          variable.  var is the variable name.

 Conditional processing:

                          If any of the following conditionals returns a true
                          result then option processing is enabled, a false
                          result turns processing off until a true condition
                          is met.

  --if-egt=str1,str2      If str1 is equal to or greater than str2.
  --if-elt=str1,str2      If str1 is equal to or less than str2.
  --if-eq=str1,str2       If str1 is equal to str2.
  --if-gt=str1,str2       If str1 is greater than str2.
  --if-lt=str1,str2       If str1 is less than str2.
  --if-negt=str1,str2     If str1 is not equal or greater than str2.
  --if-nelt=str1,str2     If str1 is not equal or less than str2.
  --if-neq=str1,str2      If str1 is not equal to str2.
  --if-ngt=str1,str2      If str1 is not greater than str2.
  --if-nlt=str1,str2      If str1 is not less than str2.
  --if-nset=var           If variable var has not been set.
  --if-set=var            If variable var has been set.

  --if-false              If this is used then set false.
  --if-true               If this is used then set true.

  --if-system=x           If the host system is equal to system x. On POSIX
                          systems (Unix) this value is tested against the value
                          returned by the uname function sysname field. Known
                          arguments supported are:

                                  bsd : Unix BSD system.
                              freebsd : Unix FreeBSD system.
                                linux : Unix Linux system..
                                 unix : Unix system.
                                  win : Windows system.
                             win9x_me : Windows 95, 98 or Me system
                                  w95 : Windows 95 system.
                                  w98 : Windows 98 system.
                                   me : Windows Millennium system.
                                  nt4 : Windows NT4 systems.
                               nt4_ws : Windows NT4 Work station system.
                           nt4_server : Windows NT4 Server system.
                                  nt5 : Windows NT5 systems.
                                w2000 : Windows 2000 system.
                                   xp : Windows XP system.
                          server_2003 : Windows NT5 Server system.
                                  nt6 : Windows NT6 systems.
                                vista : Windows Vista system.

  --if-else               If last conditional resulted in false.
  --if-end                End of a conditional block.
  --if-cmpmode=x          Set the method used for comparing values, x=0 uses
                          'C' style strverscmp() and x=1 uses strcmp(). Default
                          method is 0.

 Debugging tools:

  --bp=addr               Set a Z80 address break point.  This option can be
                          specified as many times as is required.  A break
                          point can only be detected when in debug mode.

  --bpc=count             Set a Z80 break point determined by the number of
                          instructions executed. Can only be specified once.
                          A break point can only be detected when in debug
                          mode.

  -z, --debug=options     Debugging mode.  Arguments commence with a '+'
                          character,  additional arguments may be declared in
                          the same --debug option.

                          The arguments supported are:
                          +alt - output the alternate and the I, R registers.
                          +all - output all options.
                          +count - use instruction counter in disassembly.
                          +index - output the index registers.
                          +on - turn debugging mode on without disassembly.
                          +step - turn on debugging mode and start stepping.
                          +trace - turn on debugging  mode and start tracing.

  --dump=addr             Set the initial dump address value when using the
                          dump commands.  addr may be a valid Z80 address from
                          0 to 0xFFFF. If not specified then address 0 is used.

  --echo=x                Echo a string to stdout.  The string may also contain
                          an environment str1iable.
  --echoq=x               Same as --echo option but echoes a quoted version of
                          the environment variable if any spaces are found.

  --modio=options         Module I/O debugging output.  Arguments commence with
                          a '+' character,  additional arguments may be
                          declared in the same --modio option.

                          The arguments supported are:
                          +log - logs to ubee512_log.txt (makes big log files!)
                          +raminit - uses bank numbers as DRAM init values.

                          These arguments turn on port debugging for modules:
                          +clock, +crtc, +fdc, +fdc_wtd, +fdc_wth, +func,
                          +joystick, +keystd, +keytc, +mem, +options, +paknet,
                          +pioa, +piob, +piocont, +rtc, +ubee512, +vdu,
                          +vdumem, +video, +z80.

  --regs=options          Register dump. Determines what registers will be
                          dumped when the  EMUKEY+R key is pressed.  Arguments
                          commence with a '+' character,  additional arguments
                          may be declared in the same --regs option.
                          The arguments supported are:
                          +crtc, +rtc, +z80.

 Disk drives:

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

                          LibDsk usage:
                          If LibDsk is to be used to access a floppy drive then
                          file path may be 'A:' or 'B:' for Windows or a device
                          file for Unices. i.e. /dev/fd0 and /dev/fd1 on Linux.

                          General usage:
                          See 'File path searching' further on for detailed
                          information.  The default area for disks is:

                          @UBEE512@\disks\

  --dstep                 Informs LibDsk the next Disk drives option uses
                          double stepping to support 48tpi DD disks in a 96tpi
                          DD drive. This option must precede each Disk drive
                          option when LibDsk is required.

  --dstep-hd              Same use as the --dstep option except this is for
                          48tpi DD disks in 96tpi HD drives.

  --format=type           Determines the disk format type when using LibDsk.
                          Using this option will cause the next Disk drives
                          option to use the LibDsk driver.  This option must
                          precede each Disk drive option when LibDsk is
                          required. Additional disk formats can be placed into
                          the local libdskrc file.

                          ds40 and ds80 formats will automatically make use of
                          the --side1as0 option.  Use the ds401 and ds801
                          formats if this behaviour is not required. i.e. PC
                          formatted disks)

  --lformat               Lists all the LibDsk built in and additional disk
                          formats that are available.

  --ltype                 Lists all the LibDsk driver types that are available.

  --side1as0              Informs LibDsk the next Disk drives option uses a
                          disk that has physical side one sectors containing 0
                          in the sector headers.  This allows disks created
                          with native Microbee double sided format programs to
                          be accessed correctly.  The FDC write track emulation
                          will force the side information in the sector header
                          to use the physical side value with this option.

  --type=driver           Determines what LibDsk driver will be used for the
                          next Disk drives option. This option must precede
                          each Disk drive option when LibDsk is required, if
                          not then LibDsk will attempt to automatically detect
                          the driver type to use.

  --psec                  Determines if sector probing is used for the next
                          Disk drives option. This option must precede each
                          Disk drive option when probing is required.  The
                          option allows some special disk formats to be used.

 Display related:

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

  -f, --fullscreen        Toggle state of full screen mode, the display
                          defaults to a window (use EMUKEY+ENTER to toggle).

  -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.
                          u : user's monochrome configuration.
                          c : colour monitor.

                          Note: This option by itself does not force the
                          emulation into a standard model Microbee, it's use
                          simply determines what monitor type is connected
                          to the emulated Microbee.

  --mon-fg-x=level        Set the 3 user customised monochrome foreground
                          colours.  x is the gun colour ('r', 'g', 'b').  The
                          level value is 0-255.
  --mon-bg-x=level        Set the 3 user customised monochrome background
                          colours.  x is the gun colour ('r', 'g', 'b').  The
                          level value is 0-255.
  --mon-fgl-x=level       Set the 3 user customised monochrome low intensity
                          foreground colours.  x is the gun colour
                          ('r', 'g', 'b').  The level value is 0-255.  This
                          option is only for the Premium (alpha+) models for
                          half intensity monochrome (see --hint).

  --rgb-nn-x=level        48 options to customise the Premium (alpha+) colours.
                          nn is the colour value (00-15), x is the gun colour
                          ('r', 'g', 'b').  The level value is 0-255.

  --video=x               Video initial start state. x=on to enable, x=off to
                          to disable.  Default is enabled.

  --video-depth=x         Video depth. Default is 16 bits per pixel. Other
                          depths may improve or degrade performance, i.e. sound
                          quality. These values only apply to SDL rendering. x
                          may be one of the following:

                            8 : 8 bit colour.
                          8gs : 8 bit grey scale.
                           16 : 16 bit colour.
                           32 : 32 bit colour.

  --video-type=type       Video type. The default type used is OpenGL texture
                          rendering. Other types may improve or degrade
                          performance, i.e. sound quality. <type> may be one
                          of the following:

                          gl : OpenGL (textured) hardware rendering.
                          hw : SDL hardware rendering.
                          sw : SDL software rendering.

 OpenGL rendering:

  --gl-aspect-bee=n       The aspect value you want for the Microbee display.
                          This default value is 4:3 aspect (1.333) but may be
                          changed with this option.  Don't use this to fix
                          monitor aspects, use --gl-aspect-mon for that.
                          Use a floating point value for n.  i.e. 4:3 aspect
                          is 4/3=1.333.

  --gl-aspect-mon=n       This option overrides the monitor aspect ratio worked
                          out by the emulator. This should not be needed for
                          LCD monitors running in native resolution. The value
                          may be required if running a 4:3 CRT monitor with
                          non 4:3 resolution. Use a floating point value for n.
                          i.e. 4:3 aspect is 4/3=1.333.

  filter options:         The OpenGL filter settings provide sharp or soft
                          display rendering.  One is provided for each display
                          mode.  The value for the current mode can be toggled
                          with the EMUKEY+F hot keys.  The values allowed are:

                          sharp : sharp display.
                           soft : soft display.

  --gl-filter-fs=x        filter setting for full screen mode. (sharp)
  --gl-filter-max=x       filter setting for maximised window mode. (sharp)
  --gl-filter-win=x       filter setting for resizeable window mode. (soft)

  --gl-max=x              Start up maximised if x=on, if x=off then start up in
                          a window or full screen mode depending on the use of
                          --fullscreen option. Default is off. This option is
                          currently not supported on Windows machines.

  --gl-vsync=x            Vsync: swap buffers every n'th retrace. x=off to
                          disable, x=on to enable.  default is enabled.

  --gl-winpct=n           The default window size on start up determined by a
                          percentage value from 5-100% of the desktop X
                          resolution.  If this option is not used the window
                          X size is 50% of the desktop width.

  --gl-winpix=n           The default window size on start up determined by
                          the number of pixels between 50 and the desktop X
                          resolution.  If this option is not used the window
                          X size is 50% of the desktop width.

 File related:

                          The file options are for use by the uBee512 support
                          tools.  How these are used is entirely dependent on
                          the Z80 application accessing these values.  See the
                          TOOLS.TXT file for detailed usage information.

  --file-app=name         String name of up to 255 characters. Default is an
                          empty string.
  --file-exec=n           Z80 address 0-65535 (0000-FFFF hex). Default is 0.
  --file-list=files       Host file path(s) of up to 255 characters. @UBEE512@
                          variable if used will have double quotation
                          characters added if any space characters are found.
                          Default is an empty string. This option may be used
                          repeatedly to build up an array of strings.
  --file-list-q=files     Same as --file-list option except the entire string
                          will have double quotation characters added. No
                          double quotation characters will be placed around
                          the @UBEE512@ variable. This option may be used
                          repeatedly to build up an array of strings.
  --file-load             Z80 address 0-65535 (0000-FFFF hex). Default is 0.
  --file-run=name         String name of up to 255 characters. Default is an
                          empty string.
  --file-exit=x           Enables/disables the state of the flag value, x=on
                          to enable, x=off to disable. Default is enabled.

 Information output:

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

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

  --lcon                  List the [section] names found in the configuration
                          file.
  --lconw                 Same as --lcon option except uses a wide format.
  --lcons=n               Sets the list start point for --lcon and --lconw
                          options. Default value is 1.

  --version               Obtain the version number of the emulator and SDL.

 Joystick emulation:

  --js=n                  Joystick number to use, n=0 for first joystick. n=-1
                          to disable an existing setting.

  --js-axis=x             Joystick axis mapping to buttons.  x=on to enable,
                          x=off to disable. Default is enabled.
  --js-axisb=n            Joystick axis buttons base number.  The axis button
                          offsets are 0=up, 1=right, 2=down and 3=left.  The
                          base number n is added to the offsets to generate a
                          button number. n may be any value from 0 to 124.
                          Default value is 0.
  --js-axisl=n            Determines the thresh hold level for button
                          detection.  n may be any value from 1 to 32767.
                          Default value is 3200.
  --js-clear              Clear all Microbee joystick button settings.
  --js-mbee=x             Microbee joystick emulation control. x=on to enable,
                          x=off to disable.  Default is enabled.
  --js-up=n               Button number for 'up', default is 0
  --js-right=n            Button number for 'right', default is 1
  --js-down=n             Button number for 'down', default is 2
  --js-left=n             Button number for 'left', default is 3
  --js-fire=n             Button number for 'fire', default is 4
  --js-play1=n            Button number for 'player 1', default is 5
  --js-play2=n            Button number for 'player 2', default is 6
  --js-spare=n            Button number for 'spare', default is 7

  --js-clist              List the command names available for joystick mapping.
  --js-klist              List the key names available for joystick mapping.
  --js-kbd=x              Joystick to Microbee keys mapping control.  x=on to
                          enable, x=off to disable. Default is disabled except
                          when a --js-kset or --js-ksel option is used.
  --js-kk=k               Microbee key to be mapped to a joystick button. See
                          --js-klist option for more information.
  --js-kb=n               Button n to be associated with last --js-kk=k option.
  --js-ksel=n             Select the joystick key set to use. n may be a value
                          of (0-255) Alternatively specify n as a character
                          from A-Z, the letter will be converted to numbers
                          0-25.  Default selection is determined by --js-kset.
  --js-kset=n             Place the joystick keys into set n and make active.
                          There are 256 sets of joystick keys (0-255) that may
                          be used. Alternatively specify n as a character from
                          A-Z, the letter will be converted to numbers 0-25.

 Model emulation:

                          See 'File path searching' further on for detailed
                          information.  The default area for roms is:

                          @UBEE512@\roms\

  --basic=file            Used for defining 4, 8, and 16K BASIC ROM parts.
  --basica=file           Same as --basic option.
  --basicb=file           Used for 4, 8K and ppc85/tterm ROM part B.
  --basicc=file           Used for 4K ROM part C.
  --basicd=file           Used for 4K ROM part D.

                          These --basicx options allows the ROM file image
                          specified to be used instead of the built in model
                          defaults for the BASIC ROM(s).

  --basram                The memory locations 0xA000-0xBFFF for ROM based
                          models defaults to ROM.  This option will force this
                          8K area to SRAM emulation.  The contents will contain
                          a typical SRAM pattern on start up,  it will not be
                          associated with a ROM image file.

  --charrom=file          Allows the character ROM file image specified to be
                          used instead of the built in predefined 'charrom.bin'
                          ROM.

  --col                   Enables colour emulation for standard models. This
                          option has no affect when emulating a Premium, 256TC
                          or Teleterm model.  Defaults to an RGBrgb digital
                          monitor type when used.

  --col-type=n            Same as --col option except the monitor type may be
                          selected. n=0 selects RGB analogue, and n=1 selects
                          RGBrgb monitor emulation. Default is disabled.  This
                          option has no affect when emulating a Premium, 256TC
                          or Teleterm model.

  --colprom=file          Use the file values to override the internal 82s123
                          IC 7 standard colour values. This option has no
                          affect when emulating a Premium, 256TC or Teleterm
                          model.

  --hint=x                Half intensity monochrome emulation for Premium
                          (alpha+) models.  x=on to enable, x=off to disable.
                          This is set to 'on' by default for the 256TC and
                          upgraded Premium models.  This option has no
                          affect when emulating a standard model.

  --hwflash=x             Hardware Inverse and flashing video emulation for
                          Premium (alpha+) models.  x=on to enable, x=off to
                          disable.  This is set to 'on' by default for the
                          256TC and upgraded Premium models.  This option has
                          no affect when emulating a standard model.

  --lmodel                List the available model types.

  --lpen                  Enables the use of the 6545 Light pen keys emulation.
                          This is enabled by default for all models except for
                          the 256tc and Teleterm models.

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

  --mono                  Disables colour circuit emulation for standard models.
                          This option when emulating a Premium, 256TC or
                          Teleterm model has the same affect as --monitor=g.

  --netram                The memory locations 0xE000-0xEFFF for ROM based
                          models defaults to ROM.  This option will force this
                          4K area to SRAM emulation.  The contents will contain
                          a typical SRAM pattern on start up,  it will not be
                          associated with a ROM image file.

  --netrom=file           Allows the ROM file image specified to be used
                          instead of the built in model defaults for the NET
                          ROM.

  --pak(n)=file           The --pak(n) options allows the ROM file image
                          specified to be used instead of the built in model
                          default for the PAKn ROM 0 to 7 locations.

  --pakram=n              The PAK n location will use SRAM instead of ROM
                          emulation.  The contents will contain a typical SRAM
                          pattern on start up,  it will not be associated with
                          a ROM image file. n may be any PAK number from 0-7.

  --pcg=n                 Premium (alpha+) model option that sets size of PCG
                          RAM to be emulated.  n is the size of the PCG memory
                          in Kilobytes and can be any even value between 2 and
                          32. 256TC, Premium and Teleterm models are 16K,
                          upgraded Premium models are 32K.  This option has no
                          affect when emulating a standard model.

  --piob7=signal          Determines what signal is used for PIO port B bit 7.
                          The default value depends on the model emulated.
                          The source values are: rtc, vsync, net, and pup.

  --rom1=file             Allows the ROM file image specified to be used
                          instead of the built in model default for the boot
                          ROM. This ROM is only used by all FDC models.
  --rom2=file             Allows the ROM file image specified to be used
                          instead of the built in model default for ROM2. This
                          ROM is used by all DRAM FDC models, except for the
                          256TC.
  --rom3=file             Allows the ROM file image specified to be used
                          instead of the built in model default for ROM3. This
                          ROM is used by all DRAM FDC models, except for the
                          256TC.

  --sys=name              Defines a system name,  this will be appended to some
                          files so that different operating systems using the
                          same model can still have unique names for certain
                          files.  By default this name contains nothing.  An
                          example is the loading and saving of RTC values.  By
                          default for a p128k model this would be 'p128k.rtc',
                          by defining name to be 'mysys' would then use
                          'p128k-mysys.rtc' for the file, the emulator inserts
                          the hyphen character.

  --vdu=n                 Premium (alpha+) 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.  Default is 2K.  Don't use this
                          option to increase to 8K unless you understand the
                          problems associated with it.

 Parallel printer port emulation:

                          See 'File path searching' further on for detailed
                          information.  The default area for printer is:

                          @UBEE512@\printer\

  --print=file            Printer output to file,  the output is not modified.

  --printa=file           Printer output to file,  the output is converted to
                          ASCII decimal.

 Real Time Clock (RTC) emulation:

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

 Serial port emulation:

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

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

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

 Sound emulation:

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

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

  --snd-alg1=x            Sound algorithm to prevent sound gaining in time due
                          to integer remainder losses from division operations.
                          x=on to enable, x=off to disable.  Default is off.
  --snd-freq=f            Set the sound sampling rate, f may be a value from
                          5512 to 176400 Hz.  Default frequency is 44100 Hz.
  --snd-freqadj=n         Adjusts the sound card sampling rate value. n is a
                          floating point percentage value from +/- 1 to 50 that
                          is added to the sound frequency to keep it just under
                          the speed of the Z80 CPU emulation.  Default is -2.5%
  --snd-freqlow=f         Sets the lowest sound frequency that can be produced.
                          f may be 1 to 20000Hz.  Default is 20Hz.
  --snd-holdoff=n         Number of milliseconds hold-off delay to apply each
                          time a new stream of sound bits is started. n may be
                          0 to 10000. Default is 50 milliseconds.
  --snd-hq                Sets high quality sound.  How well this works will be
                          dependent on the host platform.  This option has the
                          same affect as setting all these values:
                            --snd-holdoff=50
                            --snd-samples=2048
                            --snd-freq=88200
                            --snd-freqlow=10
                            --snd-freqadj=-0.25
                            --snd-alg1=on
  --snd-mute=x            Sound mute, use to start the emulator with the sound
                          muted until enabled. x=on to enable, x=off to
                          disable.  Default is off.
  --snd-samples=n         Sets the SDL callback data size. n must be a power of
                          2.  Values from 1 to 32768 are allowed.  Default is
                          1024 samples.
  --snd-volume=l --vol=l  Set the sound volume level.  A level of 0 to 100% is
                          allowed.  Default is 15%.

 Speed related:

  --clock=f               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).

  --clock-def=f           Set the Z80 clock frequency for emulation in MHz when
                          the uBee512 API restore function is called.  Default
                          frequency is 3.375 MHz.

  --frate=fps             Frame rate, an integer value between 1 and 1,000,000
                          is allowed.  Default is 50 FPS.

  --maxcpulag=n           This is the maximum time the Z80 CPU emulation is
                          allowed to get behind before 'catch up' is bypassed
                          for the currently lagged cycles.  A very high value
                          for n will cause the 'catch up' mode to always be in
                          affect,  using a value of 0 for n will effectively
                          disable this feature and act like 2.5.0 and earlier
                          versions. Default value is 250ms.

  --speedsel=n            CPU speed selection emulation. n=1 to enable, n=0
                          to disable.  The following models are enabled by
                          default: 256tc, p512k, 512k, p256k, 256k.

  -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 CPU clock 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 CPU clock 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 CPU clock 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.

  -x, --xtal=f            Old non preferred options to set the Z80 clock
                          frequency.  Use --clock option instead.

  --z80div=n              Determines the number of Z80 blocks emulated per z80
                          frame.  This value allows the polling rate to be
                          increased or decreased.  The polling rate per second
                          is the product of the frame rate (--frate) and this
                          value. The value of n may range from 1 to 5000. On
                          versions prior to 2.7.0 this value was 1. Default
                          value is 25.

 Tape port emulation:

                          See 'File path searching' further on for detailed
                          information.  The default area for tapes is:

                          @UBEE512@\tapes\

  --tapei=file            Tape input from a WAV file.

  --tapeo=file            Tape output to a WAV file.

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

 Variables:

                          The --varset option may be used to create variables.
                          These variables are pre-configured:

  UBEE512 or ubee512      Path to the ubee512 account.
  UBEE_VERSION            Emulator version.
  UBEE_HOST               Host system (UNIX or WIN).
  UBEE_SYS_MAJOR          On Unix systems this will be 'UNIX' On Windows
                          systems it contains one of the following:
                          win9x_me, nt4, nt5 or nt6.  Both systems will use
                          upper case for the variable value.
  UBEE_SYS_MINOR          On Unix systems this will be the value of the
                          uname.sysname member.  On Windows systems it contains
                          one of the following: w95, w98, me, nt4_ws,
                          nt4_server, w2000, xp, server_2003, or vista. Both
                          systems will use upper case for the variable value.

 File path searching:

  Path slash characters
  ---------------------
  Forward or back slashes may be used in file paths irrespective of the
  program being run under Unices or Windows environments when slash
  conversion is enabled. See --slashes option. Unices will see '\' as an
  escape sequence when used on the command line and also when found in
  configuration files and slash conversion is disabled.

  Files to be opened
  ------------------
  Existing files will first be searched for in the current directory, if the
  path is not found a second search in the default directory will take place.
  For the second search the file path specified will be appended to the default
  directory path.  The second search is not carried out if a '\', '.\', or
  '..\' are the first characters of the path or a ':' character is used under
  Windows.

  Files to be created
  -------------------
  Files to be created will be placed into the default directory unless a path
  to another location is specified by using a '\', '.\', or '..\' as the
  first characters of the path or a ':' character is used under Windows.

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 the 'micro defender' game we must emulate a standard monochrome model or
if emulating an alpha+ model use the monochrome option and disable the half
intensity emulation.  The second example uses '-mw' to force a white on a
black background monitor.
>ubee512 -a mybootdisk.dsk --mono --hint=off
>ubee512 -a mybootdisk.dsk -mw --hint=off

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 --clock=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'm having some problems using uBee512,  where can I get some help ?
A: There is a topic devoted to uBee512 on "The Bee Board" forum located
   here: http://microbee.no-ip.com/beeboard. You can post questions there.

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 active development
   expect releases every 2-3 months 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.  I may release unofficial bug fix
   releases from time to time here: http://microbee.no-ip.com/beeboard

Q: How can I receive notifications of a new release ?
A: Create a freshmeat.net account and subscribe to my project here:
   http://freshmeat.net/projects/ubee512/

Q: The display shows up as all white when using OpenGL video mode.
A: Most likely this is because you are using a video card driver that does
   not support OpenGL. Install the latest video drivers for your video
   hardware.  See 'OpenGL Rendering' under the 'Display' section for more
   information.

Q: Can I install uBee512 on a flash drive and run on different Windows
   systems directly from it ?
A: Yes, uBee512 does not make a registry entry if installed from the ZIP
   file so it is quite portable and should run on W98/Me/XP/Vista.

Q: The sound is very slow and sounds strange,  what's the problem ?
A: This problem now appears to be resolved, make sure you are using the
   latest version (2.7.0 or later).

Q: The CP/M system hangs on boot up even after replacing the disk image with
   a known good one.
A: Try deleting the @UBEE512@/rtc/rtc-file associated with the model being
   emulated as this may have become corrupted.  A new one will be created
   when the emulator exits.

Q: The LOCK key does not work correctly under win32 or x11.
A: The LOCK key behaviour can be fixed by using either the --lockfix-win32
   or --lockfix-x11 options.

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: I don't see any console output for some things when running under
   Windows.
A: Under Windows console output goes to stdout.txt.  All console output can
   be seen in another cmd Window by using the --conio 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: Use the configuration file,  you can create the entries that you require
   then simply run with: ubee512 mysetup.  You can also create batch files
   in Windows or script files under Unices that contain 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.

5. Thanks to the The Bee Board community (http://microbee.no-ip.com) for
   being so helpful especially to Johnno, vivid and PCPete for their
   assistance in various aspects of the emulator's development.

6. Thanks to ianm of microbee.no-ip.com for assisting with colour testing on
   a standard colour model Microbee. The results provided have enabled
   accurate emulation of the standard colour model possible.

Links
=====
- My project page on Freshmeat, please subscribe to my project if you like
  it, you will be notified of new releases:

  http://freshmeat.net/projects/ubee512/

- This site has a forum devoted to the Microbee and provides a lot of useful
  information for registered users.  The site is now much improved and is
  much easier to register:

  http://microbee.no-ip.com web site.

- emuControlCenter (ECC) An emulator GUI front end that has support for
  uBee512 and provides a nice interface to play Microbee games:

  http://www.camya.com/eccblog/

- Walnut Creek CDROM,  contains a lot of Microbee and CP/M stuff, see the
  'beehive' and 'mbug' directories:

  http://z80cpu.eu/mirrors/oldcomputers.dyndns.org/cdrom/cpm

- Other sites:
  http://www.digitalresearch.biz/CPM.HTM
  http://www.classiccmp.org/dunfield/
  http://www.seasip.demon.co.uk/Unix/LibDsk/
  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. (use --version option)
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)
