********************************************************************************
         uBee512 - an emulator for the Premium Microbee 512K FDD model
                      Copyright (C) 2007  Stewart Kay

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

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

uBee512 GPL
-----------
uBee512 - An emulator for the Premium Microbee 512K FDD model
Copyright (C) 2007  Stewart Kay

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

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

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

uBee512 Tools License
---------------------
Any software tools that may be supplied that are not third party are
"Freeware".  the software comes with absolutely no warranties and is 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/

- rom1.bin - the boot ROM image from the 128K Microbee.  Not included.

- charrom.bin - the character ROM image from the Microbee.  Not included.

- boot.dsk - default floppy OS boot image.  Not included.

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

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

The uBee512 is an emulator for the Premium 512K disk drive Microbee series.
It supports full Premium graphics, sound and key board emulation.  The DRAM
emulation is 512KB allowing other third party operating systems to be used.

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

Now that there are several emulators around for the Microbee this should
benefit users as ideas can be shared around to improve all the emulators.

All the development work has been carried out without any real Microbee
hardware for direct comparisons.  I gave all my Microbees and documentation
away in about the year 1997 and this is one of the reasons I have developed
the uBee512 emulator.  I have developed a lot of software for the Microbee
that was never released (I hope to release some of this at a later date). 
Since having the uBee512 emulator up and running I have been able to run
some of my software that other emulators have not been able to do.

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

There is currently no dedicated web site for this project.

Objective
---------
The main objective of the emulator is to run existing software that works on
a real Microbee.  This emulator's goal is not to emulate the underlying
Microbee ICs exactly (i.e. Z80PIO, SY6545 and WD2793) but instead concentrate
on trying to make existing software usable.

What this means is that if you write some code to run in the emulator it
might not work on a real Microbee.  An example is setting up the PIO port. 
On this emulator things like the Microbee PC speaker are assumed to be there
ready for use so even if the CP/M BIOS does not send the PIO configuration
setup data it will still work where it might not on the real Microbee.

This situation may change for each emulated module as the emulator develops
further but for now it is not the main objective.

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.  Other CPUs can make use of the emitted 'C' output of
makez80.  Currently the supported platforms that have been tested on i386
and x86_64 hardware 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 single core (3200) FreeBSD 5.4-RELEASE #2

Features
--------
The uBee512 emulator package currently provides the following 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.
* 512K DRAM emulation.
* Speaker sound emulation.
* Fully mapped keyboard, emulates all keys correctly and key repeating works
  at correct speed.
* All 6545 cursor modes supported.
* Screen is resized to suit the current 6545 registers.
* Various disk images support and has read/write capability for drives A-D.
* Speed execution accuracy and regulation is excellent and very fast in
  turbo mode.
* 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.
* 3.375 MHz or Turbo speed mode option.

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

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

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

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

Be aware that running in turbo mode option with sound can cause the sound
buffer to become full quite quickly and sound will 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.

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

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

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

On my development machine, an Athlon AMD64 dual core (3800+) and Fedora core
6 installed with the 32 bit version I was able to run 6 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.

The speed accuracy (and the sound quality) depends on the granularity of the
system timer.  You need to have a 1mS resolution.  If your resolotion 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 the FreeBSD platform.  I have
been informed that the timer can be changed to 1mS on FreeBSD but this was
not tried.

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

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

Z80 Application software
------------------------
Too numerous to mention it all, but essentially all system support programs
and 3rd party software work except for disk formatting programs, and
applications that need hardware that is not currently supported like tape,
serial, parallel port, etc.

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 Premium software search through the retro archive
(look in the CAT files) for clare1.mwb clareX.mwb, etc, QUIX-2.COM.

A huge amount of software is available at http://microbee.no-ip.com in the
uploads section.

Binary distributions
====================
Windows (win32)
---------------
A binary distribution for Windows (win32) is available in ZIP file format.

Source distributions
====================
Building the uBee512 Emulator
-----------------------------
The information provided here is for a Linux build environment, the win32
port of the emulator is cross compiled from here:

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

To compile for FreeBSD you need to be on a FreeBSD system.
 
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

Now as root:
# make install

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

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.

Installation
============
Windows:
1. Unzip the windows binary distribution to drive c:\
   Don't use any other location as the emulator expects to find things
   in that location.
2. Copy the required disk images to c:\ubee512\disks\
3. Copy the required ROM images (see ROM IMAGES below)
4. You can create a desktop link to the emulator with some options if you
   don't want to run from a command line.
5. If running from a cmd prompt from any location you will need to add a
   path for the system to find ubee512.  The path is c:\ubee512

Unices:
1. Make sure you are logged in as a normal user.
2. Run the ubee512 emulator.  The first time this occurs some directories
   will be created in your home account.  It will then exit.
3. Copy the required disk images to /home/username/.ubee512/disks/
4. Copy the required ROM images (see ROM IMAGES below)

ROM IMAGES
----------
You need to have two ROM images.

'rom1.bin' is the boot ROM.  This must be a banked DRAM model boot ROM to
allow the 512K emulation to load a banked memory operating system.

'charrom.bin' is the character ROM.  It needs two font sizes so requires a
3.375 Mhz model Microbee 4K ROM image.

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

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

LINEFEED: Numeric-ENTER
   BREAK: Numeric-PLUS
   RESET: PAGEDOWN

Other functionality:
 Exit the emulator: END
Full screen toggle: ALT+ENTER

NOTE !!!!! Be careful with END and PAGEDOWN keys,  there is no confirmation
at present for these keys so if you accidentally press these you can lose
unsaved data.

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

'.DSK'
CPCEMU Disk image format

'.IMG' or '.NW'
raw image files in nanowasp v0.22 format, 40T DS

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

The disk is recognised by the file name extention,  it is not case sensitive.

A mixture of any of these disk types are allowed for the drives A-D.

A disk image containing an operating system is required.

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

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

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

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

COMMAND LINE OPTIONS
--------------------
-a<file>	image file (path/filename) for floppy drive A
-b<file>	image file (path/filename) for floppy drive B
-c<file>	image file (path/filename) for floppy drive C
-d<file>	image file (path/filename) for floppy drive D

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

		Windows:
		c:\ubee512\disks\

		Unices:
		/home/username/.ubee512/disks/

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

		Windows:
		ubee512 -a .\myimage.dsk

		Unices:
		ubee512 -a ./myimage.dsk

-s<col>		standard graphics Microbee emulation,  turns 'off' the Premium
		(alpha+) graphics and use a standard green monitor. The <col>
		specifier allows for standard monochrome or colour support:
		   c : standard Microbee with colour
		   m : standard Microbee with Green monochrome

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

-t		turbo mode, executes Z80 code as fast as possible. Without this
		option the emulation attempts to keep Z80 CPU execution to that
		of a 3.375 MHz Microbee.

-f		start in full screen mode (use ALT+ENTER to toggle).

-m<mode>	monitor mode, if this option is not specified the colour mode
                is used. <mode> may be one of the following:
                   a : amber monitor
		   g : green monitor
		   w : white monitor, white foreground on black background
		   b : black monitor, black foreground on white background
		   c : colour monitor

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

-z		debugging output (for development purposes)

Some sample command lines
-------------------------
for a Premium SBC 128K system
>ubee512 -a boot.dsk

for a Premium SBC 128K system (a and b drives)
>ubee512 -a boot.dsk -b mydisk-ds40.dsk

for a Premium SBC 128K system and 'micro defender' game we must use a
monochrome monitor.  The '-mw' is for white on a black background.
>ubee512 -mw -a boot.dsk -b mydisk-ds40.dsk

start up in full screen mode
>ubee512 -f -a boot.dsk -b mydisk-ds40.dsk

start up in turbo mode, full screen mode, white monochrome
>ubee512 -t -f -a boot.dsk -b mydisk-ds40.dsk

Acknowledgements
================ 
1. Thanks to the nanowasp v0.22 release by David G. Churchill. This new
   project has been 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.

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

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

For bug reports you need to state the version number of the uBee512 emulator
and 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.  Also state the SDL version used
if known.

If you have access to some real Microbee hardware then please test against
that before filing any bug reports.

Replies to general help questions will depend on how much email I receive
and my available free time. I will see what I can do but hopefully a forum
can handle most of this where other users can help out and get involved.

Enjoy!

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