Ok, firstly let's get the legal bits out the way...

----
Copyright 1993/4 by James Bonfield (jkb@mrc-lmb.cam.ac.uk).
You may freely distribute this program provided:
a) This copyright notice is also copied without modifications.
b) All modifications made are clearly listed as such in the ChangeLog file.
----

Description
-----------

This is version 1.1alpha of the BBC Emulator. It provides a method of running
BBC programs on a UNIX system (it even has one of the two beeps on startup).
The code _may_ work on other systems, but this has not been tested by the
author.

The code should be still treated as alpha testing, or beta testing at the
most. The only reason I am releasing this version is due to the hole it shall
fill. In particular, much of the X11 code is definitely has that 'being
developed' look and so may still contains debugging output and masses of
redundant functions and/or comments.

Once unpacked you should find the following directories.

data		Directory of data files loaded up by the BBC. Contained here
		are the BASIC language, OS 1.2 (plus defaults for the IO mem),
		the first 0xE00 bytes of memory, the 6502 macro assembler (by
		Ian Phillips?), HackROM (James Bonfield & Stephen Youell).

simple		Code for the simplest screen IO interface.

curses		Code for an (incomplete) implementation of a curses based
	 	screen IO. Hardware scrolling is not yet supported.

X11		Code for an (also incomplete) X windows interface. This
		currently only handles modes 0, 1 and 2 (in a stretched
		fashion). Palette switching and hardware scrolling are
		currently not supported.


Compiling
---------

Firstly, edit the Makefile. There are a few tunables:

SCREEN	Which style of IO to use for the screen display. Current choices are:
	simple		no nonense very basic output (ie not PRINT TAB())
        curses		the curses package interface - allows for cursor
			control and not much else currently.

LIBS	Used in conjunction with the SCREEN definition to specify libraries
needed (eg "-lcurses -ltermcap")

ASSUME	If defined, will cheat slightly in the emulation to gain speed. Such
	assumptions are pretty safe and simplify things enormously. The only
	real assumption now is that opcodes and operands are always in
	'simple' memory. Eg that we are never going to have the program
	counter at, say, &FE30. If this really does bother you, then leave
	this undefined. But please see the notes on relative speed below.

SUPERFAST
	A few more assumptions - that we can always use the fastest methods
	available. This implies no memory mapped IO, and memory is always
	writable. Suprisingly this doesn't actually gain that much speed. I'd
	advise normally sticking to ASSUME only unless sideways RAM is not
	required and maximum speed is a must. Note that in this mode the
	mmap IO will also confuse things so that the emulator thinks shift was
	held down during boot-up resulting with the message "File not found".
	Also SUPERFAST will not work with any of the extra chip support, such
	as 6845.

DEBUG	Allows use of -d command line switch to debug 6502 code. Even enabling
	this switch appears to slow things down by around 10%, so by default
	it is not there. This also allows for opcode/operand &D4 &00 / &D4 &01
	to switch on/off debugging mode from within execution of 6502.

NEED_TIMER
	A UNIX interrupt system using itimers. This allows for efficient
	polling methods without resorting to continuous checks. So it's ideal
	(and is required by) the 6522 timer system and the raster scan of a
	6845 (the X11 interface).

SYSTEM_VIA
	Emulates the 6522 chip used for system resources. Currently this
	doesn't mean much as 6522 emulation is not complete. However this is
	required for the 6845 which uses a latch attached to the 6522 to
	obtain the screen size.

USER_VIA
	The user port 6522 chip. No attempt is made to actually connect calls
	to this to any user hardware. It's simply another 6522 with another
	couple of hardware timers to use.


Obtaining the necessary ROMS
----------------------------

For copyright reasons, the ROMs cannot be made available with the emulator. I
would like to provide these and will make a request to acorn. One possible
solution would be encrypt the ROMs in this distribution and provide a quick
and simple method of creating a 'key' on a real BBC to use as the password in
some UNIX decryption software. Currently I do not know how Acorn would view
such a method.

In the mean time, to obtain the necessary files perform the following on your
BBC micro.

*SAVE OS C000+3C00 C000
FOR I%=&0000 TO &3FFF STEP 4:I%!&4000=I%!&8000:NEXT
*SAVE BASIC 4000+4000 8000

Transfer these to your 'host' system using the filenames os.bbc and basic.bbc.
To transfer you could either try using kermit or alternatively via a machine
that can understand a BBC disk format. Unfortunately I have no futher
information regarding the transfer. I'm willing to add comments from other
people though.


Notes
-----

The same technique employed in Ian Stephenson's emulator of using opcode &D4
as a trap to execute miscellaneous UNIX calls is used (I've named this in the
debug output as opcode "UNX").

The Emulator was developed upon a PC (486sx25) running Linux. Maximum speed
acheived was around 28% slower than the beeb itself. A brief guideline of
speed can be seen here using a simplistic benchmark.

The beeb itself (BBC B issue 7) took 5.29 seconds for the operation.

compilation options			time for 'FOR I%=0 TO 30000:NEXT'
-------------------------------------------------------------------------
-DSCREEN_simple -DSUPERFAST				6.81
-DSCREEN_simple -DASSUME				8.06
-DSCREEN_simple					       15.18
-DSCREEN_curses -DASSUME				8.11
-DSCREEN_curses -DASSUME both_vias & timer		8.59
-DSCREEN_X11    -DASSUME				9.17 or ~30.5 *

* The test machine (the 486sx25) only has 4MB of memory. X11 is severly
  crippled in such circumstances and so much time was spent swapping. The
  times listed above are the user+system times added together. In the X11 case
  the real time was 30.5 seconds! Some of this difference will be due to
  swapping, and the most of the rest is the X server. A better test maybe to
  see how much CPU time the X server accumulates too. In the other cases (such
  as the first listed above) the times are very close (eg 6.81 vs 7.07).

The above hopefully illustrate that curses and 'simple' interfaces are
comparible in speed, but the X11 interface is much slower. Also the 'ASSUME'
option approximately doubles the speed of operation for the simpler
interfaces.

128K sideways RAM is supported. The startup status of the 16 banks is:

00	Read only
01	Read only
02	Read only
03	Read only
04	Read/Write
05	Read/Write
06	Read/Write
07	Read/Write
08	Macro Assembler
09	HackROM 1.18 (plug plug!)
10	Read only
11	BASIC
12	Read/Write
13	Read/Write
14	Read/Write
15	Read/Write


To Do
-----

- Add a decent *UNIX filing system.

- Sound support (driver for SPARC audio device?)

- Curses interface should understand MODEs

- UNX #&66 should also save status of support chips as well as memory.
  Sideways RAM perhaps also can be saved.

v- Load analogue of UNX #&66 needed.

- Remove all references in code to the module system. It's only acting to
  confuse people currently as it's no longer used.

- opcodes.c should optionally use either unsigned char or int types for the
  registers. The same applies for other code. I have discovered that code
  along the lines of 'char a; /* ... */ a += 3;' can be 3 times slower than the
  code 'int a; /* ... */ a += 3; a &= 0xff;' on a DECAlpha (OSF/1)! If we
  defined the register type to be int, then we can add 'reg & 0xff' on all
  read requests. Also instructions such as inc would never need to worry about
  this.

- Why do our memory write hooks return a value? It's never used.

- Fix the bugs (too numerous to list here).

- Invesitgate use of SVGAlib on Linux. Does this give a far faster response?

- 8271 emulation (see Stephen Youell, syouell@dcs.warwick.ac.uk).

- Change relative calc. code from:
  + (x < 0x80 ? x : 0x100 - x)
  to
  + (signed char)x

  Is this ok on all platforms?

- Further mmap investigations for page swapping of sideways ram.

- X11 bug: When in mode 0 (and other modes?) and I do "MOVE 0,0:DRAW 1280,0",
  why do I get a series of memcpy along the following lines?

  memcpy 37ff8, [21,1,1,1,1,1,1,1]
  memcpy 37ff8, [1,21,1,1,1,1,1,1]
  memcpy 37ff8, [1,1,21,1,1,1,1,1]
  memcpy 37ff8, [1,1,1,21,1,1,1,1]
  memcpy 37ff8, [1,1,1,1,21,1,1,1]
  memcpy 37ff8, [1,1,1,1,1,21,1,1]
  memcpy 37ff8, [1,1,1,1,1,1,21,1]
  memcpy 37ff8, [1,1,1,1,1,1,1,21]

  This results in a dotted line rather than a solid. Am I not setting the mode
  correctly somewhere? (And the OS consequently being confused).

- X11 bug: 'poked' 255 has invalid colours set.

- svgalib interface for a faster linux version.


And finally...
--------------

I am open to ideas and suggestions. If you've decided to add a particular
extension to the code please do ask me first. It may have already been done or
is being planned. My email address is jkb@mrc-lmb.cam.ac.uk. The latest
versions of the emulator can be accessed by anonymous ftp to the machine
al.mrc-lmb.cam.ac.uk in the directory pub/jkb/beeb. The latest version will be
tarred, gzipped, and named something like "beeb1.1.tar.gz".

Cheers,

	James

