Difference between revisions of "BeebEm for UNIX README"

From BeebWiki
Jump to: navigation, search
m (1 revision)
m (1 revision)
 
(No difference)

Latest revision as of 19:12, 8 March 2015

** THIS IS A PRE-RELEASE! **

BeebEm for UNIX
===============
http://beebem-unix.bbcmicro.com/

IF YOU WISH TO CONTRIBUTE TO THIS README, PLEASE DO SO AT:
http://beebwiki.jonripley.com/BeebEm_for_UNIX_README

BeebEm for UNIX is a BBC Micro and Master 128 emulator.  It enables you to
run BBC Micro software on your UNIX operating system.  BeebEm for UNIX
should work on most UNIX or Linux systems running freedesktop.org's
pkg-config, GTK+ 2.2 and Simple DirectMedia Layer (SDL) 1.2 or later.

Unlike the Windows and Mac releases, there are no binaries provided with
BeebEm for UNIX as it is distributed only as source code, which you can
modify yourself.  BeebEm for UNIX must, therefore, be compiled before it
can be installed and run.

This is a very early version of BeebEm for UNIX, so there will most likely
be a few bugs in it!  It is a port based on the BeebEm for Windows source
code, from version 3.5, currently being developed by Mike Wyatt.  BeebEm for
UNIX is still a work in progress and is not complete yet so some options
available in the Windows version are not currently in the UNIX version.

Please send all feedback to: frutbunn AT gmail DOT com

Oh, and thanks for taking the time to play with this! :-)

The copyright on everything in BeebEm for UNIX resides with David Gilbert,
the original author, as described in COPYING.


Compiling and Installing
------------------------

BeebEm for UNIX can be compiled with a C++ compiler such as G++ v4, from the
GNU Compiler Collection (GCC).  Once you have the compiler ready and the
pre-requisites above installed (along with their development packages
containing the corresponding header files), check that the file downloaded
correctly (this may be md5sum on Linux):

# md5 beebem-0.0.13.tar.gz

Then extract the source code tarball:

# tar zxvf beebem-0.0.13.tar.gz
# cd beebem-0.0.13

If you use FreeBSD, then you need to edit the configure script, so please
look at the FreeBSD notes below at this point.

To install in your home account, for your specific user only, use the
--prefix flag for configure, otherwise BeebEm for UNIX will attempt to
install into /usr/local as a global install for all users - such a global
install must be performed as root.

# ./configure --prefix=$HOME/test --enable-econet
# make
# make install-strip

Remove the source directory, if no longer wanted:

# cd ..
# rm -fr beebem-0.0.13

BeebEm for UNIX is distributed with everything you need to get going,
so just change to the installed directory and run the BeebEm for UNIX
binary:

# beebem

or, for maximum nostalgia:

# beebem welcome.ssd

It'll run the BBC welcome disc! Cool! :-)

If BeebEm for UNIX does not run see the troubleshooting section below.

FreeBSD notes:

The configure script needs a tool called 'sdl-config' to determine
where SDL resources are located. However FreeBSD ports will postfix
this command with the SDL version number, so 'sdl-config' becomes
sdl11-config.

So before running the configure script above, please edit this file
so that every occurrence of sdl-config, becomes sdl11-config.

You can automate that change with sed like so:

sed s/sdl-config/sdl11-config/g configure > configure2
chmod u+x configure2
mv configure2 configure


Running BBC Micro Software
--------------------------

BeebEm for UNIX runs BBC Micro software held in disc or tape image files
are kept in a set of directories in your 'share/beebem' area.  Some disc
images are supplied with BeebEm for UNIX, in the 'media/discs' directory.
To run a disc image, press F12 and use the 'Discs' option on the menu to
allow you access to 'Select, load and run a disc'.

The images with an 'ssd' extension are DFS images.

You can download more disc and tape images from internet sites such as
these:

  http://www.stairwaytohell.com/
  http://www.bbcmicrogames.com/
  http://www.iancgbell.clara.net/elite/

Put the disc image files into the 'media/discs' directory.


BeebEm for UNIX FAQ
-------------------

Some commonly asked questions:

Q1. How do you open the configuration menu?

A1. Press F12.

Q1. How do you save your preferences in the configuration menu?

A1. Press F12 and select 'Discs' from the menu.  Select 'Save
    configuration'.
    
Q1. How do you change the default folder for loading disks or tapes?

A1. Press F12 and select 'Discs' from the menu.  Load a disk from your
    preferred directory and then select 'Save configuration'.

    BeebEm for UNIX will remember the folder you last loaded a disk or
    tape from and default to that the next time you select load.

Q1. What key is the BBC Micro's Break key mapped to by default?

A1. Pause/Break.


Configuring BeebEm for UNIX
---------------------------

To get BeebEm for UNIX running at an optimal speed there are some
configuration options that can be changed.  BeebEm for UNIX can display
the speed of emulation relative to a real BBC Micro and the number of
frames per second (fps) being displayed.  You should see these values in
the window title bar or at the bottom of the screen in full screen mode.

You may find that the best fps rate is achieved in full screen mode by
checking the Fullscreen box on the main configuration menu.

Choosing the 640x512 resolution in the Screen configuration menu will
improve the look of the screen.

If you have a fast PC you can also improve the sound quality by selecting
the 44.1kHz sample rate on the Sound menu.

For further information on speeding up BeebEm for UNIX see the notes for
the 'Hardware' menu below.

Once you have decided on a set up you can save it using 'Save
configuration' from the 'Discs' menu.


ROM Software
------------

Although most games software is supplied on disc images there is a large
selection of ROM software available for the BBC Micro.  There are
application ROMs such as word processors and drawing packages, there are
programming language ROMs such as FORTH and BCPL, and a whole range of other
software.  The BBC Micro's operating system, BASIC language and disc filing
system are all supplied on ROM.

The BBC Micro and Master 128 (and BeebEm for UNIX) support up to 16 ROM
slots (plus one for the operating system).  The BBC Micro ROMs are kept in
subdirectories of the 'share/beebem/roms' directory.  There is one
subdirectory for each of the four models emulated.

The ROMs that BeebEm for UNIX loads are configured in the '.beebem/Roms.cfg'
file in your home directory.  You can edit this file using any text editor
to add a ROM.  Change one of the 'EMPTY' lines to the name of the ROM file
you have put in one of the 'share/beebem/roms' sub-directories.  The first
17 lines in Roms.cfg are for the BBC Micro Model B emulation, the second 17
are for the IntegraB emulation, the third for the B Plus emulation and the
last 17 for the Master 128 emulation.

To run a ROM you will need to type a command into BeebEm for UNIX.  The
exact command will depend on the ROM itself and you may need to refer to any
documentation that accompanied the ROM.  Some ROMs list the commands
available when you type '*HELP' into BeebEm for UNIX.

Any of the 16 ROM slots can be configured as RAM.  Some software
(e.g. games) can make use of this RAM so its a good idea to leave at least
one slot as RAM.

Note that certain ROMs must be present for each emulation mode to work so do
not remove these:

 BBC Model B          - OS12.ROM, BASIC2.ROM, DNFS.ROM
 BBC Model B IntegraB - OS12.ROM, IBOS.ROM, BASIC2.ROM, WDFS.ROM
 BBC Model B Plus     - B+MOS.ROM, BASIC2.ROM, WDFS.ROM
 Master 128           - MOS.ROM, TERMINAL.ROM, BASIC4.ROM, DFS.ROM

The default set of ROMs configured for the Master 128 mode are MOS 3.20.
The MOS 3.50 ROMs are also included.  To use them rename the
share/beebem/roms/M128 directory to M128-MOS3.2 and rename the M128-MOS3.5
directory M128.


Keyboard Mappings
-----------------

For default mapping most of the keys are the same on the Beeb and PC but
these are not:

   PC               Beeb

   F12              N/A (Options)
   F1-F9            f1-f9
   Pause/Break      Break
   -_               ;+
   =+               -=
   `                _
   #~               ^~
   ;:               @
   '@               :*
   Insert           Copy


Using Disc Images
-----------------

BeebEm for UNIX emulates two double sided floppy disc drives, known as
drives 0 and 1 (the second sides are drive 2 and 3).  You can load a disc
image file into either drive 0 or 1 using the Discs menu in BeebEm for UNIX.

Some useful disc commands are:

  *CAT              - List files on the disc
  *DRIVE <drive>    - Change default drive to number <drive>
  *TITLE <title>    - Put a title on the disc
  *DELETE <file>    - Delete a file
  LOAD "<file>"     - Load a BASIC program
  CHAIN "<file>"    - Load and run a BASIC program
  SAVE "<file>"     - Save a BASIC program
  *RUN <file>       - Load and run a binary program

To boot (i.e. run) a disc you press Shift & Pause/Break (hold the shift key
down and press Pause/Break).  If a disc does not boot it is probably because
it has not been set up to be bootable.

A bootable disc needs to have a file called !BOOT on it and it needs to be
configured to run the !BOOT file when its booted.  If a disc image has a
!BOOT file on it but it does not boot then try running the following command
(you will need to switch off write protection first):

  *OPT4,3

If you want to write data to a disc image (e.g. save a game position) you
will need to make sure that 'Read only' is switched off on the Discs menu
for the drive you are using.  Disc writes will then write data straight back
to the image file on your PC disc.

If you want to use ADFS discs in the Master 128 mode then load an ADFS disk
image (such as the MasterWelcome.adl image in share/beebem/media/discs) and
type '*ADFS' to mount it.  You can also press A & Pause/Break to mount an
ADFS disc.

ADFS is also supported in Model B and B Plus modes.  Note that in Model B
mode you will need to select the Acorn 1770 disc controller and add 
ADFS-1.30.rom to Roms.cfg.

You can find out more information about using discs by reading the DFS (Disc
Filing System) guides available on the internet.

WARNING - some of the disc images you will find on the Internet or that you
create yourself will have an invalid catalogue (they contain just enough
information for disc reads to work but not writes).

When you write enable a disc BeebEm for UNIX checks the disc catalogues and
it will display a warning message if either are invalid.  If you get a warning
message then do NOT write to the disc image, you will lose data.

To fix an invalid catalogue do the following:

1. Start BeebEm for UNIX and load the invalid image into drive 1.

2. Create a new disc image file in drive 0.

3. If the invalid image uses a Watford DFS 62 file catalogue then
   format the new disc image with a 62 file catalogue (you need the
   Watford DFS ROM installed), type:
     *ENABLE
     *FORM80 0

4. Copy all the files from the invalid disc to the new one and set the
   shift break option and title, type:
     *COPY 1 0 *.*
     *OPT4,3
     *TITLE <title>

The new image will now have a valid catalogue.  If you are using double
sided images then remember to format and copy both sides (the second sides
of disc 0 and 1 are 2 and 3).


SCSI & SASI Disk Support
------------------------

BeebEm for UNIX supports emulated SCSI and SASI hard disks.  There are 4
10MB pre-formatted ADFS SCSI disk images in the /share/beebem/media/scsi
sub-directory in your user's home directory (the scsi?.dat files).  The
disks can be used in Model B (need to add ADFS-1.30.rom to Roms.cfg), B Plus
or Master 128 mode.  To use the disk images enable hard drive emulation on
the Devices menu and press A & Pause/Break to boot in ADFS mode (ignore the
error for drive 4 if in Master mode).  The hard disks then appear as drives
0 to 3.  Floppy disks can still be accessed as drives 4 and 5.

There are some demo tunes in scsi0.dat which you can listen to with the PLAY
program.

There is also the sasi0.dat file which is a Torch Z80 hard disc image (see
README_Z80.TXT).


Using Tape Images
-----------------

BeebEm for UNIX emulates a cassette recorder.  You can load a tape image
file using the Tapes menu in BeebEm for UNIX.  There is a sample tape image
in the share/beebem/media/tapes folder.

Some useful tape commands are:

  *TAPE             - Select tape filing system
  *CAT              - List files on the tape
  LOAD ""           - Load a BASIC program
  CHAIN ""          - Load and run a BASIC program
  SAVE "<file>"     - Save a BASIC program
  *RUN              - Load and run a binary program

Most tapes can be run by typing:

  *TAPE
  CH.""

if that does not work, rewind the tape and try:

  *TAPE
  *RUN

Tape loading can be quite slow so BeebEm for UNIX has menu options to
artificially speed up loading.  You can also use the speed menu to speed
up the whole emulation, which speeds up tape loading.


Econet Support
--------------

BeebEm for UNIX emulates an econet network.  This allows multiple instances
of BeebEm for UNIX to communicate with other.  Enable econet support from
the Devices menu in BeebEm for UNIX.

Each machine attached to an econet has a station number (between 1 and 254)
associated with it.  An econet may also have a file server attached to it
(special station number 254).

BeebEm for UNIX emulates an econet using IP datagrams.  Each station on the
network needs a unique IP address and port number combination.  Each
instance of BeebEm for UNIX needs to know the address and port number of the
other instances on the network, this information is configured in the
'Econet.cfg' file.

The default Econet.cfg file has been set up so that the first 5 instances of
BeebEm for UNIX run on a single machine will get allocated unique station
and port numbers.  The first instance will be allocated a station number 254
(file server) and next 4 will be allocated station numbers 101 to 104.  See
the notes in Econet.cfg for more details.

An econet file server enables a disk file system to be shared by all of the
stations on the network.  Acorn produced various versions of file server
software.  The level 1 and 2 file server software is included in disk images
with BeebEm for UNIX.  The server software must be run on station number
254.

To run the level 1 server, load the 'econet_level_1_utils.ssd' disk image
and run the file server by typing 'CH."FS"'.

You will be prompted for:
 - Number of files per user - enter 3
 - Manual configuration - enter Y
 - Directory for first station - enter A
 - Station number - enter 101
 - Directory for second station - enter B
 - Station number - enter 102
 - Directory for third station - just press enter

The file server will then start running and report that it is ready.

The level 2 server is a little more complicated to set up.  It requires the
6502 second processor support to be enabled and requires a special "master"
disk to be formatted (must be a double sided disk).  I suggest you read the
"The Econet Level 2 Fileserver Manager's Guide" (available here
http://www.bbcdocs.com/) if you want to set up a level 2 server.

To use the econet file system from a station you will need to have a ROM
installed that supports the econet file system (such as the Acorn DNFS ROM
installed in Model B mode).  To switch a station into econet file system
mode press N & Pause/Break.  The econet station number should be shown on
screen.  To switch without pressing the break key type '*NET'.  You can then
use commands such as *CAT, LOAD, SAVE and CHAIN to access files on the
server.

The econet emulation in BeebEm for UNIX is not perfect and is susceptible to
timing issues.  When a message is being sent between stations BeebEm for
UNIX waits for a short time for the econet to become free again before
sending the next message.  If the delay is too small messages can interfere
with each other and cause a "Net Error" to be reported.  If it is too long a
station can report "Line Jammed".  The waiting time is set by default to
100000 cycles (0.05s) but can be overridden by a command line option
'-EcoFF'.  If you see "Net Error" report try a '-EcoFF 500000', for "Line
Jammed" try '-EcoFF 50000'.


Master 512 Co Processor Support
-------------------------------
The software now supports the Master 512 Co-Processor board.

The Master 512 board was an add-on card to the BBC computers which allowed you
to run DOS Plus (based on CP/M but largely MS-DOS compatible) software. 
It was 80186 based, ran at 10 MHz came with 512K of RAM (or 1MB with third 
party upgrades) and connected to the BBC via the Tube interface.

You start the Master 512 by selecting 80186 Second Processor off the Devices
menu. This will boot off a 10MB hard disc image (ADFS Drive 0) which comes
pre-installed with the original DOS Plus system and the GEM application software.
The emulator will also recognise Drive A and B if a suitable DOS Plus formatted
disc is loaded. The emulator should recognise various disc formats (look at
the DISK program for more info) but I would only recommend using 640K ADFS .adl
format and 800K DOS Plus .img format discs.

GEM can be started by typing 'GEM' from the command prompt. GEM uses the AMX
mouse support which must be enabled for the mouse to work. I would recommend you
start GEM first then enable AMX Mouse support afterwards. Please note that mouse
support works but due to the acceleration factors built into the GEM driver, 
mouse movement can be a bit erratic. I hope to improve this in future versions 
of the emulator.

The Master 512 should run most MS-DOS 2.1 compatible software but no guarantees
are given for what will and what won't work.

I will start a library of known good disc images at :

http://www.g7jjf.com/512_disc_images.htm

Please feel free to send me any more you know work with the Master 512.


Acorn Z80 Co Processor Support
------------------------------
The software now supports the Acorn Z80 Co-Processor board.

The Acorn Z80 was a CP/M based system running with 64KB RAM on a Z80
processor.

You start the Acorn Z80 by selecting Acorn Z80 Co-Processor off the Devices
menu. If you load a CP/M system disc in drive 0, the system will then boot
to an A: prompt.

I have included a CP/M Utilities disc in the installation which will boot
the system. The Acorn Z80 originally came with 7 discs which can be download
from my web site at :

http://www.g7jjf.com/acornz80_disc_images.htm

These discs contain the Acorn Z80 application software including :

CPM Utilities
BBC Basic
Mallard Basic
CIS Cobol
MemoPlan
GraphPlan
FilePlan
Accountant
Nucleus

You will also find some manuals for this software on my site as well.

The Acorn Z80 should also run most CP/M compatible software but no guarantees
are given for what will and what won't work.

I will start a library of known good disc images at :

http://www.g7jjf.com/acornz80_disc_images.htm

Please feel free to send me any more you know work with the Acorn Z80.


Menu Options
------------

BeebEm UNIX Menu:

  About        - Show version number and date of BeebEm for UNIX.

  Reset        - "Power-On" reset for when a game crashes.

  Quit         - Quit BeebEm for UNIX.

  Fullscreen   - Switch to full screen mode.

  Okay         - Accept Preferences

System Menu:

  BBC Model           - Allows you to switch between the BBC Model B types
                        and Master 128 emulation.

  Model B Floppy Controller - Allows you to select the Model B disc hardware
                        emulation.  To use an alternative floppy disc 
                        controller (FDC) board you will need to use an
                        appropriate ROM (e.g. Acorn DFS2.26 for the Acorn 
                        1770 board).

  Undocumented Instructions - Some games use undocumented instructions so
                        try enabling the full set if something does not 
                        work.  Selecting documented instructions only may
                        speed BeebEm for UNIX up.

  Ignore Illegal Instructions - When disabled a dialog appears detailing
                                the opcode and program counter.

Sound Menu:

  Sound support  - Switch sound on or off.

  Exponential Volume - Enables an exponential volume scale.  Makes the 
                       sound output better.
                       
  Sound is low latency -  The audio support will allow a longer latency /
                          lag-time for sound effects to sync with the screen.

  Speech support - Switch text to speech generation on or off (see features
                   for visually impaired users below)

  Sound Effects  - Switches on the sound of the cassette motor and the
                   sound of tape software loading.

  44.1 kHz       - Sets the sound sample rate.  The higher it is the better
  22.05 kHz        the sound quality but the slower BeebEm for UNIX runs.
  11.025 kHz

  Full Volume    - Set the sound volume.
  High Volume
  Medium Volume
  Low Volume

Speed Menu:

  Real Time    - Runs BeebEm for UNIX at the same speed as a real BBC Micro.

  Emulator Speed - Runs BeebEm for UNIX at a fixed speed relative to a real
                   BBC Micro.  The frame rate may need to be reduced for the
                   higher speeds.

Devices Menu:

  65C02 Second Processor - Enables/disables the 65C02 second processor 
                        emulation.  Note that in Master 128 mode the second 
                        processor  may be disabled in the CMOS settings.
                        To enable it type this command and press 
                        break (F12):
                            *CONFIGURE TUBE

  Torch Z80 Second Processor - Enables/disables the Z80 second processor 
                        emulation.  See the README_Z80.TXT file for more
                        details.

  Acorn Z80 Second Processor - Enables/disables the Acorn Z80 second
                        processor emulation.

  Master 512 80186 - Enables/disables the Master 512 80186 Co-Processor.


  Econet active       - Switch Econet emulation on or off.  See the Econet 
                        section above for more details.

  Hard drives active  - Switch SCSI/SASI hard drive emulation on or off.
                        See the SCSI/SASI section above for more details.

  Microvetic Touch Screen active - Enable/disables touch screen support.

Keyboard Menu:

  Disabled

AMX Menu:

  On/Off          - Switch AMX mouse on or off.  Note that you may find the
                    AMX mouse easier to use if you reduce the BeebEm for
                    UNIX speed to 0.9 or 0.75 speed.

  L+R for Middle  - Simulates a middle button press when you press the left
                    and right buttons together.

  Map to 160x256  - Coordinate range to map the mouse position to.
  Map to 320x256    Pick the one that gives AMX mouse movements nearest to
  Map to 640x256    your normal mouse movements.

  Adjust +50%     - Percentage to increase or decrease the AMX map sizes.
  Adjust +30%       Pick the one that gives AMX mouse movements that are
  Adjust +10%       slightly greater than the corresponding normal mouse
  Adjust -10%       movements.  You can then match up the AMX and normal
  Adjust -30%       pointer positions by moving the normal pointer to the
  Adjust -50%       edges of the BeebEm for UNIX window.  This is easiest
                    to do in full screen mode.

Tapes Menu:

  Unlock tape         - Removed the lock flag from files as they are loaded.
                        This enables you to *LOAD a locked file.
  Tape speed          - Select the speed at which tape software loads and 
                        saves.
  Insert tape    - Load a tape image.  To load software off a tape type:
                   *TAPE
                   PAGE=&E00
                   CH.""
  Rewind tape         - Reset the tape position to the start.

Screen Menu:

  Grille Graphics      - When rendering 256 Beeb scanlines on 512 UNIX
                         scanlines, 1 x scanline represents the Beeb
                         scanline and the other is black.

  Grille Teletext      - see Grille Graphics

  Hide mouse pointer   - Show or hide the mouse cursor while it is over the
                         BeebEm for UNIX window (useful when using the AMX
                         mouse).

  Display FPS          - Show or hide the relative speed and the number of
                         frames per second.
                         
  LEDs are:            - The Beeb keyboard and disc (1770 only) LEDs can be 
                         shown at the bottom of the BeebEm for UNIX window.

  Busy-wait:           - When BeebEm for UNIX isn't busy doing stuff, it'll
                         release time back to the OS.  Some systems take too
                         long to return to BeebEm for UNIX again and the
                         emulator consequently runs too slowly, so the busy
                         wait allows you to waste time in an a loop, rather
                         than give time back to the OS.

  Monitor is:          - Selects the type of monitor to emulate.

  Fullscreen Resolution - Screen resolution to use in full screen mode.  The
                          higher resolutions may look better.

  Windowed Resolution  - Sets the window size.

ROM writes Menu:

  Allow ROM writes    - Enable/disable ROM writes for each ROM slot.
                        ROMs read at start-up are write protected by
                        default.  Some ROM software was supplied on 
                        small expansion boards that had some RAM on them.
                        These ROMs require write access in order to work.

Discs Menu:

  Select, load and run a disc - Loads a disc image into drive 0 and boots
                                (runs) it.

  Load state   - Load the state of BeebEm for UNIX.  Note that ROM data is
                 not saved so if you have changed the ROMs that are loaded
                 when BeebEm for UNIX starts (in Roms.cfg) then a restored
                 state may not work.  State files are put in the
                 'share/beebem/state' directory by default.

  Change disk in drive 0 - Load a disc image into drive 0 or 1.  Discs are
  Change disk in drive 1   write protected when loaded to prevent any
                           accidental data loss.  Boot a disc by pressing
                           Shift & Pause/Break.

  Create new disc image in drive 0 - Creates a new disc image in drive 0 or
  Create new disc image in drive 1   1.  Use the filetype field to select
                                     the type of disc image to create.  New
                                     disc images are write enabled when
                                     created.  The images have a standard 31
                                     file catalogue by default.  If you want 
                                     a 62 file catalogue (Watford DFS) then
                                     format the disc.

  Save state   - Save the state of BeebEm for UNIX.  This is useful for
                 saving your position in a game for example.  Note that ROM
                 data is not saved so if you have changed the ROMs that are
                 loaded when BeebEm for UNIX starts (in Roms.cfg) then a
                 restored state may not work.  State files are put in the
                 'share/beebem/state' directory by default.

  Disk 0: Read only - Toggles write protection for drive 0.  Keep discs
                      write protected unless you intend to write to them.
                      Also see the WARNING above in the 'Using Disc Images'
                      section.
  Eject Disk 0 - Ejects the disc image currently loaded.  The name of the
                 file currently loaded is shown.

  Disk 1: Read only - Toggles write protection for drive 1.  Keep discs
                      write protected unless you intend to write to them.
                      Also see the WARNING above in the 'Using Disc Images'
                      section.
  Eject Disk 1 - Ejects the disc image currently loaded.  The name of the
                 file currently loaded is shown.

  Save configuration - Saves the BeebEm for UNIX settings to the current
                       preferences file.  Settings include the selected 
                       menu options, window position and CMOS RAM contents.


Command Line Options
--------------------

The following command line options can be passed to BeebEm for UNIX:

  -EcoStn <Econet station number>
  -EcoFF <Econet flag fill timeout, see the econet section>
  <disk image file name>
  <tape file name>
  <state file name>
  
If a disk image or a state file name is passed to BeebEm for UNIX on the
command line it will be run automatically.  The name can include the full
path or it can just be the name of a file in the 'state/beebem/media/discs'
or 'share/beebem/state' directory.

If a tape image name is passed to BeebEm for UNIX on the command line it
will be loaded.  The name can include the full path or it can just be the
name of a file in the 'share/beebem/media/tapes' directory.


Emulated Hardware
-----------------

The hardware emulated by BeebEm for UNIX is that of a standard BBC Micro
Model B, a Model B with IntegraB board, Model B Plus or Master 128 with a
few small additions.  An optional 65C02 second processor is also emulated.
The emulation is near enough accurate to run most software.

Hardware common to all the Model B types and Master 128:

  74689 Sound chip with 3 tone channels and one noise channel.
  uPD7002 Analogue to Digital Converter
  32K RAM
  6845 Cathode Ray Tube Controller (CRTC)
  Acorn proprietary VIDPROC (Video Processor)
  SAA5050 Teletext generator
  System and User 6522 Versatile Interface Adaptors (VIAs)
  "IC32" Addressable latch
  Full BBC Micro keyboard
  ROMSELect Register
  6854 Advanced Data-Link Controller (Econet)

Model B Specific hardware:

  Full 6502 Processor with all undocumented opcodes
  Sixteen 16K Paged ROM banks, with Sideways RAM option
  16K OS ROM
  8271 Floppy Disc Controller

Model B Plus Specific hardware:

  Four 16K Sideways RAM banks
  16K B+ MOS ROM
  20K Video Shadow RAM
  8K Filing System RAM
  4K Screen Operations RAM

Master 128 Specific hardware:

  65C12 Processor with all undocumented opcodes filled in with
    corresponding undocumented 6502 opcodes
  Seven 16K Paged ROMs
  Four 16K Sideways RAM banks
  16K MOS ROM
  20K Video Shadow RAM
  8K Filing System RAM
  4K Screen Operations RAM
  1770 Floppy Disc controller
  146818 Realtime Clock and CMOS RAM (50 bytes)
  ACCess CONtrol register

65C02 Second Processor:

  65C12 Processor
  64K on RAM
  2K boot ROM
  TUBE ULA chip

For information on the IntegraB see the documentation in the 'doc'
directory.


Troubleshooting
---------------

This version of BeebEm for UNIX will work on on most UNIX systems running
freedesktop.org's pkg-config, GTK+ 2.2 and Simple DirectMedia Layer (SDL)
1.2 or later.

Press F12 to access the configuration menu, and select 'Discs' then 'Save
configuration' to store your preferences.

If something goes wrong and you want to clear your user configuration, then
just delete '.beebem' in your home directory and all settings will be
recreated with default values.  (Backup your hard disk images first of
course!)

If you have any problems please email me and I'll try to help out:

  frutbunn AT gmail DOT com


Uninstalling BeebEm for UNIX
----------------------------

If you wish to uninstall BeebEm for UNIX then delete the bin/beebem binary
and the share/beebem directory from the directory you installed BeebEm for
UNIX in.

Your user configuration files are stored in $HOME/.beebem. Please
be aware that the SASI/SCSI hard disc images are quite large, so
if you remove BeebEm for UNIX, you may wish to delete this directory too.

All user specific configuration and hard disc images etc will be
lost of course!


Known Problems and Planned Future Development
---------------------------------------------

Current known problems with the emulator:

    * Keyboard mapping still needs work, and is QWERTY only.
    * Fullscreen FPS indicator does not work in lower resolutions.
    * When fullscreen/windowed view switches sometimes the GUI isn't
      repainted. (Press tab a few times).
    * Watch out for alert boxes displayed over the GUI, sometimes they
      don't standout!

Much of the BeebEm for Windows functionality has yet to be ported - such
as the Logical and User Defined Keyboard Mapping configuration options,
for example.

The video emulation needs most work.  All resolutions other than the 640x512
are a 'short term' botch!  The aim is to greatly improve performance of video
emulation (for SDL) - maybe even X-Video support (for X11)!

Amongst other things, BeebEm for UNIX also needs much better sound
integration (i.e.: done properly like the Windows version instead of the
current hack), a debugger and a native file selector to help finally remove
the GTK+ dependency.


Authors
-------

Thanks go to the following people for contributing to BeebEm for UNIX:

  David Gilbert
  Nigel Magnay
  Robert Schmidt
  Mike Wyatt
  Laurie Whiffen
  Richard Gellman
  Ken Lowe
  Jon Welch
  Rob O'Donnell
  David Eggleston

If there are any other features you would like to see in the UNIX version
of BeebEm then send me an email.  I cannot promise anything but I may find
some time to add them.

David Eggleston
frutbunn AT gmail DOT com
http://beebem-unix.bbcmicro.com/