XRoar - a Dragon/Tandy Coco emulator
Copyright (C) 2003-2005 Ciaran Anscomb <xroar@6809.org.uk>


Homepage: http://www.6809.org.uk/dragon/xroar.shtml


The aim of this project is to develop a fully usable Dragon emulator for
Unix-like operating systems and the GP32 handheld device.  Because the
architecture of the Tandy CoCo 2 was very similar to the Dragon, it is
also possible to use it to emulate those machines too (the only major
differences are: ROM BASIC, keyboard layout).


ACKNOWLEDGEMENTS

The macros for manipulating the condition code register are based on
those used in the MAME 6809 core (in particular, those involved with
calculating the 'V' bit).

The Mac OS X 'Carbon' file requester code is based on a contribution by
Stuart Teasdale.

The rest is the result of reading too many datasheets.


COMPILING

To build, type 'make' on its own.  For supported native builds, this will
determine the host OS type and build appropriately.  Here are the supported
targets:

linux     - Linux target with OSS audio, OpenGL and Xv video.
solaris   - Solaris target with Sun audio and SDL video.
gp32      - Cross-compile to GP32 (ARM target).
macosx    - PowerPC Mac OS X target with OpenGL and CoreAudio support.
windows32 - Cross-compile for Windows.

The GP32 and Windows32 builds are cross-compiles and set TOOL_PREFIX, which
you can override if needed.  For example:
        make gp32 TOOL_PREFIX=arm-none-elf-
    or: make windows32 TOOL_PREFIX=i586-mingw32msvc-

When building more than one version, be sure to type 'make clean' in
between builds, or else object files will remain that have been compiled
for a different platform.


INSTALLATION

Unix: Copy the file 'xroar' to somewhere in your path.

GP32: Upload the file 'xroar.fxe' to gp:/gpmm/.  The ROM files, all
      cassette images, snapshots and disk images should be in
      gp:/gpmm/dragon/.

Windows: The file 'xroar.exe' needs to be run from the directory that
         contains your firmware ROMs.

You will need a copy of the Dragon or CoCo firmware ROMs.  If you don't
have the tools to transfer this from your original Dragon or CoCo, you
may find one somewhere on the web.  Although I personally think that
such ROMs should be freely available, the copyright holders may think
differently (and given that Microsoft wrote the BASIC ROM, it's quite
likely they do), so I don't feel comfortable offering them up myself.

If you want to use the virtual disk support, you will also need a DOS
firmware ROM.  Only the WD2797-based DragonDOS controllers are emulated.

Firmware ROMs can be either raw (".rom") or PC Dragon style (".dgn").
The base names to use for these files are:

Dragon 32               d32, dragon32                   (16K)
Dragon 64 ROM 1         d64_1, d64rom1                  (16K)
Dragon 64 ROM 2         d64_2, d64rom2                  (16K)
CoCo BASIC              bas13, bas12, bas11, bas10      (8K)
CoCo Extended BASIC     extbas11, extbas10              (8K)
CoCo Disk BASIC         disk11, disk10                  (8K)
DragonDOS               sdose6, ddos10                  (8K)

You can override the default ROMs using command line switches as
documented below.

On the GP32, firmware ROMs must be in gp:/gpmm/dragon/.  For other builds,
they should either be in the current working directory (only option for
Windows32) when running the emulator, or in one of these directories:

Mac OS X        ~/.xroar/roms or Library/XRoar/Roms (System or user directory)
Other Unix      ~/.xroar/roms or /usr/local/share/xroar/roms


COMMAND LINE SWITCHES

  -machine MACHINE      emulated machine [dragon32|dragon64|tano|coco]
  -bas FILENAME         specify BASIC ROM to use (CoCo only)
  -extbas FILENAME      specify Extended BASIC ROM to use
  -noextbas             disable Extended BASIC
  -dos FILENAME         specify DOS ROM (or CoCo Disk BASIC)
  -nodos                disable DOS (ROM and hardware emulation)
  -cart FILENAME        specify ROM to load into cartridge area ($C000-)
  -vo MODULE            specify video module (-vo help for a list)
  -fs                   request initial full-screen mode
  -ao MODULE            specify audio module (-ao help for a list)
  -ui MODULE            specify user-interface module (-ui help for a list)
  -snap FILENAME        load snapshot after initialising
  -h                    display this help and exit


UNIX CONTROLS

Full keyboard support plus:
Ctrl+[1-4] .... Insert a virtual disk into drive 1-4.
Ctrl+A ........ Cycle through artifacted video modes (hi-res only).
Ctrl+B ........ Load CoCo ".bin" binary file.
Ctrl+C ........ Quit emulator.
Ctrl+E ........ Toggle DOS emulation on/off - reset to take effect.
Ctrl+H ........ Load ".hex" Intel HEX-record.
Ctrl+J ........ Cycle through joystick emulation modes (None, Left, Right).
Ctrl+K ........ Toggle between Dragon and CoCo keyboard layout.
Ctrl+L ........ Load a snapshot.
Ctrl+M ........ Toggle between Dragon and CoCo emulation (resets machine).
Ctrl+R ........ Soft reset.
Ctrl+Shift+R .. Hard reset.
Ctrl+S ........ Save a snapshot.
Ctrl+T ........ Insert ".cas" virtual cassette.
Ctrl+Shift+T .. Insert virtual cassette and autoload first program.
Ctrl+Z ........ Enable keyboard translation mode.

In translation mode, characters typed on the host keyboard are translated
into the correct keypresses required on the emulated machine to achieve
the same character.

Joystick support is very basic and unconfigurable at the moment, and is
based on using a PS2 controller through a PS2-USB converter (although any
joystick supported by the OS should work).  Alternatively, use joystick
emulation (Ctrl+J) to simulate a joystick with the cursor keys, with
Left Alt as fire.


GP32 CONTROLS

The controller can be cycled through four modes by pressing the left
shoulder button.  These modes are:

 * KEYBOARD - D-pad selects a key, B presses a key, hold down right
              shoulder button to press shift.
 * CURSORS  - D-pad map to Dragon cursor keys.  B is shift, A is space,
              right shoulder button is enter.
 * RIGHT JOYSTICK - D-pad controls right joystick motion.  B is fire
              button.  A is space, right shoulder button is enter.
 * LEFT JOYSTICK - D-pad controls left joystick motion, with other
              controls as with right joystick mode.

At any time, pressing select will bring up a menu allowing you to load
a snapshot, toggle DOS emulation, insert a tape or disk, switch between
Dragon & CoCo, switch keymaps and reset the machine.  At present, there
is no way to save a snapshot, but you can generate them with the Unix
version and upload them.

If the tape is accessed (eg, you typed 'CLOADM' or 'CLOAD'), you need
to remember to insert a cassette file (".cas") from the menu.


CASSETTE IMAGES

Tools exist online to generate ".cas" cassette images, but they only
work under DOS (or presumably Windows).  Check the software section of
http://www.dragon-archive.co.uk/ for details.  That site also includes
quite a few titles that have already been converted for your convenience.
If you wish to play the game 'Buzzard Bait' (an excellent Joust clone),
you'll *have* to download the version there, because the original
required a dongle to be inserted, and obviously I don't emulate that.
Please note that site's usage requirements, and don't abuse the archive.


SNAPSHOTS

Snapshot files are *not* compatible with the traditional ".pak" files
used in other emulators.  I may support them in future, but the file
format looks pretty horrible.  This snapshot format is subject to change,
but a snapshot made in this release may well work fine in later ones.
At the moment, the most reliable way of loading programs is to use
cassette images or virtual disks, but if you have a Unix-like box,
you'll probably want to generate snapshots for your own convenience.


BUGS

Sub-line graphics mode changing now works, but shows up some slight
timing flaws.  Nifty effects in Rommel's Revenge or Dragonfire, for
example, will not be accurately represented.


COPYING

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

See the file 'COPYING' for the full terms.
