XRoar Dragon Emulator Manual

Table of Contents

About this manual

This manual is for XRoar (version 1.0.2), a Dragon and Tandy 8-bit computer emulator.

XRoar 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 3 of the License, or (at your option) any later version.

XRoar 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, see <https://www.gnu.org/licenses/>.


1 Getting started


1.1 Introduction

XRoar emulates the Dragon 32/64; Tandy Colour Computers 1, 2 and 3; the Tandy MC-10; and some other similar machines or clones. It runs on a wide variety of platforms. Emulated hardware includes:

Other features include:

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

XRoar can also be compiled to WebAssembly, and redistributing it in this form may provide a convenient way for users to run your Dragon software. See XRoar Online for an example.


1.2 Notes for version 1.x

Version 1.x comes with support for two new emulated machines: the Tandy Colour Computer 3 and the Tandy MC-10. Some major changes have taken place under the hood, and although most things should remain familiar, for some special uses, here are the things you need to know.

Snapshots now store much more state, and of course support the new emulated machines, but this means the format had to change. Snapshots from the last 0.x release are still recognised, and can be loaded, but this support is likely to be removed in time.

The tape emulation now supports manual pause control. On the MC-10, this defaults to paused, as it has no ability to remotely control the tape motor. You will need to un-pause after typing CLOAD or CLOADM on the MC-10 (File → Cassette → Play, or from the tape control tool; autorunning will do this automatically).

Previously, the Glenside IDE controller would use a fixed HD image file in the current working directory called hd0.img. You must now specify an image with the -load-hd0 option. There is also the new ability to attach a second hard disk image with -load-hd1, if you have software that can access it.

Similarly, the NX32 and MOOH cartridges would use a fixed SD image file, and you must now specify it with the -load-sd option.


1.3 Prerequisites

After installing XRoar (see Installation), the first thing to do is make sure you have the firmware ROM images available for the system you wish to emulate. Without these, you will see rubbish on the screen (probably a checkerboard pattern, reflecting the initial state of RAM, see Troubleshooting).

These firmware images can be transferred from your original machine (with some effort, outside the scope of this document) or more likely found online on one of the archive websites. XRoar searches certain directories for these images, depending on platform, including (where ‘~’ indicates your "home directory"):

PlatformROM path
Unix/Linux~/.xroar/roms:prefix/share/xroar/roms
Windows:~/Documents/XRoar/roms:~/AppData/Local/XRoar/roms:
~/AppData/Roaming/XRoar/roms
Mac OS X~/Library/XRoar/roms:prefix/share/xroar/roms

Firmware ROM image files should have a .rom extension, and be headerless (so their file size will be an exact power of two bytes). For most use cases, you’ll need the BASIC ROM image(s) and a disk controller ROM image. Here are the expected filenames for the most common images:

Firmware ROMFilenameFile size
Dragon 32 BASICd32.rom16K (16384 bytes)
Dragon 64 32K BASICd64_1.rom16K
Dragon 64 64K BASICd64_2.rom16K
DragonDOSddos10.rom8K (8192 bytes)
Tandy Colour BASICbas13.rom8K
Tandy Extended BASICextbas11.rom8K
Tandy Super ECB (CoCo 3)coco3.rom32K (32768 bytes)
Tandy Super ECB (PAL CoCo 3)coco3p.rom32K
Tandy RS-DOSdisk11.rom8K
Tandy Microcolour BASIC (MC-10)mc10.rom8K

Other machines (in particular the less common Dragon 200-E) will need a different set of ROM images, and other supported peripherals may also need their own firmware.


1.4 User-interface introduction

With the prerequisites satisfied, on running XRoar you should now be presented with a window showing an emulated machine with a menu bar at the top showing (at least) File, View, Hardware and Tool menus. Mac OS users will see the menu bar at the top of the whole screen instead. There are often keyboard shortcuts for these, detailed throughout this manual and listed in Keyboard shortcuts.

You can put XRoar into fullscreen mode by selecting View → Full Screen, but you will notice that the menu bar disappears. To return to windowed mode, use the keyboard shortcut CTRL+F, or just F11. You can also toggle the menubar manually by pressing CTRL+M.

As you type, you may notice that certain keys don’t produce the character you pressed. This is because by default, XRoar tries to map keys such that they closely approximate their locations on the machine being emulated, so minus on a modern PC keyboard types colon in the emulated machine. This is good for playing games, where key placement is often important. Be aware that some keys don’t have useful equivalents on modern keyboards: for CLEAR, press HOME, or the backtick key; for BREAK, press ESCAPE.

You can tell XRoar to translate PC keys to emulated keypresses by selecting Tool → Keyboard Translation. For more about the keyboard, including mapping keys, see Keyboard.

XRoar supports real joysticks, and simulating joysticks with the keyboard or mouse. You can select which method is used for each of the emulated joysticks in the Hardware → Right Joystick and Hardware → Left Joystick menus. The Keyboard option maps the cursor keys to joystick directions1, with ALT and SUPER mapped to the first and second firebuttons respectively2. The Mouse option relates the pointer position within the window to a joystick’s floating position, with the left mouse button bound being the firebutton. Much of this can be configured, see Joysticks.

The Hardware menu also allows you to select which machine to emulate, and attach a cartridge to the running machine. If ROM images were found for it, you’ll probably see that a disk cartridge is already attached. Swapping cartridges ’live’ is not something you’d generally do on a real machine, and if you change the selection, you may need to select Hardware → Hard Reset to see the effect.


1.5 Running programs

XRoar tries to make running programs easy; after all, it’s probably why you installed an emulator in the first place. Select File → Run to open a file requester, and select the program media image; in the majority of cases, and so long as the program was intended for the machine you have selected, XRoar will "do the right thing" to try and start it.

As with much automation, we can’t foresee every eventuality, and sometimes you’ll have to launch the program manually. In this case, you can still simply attach the image (without autorunning it) by selecting File → Load, then follow the programs own instructions.

Here’s what XRoar tries to do with various types of media image. XRoar uses filename extensions to decide how to handle an image, so be sure to check that this is correct.

ROM cartridge images typically have a .rom extension (just like the firmware ROM images). XRoar will create and insert a ROM cartridge (it will appear in the list under Hardware → Cartridge) and, if autorunning, set it up to generate the autostart signalling and hard reset the emulated machine.

For cassette images (usually a .cas or .wav), XRoar will try to determine the type of the first program in the image, and autorunning will issue the ‘CLOAD’ or ‘CLOADM’ command accordingly, followed by ‘EXEC’ or ‘RUN’ as appropriate. See Cassettes.

The only standard way of autostarting the program on a disk image is through its boot sectors, so in this case XRoar will issue the ‘BOOT’ (Dragon) or ‘DOS’ (Tandy CoCo) command. These are the most likely to fail as many disk images do not have boot sectors: read the instructions for yours! Disk images can come in many formats, and the file extension is used to discriminate; the most common are VDK (.vdk extension) or JVC (.dsk extension). See Floppy disks.


1.6 Troubleshooting

1.6.1 No BASIC ROM

The most common issue when first using XRoar. You start the emulator and only see a checkerboard pattern of orange and inverse ‘@’ signs (or on the CoCo 3, some other pattern that’s not the usual copyright messages). This probably indicates that XRoar could not locate any BASIC ROM images. Acquire some and put them in the directory appropriate to your platform.

Emulator with and without BASIC ROM

Figure 1.1: Emulator with and without BASIC ROM

1.6.2 Program lacks colour

You remember a program being in colour, but all you see is black and white.

American software was often written to exploit cross-colour artefacts, where alternating patterns of black and white would "trick" the TV into displaying colour. XRoar supports this, and should enable it by default when you choose an NTSC machine. If you’re running an NTSC game on a PAL machine, you can still force XRoar to render the colours by selecting a cross-colour option from View → TV Input. There are also options that affect the fidelity of this rendering. See Video output for more details.

Time Bandit, Dunlevy & Lafnear, 1983 in different cross-colour modes

Figure 1.2: Time Bandit, Dunlevy & Lafnear, 1983 in different cross-colour modes

1.6.3 Can’t access HD/SD image

If you’ve been using previous versions of XRoar with the IDE, MOOH, or NX32 cartridges, you now need to specify the image filename with -load-hd0 (HD image for IDE) or -load-sd (SD image for NX32, MOOH).

1.6.4 Debug messages

XRoar prints diagnostic messages to standard output and standard error, and these may help narrow down a problem. You can increase their verbosity with various command-line options. See Debugging for more information.

Windows generally does not show these messages by default. but you can allocate a console by running XRoar from the command line and including -C as the very first option.


2 Configuration

XRoar can be configured by placing options into a configuration file, or by specifying options on the command line. The file is read first, then any command line options take precedence.

Many options may be preceded by ‘no-’ to invert their meaning or reset their value.

To print the 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. For a complete version including default values, use -config-print-all.


2.1 The configuration file

The configuration file is called xroar.conf. Good default locations for xroar.conf are listed in Installation, 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 colon-separated (‘:’) list of directories. Here are the defaults:

PlatformDefault XROAR_CONF_PATH
Unix/Linux~/.xroar:prefix/etc:prefix/share/xroar
Mac OS X~/Library/XRoar:~/.xroar:prefix/etc:prefix/share/xroar
Windows:~\Documents\XRoar:~\AppData\Local\XRoar:~\AppData\Roaming\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).

A leading tilde character (‘~’) 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 file as the very first option to XRoar.

Directives are listed in xroar.conf one per line. They contain an option, possibly followed by whitespace and a value. Trailing whitespace is ignored. Empty lines are skipped, and any line where the first non-whitespace character is a hash (‘#’) is treated as a comment. Options do not need their leading dash (‘-’) in the configuration file.

If a value contains special characters, or if you want trailing whitespace to be included in the value, you must escape those characters. Sections contained within pairs of single or double quotes are escaped, except the backslash (‘\’) which introduces an escape sequence:

SequenceDescription
\0Null (NUL), ASCII 0. Note that this is only permitted when not followed by another octal digit, as it may be confused with an octal byte, so it may be preferable to use ‘\x00’ instead.
\aBell (BEL), ASCII 7, no equivalent on the Dragon keyboard.
\bBackspace (BS), ASCII 8, LEFT.
\eEscape (ESC), ASCII 27, no equivalent on the Dragon keyboard, but mapped to BREAK by the -type option.
\fForm Feed (FF), ASCII 12, CLEAR.
\nNewline (NL), ASCII 10, DOWN. Not usually used by the Dragon as a line ending, instead try ‘\r’.
\rCarriage Return (CR), ASCII 13, ENTER.
\tHorizontal Tab (HT), ASCII 9, RIGHT.
\vVertical Tab (VT), ASCII 11, no equivalent on the Dragon keyboard.
\nnn8-bit byte with value specified as a three-digit octal number, nnn.
\xhh8-bit byte with value specified as a two-digit hexadecimal number, hh.
\uhhhh16-bit Unicode codepoint specified as a four-digit hexadecimal number, hhhh. Internally, this will be encoded as UTF-8.

Any other character following a backslash—including another backslash—is included verbatim. For example, this will be necessary in the configuration file under Windows when file paths include the backslash as a directory separator.


2.2 Command line options

On the command line, it is assumed that your shell will handle argument quoting, so any quote characters will be included verbatim. Escape sequences are still parsed, except when an option expects a filename, as shells often use their own escaping mechanisms when autocompleting filename arguments.


3 Machines


3.1 Machine profiles

XRoar creates a list of machine profiles from built-in and user-supplied configuration. One of these profiles is selected at startup, using either the -m name option (short for -default-machine name) on the command line, or by XRoar testing each profile in turn to see if its configured ROM image files are available.

Each machine profile has a base architecture (specified with the -machine-arch option). See Machines for details of the supported architectures, and which machine profiles are built-in.

-m name,
-default-machine name
Default machine profile to select on startup.
-machine nameCreate or modify named machine profile. The remaining options configure the profile. -machine help lists currently defined profiles.
   -machine-desc textDescription shown in -machine help and menu options.
   -machine-arch archBase machine architecture. See Machines for a list. ‘dragon32, dragon64, coco, coco3’ or ‘mc10’.
   -machine-keyboard typeOverride the type of keyboard attached to machine. ‘dragon, dragon200e, coco’ or ‘coco3’.
   -machine-cpu cpuFitted CPU. One of ‘6809’ or ‘6309’. Not applicable to the MC-10.
   -bas romROM image for Colour BASIC (CoCo) or Microcolour BASIC (MC-10).
   -extbas romROM image for Extended BASIC (Super Extended BASIC on the CoCo 3).
   -altbas romROM image for 64K-mode Extended BASIC (Dragon 64, Dragon 200-E).
   -no-bas,
   -no-extbas,
   -no-altbas
Indicate the corresponding ROM is not fitted in this machine.
   -ext-charset romROM image to use for external character generator.
   -tv-type typeOne of ‘pal’, ‘ntsc’ or ‘pal-m’. PAL-M is treated the same as NTSC, except with magenta-green cross-colour instead of blue-red (simulated composite rendering only at the moment).
   -tv-input inputOne of ‘cmp’ (composite video, no cross-colour), ‘cmp-br’ (composite video, blue-red cross-colour), ‘cmp-rb’ (composite video, red-blue cross-colour) or ‘rgb’ (RGB video, CoCo 3 only).
   -vdg-type typeIndicate the VDG variant fitted. One of ‘6847’ or ‘6847t1’.
   -ram kbytesAmount of RAM fitted in kilobytes. Valid sizes are 4-64K for Dragon and Tandy CoCo 1/2; 128K or 512K for the Tandy CoCo 3; 2K, 4K or 20K for the Tandy MC-10.
   -machine-cart nameDefault cartridge to attach.
   -no-machine-cartIndicate 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 -m pippin:

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

3.2 Machine architectures

XRoar supports several underlying machine architectures, and has one or more built-in machine profile configurations based on each one. See Machine profiles for more information on modifying or creating profiles. The rest of this section describes the available architectures.


3.2.1 Dragon 32

Released in 1982, the Dragon 32 closely follows Motorola’s reference design for the MC6809 CPU, MC6883 Synchronous Address Multiplexer and the MC6847 Video Display Generator. Dragon Data also chose to make it electrically compatible with some of Tandy’s peripherals for their Colour Computer; notably the joystick and cartridge ports. In addition, it has a parallel port, making it compatible with the majority of printers on the market at the time.

Architecture ‘dragon32’. Built-in machine profile ‘dragon32’.


3.2.2 Dragon 64

The Dragon 64 was released the next year, in 1983. In upped the on-board RAM to 64K and provided a reassembled version of Microsoft BASIC to make use of it. It also added a serial port, though that is not yet emulated by XRoar.

There are a few more changes to the motherboard than just extra RAM, so XRoar treats this as a separate architecture.

Architecture ‘dragon64’. Built-in machine profiles: ‘dragon64’, ‘tano’ (American NTSC version of Dragon 64 by Tano), ‘dragon200e’ (localised Spanish Dragon 64 from Eurohard).


3.2.3 Tandy Colour Computer 1/2

An earlier (1980) Tandy machine made using Motorola’s reference design, primarily marketed in the USA. Sold at many price points, with 4K (originally), 16K, 32K or 64K of RAM and either with or without Extended Colour BASIC. Later versions came with a new version of the VDG, the MC6847T1, which included true lowercase characters.

Architecture ‘coco’. Built-in machine profiles: ‘coco’, ‘cocous’ (NTSC), ‘coco2b’ (T1), ‘coco2bus’ (NTSC, T1), ‘mx1600’ (Mexican clone by Dynacom).


3.2.4 Tandy MC-10

Released in 1983, a little too late to compete with the Sinclair ZX-81, it was discontinued a year later. A cut-down machine based on the Motorola MC6803, but still using the MC6847 VDG and containing a version of Microsoft BASIC. Comes with 4K of RAM, but much of the small amount of software available for it assumes an additional 16K RAM pack.

Architecture ‘mc10’. Built-in machine profile ‘mc10’. XRoar’s MC-10 support is very new, and may contain more obvious errors.


3.2.5 Tandy Colour Computer 3

In 1986, Tandy released the Colour Computer 3. They had developed a custom chip, the TCC1014 (GIME), with VLSI to replace the SAM and VDG, and it supported extended graphics modes, more memory (up to 512K directly) and a timer function, along with somewhat better interrupt handling and the ability to run at twice the clock speed. A major development, it maintained a high degree of compatibility with its predecessors, losing some lesser-used (in the USA) graphics modes.

Note that the CoCo 3 generates different colours depending on whether you use the Composite Video or RGB outputs. The NTSC version defaults to assuming Composite Video, while the PAL version always used the RGB output from the GIME.

Architecture ‘coco3’. Built-in machine profiles: ‘coco3’ (NTSC), ‘coco3p’ (PAL). XRoar’s CoCo 3 support is very new, and may contain more obvious errors.


4 Cartridges


4.1 Cartridge profiles

Similarly, XRoar contains a list of cartridge profiles, each with an underlying type.

-cart nameCreate or modify named cartridge profile. -cart help lists currently defined profiles. The remaining options configure the profile.
   -cart-desc textCartridge description shown in -cart help and menu options.
   -cart-arch archCartridge architecture. See Cartridge types for a list.
   -cart-rom fileThe ROM image specified will be mapped from $C000.
   -cart-rom2 fileThe ROM image specified will be mapped from $E000.
   -cart-beckerEnable Becker port where supported.
   -cart-autorunAuto-start cartridge using FIRQ.

There are no cartridges usable with the MC-10 yet (the 16K expansion is technically a cartridge, but XRoar currently emulates that as though it were on-board).

Built-in cartridge profiles exists with sensible defaults for each of the cartridge types except ‘rom’ (for which a profile is simply created when you try to autorun a ROM image), each with the same name as the type.

Defining new cartridge profiles is most usefully done in the configuration file, for example:

cart mydos
  cart-desc "SuperDOS E6"
  cart-arch dragondos
  cart-rom sdose6.rom
  cart-rom2 dosdream.rom

This will define a cartridge called ‘mydos’ as a DragonDOS cartridge with its ROM replaced with sdose6.rom, and an additional ROM called dosdream.rom (this was my setup in the 80s - DOS Dream is a very useful ROM-based editor/assembler/deugger that coexists with DragonDOS - advert over).

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 -no-machine-cart 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).


4.2 Cartridge types

XRoar supports several types of cartridge, and has at least one built-in cartridge profile configurations for each one. See Cartridge profiles for more information on modifying or creating profiles. The rest of this section describes the available types.


4.2.1 DragonDOS

The official Dragon Data disk system for the Dragon. Supports 80 track, double sided, double-density floppy disks.

Emulation supports the Becker port mapped to $FF49/$FF4A, if enabled.

Type ‘dragondos’. Built-in cartridge profile ‘dragondos’.


4.2.2 Delta

Premier Microsystems’ alternative Dragon disk system. Apparently two versions of this may have existed; XRoar emulates the double-density version.

Type ‘delta’. Built-in cartridge profile ‘delta’.


4.2.3 RS-DOS

Tandy’s disk interface for the CoCo. Typically supports only 35-track single-sided double-density disks, though more is accessible using OS-9.

Emulation supports the Becker port.

Type ‘rsdos’. Built-in cartridge profile ‘rsdos’, ‘becker’ (with Becker port enabled, expecting hdbdw3bck.rom).


4.2.4 Glenside IDE controller

Interfaces the Tandy CoCo to up to two IDE hard disks. Its IO is generally memory mapped to addresses $FF50–$FF58. Also optionally supports the Becker port.

The controller supports up to two drives, and you can specify the image to use in each with -load-hd0 file or -load-hd1 file. If file does not exist, a 256MB empty image is created when the controller first tries to access it.

Sectors are 512 bytes, and while some software may use all 512, others only access 256 bytes per sector, padding the other 256 bytes (or simply doubling them up).

Type ‘ide’. Built-in cartridge profile ‘ide’.


4.2.5 NX32 and MOOH cartridges

Two memory expansion cartridges created by Tormod Volden for the Dragon. Both accept an SD card image. These images have no header information and contain 256-byte sectors.

The earlier NX32 provides simple bank switching, while the MOOH provides extensive MMU functionality very like that in the Tandy CoCo 3.

Types ‘nx32’, ‘mooh’. Built-in cartridge profiles: ‘nx32’, ‘mooh’. Both require fleshing out with ROM information, and an SD card image specified, e.g.:

cart mooh
  cart-rom sdbdos-eprom8-all-v1.rom

load-sd "~/xroar/sdcard.img"

4.2.6 Games Master Cartridge

The Games Master Cartridge (‘gmc’), created by John Linville, provides the ability to bank switch up to 64K of cartridge ROM, along with an on-board SN76489 sound chip.

This cartridge type is selected automatically (and configured to autostart) if you autorun a ROM image larger than 16K.

Type ‘gmc’. Built-in cartridge profile ‘gmc’ is configured with no ROM installed, and to not auto-start.


4.2.7 Orchestra 90-CC sound cartridge

A simple expansion that provides two 8-bit DACs for stereo sound (but still driven by the CPU). An on-board ROM for the CoCo provides an interface to composition, but if autorun is disabled, the hardware itself works fine on the Dragon.

Type ‘orch90’. Built-in cartridge profile ‘orch90’.


4.2.8 Multi-Pak Interface

The Multi-Pak Interface (‘mpi’) is a CoCo add-on by Tandy that allows up to four cartridges to be connected, selectable by software or hardware switch.

The RACE Computer Expansion Cage is a Dragon add-on by RACE similar to the MPI. Addressing and behaviour differs.

If you attach either Multi-Pak Interface (MPI), you’ll want to populate one or more of its slots (numbered 0-3). Use -mpi-load-cart [slot=]name to attach a named cartridge to the specified (or next) slot. Configure the initially selected slot with -mpi-slot slot.

It’s not recommended to load more than one DOS cartridge into the MPI. As things stand, only the last one (in slot order) will have the emulated drives properly connected.

Types ‘mpi’, ‘mpi-race’. Built-in cartridge profiles: ‘mpi’, ‘mpi-race’ (RACE variant).

machine coco
  machine-cart mpi

mpi-load-cart 0=orch90
mpi-load-cart 3=rsdos
mpi-slot 3

4.2.9 Becker port

Not a cartridge in and of itself, XRoar supports an emulator-only feature that enables it to connect to a server using a TCP connection and 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 many cartridge types.

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 pyDriveWire and DriveWire 4.


5 Storage media


5.1 Cassettes

Cassette tape was the primary method of loading software until floppy disk drives were available, and remained popular for games distribution even then as it served the largest market. Data is encoded onto cassette tape as audio, all currently-emulated machines using the same format, where a single cycle represents one bit of data, and its wavelength determines the bit’s value.

The Dragon and Tandy Colour Computers have a built-in cassette relay that can control the cassette motor remotely, but the MC-10 does not. After you type the appropriate load command on an MC-10, you will have to manually start the player.

XRoar supports tapes as raw sampled audio in WAV format (.wav), or in the more compact CAS format (.cas) which represents bits of data directly (files for the MC-10 are typically still CAS format, but with a .c10 extension; these will also work).

An extension to the CAS format called CUE is also supported. This comprises extra data at the end of the file that marks up the CAS file to indicate portions of silence, or the wavelength used for each bit. This enables it to better represent the structure of the original tape, support certain fast loaders, yet for data within the file to remain readable with a hex editor if it is correctly aligned.

XRoar can also attach BASIC ASCII text files (with .bas or .asc file extensions) and interpret them as cassettes, providing a useful way to edit these in your favourite text editor before loading into the emulator. Note: this feature is not supported by the MC-10.

The tape used for writing is considered separate to the read tape (this is an emulator-friendly approach to prevent overwriting your programs, though it would have been possible with two cassette decks).

Under Windows and Mac OS, the File → Cassette menu contains controls to insert or rewind the input and output tapes, play/pause and toggle options.

In the Unix/Linux GTK+ interface, these options are available from the tape control dialog, which you can open with Tool → Tape control or by pressing CTRL+T. This dialog will also show you the programs found on a cassette and allow you to double click them to seek to the appropriate position.

-load-tape fileAttach file as tape image for reading.
-tape-write fileOpen file for tape writing.
-tape-pan positionPan stereo input. Floating point number from ‘0.0’ (full left) to ‘1.0’ (full right). The default of ‘0.5’ mixes the two channels equally.
-tape-hysteresis pcRead hysteresis as percentage of full scale (default is 1%).
-no-tape-fastDisable fast tape loading. The default is enabled, which uses ROM intercepts to speed up loading.
-no-tape-pad-autoDisable automatic padding of short leaders in CAS files (see below).
-tape-ao-rate hzSet tape writing frame rate to hz (affects audio file output, e.g. WAV). Default: ‘9600’Hz.
-tape-rewriteEnable tape rewriting (see below).
-tape-rewrite-gap-ms msGap length in milliseconds to write in rewrite mode (1-5000ms, default 500ms).
-tape-rewrite-leader nLength of leaders in bytes to write in rewrite mode (1-2048 bytes, default 256).
-snap-motoroff fileWrite a snapshot to file each time the cassette motor is switched off.

Tape padding defaults to on, may be useful to disable with -no-tape-pad-auto if you are having trouble loading. A lot of old CAS tape images were created with their leaders truncated. This worked fine in emulators that fully intercepted the ROM to load them, but causes issues when converted to audio to play out to a real machine.

Tape rewriting, enabled with -tape-rewrite is a special mode where the ROM is intercepted, and anything read from the input tape is rewritten to the output tape. Custom loaders may defeat it, but otherwise this is a good way of creating a well-formed CAS file, with bytes aligned and consistent leader lengths.

The -snap-motoroff file option is useful for getting a dump of the machine state at the moment a program has finished loading, but before it has started executing. If you specify file with a .ram extension, you can get a simple RAM dump, viewable in a hex editor.


5.2 Floppy disks

Floppy disk drives provide much faster access to data than cassette tape. Initially costly, prices did fall somewhat, so these became a fairly common expansion.

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

-load-fdX fileLoad disk image file file into drive X (0–3).
-disk-write-backDefault to enabling write-back for disk images.
-no-disk-auto-os9Don’t try to detect headerless OS-9 JVC disk images.
-no-disk-auto-sdDon’t assume single density for 10 sector-per-track disks.

Under Windows and Mac OS, the File → Drive X menus allow you to insert or eject disks, create new disks, or toggle the write-enable and write-back options.

In the Unix/Linux GTK+ interface, these options are available from the disk control dialog, which you can open with Tool → Disk control or by pressing CTRL+D.

Note that RS-DOS for the Tandy Colour Computer numbers its drives from zero instead of one, so when you perform operations on Drive 1, from the CoCo’s point of view, that will be Drive 0.

-load-fdX fileLoad disk image file file into drive X (0–3).
-disk-write-backDefault to enabling write-back for disk images.
-no-disk-auto-os9Don’t try to detect headerless OS-9 JVC disk images.
-no-disk-auto-sdDon’t assume single density for 10 sector-per-track disks.

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 back to the disk image file. This default protects your files from being corrupted, but you can change the default behaviour to turn write back on with the -disk-write-back option.

Even with write-back enabled, disk images are not usually rewritten until they are ejected, changed, or you quit the emulator. However, you can force rewriting the image files at any time by pressing CTRL+SHIFT+D.

The JVC format specifies that the disk images without headers are single-sided, but some double-sided disk images have been made available without headers. These cannot normally be distinguished from a single-sided disk that happens to have twice the number of tracks. If an OS-9 filesystem is present, the identification sector is inspected to determine the correct disk structure. This step will always be performed for headerless images with the .os9 filename extension, but may be disabled for the other valid JVC filename extensions with -no-disk-auto-os9.


5.3 Hard disks

The Glenside IDE controller interfaces hard disks to the Tandy CoCo, and the MOOH and NX32 memory expansions can each provide access to an SD card.

Hard disk images consist of 512 bytes of header information, 512 bytes of IDENTIFY information, followed by sector data in LSN order, 512 bytes each. If an image does not exist when accessed, a 256MB image is created for you, as the header information may be difficult to construct otherwise.

SD images contain no header information, just sector data in LSN order, 256-bytes each.

-load-hdX fileUse file as the hard disk image for drive X (0 or 1).
-load-sd fileUse file as the SD card image.

6 Peripherals


6.1 Keyboard

-keymap codeSpecify host keyboard layout. -keymap help for a list. Default: ‘uk
-kbd-bind hkey=[pre:]dkeyBind host key hkey to emulated key dkey.
-kbd-translateStart up in translated keyboard mode.
-type stringIntercept ROM calls to type string into BASIC on startup.

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.

When binding keys with -kbd-bind, if the emulated key dkey is prefixed with "preempt:" or "pre:", this binding preempts translation; useful for modifier keys. Interpretation of hkey depends on which user-interface toolkit is in use, and it might be useful to run with -debug-ui 1 to see what the toolkit calls your host keys.

Special values for dkey are: ‘colon’, ‘semicolon’, ‘comma’, ‘minus’, ‘fullstop’, ‘period’, ‘dot’, ‘slash’, ‘at’, ‘up’, ‘down’, ‘left’, ‘right’, ‘space’, ‘enter’, ‘clear’, ‘break’, ‘escape’, ‘shift’, ‘alt’, ‘ctrl’, ‘control’, ‘f1’, ‘f2’.

For position-based mapping (untranslated), 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. This is basically the equivalent of a pre-rolled list of -kbd-bind options.

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+Return 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).

The keyboards of the Dragon and Tandy CoCo operate in the same way, but the matrix and/or key layouts differ. When you select a machine, the appropriate layout is selected for you, but you can toggle between them by pressing CTRL+K, which can sometimes be useful when running software designed for the other machine.

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”).


6.2 Joysticks

Analogue joysticks are very common peripherals for the Dragon and Tandy CoCo. Many games require them, and some productivity applications even use them as a mouse-like input device. Joysticks are electrically compatible between the machines, though some CoCo joysticks use a 6-pin DIN connector instead of 5-pin DIN, and these will not plug into the Dragon. On the CoCo 3, this extra pin can carry the signal for an extra firebutton.

XRoar can simulate these analogue joysticks using a variety of input methods. There are a few built-in joystick configuration profiles, or new ones can be defined. Here are the built-ins:

NameDescription
joy0First two axes and first two buttons of first physical joystick
joy1First two axes and first two buttons of second physical joystick
kjoy0Keyboard based virtual joystick using cursor keys and Left Alt.
mjoy0Mouse based virtual joystick mapped to screen position

If present, ‘joy0’ maps to the Dragon’s right joystick port, and ‘joy1’ to the left joystick port. You can specify different profiles to map with -joy-right name or -joy-left name. Select which joystick is mapped to each port at any time with the Hardware → Right joystick or Hardware → Left joystick menus. You can also swap the left and right joystick mappings by just pressing CTRL+SHIFT+J.

They keyboard-based virtual joystick can be quickly cycled through the ports by pressing CTRL+J. The first press will map it to the right joystick, the second to the left joystick instead, and pressing a third time unmaps it. You can change which virtual joystick is cycled in this way with the -joy-virtual name option.

The MC-10 has no built-in joystick ports, but an expansion (that can not be used at the same time as the 16K RAM expansion!) allows the connection of digital joysticks. These are not yet supported by XRoar.

-joy nameCreate or modify named joystick profile. -joy help lists currently defined profiles.
   -joy-desc textJoysticks description shown in -joy help.
   -joy-axis axis=input:[args]Configure joystick axis. -joy-axis help to list physical joysticks.
   -joy-button btn=input:[args]Configure joystick button. -joy-button help to list physical joysticks.
-joy-right nameMap right joystick.
-joy-left nameMap left joystick.
-joy-virtual nameSpecify the virtual joystick to cycle. Default: ‘kjoy0

The axis and button mapping options used while configuring a profile need some explaining.

Configure axes with -joy-axis axis=input:[args]. The axis is either ‘X’ or ‘Y’ (or numbered 0–1).

Configure buttons with -joy-button button=input:[args]. The button is either 0 (first button), or 1 (second button—only useful on the CoCo 3).

In both cases, the input selects a source for the input from the list below, and the args specify which one to use.

InputAxis argsButton args
physicaljoystick-index,[-]axis-indexjoystick-index,button-index
keyboardkey-name0,key-name1key-name
mousescreen-offset0,screen-offset1button-number

The ‘-’ before the axis index when configuring a physical joystick will invert that axis. Key names for the keyboard module depend on the underlying toolkit. The default screen offsets for the mouse module are ‘X=2,254’ and ‘Y=1.5,190.5’ which gives reasonable behaviour for some games and utilities.

To list the physical joysticks seen by XRoar, with the index numbers to use in the options above, specify either -joy-axis help or -joy-button help.

Joystick configuration is complex, but flexible. For example, you can combine input sources by specifying different modules for each axis. This configuration example creates a profile called ‘mixed’ that uses the mouse for the X-axis and firebutton, but the keys A and Z on the keyboard for the Y-axis. It then ensures this profile is the one used when you press CTRL+J.

joy mixed
  joy-axis X=mouse:
  joy-axis Y=keyboard:a,z
  joy-button mouse:

joy-virtual mixed

6.3 Printers

The Dragon machines have parallel printer ports, and XRoar supports these, sending output either to a file, or through a command pipe. The pipe approach allows you to apply a filter to the output, and/or send it to a real attached printer using normal Unix commands (SUB: check whether Windows users can do this sort of thing yet).

The CoCo and MC-10 machines have serial printer ports. XRoar doesn’t support these directly yet, but a limited form of print redirection is implemented 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.

-lp-file fileAppend printer output to file.
-lp-pipe commandPipe printer output to command.

Use the -lp-file file option to send printer output to a file, or -lp-pipe command to send it through a pipe. Pressing CTRL+SHIFT+P will flush the current stream by closing it, so if you are using a pipe, the filter will complete. The stream will be re-opened when any new data is sent.

Under Unix, the enscript utility is good for processing output and sending it to a configured printer, 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).


7 Files

-load fileLoad or attach file. XRoar will try to do the right thing based on the file type (usually determined by file extension).
-run fileAs -load, but try to autorun the file after attaching.
-load-tape fileAttach file as tape image for reading. See Cassettes.
-tape-write fileOpen file for tape writing. See Cassettes.
-load-fdX fileLoad disk image file file into drive X (0–3). See Floppy disks.
-load-hdX fileUse file as the hard disk image for drive X (0 or 1). See Hard disks.
-load-sd fileUse file as the SD card image. See Hard disks.
-lp-file fileAppend printer output to file. See Printers.

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

Cassettes, Floppy disks, and Hard disks are each discussed in Storage media. The other kinds of file recognised by XRoar are discussed here.


7.1 ROM cartridges

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


7.2 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.

Most internal state should be dumped to the snapshot. External data like ROM images or disk image files will be referenced by name, so when you read the snapshot back in, they need to exist in the same place they were before.

State that is explicitly not included in snapshots includes Becker port DriveWire connections and GDB listen parameters. These will use your local settings, which default to interacting with the local host only.

Note that the snapshot format has changed since version 0.37 to accommodate the new CoCo 3 and MC-10 support, along with other complex device state. The old snapshot format is deprecated, but can still be read for now.


7.3 Binary files

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

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

7.4 Firmware ROM images

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

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, the primary examples being:

Firmware ROMROM listCanonical image names
Dragon 32 BASIC@dragon32d32.rom
Dragon 64 32K BASIC@dragon64d64_1.rom
Dragon 64 64K BASIC@dragon64_altd64_2.rom
Dragon 200-E 32K BASIC@dragon200ed200e_1.rom
Dragon 200-E 64K BASIC@dragon200e_altd200e_2.rom
Dragon 200-E Charset@dragon200e_charsetd200e_26.rom
Tandy Colour BASIC@cocobas13.rom, bas12.rom, bas11.rom, bas10.rom
Tandy Extended BASIC@coco_extextbas11.rom, extbas10.rom
Tandy Super ECB (CoCo 3)@coco3coco3.rom
Tandy Super ECB (PAL CoCo 3)@coco3pcoco3p.rom
Tandy Microcolour BASIC@mc10mc10.rom
DragonDOS@dragondos_compatdplus49b.rom, sdose6.rom, ddos10.rom
Delta System@deltadelta.rom
RS-DOS@rsdosdisk11.rom, disk10.rom
RS-DOS with Becker port@rsdos_beckerhdbdw3bck.rom
Orchestra 90-CCorch90.rom

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 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 each ROM image loaded. XRoar uses these CRCs to determine 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 preceded by ‘0x’, or the name of a nested list preceded 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.


8 User interface


8.1 User interface selection

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 moduleSelect user-interface module. -ui help to list compiled-in modules.

8.1.1 GTK+ user interface

Select with -ui gtk2.

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

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


8.1.2 SDL user interface

Select with -ui sdl.

More limited than the GTK+ interface, providing keyboard shortcuts and, in the Mac OS X and Windows variants, some basic menus.

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


8.1.3 NULL user interface

Select with -ui null.

Show nothing! This can actually be useful when running XRoar from a script or, if you like, to act as a music player. To disable audio too, run with -ao null. XRoar will happily emulate a machine for you with nothing to show for it.


8.2 Video output

-fsStart full-screen. Toggle full-screen with CTRL+F or F11.
-fskip framesSpecify frameskip. Default is ‘0’. May be helpful on slower machines.
-gl-filter filterFiltering method to use when scaling the screen. One of ‘linear’, ‘nearest’ or ‘auto’ (the default). OpenGL output modules only.
-invert-textStart up with inverted text mode.
-ccr rendererComposite video cross-colour renderer. One of ‘simple’ (very fast), ‘5bit’ (fast, more accurate) or ‘simulated’ (slow, very 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. On the CoCo 3, a fourth mode is included that switches to the RGB output.

Inverted text mode may be toggled by pressing CTRL+SHIFT+I.


8.3 Audio output

-ao moduleSelect audio output module. -ao help for a list.
-ao-device deviceModule-specific device specifier. e.g. /dev/dsp for OSS.
-ao-format formatSpecify audio sample format. -ao-format help for a list.
-ao-rate hzSpecify audio frame rate, where supported. The default is taken from the operating system if possible, otherwise it will usually be ‘48000’.
-ao-channels nSpecify number of channels (1 or 2). Default is usually ‘2’.
-ao-fragments nSpecify number of audio fragments.
-ao-fragment-ms msSpecify audio fragment size in milliseconds.
-ao-fragment-frames nSpecify audio buffer size in frames.
-ao-buffer-ms msSpecify total audio buffer size in milliseconds.
-ao-buffer-frames nSpecify total audio buffer size in frames.
-ao-gain dbSpecify audio gain in dB relative to 0 dBFS. Only negative values really make sense here. Default: ‘-3.0
-volume volumeOlder way to specify volume. Simple linear scaling, using values 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, its stereo output needs to be mixed with the Dragon’s normal audio. To allow a small amount of headroom for this, the default gain is set to ‘-3.0’ (dB relative to full scale), but be aware that it would still be possible for this to clip depending on what’s happening on the internal sound bus. A setting of -ao-gain -9.0 would give plenty of headroom (at the expense of a quieter overall sound).


9 Debugging

-gdbEnable GDB target.
-gdb-ip addressAddress of interface for GDB target. Default: ‘127.0.0.1
-gdb-port portPort for GDB target to listen on. Default: ‘65520
-traceStart with trace mode on. CTRL+V toggles.
-debug-fdc flags
-debug-file flags
-debug-gdb flags
-debug-ui flags
Various per-subsystem debugging flags. The special value ‘-1’ enables all flags for the subsystem.
-v level
--verbose level
General debug verbosity (0–3). Default: ‘1
-q
--quiet
Equivalent to -verbose 0.
-timeout nExit emulator after running for n seconds.
-timeout-motoroff nExit emulator n seconds after cassette motor switches off, or end of tape reached.
-snap-motoroff fileWrite a snapshot to file each time the cassette motor switches off, or end of tape reached.

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.

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. Very useful when piped through less, as you can use simple text searches.

Note that GDB support is not currently implemented for the 6803 used by the MC-10, but trace mode is.

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

0x0001Keyboard event debugging.

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

0x0001Print summary information such as load or exec addresses.
0x0002Hex dump of all data read into memory.
0x0004Print filename block metadata when autorunning a tape.

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

0x0001Show FDC commands.
0x0002Show all FDC states.
0x0004Hex dump of read/write sector data.
0x0008Hex dump of Becker port conversation data.
0x0010General FDC event debugging.

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

0x0001Connection open and close.
0x0002Show packet data.
0x0004Checksum reporting.
0x0008Report 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:

0Quiet. Only warnings and errors printed.
1Print startup diagnostics and emulator state changes (default).
2Report some emulated machine state changes.
3Miscellaneous internal debugging.

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

XRoar can quit a number of seconds after the cassette motor is switched off with the -timeout-motoroff seconds option. This is useful in the case of automatic tape rewriting. A value of 1 is usually sufficient to account for the brief motor click that occurs after header blocks and during gapped loading.

Similarly, a snapshot can be automatically written after loading with the -snap-motoroff file option. The file is overwritten each time the motor transitions to off. This can be used to help analyse the machine state immediately after loading, before any autorun code has taken effect (specifying a .ram snapshot may be particularly useful here for analysis).

To see debug output from the pre-built Windows binary, run it with -C as the first option to allocate a console.


10 Acknowledgements

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

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.

Alan Cox contributed the IDE code.

Tormod Volden contributed support for his NX32 and MOOH devices (including general SPI and SD image support).

Various people have provided feedback or test cases that have helped nail down bugs; read the ChangeLog for details.

And thanks to all the people on the Dragon Archive Forums, CoCoTALK! Discord and IRC that have provided helpful feedback and insight.


Appendix A Installation


A.1 Binary packages

Pre-built binary packages are available from the XRoar home page. 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 version 2 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.


A.1.1 Mac OS X binary package

Download and unzip the appropriate .zip distribution for your system. 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.


A.1.2 Windows binary package

Download and unzip the appropriate .zip distribution for your system.

The easiest way forward is to simply put ROM images into the directory created when you unzip the distribution, and then run the .exe straight from there. You can also put any configuration file (xroar.conf) here.

However, if you want to avoid having to move files around each time you upgrade, you can create Documents/XRoar to contain your configuration file, and a subdirectory of that, Documents/XRoar/roms for ROM images.

Note when troubleshooting that the logging from the Windows binary is probably only going to be visible if you run it with the -C option (must be the first option) to allocate a console.

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


A.2 Building from source


A.2.1 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 install build-essential libsndfile1-dev libgtk2.0-dev \
        libgtkglext1-dev libasound2-dev

Under Mac OS X, first be sure to install Apple’s Xcode package. The easiest way to then ensure you have XRoar’s dependencies available is to use a system like Homebrew or MacPorts. For Homebrew, the following command will install the required dependencies:

$ brew install libsndfile sdl2

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

GTK+, the GIMP toolkit, provides the most full-featured user interface. It is only usable as such if you also have GtkGlExt, an OpenGL extension used to provide video output. Otherwise, it can provide a file requester for use by other user interfaces. Version 2 only.

SDL, 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. Version 2 required.

POSIX Regular Expressions are used in option parsing, so TRE is required on non-POSIX platforms (e.g. Windows).

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 is recommended to enable support for using audio files as cassette images.


A.2.2 Compilation

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

$ gzip -dc xroar-1.0.2.tar.gz | tar xvf -
$ cd xroar-1.0.2
$ ./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.

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.

XRoar can be built to a WebAssembly target using Emscripten. With the SDK installed, run emconfigure ./configure --enable-wasm to set up the build environment. Build with emmake make. HTML/JavaScript and CSS examples for interfacing to the output are included in the wasm/ subdirectory.


Appendix B Keyboard shortcuts

A summary of commonly available keyboard shortcuts.

CTRL+[1-4]Insert disk into drive 1–4.
CTRL+SHIFT+[1-4]Create new disk in drive 1–4.
CTRL+[5-8]Toggle write enable on disk in drive 1–4.
CTRL+SHIFT+[5-8]Toggle write back on disk in drive 1–4.
CTRL+ACycle through cross-colour modes (and RGB on CoCo 3).
CTRL+DOpen disk control tool (GTK+ only).
CTRL+SHIFT+DFlush disk images.
CTRL+EToggle cartridge on/off - reset to take effect.
CTRL+F
   or F11
Toggle full screen mode.
CTRL+SHIFT+H
   or PAUSE
Halt the CPU (not on the MC-10).
CTRL+SHIFT+IToggle text mode inverse video.
CTRL+JCycle through joystick emulation modes (None, Right, Left).
CTRL+SHIFT+JSwap left and right joysticks.
CTRL+KToggle Dragon/CoCo keyboard layout (not on the MC-10).
CTRL+LLoad a file.
CTRL+SHIFT+LLoad and attempt to autorun a file.
CTRL+MToggle menubar.
CTRL+SHIFT+PFlush printer output.
CTRL+QQuit emulator.
CTRL+RSoft reset emulated machine.
CTRL+SHIFT+RHard reset emulated machine.
CTRL+SSave a snapshot.
CTRL+TOpen the tape control tool (GTK+ only).
CTRL+VToggle trace mode.
CTRL+WAttach a virtual cassette file for writing.
CTRL+ZEnable keyboard translation mode.
F12Run at maximum speed while held.
SHIFT+F12Maximum speed toggle.

Appendix C File formats

XRoar recognises most file types by their file extension.

ExtensionDescription
.cas, .c10Compact cassette image. CUE data can optionally mark up silence and the wavelength to use for each bit.
.bas, .ascASCII BASIC files. XRoar will wrap the ASCII text in the appropriate file structure to present to the emulated machine as saved ASCII BASIC. Does not work on the MC-10. Read-only.
.wavStandard audio data file can be used as a cassette image.
.dmkDisk image file in a format defined by David Keil. These images store a lot of information about the structure of a disk and support both single and double density data.
.jvc, .os9, .dskDisk image file in a basic sector-by-sector format with optional header information.
.vdkAnother disk image file format, used by PC-Dragon.
.snaXRoar-specific snapshots preserve machine state. Old v1 snapshots can still be read, but writing a snapshot uses the new v2 format.
.ramWhen a .ram extension is given while writing a snapshot, a simple RAM dump is generated instead. Write-only.
.bin, .dgn, .ccoBinary file in DragonDOS or RS-DOS format (autodetected). Read-only. ,,
.hexIntel hex record. An ASCII format that encodes binary data and where in memory to load it. Read-only.
.rom, .cccROM image file. Simple binary dump of a ROM IC. Machine firmware images and ROM cartridge images are in this format. Read-only.

Appendix D Option list

Options may be specified in the configuration file, xroar.conf, or on the command line. The leading dash (‘-’) is not required in the configuration file.

Startup options
-CAllocate a console window to see debug messages (Windows-only).
-c fileSpecify a different configuration file.
-no-cDon’t read the configuration file.
-no-builtinDisable built-in configuration. Unless you also define a machine yourself, XRoar will abort.
MachinesSee Machines.
-m name,
-default-machine name
Default machine profile to select on startup.
-machine nameCreate or modify named machine profile. The remaining options configure the profile. -machine help lists currently defined profiles.
   -machine-desc textDescription shown in -machine help and menu options.
   -machine-arch archBase machine architecture. See Machines for a list. ‘dragon32, dragon64, coco, coco3’ or ‘mc10’.
   -machine-keyboard typeOverride the type of keyboard attached to machine. ‘dragon, dragon200e, coco’ or ‘coco3’.
   -machine-cpu cpuFitted CPU. One of ‘6809’ or ‘6309’. Not applicable to the MC-10.
   -bas romROM image for Colour BASIC (CoCo) or Microcolour BASIC (MC-10).
   -extbas romROM image for Extended BASIC (Super Extended BASIC on the CoCo 3).
   -altbas romROM image for 64K-mode Extended BASIC (Dragon 64, Dragon 200-E).
   -no-bas,
   -no-extbas,
   -no-altbas
Indicate the corresponding ROM is not fitted in this machine.
   -ext-charset romROM image to use for external character generator.
   -tv-type typeOne of ‘pal’, ‘ntsc’ or ‘pal-m’. PAL-M is treated the same as NTSC, except with magenta-green cross-colour instead of blue-red (simulated composite rendering only at the moment).
   -tv-input inputOne of ‘cmp’ (composite video, no cross-colour), ‘cmp-br’ (composite video, blue-red cross-colour), ‘cmp-rb’ (composite video, red-blue cross-colour) or ‘rgb’ (RGB video, CoCo 3 only).
   -vdg-type typeIndicate the VDG variant fitted. One of ‘6847’ or ‘6847t1’.
   -ram kbytesAmount of RAM fitted in kilobytes. Valid sizes are 4-64K for Dragon and Tandy CoCo 1/2; 128K or 512K for the Tandy CoCo 3; 2K, 4K or 20K for the Tandy MC-10.
   -machine-cart nameDefault cartridge to attach.
   -no-machine-cartIndicate that XRoar is not to automatically attempt to attach a DOS cartridge to this machine (the default is to try).
CartridgesSee Cartridges.
-cart nameCreate or modify named cartridge profile. -cart help lists currently defined profiles. The remaining options configure the profile.
   -cart-desc textCartridge description shown in -cart help and menu options.
   -cart-arch archCartridge architecture. See Cartridge types for a list.
   -cart-rom fileThe ROM image specified will be mapped from $C000.
   -cart-rom2 fileThe ROM image specified will be mapped from $E000.
   -cart-beckerEnable Becker port where supported.
   -cart-autorunAuto-start cartridge using FIRQ.
Multi-Pak InterfaceSee Multi-Pak Interface.
-mpi-slot slotInitially select slot (0–3).
-mpi-load-cart [slot]=nameInsert cartridge into next or numbered slot.
Becker portSee Becker port.
-beckerPrefer becker-enabled DOS cartridge when picked automatically.
-becker-ip addressAddress or hostname of DriveWire server. Default: ‘127.0.0.1
-becker-port portPort of DriveWire server. Default: ‘65504
CassettesSee Cassettes.
-load-tape fileAttach file as tape image for reading.
-tape-write fileOpen file for tape writing.
-tape-pan positionPan stereo input. Floating point number from ‘0.0’ (full left) to ‘1.0’ (full right). The default of ‘0.5’ mixes the two channels equally.
-tape-hysteresis pcRead hysteresis as percentage of full scale (default is 1%).
-no-tape-fastDisable fast tape loading. The default is enabled, which uses ROM intercepts to speed up loading.
-no-tape-pad-autoDisable automatic padding of short leaders in CAS files (see below).
-tape-ao-rate hzSet tape writing frame rate to hz (affects audio file output, e.g. WAV). Default: ‘9600’Hz.
-tape-rewriteEnable tape rewriting (see below).
-tape-rewrite-gap-ms msGap length in milliseconds to write in rewrite mode (1-5000ms, default 500ms).
-tape-rewrite-leader nLength of leaders in bytes to write in rewrite mode (1-2048 bytes, default 256).
-snap-motoroff fileWrite a snapshot to file each time the cassette motor is switched off.
Floppy disksSee Floppy disks.
-load-fdX fileLoad disk image file file into drive X (0–3).
-disk-write-backDefault to enabling write-back for disk images.
-no-disk-auto-os9Don’t try to detect headerless OS-9 JVC disk images.
-no-disk-auto-sdDon’t assume single density for 10 sector-per-track disks.
Hard disksSee Hard disks.
-load-hdX fileUse file as the hard disk image for drive X (0 or 1).
-load-sd fileUse file as the SD card image.
KeyboardSee Keyboard.
-keymap codeSpecify host keyboard layout. -keymap help for a list. Default: ‘uk
-kbd-bind hkey=[pre:]dkeyBind host key hkey to emulated key dkey.
-kbd-translateStart up in translated keyboard mode.
-type stringIntercept ROM calls to type string into BASIC on startup.
JoysticksSee Joysticks.
-joy nameCreate or modify named joystick profile. -joy help lists currently defined profiles.
   -joy-desc textJoysticks description shown in -joy help.
   -joy-axis axis=input:[args]Configure joystick axis. -joy-axis help to list physical joysticks.
   -joy-button btn=input:[args]Configure joystick button. -joy-button help to list physical joysticks.
-joy-right nameMap right joystick.
-joy-left nameMap left joystick.
-joy-virtual nameSpecify the virtual joystick to cycle. Default: ‘kjoy0
PrintersSee Printers.
-lp-file fileAppend printer output to file.
-lp-pipe commandPipe printer output to command.
FilesSee Files.
-load fileLoad or attach file. XRoar will try to do the right thing based on the file type (usually determined by file extension).
-run fileAs -load, but try to autorun the file after attaching.
-load-tape fileAttach file as tape image for reading. See Cassettes.
-tape-write fileOpen file for tape writing. See Cassettes.
-load-fdX fileLoad disk image file file into drive X (0–3). See Floppy disks.
-load-hdX fileUse file as the hard disk image for drive X (0 or 1). See Hard disks.
-load-sd fileUse file as the SD card image. See Hard disks.
-lp-file fileAppend printer output to file. See Printers.
Firmware ROM imagesSee Firmware ROM images.
-rompath pathSet ROM search path. A colon-separated list of directories.
-romlist name=listDefine a ROM list.
-romlist-printPrint defined ROM lists and exit.
-crclist name=listDefine a CRC list.
-crclist-printPrint defined CRC lists and exit.
-force-crc-matchForce per-architecture CRC matching.
User interfaceSee User interface selection.
-ui moduleSelect user-interface module. -ui help to list compiled-in modules.
Video outputSee Video output.
-fsStart full-screen. Toggle full-screen with CTRL+F or F11.
-fskip framesSpecify frameskip. Default is ‘0’. May be helpful on slower machines.
-gl-filter filterFiltering method to use when scaling the screen. One of ‘linear’, ‘nearest’ or ‘auto’ (the default). OpenGL output modules only.
-invert-textStart up with inverted text mode.
-ccr rendererComposite video cross-colour renderer. One of ‘simple’ (very fast), ‘5bit’ (fast, more accurate) or ‘simulated’ (slow, very accurate). Default is ‘5bit’.
Audio outputSee Audio output.
-ao moduleSelect audio output module. -ao help for a list.
-ao-device deviceModule-specific device specifier. e.g. /dev/dsp for OSS.
-ao-format formatSpecify audio sample format. -ao-format help for a list.
-ao-rate hzSpecify audio frame rate, where supported. The default is taken from the operating system if possible, otherwise it will usually be ‘48000’.
-ao-channels nSpecify number of channels (1 or 2). Default is usually ‘2’.
-ao-fragments nSpecify number of audio fragments.
-ao-fragment-ms msSpecify audio fragment size in milliseconds.
-ao-fragment-frames nSpecify audio buffer size in frames.
-ao-buffer-ms msSpecify total audio buffer size in milliseconds.
-ao-buffer-frames nSpecify total audio buffer size in frames.
-ao-gain dbSpecify audio gain in dB relative to 0 dBFS. Only negative values really make sense here. Default: ‘-3.0
-volume volumeOlder way to specify volume. Simple linear scaling, using values 0–100.
DebuggingSee Debugging.
-gdbEnable GDB target.
-gdb-ip addressAddress of interface for GDB target. Default: ‘127.0.0.1
-gdb-port portPort for GDB target to listen on. Default: ‘65520
-traceStart with trace mode on. CTRL+V toggles.
-debug-fdc flags
-debug-file flags
-debug-gdb flags
-debug-ui flags
Various per-subsystem debugging flags. The special value ‘-1’ enables all flags for the subsystem.
-v level
--verbose level
General debug verbosity (0–3). Default: ‘1
-q
--quiet
Equivalent to -verbose 0.
-timeout nExit emulator after running for n seconds.
-timeout-motoroff nExit emulator n seconds after cassette motor switches off, or end of tape reached.
-snap-motoroff fileWrite a snapshot to file each time the cassette motor switches off, or end of tape reached.
Help options
-config-printPrint configuration to standard out.
-config-print-allPrint configuration to standard out, including defaults.
-h, --helpPrint help text and exit.
-V, --versionPrint version information and exit.

In addition, various other options accept ‘help’ as an argument to print a list of values they accept.


Footnotes

(1)

While mapped as a joystick, the cursor keys won’t work as actual emulated keys.

(2)

The second firebutton is only useful on the CoCo 3.

(3)

If you have cloned the git repository, you will need GNU Build System packages installed: ‘autoconf’, etc. Running ./autogen.sh should then generate the configure script, which you can run as normal.