********************************************************************************
                                    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 only to the uBee512 sources, the
binaries produced from it and the associated documentation.  The SDL, LibDsk
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
---------------------
Any software tools that may be supplied that are not third party are
"Freeware".  the software comes with absolutely no warranties and are to be
used at your own risk.  The code is provided "as-is".

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

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

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

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), 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 model is also emulated.

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

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

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 to 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 Fedora core 6 using the
  32 bit version. 

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

Features
--------
New for this release:
* LibDsk has been added allowing direct floppy access, various disk image
  formats DSK, EDSK, TD0, CopyQM, etc. Other disk drivers under Windows and
  Unices are also possible.
* Added --side1as0 option to allow disks in LibDsk to correctly read side 1
  when the sector header contains side 0. Microbee DS80 and DS40 formats can
  have this problem depending on the format program that was used.
* Added a sector size probing option --psec to access protected floppy disks
  and edsk images.
* Added emulation of the FDC write track command.  Format and Init programs
  now work when using LibDsk.
* Added +fdc_wtd and +fdc_wth write track debug output options.
* Model information and drive status now appears in the program's title bar.
* Added A libdskrc file containing common Microbee formats for LibDsk.
* Re-instated the alpha+ --vdu option functionality.  Default is 2K for VDU
  memory (no banking), 8K banked can be selected.
* Re-instated the paging of the text output for the --help option in Windows
  as default buffers in the console are not large enough.

Fixed:
* Alpha+ VDU colour bank selection issue resolved by defaulting to 2K of VDU
  RAM instead of 8K.
* FDC status results.

Overall features:
* Full Premium (Alpha+) model graphics support. 32K PCG, 8K Screen, 8K
  Colour and 8K Attribute RAM.
* Premium (Alpha+) emulation of the hardware inverse and flashing video
  defined in attribute RAM.
* Premium composite monochrome half intensity emulation.
* Teleterm 256TC 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.
* Real Time Clock (RTC) emulation.
* Fully mapped 6545 and 256TC keyboard, emulates all keys correctly and key
  repeating works at correct speed.
* All 6545 cursor modes supported.
* Screen is resized to suit the current 6545 registers.
* 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
  and black.
* Standard Microbee emulation option for backwards compatibility.  (i.e. No
  Premium graphics)
* Full screen mode.
* Emulator 'hacking' options.
* Z80 Debugging tools built in.
* Tools allowing files to be copied between the host system and CP/M.

Premium emulation
-----------------
Premium Microbees were released standard with 16K of PCG and 2K each of
screen, attribute and colour RAM (VDU) but was able to be expanded to 32K
PCG and 8K for VDU RAM with later models shipped with the full 8K.  There
are emulation options that determines if 16 or 32K PCG and 2 or 8K VDU RAM
is emulated.

Part of the Premium's new graphics was support for monochrome intensity,
hardware flashing of video and inverse video.  all of these have 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.

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

Early colour emulation
----------------------
Colour emulation for models prior to the Premium and 256TC models Microbees
has 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 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 adjust 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.

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.

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

Even faster speed is possible by specifying the 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.

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 Teleterm 256TC
* 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://z80cpu.eu/mirrors/oldcomputers.dyndns.org/cdrom/cpm/beehive/
http://z80cpu.eu/mirrors/oldcomputers.dyndns.org/cdrom/cpm/simtel/cpmug/
http://www.retroarchive.org/cpm/cdrom/SIMTEL/CPMUG/

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

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

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

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

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

LibDsk support is pre-set to be compiled in but can be disabled in the
Makefike 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,  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. Copy the required disk images to the installed program directory
   ubee512\disks\ (see DISK IMAGES below)
6. Copy the required ROM images (see ROM IMAGES below)
7. Optional is to place tape wave files in ubee512\tapes\

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. Copy the required disk images to the installed program directory
   ubee512\disks\ (see DISK IMAGES below)
5. Copy the required ROM images (see ROM IMAGES below)
6. Optional is to place tape wave files in ubee512\tapes\
7. You can create a desktop link to the emulator with some options if you
   don't want to run from a command line.

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

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

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

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

Copy all required ROMs to the following locations:

Windows:
Installed location\ubee512\roms\

Unices:
Your home location/.ubee512/roms/

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

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

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

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 is also some other programs, see the TOOLS.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 write
protected.  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 - Teleterm 256TC, 256K DRAM FDD
p512k - Premium, 512K DRAM FDD
512k  - Standard, 512K DRAM FDD
p256k - Premium, 256K DRAM FDD (64K Premium to 256K upgrade)
256k  - Standard, 256K DRAM FDD (64K CIAB to 256K upgrade)
p128k - Premium, 128K DRAM FDD
128k  - Standard, 128K DRAM FDD (SBC)
p64k  - Premium, 64K DRAM FDD
64k   - Standard, 64K DRAM FDD (CIAB)
56k   - APC 56K RAM, FDD (Advanced Personal Computer)
ppc85 - Premium, PC85 32K Tape
pc85  - Standard, PC85 32K Tape
pc    - PC 32K Tape (Personal Communicator)
ic    - IC 32K Tape
2mhz  - First model and kits, 32K Tape

The p512k model is emulated if no 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 latest colour
circuitry, 1 is the earlier colour circuitry and no entry is monochrome. 
The earlier colour circuit emulation can be enabled with --col 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.

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

MHI:
This is the monochrome half intensity video emulation supported by the 256TC
and Premium models.  The 256TC has this as standard.  The Premium models
required some hardware changes to enable this feature.  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.  The 256TC model 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   1   -   -   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   1   -   -   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
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
--------------
* The bn60.rom, a Premium graphical 128K boot ROM will not boot the disk.
  This may not be an emulator problem.

* Early colour emulation for models prior to the Premium and 256TC models
  requires the data stored in the 82S123 fusible link PROM on the colour
  board to be known to emulate all the foreground colours correctly.  To
  date I have not been able to ascertain this information.  An alternative
  to having this data is to run a Microbee program I wrote that displays all
  foreground colour combinations on an early colour model and taking a
  picture of the display and sending it to me, from this the other values
  can be worked out.

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 image appears to be defective.  Use the
    alternative ROM image shown in the 256TC model section below.

Limitations
-----------
The '56k' 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.

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

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

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

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

Each FDD model has a default boot disk image name,  the default image must
be located in the ubee512/disks directory.  If the default model boot disk
image can not be opened the emulator will attempt to open the fall-back
image 'boot.dsk' except for the 56K, 64K models, or the user may specify
what image should be used.

Model: 256tc                                  Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
  boot ROM: 256TC.ROM                         16K  BIOSNEW2.DAT (v1.15)
                                              16K  tc256r12.bin (does not work)
extra ROMs: 256TC_2.ROM (optional)            16K
            256TC_3.ROM (optional)             8K
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: ppc85 (Premium PC85)                   Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
BASIC ROMs: PREM-A.ROM                        16K  PREM-A.ROM v5.29e (banked)
            PREM-B.ROM                         8K  PREM-B.ROM v5.29e
   Net ROM: PREM_NETWORK.ROM                  16K  TELC321.ROM v3.2.1
  PAK0 ROM: PREM-C.ROM   (Wordbee)            16K  PREM-C.ROM v1.3
  PAK1 ROM: PREM-E.ROM   (Basic help)         16K  PREM-E.ROM 
  PAK2 ROM: PREM-F.ROM   (Busycalc/PC85 Menu) 16K  PREM-F.ROM Busy Calc III
  PAK3 ROM: PREM-G.ROM   (Graphics/Database)  16K  PREM-G.ROM
  PAK4 ROM: PREMVTEX.ROM (Vidotex)            16K  PREM-PREMVTEXT.ROM v2.35
  PAK5 ROM: PREM-I.ROM   (Shell)              16K  PREM-I.ROM
  PAKx ROM: PREM_PAK6.ROM - PREM_PAK7.ROM     16K

Model: pc85                                   Max  Possible Versions/ROMs
-------------------------------------------------------------------------------
BASIC ROMs: PC85_BASIC.ROM                    16K  5.24 ?
   Net ROM: PC85_NETWORK.ROM (8K)             16K  TELC321.ROM ?
  PAK0 ROM: PC85_PAK0.ROM (Wordbee)            8K  wbee12.rom ?
  PAKx ROM: PC85_PAK1.ROM - PC85_PAK7.ROM     16K  ?

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
   Net ROM: PC_NETWORK.ROM                     8K  Telcom v3
  PAK0 ROM: PC_WBEE.ROM (Wordbee)              8K  wbee12.rom
  PAK1 ROM: PC_PAK1.ROM                        8k  COMMAND file (Basic help)
  PAKx ROM: PC_PAK2.ROM - PC_PAK7.ROM          8K

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
   Net ROM: IC_NETWORK.ROM                     4K  telc12.rom telc11.rom
  PAK0 ROM: IC_WBEE.ROM (Wordbee)              8K  wbee12.rom
  PAKx ROM: IC_PAK1.ROM - IC_PAK7.ROM          8K

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

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

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

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

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

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

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

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

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:

256TC Model
  SELECT: PAGEUP

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

All Models
   BREAK: PAUSE/BREAK

On a Microbee (not 256TC) 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 functionality:

The EMUKEY is the HOME or ALT keys.  The ALT key is not usable in the 256TC
model unless the --lpen option is also specified.

Exit the emulator         END
Reset the emulator        PAGEDOWN
Full screen toggle        EMUKEY + ENTER
Tape rewind               EMUKEY + T
Dump memory (--dump=n)    EMUKEY + D
Dump memory (+ 0x0080)    EMUKEY + 1
Dump memory (+ 0x1000)    EMUKEY + 2
Dump memory (- 0x0080)    EMUKEY + 3
Dump memory (- 0x1000)    EMUKEY + 4
Dump memory   (repeat)    EMUKEY + 5
Register dump             EMUKEY + R
Debug trace on/off        EMUKEY + \
Debug step                EMUKEY + BS
Debug step * 10           EMUKEY + [
Debug step * 20           EMUKEY + ]
Debug mode on             EMUKEY + =
Debug mode off            EMUKEY + -

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

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

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

  LEFT BUTTON: Toggles full screen mode.
MIDDLE BUTTON: Reset the emulator.
 RIGHT BUTTON: Exit the emulator.

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

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

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

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

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

DISK IMAGE FILES (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.

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 now part of 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):

--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 30 FPS and a CPU clock frequency of 3375000 Hz is
used to determine how many cycles of Z80 code are executed in one block:

cycles = clock / framerate

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

time = cycles / clock

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

delay = time - timex

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

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

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

Now that 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:

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

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

 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.

  --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, +keystd,
                          +keytc, +mem, +paknet, +pioa, +piob, +piocont, +rtc,
                          +vdu, +vdumem, +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.

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

                          Windows:
                          installed location\ubee512\disks\

                          Unices:
                          your home path/.ubee512/disks/

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

                          Windows:
                          ubee512 -a .\myimage.dsk

                          Unices:
                          ubee512 -a ./myimage.dsk

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

  --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        Start in full screen mode (use ALT+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
                          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.

 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.

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

 Model emulation:

  --col                   Enables early colour circuit emulation for standard
                          models.  This option has no affect when emulating a
                          Premium or 256TC 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.

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

  --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, ppc85, pc85, pc, ic, and 2mhz.

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

  --pcg=n                 Premium 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 and Premium 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.

  --vdu=n                 Premium model option that sets size of VDU RAM to be
                          emulated.  n may be 2 or 8.  The VDU RAM size
                          determines the number of screen, attribute and colour
                          RAM banks.  Default is 2K.  Don't use this option to
                          increase to 8K unless you understand the problems
                          associated with it.

 Parallel printer port emulation:

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

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

 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

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

 Speed related:

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

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

 Tape port emulation:

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

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

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

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

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

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

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

Q: 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: 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: It appears to be a system and/or sound driver related problem on some
   set-ups. Check that you are using the correct and latest drivers for your
   system.  Send me a bug report especially if you find a fix so that the
   solution can be shared with others.

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: Create a batch file(s) in Windows or script file under Unices that
   contains your favourite start up methods.  Alternatively create desktop
   links with the command options included.

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

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

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

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

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

5. Thanks to the The Bee Board community (http://microbee.no-ip.com) for
   being so helpful and especially to Johnno and vivid for their valuable
   assistance.

Links
=====
- http://freshmeat.net/projects/ubee512/
- http://microbee.no-ip.com web site.  This site provides a lot of useful
  information for Microbee users.

- http://z80cpu.eu/mirrors/oldcomputers.dyndns.org/cdrom/cpm
- http://www.digitalresearch.biz/CPM.HTM
- http://www.classiccmp.org/dunfield/
- http://www.seasip.demon.co.uk/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)
