.\" $NetBSD: xbeeb.1,v 1.2 2000/06/05 18:12:57 skrll Exp $
.\"
.Dd May 27, 2000
.Dt XBEEB 1
.Sh NAME
.Nm xbeeb
.Nd Acorn BBC Micro emulator with X interface
.Sh SYNOPSIS
.Nm
.Op Fl ahV?
.Op Fl o Ar file
.Oo
.Fl p Ns Op Ns Ar number
.Ar file
.Oc
.Op Fl w Ar number
.Op Fl s Ar number
.Op Fl m Ar mode
.Op Fl d Ar dir
.Op Ar file
.Sh DESCRIPTION   
The
.Nm
program is an X11 based emulator of the Acorn BBC
(British Broadcasting Corporation) Micro. The BBC Micro
was first produced in the early 1980s by Acorn Computers
of Cambridge.
.Pp
The BBC Micro was based on the 6502 processor with a 16k
operating system ROM, upto 32k RAM and 15 paged 16k ROMs for
utilities.       
.Ss Options
The options are as follows:
.Bl -tag -width Ds
.It Fl ?
Display usage information.
.It Fl a
Emulate the Model A only - if available.
.It Fl d Ar dir
Use 
.Ar dir
as the directory for disk emulation.
.It Fl h
Display usage information.
.It Fl m Ar mode
Start in display mode
.Ar mode .
.It Fl o Ar file
Load the
.Ar file
as the Operating System image, i.e. at address 0xc000.
.It Xo
.Fl p Ns Op Ns Ar number
.Ar file
.Xc
Load the ROM image specified by
.Ar file
into the paged ROM location specified by
.Ar number .
If
.Ar number
is not specified the image is loaded into ROM number 15.
.It Fl s Ar number
Set the DIP switches to
.Ar number ,
where
.Ar number
can be specified in octal, decimal or hex. Only the 5
least significant bits of
.Ar number
are used by the emulator.
.It Fl V
Display the version information.
.It Fl w Ar number
Set the paged ROM slot specified by
.Ar number
as writable.
.It Ar file
Load the snapshot
.Ar file
as the start point of the emulator.
.El
.Ss Implementation
All of the instruction set of a standard 6502 CPU, 
Illegal or undocumented opcodes on the NMOS 6502
and changes for the CMOS R65C02 and R65C12 are implemented.
.Pp
The 6522 VIA implementation is almost complete.  The
emulation of the system VIA is sufficient to provide clock
interrupts and keyboard handling for the OS.
.Pp
The CRTC, Serial ULA and display implementation is
complete enough to provide a reasonable emulation of the
display. X11 fonts for all the teletext characters are
provided.
.Ss Keyboard
The keyboard handling is pretty much there, but not
quite perfect as the Beeb has a somewhat non-standard
keyboard layout compared with most available today.
.Pp
There are a number of keys on the BBC Micro that do not
work in the same way as a standard PC keyboard. As the
keycodes depend on your X setting experimentation is
probably the best way to understanding the mapping. Some
important keys should be as follows:
.Pp
.Bl -bullet -compact
.It
Pause is the BREAK key
.It
Right Alt is the SHIFT LOCK key
.It
F10 is the F0 key
.It
End quits the emulator
.It
Home creates a snapshot
.It
Enter on the keypad changes the directory used for the
emulated file system
.El
.Ss Snapshots
There is a snapshot format for saving the complete
machine state.
.Ss Disk Emulation
The emulated disk system requires a directory containing a
set of files present on a given disk, exactly as they
would appear on a BBC disk. In addition there is a file
called 
.Qq __CATALOG__
which contains the name, load and
execution address, length and sector number for each file
as it would be displayed by *INFO
.Pp
The sectory number is unused in this emulation - it's
there for the sake of completeness and maybe used in the
future. 

.Sh FILES
.Bl -tag -width @PREFIX@/@XBEEBROOT@/roms/xdfs0.70.rom -compact
.It Pa @PREFIX@/@XBEEBROOT@/roms/OS1.2.rom
the Operating System rom image
.It Pa @PREFIX@/@XBEEBROOT@/roms/BASIC2.rom
the BBC Basic rom image
.It Pa @PREFIX@/@XBEEBROOT@/roms/xdfs0.70.rom
the XDFS rom image required for disc emulation
.El
.Sh BUGS
The following are known bugs:
.Bl -bullet
.It
Serial IO, the ADC, Econet, the FRED and JIM
memory-mapped IO pages, the Tube and User VIA are pretty
much all ignored.
.It
The mark/space ratio for flashing teletext is a guess.
I haven't a clue what it really is.
.It
The emulator possibly only works on pseudo-colour X
displays. It is untested on any others.
.It
The MODE 7 screen emulation flickers because it updates
the whole screen when it changes, rather than just the
changed bits. The reason it works this way is
because of the handling of double height characters -
the context of each line may change because of a change in
the line above it.
.It
The code for re-initialising the screen when a snapshot
has been loaded is quite horrid and is probably the
source of a number of bugs. It needs more thought and
work.
.It
There are numerous places where it is unknown how the
emulator should handle a given situation. These are
usually documented in the code, but will cause a fatal
error if encountered.
.It
The cursor isn't implemented for bitmapped modes.
.It
Handling of mixed case in filenames is incomplete. If a
filename is mixed case on the disk, it's exact name must
be used in any command for loading or running it.
.It
Although you won't hear anything, the emulator still
does all that's necessary from the programming point of
view to make sounds even if you don't have sound support.
This means that there will be delays in programs that play
sounds before they continue. The emulator hasn't crashed,
honest.
.It
Handling of hardware-scrolled screens isn't perfect.  In
the efs-demo and xdfs-demo directories there's a program
called B.DEMO that will usually demonstrate the problem.  
.It
Changing the Horizontal Sync. register in the
CRTC isn't implemented but is required for some games.
.It
The counter in Hopper is screwy. I did have this
working at once stage, but I've broken it again.
.It
The screen window overlaps the window with the LED
status in sometimes.
.El
.Sh WEB Resources
The best site for information about BBC Micro is
.B http://www.nvg.ntnu.no/bbc
.Sh AUTHORS
This program was written by James Fidell. This man page was
put together by Nick Hudson (nick@nthcliff.demon.co.uk)