     [file version.texi not included]

This manual is for XRoar (version Unknown), a Dragon and Tandy Colour Computer emulator.

Copyright © 2014 Ciaran Anscomb.

Introduction
************

XRoar is a Dragon emulator that runs on a wide variety of platforms.  Due to hardware similarities, XRoar also emulates the Tandy Colour Computer (CoCo) models 1 & 2.  Some features are:

  * Emulates Dragon 32, Dragon 64, Dragon 200-E, Tandy CoCo 1 & 2, and compatibles.

  * Emulates DragonDOS, Delta and RSDOS disk systems.

  * Emulates the Orchestra 90-CC stereo sound cartridge.

  * Supports both raw and translated keyboard modes.

  * Reads and writes virtual cassettes (compact .cas files and audio files).

  * Reads and writes VDK, JVC and DMK format virtual floppy diskettes.

  * Saves and loads machine snapshots.

  * Provides a GDB target for remote debugging.

XRoar was originally written to run on Solaris, Linux and the GP32 handheld. Later, it was ported to the Nintendo DS.  Support has now been dropped for the GP32 and NDS as emulation accuracy, and thus the CPU requirement, has increased.

XRoar is easily built from source under Linux, and binary packages are provided for Mac OS X and Windows.

Getting started
***************

Installation & running
======================

Pre-built binary packages are available from the XRoar home page (http://www.6809.org.uk/xroar/).  If one is not available for your architecture, you will need to build from source.  XRoar should build and run on any POSIX-like system for which SDL is available.

You will also need BASIC ROM images---binary dumps of the firmware from an original machine.  The originals were part-written by Microsoft, so they are not distributed in the XRoar packages.

Mac OS X binary package
-----------------------

Download the appropriate .dmg image for your system.  Open the image and drag the application icon to /Applications/.

For troubleshooting or testing options, it's often a good idea to run from the command line, but application packages don't make that trivial.  A symbolic link to somewhere in your PATH is all that's required.  e.g.:

     $ sudo ln -s /Applications/XRoar.app/Contents/MacOS/xroar \
             /usr/local/bin/xroar

After this, you can start the emulator by simply typing xroar followed by any command line options.

ROM images should be placed in a directory you create under your HOME named ~/Library/XRoar/roms/ (not the system directory, /Library/. Name any configuration file you create ~/Library/XRoar/xroar.conf.

The Mac OS X build provides a menu for access to certain features, and often accepts the more familiar Command+KEY in place of the Ctrl+KEY shortcuts listed in this manual.

Windows binary package
----------------------

Download and unzip the appropriate .zip distribution for your system. The easiest way forward is to simply run it from this directory.

Copy ROM images to the same directory, and if you create a configuration file, simply name if xroar.conf and put it in the same directory.

Note when troubleshooting that the Windows packages are built using MinGW (http://www.mingw.org/) (Minimalist GNU for Windows), and instead of printing to the console, useful information will end up in files called stdout.txt or stderr.txt.

The Windows build provides menu-based access to certain features.

Building from source
====================

Dependencies
------------

If there is no binary package for your system, you will have to build from source.  XRoar can use various backend toolkits, and you will need to ensure you have their development files installed.  If you're using Debian, this can (at the time of writing) be achieved with the following simple command:

     $ sudo apt-get install build-essential libsndfile1-dev libgtk2.0-dev \
             libgtkglext1-dev libasound2-dev

Under Mac OS X, first be sure to install Apple's Xcode (https://developer.apple.com/xcode/) package.  The easiest way to then ensure you have XRoar's dependencies available is to use a system like Homebrew (http://mxcl.github.com/homebrew/) or MacPorts (http://www.macports.org/).  For Homebrew, the following command will install the required dependencies:

     $ brew install libsndfile sdl

Otherwise, you'll have to do a bit of platform-specific research to ensure you have all the dependencies for a full build:

GTK+ (http://www.gtk.org/), the GIMP toolkit, provides the most full-featured user interface.  It is only usable as such if you also have GtkGlExt (http://projects.gnome.org/gtkglext/), an OpenGL extension used to provide video output.  Otherwise, it can provide a file requester for use by other user interfaces.

SDL (http://www.libsdl.org/), Simple Directmedia Layer, provides a slightly more basic user experience.  Menus are added using native code under Mac OS X and Windows; any other target using SDL will support only keyboard shortcuts.  Unless you are building for Linux, SDL is required to use joysticks.

Other supported audio APIs: OSS, ALSA, PulseAudio, CoreAudio.  Some other options are still in the code base, but have not been tested in a while.

libsndfile (http://www.mega-nerd.com/libsndfile/) is recommended to enable support for using audio files as cassette images.

Compilation
-----------

Once you have the dependencies, building XRoar follows a familiar procedure:

     $ gzip -dc xroar-Unknown.tar.gz | tar xvf -
     $ cd xroar-Unknown
     $ ./configure
     $ make
     $ sudo make install

The configure script has a lot of options guiding what it tests for, specifying cross-compilation, changing the install path, etc.  List them all with the --help option.  Be aware that this is a custom script, it is not generated by the GNU build system.

By default, configure will set up an install prefix of /usr/local, but this can be changed by using the --prefix=PATH option.

Once built, run make install as root (or use sudo, as in the example above) to install the binary and info documentation on your system. The executable is called xroar.  ROM images should be placed either in your home directory as ~/.xroar/roms/, or under the installation prefix as prefix/share/xroar/roms/.  Any configuration file should be created as ~/.xroar/xroar.conf.

XRoar can be built on one platform to run on another.  The Windows binary package is built like this.  To specify a cross-compile, use the --host=HOST argument to configure.  For example, to build for Windows, you might use ./configure --host=i686-w64-mingw32. Getting everything ``just so'' for a cross-build can be a tricky procedure, and the details are beyond the scope of this manual.

Running programs
================

Images of ROM cartridges, cassettes and disks can all be attached by pressing Ctrl+L.  Cassettes will be positioned at the beginning of the ``tape'' and disks will be inserted into Drive 1.

To attach an image and try to automatically start it, press Ctrl+Shift+L instead.  XRoar will try and start the program using the normal method for the type of image:

  * If a BASIC program is found on a cassette, XRoar types ``CLOAD'', waits for the program to load, then types ``RUN''.

  * For machine code programs on cassette, XRoar types ``CLOADM:EXEC''.

  * If a ROM cartridge is inserted, the emulated machine is power cycled.

  * If a disk image is autorun, XRoar types ``BOOT'' (Dragon) or ``DOS'' (CoCo).

If you have trouble with a program, refer to its loading instructions: it may require a different series of commands to get going.  If you still have issues, see Cartridges, Cassettes, or Disks.

The keyboard layout of modern machines is not identical to that of the Dragon, so XRoar provides two ways of working.  The default, ``untranslated'', is to map key positions as closely as possible (e.g., the key to the right of P maps to @).  Pressing Ctrl+Z toggles ``translated'' mode, which tries to map key symbols closely instead (e.g., pressing ' will press Shift+7 in the emulated machine).

In addition, a couple of keys aren't always available on modern keyboads, so Escape maps to the Dragon's BREAK key, and Home maps to CLEAR.  See Keyboard.

XRoar will make use of attached joysticks, but can also emulate them with the cursor keys and Left Alt.  Press Ctrl+J to cycle through three emulation modes: No joystick emulation (default), Right joystick, Left joystick.  See Joysticks.

Configuration file
==================

This manual details the options available for configuring XRoar.  Each option can be passed on the command line or placed in a configuration file called xroar.conf.  xroar.conf is read first, and any command line options then take precedence.  Directives are listed in xroar.conf one per line, and the leading dashes may be omitted.

The installation and compilation sections above list good default locations for xroar.conf, but it is actually searched for in a list of directories. You can override this search path with the XROAR_CONF_PATH environment variable, which contains a :-separated list of directories.  Here are the defaults:

Platform   Default XROAR_CONF_PATH
Unix/Linux   ~/.xroar:prefix/etc:prefix/share/xroar
Mac OS X   ~/Library/XRoar:~/.xroar:prefix/etc:prefix/share/xroar
Windows   :~/Local Settings/Application Data/XRoar:~/Application Data/XRoar

Note the leading : in the Windows default indicates an empty entry, meaning it will look in the current working directory first (i.e., you can put xroar.conf into the directory from which you run XRoar).

~ indicates the user's home directory: the HOME environment variable on Unix systems, or USERPROFILE on Windows.  prefix is the installation prefix, which is usually /usr/local.

To bypass the search path and start XRoar using a specific configuration file, pass -c FILENAME as the very first option to XRoar.

To print the complete current configuration to standard output (suitable for redirection to a config file), run with -config-print.  This will include all the built-in machine and cartridge definitions.

Hardware emulation
******************

Machines
========

With no other options, XRoar searches the ROM path and determines which supported machine has firmware ROM images are available.  It tries in this order: Dragon 64, Dragon 32, Tandy CoCo.  This can be overridden with the -default-machine NAME option.  XRoar has built-in configurations for the following machines:

Name   Description
dragon32   Dragon 32 (PAL).
dragon64   Dragon 64 (PAL).
dragon200e   Dragon 200-E (PAL).
tano   Tano Dragon (NTSC).
coco   Tandy Colour Computer (PAL).
cocous   Tandy Color Computer (NTSC).
mx1600   Dynacom MX-1600 (PAL-M).

You can create new machine configurations or reconfigure existing ones.  Select a machine configuration with -machine NAME, and use the following options to modify it:

-machine-desc NAME
     Description shown in -machine help.

-machine-arch ARCH
     Base machine architecture.  One of dragon64, dragon32 or coco.

-machine-cpu CPU
     Fitted CPU.  One of 6809 or 6309.  Hitachi 6309 support is not as well tested.

-bas ROM
     ROM image to use for Colour BASIC (CoCo only).

-extbas ROM
     ROM image to use for Extended BASIC.

-altbas ROM
     64K-mode Extended BASIC for Dragon 64 & Dragon 200-E.

-nobas
-noextbas
-noaltbas
     Indicate the corresponding ROM is not fitted in this machine.

-ext-charset ROM
     ROM image to use for external character generator.

-tv-type TYPE
     One of pal, ntsc or pal-m.  PAL-M support is not complete, and will instead be treated the same as NTSC.

-vdg-type TYPE
     Indicate the VDG variant fitted.  One of 6847 or 6847t1.

-ram KBYTES
     Amount of RAM fitted.

-machine-cart NAME
     Default cartridge to attach.  See Cartridges.

-nodos
     Indicate that XRoar is not to automatically attempt to attach a DOS cartridge to this machine (the default is to try).

For example, if the following lines were placed in your xroar.conf, a new machine could be selected with -default-machine pippin:

     machine pippin
     machine-desc Dragon Pippin (prototype)
     machine-arch dragon32
     ram 16

Cartridges
==========

The default cartridge for a machine is selected with the -machine-cart option.  XRoar has built-in definitions for four cartridges:

dragondos

     DragonDOS, official disk interface cartridge from Dragon Data Ltd.  Based on the WD2797 Floppy Disk Controller chip.

delta

     Delta System, Premier Microsystems' disk interface cartridge for the Dragon. Mk 2, based on the WD2791 controller.

rsdos

     RSDOS, Tandy's disk interface cartridge for use with the CoCo.  Based on the WD1793 controller.

orch90

     The Orchestra 90-CC cartridge provides stereo 8-bit audio output.  The default ROM is CoCo-only, but the hardware is compatible with the Dragon.

You can create new cartridge configurations or reconfigure existing ones. Select a cartridge configuration with -cart NAME, and use the following options to modify it:

-cart-desc TEXT

     Cartridge description shown in -cart help.

-cart-type TYPE

     Set cartridge base type.  One of rom, dragondos, delta, rsdos or orch90.

-cart-rom FILENAME

     The ROM image specified will be mapped from $C000.

-cart-rom2 FILENAME

     The ROM image specified will be mapped from $E000.

-cart-becker

     Enable becker port where supported.

-cart-autorun

     Auto-start cartridge using FIRQ.

Defining extra cartridges is most usefully done in the configuration file, for example:

     cart sdose6
     cart-desc SuperDOS E6
     cart-type dragondos
     cart-rom sdose6.rom
     cart-rom2 dosdream.rom

This will define a cartridge called sdose6 as a DragonDOS cartridge with its ROM replaced with sdose6.rom, and an additional ROM called dosdream.rom.

XRoar will automatically attempt to find a disk interface relevant to the current machine unless a specific default has been configured for the machine with -machine-cart, or automatic selection is disabled with the -nodos option.

Selecting a ROM image file with the -load or -run command line options, or with Ctrl+L or Ctrl+Shift+L, will attach a ROM cartridge.

Within the emulator, cartridges can be enabled or disabled by pressing Ctrl+E.  You will almost certainly want to follow this with a hard reset (Ctrl+Shift+R).

Becker port
-----------

XRoar supports an emulator-only feature that enables it to connect to a server using a TCP connection to access remote facilities such as disk images and MIDI devices---the ``becker port''.  This appears as a memory-mapped device, and XRoar supports it as an optional feature of the DOS cartridge.

Enable this port when configuring a cartridge with -cart-becker.  The -becker option tells XRoar to prefer a cartridge with it enabled when automatically selecting one.

The IP and port to connect to can be specified with the -becker-ip and -becker-port options.  These default to 127.0.0.1 and 65504 respectively, matching the defaults for DriveWire 4, the most popular server application used to provide such facilities.

Files
*****

In general, files can be attached on the command line with -load FILENAME, or by pressing Ctrl+L.  XRoar judges the type of file based on its extension.  To attempt to intelligently autorun a file, use -run FILENAME or press Ctrl+Shift+L. See Running programs for the methods XRoar will use to autorun a file.

Cassettes
=========

XRoar supports three types of cassette image:

Extension   Description
.cas
Cassette file.  Simple binary representation of data contained on a
tape.  Cannot represent silence, or some custom encodings.
.wav
Cassette audio file.  XRoar can read sampled audio from original
cassettes.
.bas, .asc
ASCII BASIC file.  XRoar will convert text on the fly into blocks suitable
for loading in ASCII mode.  Read-only.

To create a cassette image for writing (with the CSAVE or CSAVEM BASIC commands, for example), use the -tape-write FILENAME option, or press Ctrl+W.  Created files will be truncated to zero length, so be careful not to overwrite any existing files with this command.

The currently open tape files used for reading and writing are distinct.

The -tape-fast option accelerates tape loading by intercepting ROM calls.  Disable with -no-tape-fast.  On by default.

The -tape-rewrite option enables rewriting of anything read from the input tape to the output tape.  This is useful for creating ``well formed'' .cas files.

The remaining options affect how XRoar attempts to cope with bad tape images (images that, were they simply converted to audio files, would not load on a real Dragon):

The -tape-pad option tries to make loading more reliable by intercepting ROM calls and assuming extra leader bytes where appropriate. Disable with -no-tape-pad.

The -tape-pad-auto option will, for .cas files, automatically switch on leader padding when insufficient initial leader bytes are found at the beginning of the file, otherwise it is left alone.  Disable with -no-tape-pad-auto.  On by default.

Where available, these options can be changed on the fly in the GUI.

Disks
=====

If a disk interface cartridge is selected, XRoar supports virtual disks.  Three virtual disk formats are supported:

Extension   Description
.dmk
Disk image file in a format defined by David Keil.  They store a lot of
information about the structure of a disk and support both single and double
density data.  All disk images are manipulated internally in (near enough) this
format.
.jvc, .os9, .dsk
Disk image file in a basic sector-by-sector format with optional
header information.
.vdk
Another disk image file format, used by PC-Dragon.

To insert a disk into a particular drive, press Ctrl+[1-4].

When you attach a disk, it is read into memory, and subsequent disk operations are performed on this in-memory copy.  Write enable defaults to on (so write operations on the copy will work), but write back defaults to off, so updates will not be written to the disk image file.  To toggle write enable, press Ctrl+[5-8], where the number to press is the drive number plus 4.  To toggle write back, press Ctrl+Shift+[5-8].  Even with write back enabled, image files will not be updated until the disk in a virtual drive is changed, or you quit the emulator.

Where available, these options can also be changed on the fly in the GUI.

Write back can be set to default to on with the -disk-write-back command line option.

The JVC format specifies that the default number of sides in a headerless image is 1, but some disk images are distributed without headers that are double-sided.  These cannot normally be distinguished from a single-sided disk with double the number of tracks, but if an OS-9 filesystem is present, the information is contained within the first sector.  Because this information may be confused with other valid disk contents, the behaviour can be disabled with -no-disk-auto-os9.  Disk images with the extension .os9 without headers always ignore this option, however.

You can create a new blank disk in a virtual drive by pressing Ctrl+Shift+[1-4].  You will be a prompted for a filename, and the extension determines which type of file will be written.

ROM cartridges
==============

ROM cartridge images have a .rom or .ccc extension.  Because XRoar supports other types of cartridge, loading a ROM image actually just creates a cartridge instance of type rom.  See Cartridges.

Snapshots
=========

XRoar can save out a snapshot of the emulated machine state and read the snapshots back in later.  To save a snapshot, press Ctrl+S. When using Ctrl+L to load a file, anything ending in .sna will be recognised as a snapshot.

What is included in snapshots: Selected machine architecture, complete hardware state, current keyboard map, filenames of attached disk image files.

What is not (yet) included: Actual disk image data (only where to find it), attached cassettes or cartridge ROM contents.

Binary files
============

File types containing raw binary data to be loaded into RAM:

Extension   Description
.bin
Binary file (DragonDOS or CoCo).  XRoar can load these directly into memory
and optionally autorun them.  Read-only
.hex
Intel hex record.  An ASCII format that encodes binary data and
where in memory to load it.  Read-only

Firmware ROM images
===================

Firmware ROM image files are configured as part of a machine or a cartridge. They have an extension of .rom or .dgn, and can be specified as:

  * Complete path to a file.

  * Base filename of an image, to be discovered within a search path.

  * Base filename of an image, omitting the extension.  XRoar will search as above, appending the known ROM file extensions.

  * An @ character followed by the name of a ROM list.

A ROM list is a comma-separated list of images, each following the rules above. ROM lists may refer to other ROM lists.  Define a ROM list with -romlist NAME=IMAGE[,IMAGE]....  View the defined ROM lists with -romlist-print.

To make life easier, the default image for each type of machine or cartridge usually refers to a ROM list which contains all the corresponding filenames seen ``in the wild'':

Firmware ROM   ROM list   Canonical image names
Dragon 32 BASIC   @dragon32   d32
Dragon 64 32K BASIC   @dragon64   d64_1
Dragon 64 64K BASIC   @dragon64_alt   d64_2
Dragon 200-E 32K BASIC   @dragon200e   d200e_1
Dragon 200-E 64K BASIC   @dragon200e_alt   d200e_2
Dragon 200-E Charset  @dragon200e_charset   d200e_26
Tandy Colour BASIC   @coco   bas13, bas12, bas11, bas10
Tandy Extended BASIC   @coco_ext   extbas11, extbas10
DragonDOS   @dragondos_compat   dplus49b, sdose6, ddos40, cdos20
Delta System   @delta   delta
RS-DOS   @rsdos   disk11, disk10
RS-DOS with becker port   @rsdos_becker   hdbdw3bck
Orchestra 90-CC   orch90

The default search path for images specified only as a base filename varies by platform, and is detailed in Getting started.  This path can can be overridden with the option -rompath=PATH, where PATH is a colon-separated list of directories to search.  The path is parsed in the same manner as the configuration file search path (see Getting started).

The XROAR_ROM_PATH environment variable can also be used to specify the search path, but this behaviour is deprecated and may be removed in a future version.

A CRC32 value is calculated (and reported) for loaded ROM images.  XRoar uses these CRCs to determine automatically whether certain breakpoints can be used (e.g., for fast tape loading).  The lists of CRCs matched can be defined in a similar way to ROM lists using the -crclist LIST=CRC[,CRC]... option.  Each CRC is a 8-digit hex number preceeded by 0x, or the name of a nested list preceeded by @.  Use this if you have a modified version of a BASIC ROM that maintains compatible entry points with an original.  View the current lists with -crclist-print.

Sometimes it may be useful to force CRC matching so that breakpoints apply (e.g., you are modifying a ROM image and don't wish to have to add its CRC to the match list each time you modify it).  The -force-crc-match option forces the CRCs to be as if an original ROM image were loaded.

User interface
**************

User interface module
=====================

The user interface depends on supporting toolkit packages as described in Building from source.  Selection of user interface module may affect which other types of module are available: in particular, video output is strongly tied to the user interface.

-ui MODULE
     Select user-interface module.  -ui help to list compiled-in modules.

GTK+ user interface
-------------------

Select with -ui gtk2.

This is the most full-featured user interface.  It provides extensive dynamic menus, and control dialogues for cassette and disk files.  This is the preferred interface under Linux.

Only one video module is usable with this user interface: gtkgl.

SDL user interface
------------------

Select with -ui macosx (Mac OS X menus), -ui windows32 (Windows menus) or -ui sdl (no menus).

A more limited interface, still including an amount of menu-based control under Mac OS X and Windows.  Other actions require the use of XRoar's keyboard shortcuts.  Provides three video output modules: sdlgl (OpenGL, preferred), sdlyuv (YUV, often accelerated under X11) and sdl. -vo sdl is the least capable, but most compatible; try this if you are having problems with OpenGL.

Under Mac OS X, many operations are usable by pressing Command+KEY as well as the usual shortcut of Ctrl+KEY.

Video output
============

-vo MODULE

     Video output module to use.  Available modules depend on the selected user-interface module.  -vo help for a list.

-fs

     Start full-screen.  Toggle full-screen with Ctrl+F or F11.

-fskip FRAMES

     Specify frameskip.  Default is 0.  For slower machines.

-gl-filter FILTER

     Filtering method to use when scaling the screen.  One of linear, nearest or auto (the default).  OpenGL output modules only.

-invert-text

     Start up with inverted text mode.

-ccr RENDERER

     Cross-colour renderer.  Either simple (very fast) or 5bit (fast, more accurate).  Default is 5bit.

Real NTSC machines start in one of two cross-colour states at random.  Games often prompt the user to ``Press Enter if the screen is red'', for example. You can press Ctrl+A, to cycle through three modes: Off, Blue-red and Red-blue.

Inverted text mode may be toggled by pressing Ctrl+Shift+I.

Audio output
============

-ao MODULE

     Select audio output module.  -ao help for a list.

-ao-device DEVICE

     Module-specific device specifier.  e.g., /dev/dsp for OSS.

-ao-format FORMAT

     Specify audio sample format.  -ao-format help for a list.

-ao-rate HZ

     Specify audio frame rate, where supported.  The default is taken from the operating system if possible, otherwise it will usually be 48000.

-ao-channels N

     Specify number of channels (1 or 2).  Default is usually 2.

-ao-fragments N

     Specify number of audio fragments.

-ao-fragment-ms MS

     Specify audio fragment size in milliseconds.

-ao-fragment-frames FRAMES

     Specify audio buffer size in frames.

-ao-buffer-ms MS

     Specify total audio buffer size in milliseconds.

-ao-buffer-frames FRAMES

     Specify total audio buffer size in frames.

-fast-sound

     Slightly faster audio support by ignoring certain uncommon state changes.

-volume VOLUME

     Specify audio volume (0 - 100).

Audio latency is a concern for emulators, so XRoar allows the buffering characteristics to be configured with the fragment and buffer options above. Not all audio modules support all options, but setting the total audio buffer size will usually have an effect.  Bear in mind that any figures reported by XRoar reflect what it was able to request, and won't include any extra buffering introduced by the underlying sound system.

When the Orchestra 90-CC cartridge is attached, audio levels will be reduced due to the need to mix in a stereo output.

Keyboard
========

The default mapping of host keys to emulated keys is based on the original positions of the keys, with certain exceptions: cursor keys are mapped directly, Escape maps to the Dragon's BREAK key, and Home maps to CLEAR.  Other keys may also be mapped to CLEAR if there is a choice in your selected keymap that doesn't conflict with a regular character in translated mode.

For position-based mapping, XRoar needs to be informed of the layout of the host's keyboard.  If it is not the default (UK), use the -keymap CODE option.

XRoar can also be put into ``translated'' keyboard mode, where characters typed on a PC keyboard are translated into the equivalent keystrokes on the Dragon. Use the -kbd-translate option to default to this mode.  Press Ctrl+Z at any time to toggle between the two modes.

In translated mode, Shift+Enter is mapped to the Caps Lock combination (Shift+0 usually, Shift+Enter on the Dragon 200-E).  Similarly, Shift+Space is mapped to the ``pause output'' combination (Shift+@ usually, Shift+Space on the Dragon 200-E).

-keymap CODE
     Specify host keyboard layout.  -keymap help for a list.  Default is uk.

-kbd-translate
     Start up in ``translated'' keyboard mode.

-type STRING

     Intercept ROM calls to type STRING into BASIC on startup.

The keyboards of the Dragon, Dragon 200-E and Tandy CoCo operate in the same way, but the matrix and/or key layouts differ.  When you select a machine (see Machines), the appropriate layout is selected for you, but you can cycle between the three by pressing Ctrl+K.

XRoar will simulate the ``ghosting'' effects inherent in a simple matrix design, but the accuracy of this simulation will depend very much on your host keyboard, which vary greatly in the amount of simultaneous keypresses they support (for more information, search for ``NKRO'').

Joysticks
=========

XRoar supports attached joysticks, or can emulate them using the keyboard or mouse (``virtual joysticks'').  There are a few built-in configurations, or new ones can be defined.  Here are the built-ins:

Name   Description
joy0   First two axes and first two buttons of first physical joystick
joy1   First two axes and first two buttons of second physical joystick
kjoy0   Keyboard based virtual joystick using cursor keys and Left Alt.
mjoy0   Mouse based virtual joystick mapped to screen position

By default, joy0 (the first physical joystick) is mapped to the Dragon's right joystick port, and joy1 (the second physical joystick) to the left port.  Map different named joysticks with -joy-right NAME and -joy-left NAME.  Right and left joystick mapping can be easily swapped by pressing Ctrl+Shift+J.

A configured ``virtual joystick'' can be used by pressing Ctrl+J.  The first press substitutes it for the right joystick, the second press with the left joystick and a third press disables it again. The virtual joystick defaults to the keyboard-based kjoy0 described above, but can be reconfigured with -joy-virtual NAME.

A joystick configuration can be created or configured by selecting it by name with -joy NAME, and then configuring its axes with -joy-axis INDEX=SPEC and buttons with -joy-button INDEX=SPEC.  In each case, SPEC has the syntax INTERFACE:ARGS, with ARGS being a comma-separated list, the format of which is specific to INTERFACE:

Interface   Axis args   Button args
physical   JOYSTICK-INDEX,[-]AXIS-INDEX   JOYSTICK-INDEX,BUTTON-INDEX
keyboard   KEY-NAME0,KEY-NAME1   KEY-NAME
mouse   SCREEN-OFFSET0,SCREEN-OFFSET1   BUTTON-NUMBER

For physical joysticks a - before the axis index inverts the axis.  Key names for the keyboard interface depend on the underlying toolkit.  The default screen offsets for the mouse interface are X=2,254 and Y=1.5,190.5 which gives a nice spread.

Printing
========

XRoar supports redirecting the Dragon parallel printer output to a file or pipe with the -lp-file or -lp-pipe option.  Printed data will be sent to the appropriate stream.  Pressing Ctrl+Shift+P will flush the current stream by closing it (so if the stream is a pipe, the filter will complete).  The stream will be re-opened when any new data is sent.

The pipe feature allows you to use useful print filters such as enscript, e.g., -lp-pipe "enscript -B -N r -d printer-name".  This will send a job to your printer, using carriage returns as line feeds (the Dragon default), each time you press Ctrl+Shift+P (or exit the emulator).

-lp-file FILENAME
     Append printer output to FILENAME.

-lp-pipe COMMAND
     Pipe printer output to COMMAND.

Note that the CoCo uses a serial printer port.  As full serial support is yet to be added, a very limited form of print redirection is implemented for the CoCo using a ROM BASIC intercept.  This is enough to support BASIC commands like LLIST, but will not cope with programs implementing their own serial routines.

Debugging
=========

XRoar can act as a remote target for GDB using a network socket.  When GDB connects, emulation is stopped.  GDB can then inspect memory, instruct the target to set breakpoints and watchpoints (read, write and access), single step or continue execution.  A version of GDB patched to specifically support 6809 targets can also perform disassembly and inspect registers.  For more information on how to use GDB, see the GDB Documentation (http://www.gnu.org/software/gdb/documentation/).

Enable the GDB remote target with -gdb.  The default IP and port for the target are 127.0.0.1 and 65520.  These can be overridden with the -gdb-ip and -gdb-port options.

XRoar also supports a simpler ``trace mode'', where it will dump a disassembly of every instruction it executes to the console.  Toggle trace mode on or off with Ctrl+V.  Trace mode can be enabled from startup with the -trace option.

User-interface debugging flag can be enabled with -debug-ui VALUE, where only one value is currently supported:

0x0001
     Keyboard event debugging.

Hex & binary file debugging can be enabled with -debug-file VALUE, where the value is a bitwise ORing of the following:

0x0001
     Print summary information such as load or exec addresses.

0x0002
     Hex dump of all data read into memory.

Floppy controller debugging can be enabled with -debug-fdc VALUE, where the value is a bitwise ORing of the following:

0x0001
     Show FDC commands.

0x0002
     Show all FDC states.

0x0004
     Hex dump of read/write sector data.

0x0008
     Hex dump of becker port conversation data.

The GDB stub can also emit debug information about its own operation with -debug-gdb VALUE, where value is a bitwise ORing of:

0x0001
     Connection open and close.

0x0002
     Show packet data.

0x0004
     Checksum reporting.

0x0008
     Report on general queries.

The special value argument of -1 parses as ``all bits set'', and so enables all corresponding debug options.

XRoar prints various other informational messages to standard output by default, including when the state of certain toggles is modified.  Verbosity can be changed with the -verbose LEVEL option.  -quiet is equivalent to -verbose 0.  Levels are:

0
     Quiet.  Only warnings and errors printed.

1
     Print startup diagnostics and emulator state changes (default).

2
     Report some emulated machine state changes.

3
     Miscellaneous internal debugging.

XRoar can be told to exit after a number of (emulated) seconds with the -timeout SECONDS option.

Keyboard shortcuts
==================

A summary of commonly available shortcuts.

Ctrl+A
     Cycle through cross-colour video modes (hi-res only).

Ctrl+D
     Open disk control dialogue (GTK+ only).

Ctrl+E
     Toggle DOS emulation on/off - reset to take effect.

Ctrl+F, F11
     Toggle full screen mode.

Ctrl+Shift+H, Pause
     Toggles pause mode (HALTs the CPU).  As seen on the Dynacom MX-1600.

Ctrl+Shift+I
     Toggle text mode inverse video.

Ctrl+J
     Cycle through joystick emulation modes (None, Right, Left).

Ctrl+Shift+J
     Swap left and right joysticks.

Ctrl+K
     Cycle through Dragon, Dragon 200-E and CoCo keyboard layouts.

Ctrl+L
     Load a file (see below).

Ctrl+Shift+L
     Load a file and attempt to autorun it where appropriate.

Ctrl+M
     Cycle through emulated machine types (resets machine).

Ctrl+Shift+P
     Flush printer output.

Ctrl+Q
     Quit emulator.

Ctrl+R
     Soft reset emulated machine.

Ctrl+Shift+R
     Hard reset emulated machine.

Ctrl+S
     Save a snapshot.

Ctrl+T
     Open the tape control dialogue (GTK+ only).

Ctrl+V
     Toggle trace mode.

Ctrl+W
     Attach a virtual cassette file for writing.

Ctrl+Z
     Enable keyboard translation mode.

F12
     While held, the emulator will run at the maximum possible speed.

Shift+F12
     Toggle rate limiting.  Emulator will run at maximum speed until pressed again.

Troubleshooting
***************

Some commonly encountered issues:

  * I only see a checkerboard pattern of orange and inverse @ signs.

This probably indicates that XRoar could not locate any BASIC ROM images. Acquire some and put them in the directory appropriate to your platform.  XRoar tries to find ROMs for machines in the following order if you do not specify a default machine: Dragon 64, Dragon 32, CoCo.

Emulator with and without BASIC ROM
Figure: Emulator with and without BASIC ROM

  * A black window appears.  Commands typed blind appear to work.

This has cropped up a few times for people using Windows.

By default, XRoar tries to use OpenGL for its video output.  Windows versions even as late as Windows 7 have been reported to come with drivers that do not even support basic texture rendering (OpenGL Extension Viewer reports ``Max texture image units: 0'').  If this is the case, try running with the -vo sdl option, which should select an unaccelerated, non-scalable output.

  * This program is supposed to be in colour, but all I see is black & white.

Try pressing Ctrl+A one or more times.  What this really means is that you're used to running the program on an NTSC machine, and it makes use of cross-colour, but XRoar is emulating a PAL machine.  Try starting with -default-machine tano or -default-machine cocous.

Time Bandit, Dunlevy & Lafnear, 1983 in different artifact modes
Figure: Time Bandit, Dunlevy & Lafnear, 1983 in different artifact modes

Acknowledgements
****************

I made reference to the MAME 6809 core for clues on how the overflow bit in the condition code register was handled.

Thanks to all the people on the Dragon Archive Forums (http://archive.worldofdragon.org/phpBB3/) for helpful feedback and insight.

Darren Atkinson's Motorola 6809 and Hitachi 6309 Programmers Reference has been very useful for 6309 support and fleshing out some of the illegal instructions on the 6809.