About this manual ¶

1.1 Recent changes ¶

Changes in version 1.7 include:

• SDL gamepad database reading with -joy-db-file.
• New evdev-based Linux joystick/gamepad support.
• Large changes to underlying UI mechanisms.

Previous changes in 1.x include:

Important: Floppy disk write-back is now enabled by default. Writes to images held in memory will overwrite the on-disk file when ejected (or quitting XRoar). You can get the old file-preserving default behaviour back with -no-disk-write-back.

RAM organisation selection with -ram-org, and initialisation pattern selection with -ram-init.

The -ccr simulated renderer is replaced with more CPU-intensive code that also handles PAL. The old NTSC-only renderer is still available using -ccr partial.

Larger or smaller picture area can be selected, and XRoar can stretch 60Hz output to reproduce the apparent aspect ratio seen on CRTs in those countries.

Many video options can be changed on the fly in a new TV Controls dialog.

Screenshots in PNG format can be saved if XRoar is built with libpng.

More machines are emulated than in 0.x. A new snapshot format that preserves more state was required to support these. Old snapshots should still load for now, though this will likely be removed in time.

Tape emulation now supports manual pause control, required for using the MC-10 & Alice, as they have no remote tape motor control.

HD/SD images are now specified with -load-hd0 and -load-hd1. IDE images with a header should be distinguished from headerless files by giving them a .ide extension.

MPI slot configuration is now per-cart rather than global.

2.1 Prerequisites ¶

To run XRoar, you will need to make sure you have the firmware ROM images available for the system you wish to emulate. These 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. Where XRoar looks to find these images depends on your host OS; the rest of this chapter will go into detail.

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 and sizes (in bytes) for some of the most commonly-required images:

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

2.2 Getting started under Linux/Unix ¶

If you configure a suitable Apt repository under Debian or Ubuntu, you should simply be able to apt install xroar (as root, or using sudo). See the XRoar homepage for links to an Apt repository for Debian, or to Launchpad for Ubuntu.

Otherwise, if you are comfortable building from source, see Building from source.

In your home directory, create directories ~/.xroar/ and ~/.xroar/roms/:

$ mkdir -p ~/.xroar/roms

Copy your firmware ROM images (Prerequisites) into ~/.xroar/roms/. For example, covering the most common machines, you might end up with a directory looking like this:

$ ls -l ~/.xroar/roms/
[...]
-rw-r--r-- 1 user group  8192 Jan  1  1982 bas13.rom
-rw-r--r-- 1 user group 32768 Jul 30  1986 coco3.rom
-rw-r--r-- 1 user group 32768 Jul 30  1986 coco3p.rom
-rw-r--r-- 1 user group 16384 Aug  1  1982 d32.rom
-rw-r--r-- 1 user group 16384 Aug  1  1983 d64_1.rom
-rw-r--r-- 1 user group 16384 Aug  1  1983 d64_2.rom
-rw-r--r-- 1 user group  8192 Jun  1  1983 ddos10.rom
-rw-r--r-- 1 user group  8192 Jan  1  1982 disk11.rom
-rw-r--r-- 1 user group  8192 Jan  1  1982 extbas11.rom
-rw-r--r-- 1 user group  8192 Oct  1  1983 mc10.rom

Start the emulator by typing xroar at the command line, or by selecting it from Applications → Games if your environment provides an applications menu.

Running xroar --help will display the supported command line options. Each of the command line options can also appear in a configuration file, which should be called ~/.xroar/xroar.conf. You can configure many defaults and even extra machines and cartridges in this file. See Configuring XRoar for more details.

2.3 Getting started under Windows ¶

The simplest way to get going under Windows is to unpack the .zip file and copy all your ROM images into the created subdirectory, alongside the executable. You can also create a configuration file here called xroar.conf. Double click xroar.exe to run, and XRoar will look in the same directory that you start it from, and everything should work.

However, if you want a more organised installation where you don’t have to re-copy files around every time you upgrade, read on.

In your user profile, there should exists a LocalAppData directory. This is something Windows calls a “Known Folder”. You should be able to browse to it by entering %LOCALAPPDATA% as a path in an explorer window. ¹

Under %LOCALAPPDATA%, create a subdirectory called XRoar. Then within that, create a further subdirectory named roms. You can then copy your ROM images into %LOCALAPPDATA%\XRoar\roms\.

Start the emulator by double clicking xroar.exe or, if you installed the .msi, by selecting XRoar from the start menu.

You can also run XRoar from the command line, and it supports the same options as under Linux/Unix. By default GUI applications under Windows have no access to a console, so run XRoar with -C as the very first option and it will first try to attach to the console of the parent process—that is, send text output to the shell window you have open—and if that fails, it will create its own console window. This lets you see various notifications that can be useful when determining why something isn’t working the way you expect.

For example, run xroar.exe -C --help to display a list of the supported command line options. Each of the command line options can also appear in a configuration file, which should be called %LOCALAPPDATA%\XRoar\xroar.conf. You can configure many defaults and even extra machines and cartridges in this file. See Configuring XRoar for more details.

2.4 Getting started under Mac OS X+ ¶

Download and unzip the appropriate .zip distribution for your system. Drag the application icon to /Applications/.

ROM images should be placed in a directory you create named ~/Library/XRoar/roms/ (under your HOME directory, not the system directory, /Library/).

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. It does not provide control dialog boxes; often, options in these dialogs will instead be found in the menu hierarchy.

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.

For example, run xroar --help to display a list of the supported command line options. Each of the command line options can also appear in a configuration file, which should be called ~/Library/XRoar/xroar.conf (under your HOME directory). You can configure many defaults and even extra machines and cartridges in this file. See Configuring XRoar for more details.

2.5 Building from source ¶

It is straightforward to build XRoar from source on any Unix-like OS so long as you have the normal build tools installed, and satisfy a few dependencies.

The binary packages for Windows are cross-compiled under Linux using MinGW; it may be possible to build natively using something like MSYS2 or Cygwin, but this is untested.

XRoar depends on external libraries for most aspects of its user interface:

• GTK+ 3 is recommended, and provides video, menus, and dialogs. It may be possible to use GTK+ under Mac OS X+, but this is untested. GTK+ 2 is deprecated, but still usable if you also have GtkGLExt installed.
• SDL 2 provides a simpler interface, but extra code for Mac OS X+ adds some basic menus and file requester dialogs. For non-Linux systems, it may also be the easiest way to get support for joysticks and audio.
• PulseAudio or ALSA can also be used for audio support. Older code still exists for OSS and Jack, but these have not been tested for a while.
• libpng is recommended, and allows the saving of screenshots in PNG format.

Under Debian, these dependencies can be satisfied with this simple invocation of Apt:

$ sudo apt install build-essential libgtk-3-dev \
                   libpulse-dev libpng-dev

XRoar uses the GNU Build System (Autotools), so the compilation process should be very familiar. The following process compiles XRoar and installs it into /usr/local, like most other software built this way:

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

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

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.

2.6 The command line ¶

Any option that can go in the configuration file can also be specified on the command line. Just be sure to prefix the option’s name with a dash (‘-’). See Configuring XRoar.

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.

Windows has a bit of an odd relationship with standard I/O, so in order to see diagnostic output or help text, you need to tell XRoar to attach to a console. Do this by specifying -C (capital ’c’) as the very first option.

As a special case, the last machine selected on the command line is used as the default machine, and the last cartridge specified is attached to that machine. This means you can just use -m name instead of -default-machine name, and -cart name instead of -machine-cart name.

2.7 Troubleshooting ¶

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

2.7.2 Program lacks colour ¶

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

American software is often written to exploit cross-colour artefacts, where alternating patterns of black and white will “trick” the TV into displaying colour. XRoar supports this, and should enable it by default when you choose an NTSC machine. See Composite rendering.

3.1 Selecting a machine ¶

The Hardware → Machine submenu allows you to select a different machine to emulate. XRoar will hard reset the new machine.

You can specify a default machine in xroar.conf:

default-machine dragon32

Finally, you can select a machine from the command line, e.g. xroar -m dragon32. Specify -m help for a list of profiles.

3.2 Selecting a cartridge ¶

The Hardware → Cartridge submenu lets you select a new cartridge to be attached to the currently-running machine. XRoar will not hard reset the machine, but it is usually advisable to do so, either by selecting Hardware → Hard Reset or by pressing CTRL+SHIFT+R.

You can specify a default cartridge for a machine in xroar.conf:

machine dragon64
  machine-cart mydos

And you can specify a cartridge on the command line, e.g. xroar -m dragon64 -cart mydos. Specifying -no-machine-cart will prevent the usual attempt to automatically find a disk controller cartridge for a machine. Specify -cart help for a list of profiles.

There are no cartridges usable with the MC-10/Alice yet (the 16K expansion is technically a cartridge, but XRoar currently emulates that specially).

3.3 Running programs ¶

XRoar tries to make quickly running simple programs easy. If you want to plug in a game cartridge, attach and load from a cassette image, or even run an unadorned DragonDOS or RS-DOS binary, just select File → Run or press CTRL+SHIFT+L. To attach media without trying to autorun a program, select File → Load or press CTRL+L. Alternatively, open one of the media control dialogs; see Cassette tape control or Floppy disk control.

From the command line, you can use -load file or -run file to achieve the same results. You can even simply specify a filename as the last option to try and run it:

xroar -m cocous daggorath.rom

XRoar will decide how to treat the file you select based on its extension:

.cas, .c10, .wav, .k7 

Cassette image. XRoar will attach the image as the input cassette and try and look for the first file on the tape. Depending on its type, it will automatically type ‘CLOADM’ (machine code) or ‘CLOAD’ followed by ‘RUN’ (BASIC). Some programs with special load instructions are recognised automatically.

.bas, .asc 

ASCII BASIC program. The Dragon (and Tandy Colour Computer) ROM has the ability to save and load BASIC in an untokenised form. It still requires saving as a series of short blocks though, so if you load one of these, XRoar will automatically simulate this format to load with ‘CLOAD’.

.rom, .ccc 

Cartridge image. XRoar will create and insert a ROM cartridge with this file as its ROM data. Some cartridges aren’t simple ROM images; XRoar can automatically recognise some of these and decide whether a Games Master Cartridge should be used, for example.

.vdk, .dsk, .jvc, .os9, .dmk 

Floppy disk image. XRoar will insert the floppy and type ‘BOOT’ (or ‘DOS’ under RS-DOS). If the result is ‘?BT ERROR’ (DragonDOS) or a clear screen (RS-DOS) and nothing else happening, that just means there was no boot track. You’ll have to follow the load instructions for the software in question, which vary too much for XRoar to have built-in rules for.

.bin 

A DragonDOS or RS-DOS binary file. XRoar will determine which type it is from the header and load it into RAM, then tell the CPU to jump to its start (EXEC) address.

In the case of floppy disk images in particular, there are many different formats, and sometimes you see files in one format with the file extension of another (e.g. just a generic .dsk, which XRoar will assume is a simple sector dump). If you have issues, do check your file extensions.

This is not an exhaustive list of the types of file XRoar can make use of, just the ones it knows how to automatically load programs from.

3.4 Cassette tape control ¶

Select File → Cassette tapes or press CTRL+T to open the cassette tape control dialog.

In this dialog you can insert a tape, eject the current tape, and control the cassette motor with play and pause controls. Note that for machines without motor control (MC-10, Alice), the tape will default to paused, and you will have to manually press play here after typing the load command.

In addition, you can rewind the tape or specifically set its position by dragging the scroll bar beneath the image filename. XRoar will also scan a tape file for Dragon programs, allowing you to double click a program filename to seek to it directly.

The input and output tapes can be managed separately - click on their tab names to move between them. While this isn’t a configuration that you’d often have in real life, it does make some uses of the emulator more convenient.

In the input tab, you can also see some tick boxes for setting emulator options:

Fast loading 

XRoar intercepts ROM calls to speed loading.

CAS padding 

XRoar automatically inserts extra leader if a CAS file doesn’t seem to have enough. This is common with early tape conversions.

Rewrite 

XRoar intercepts ROM calls to rewrite any data read from the input tape to the output tape in a sanitised format, with consistent leaders, gaps, and byte-aligned data. Useful for creating CAS files from WAV input, or even to regenerate a cleaner WAV file.

Under Mac OS X+, most functionality is found in the File → Cassette menu.

3.5 Floppy disk control ¶

Select File → Floppy disks or press CTRL+D to open the floppy disk control dialog.

In this dialog you can insert existing, create new, or eject floppy disk images from each of four emulated drives. Note that images are loaded into RAM; writes go to the in-RAM copy. The image is written back to the file when ejected (or you quit the emulator). The currently selected drive, track, and head are also displayed.

There are tick boxes per inserted disk to control emulator behaviour:

Write enable 

Basically the “write protect label” (or tab) on a floppy disk. Unticking this prevents the emulated system from writing to the disk.

Write back 

Unticking this box means that whatever changes are made to the in-RAM copy will not be written back to the floppy image file.

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.

Under Mac OS X+, floppy disk options can be found under per-drive submenus of the File menu.

3.6 Video options ¶

The View menu contains various video-related options. Zoom and Full screen are fairly self-explanatory. Inverse text simulates a common Dragon hardware modification to invert the colours only in text mode. The rest need a bit more explanation.

3.6.1 TV input ¶

The TV input menu lets you pick between various video signals from the emulated machine. “S-Video” is basically a palette-based output, reflecting the way an S-Video cable avoids cross-talk between the components of a video signal. “RGB” is only currently useful on the CoCo 3, which emits a completely different set of colours on its RGB port. The two “Composite” options employ a composite video renderer (see below), with two pixel-to-colour phase relationships; VDG-based systems tended to come up in one or the other at random, so this lets you pick the “other” one if a title expects it.

---

3.6.2 Composite rendering ¶

XRoar has a selection of composite renderers built in that trade off CPU time for accuracy in different ways to reproduce the artefacts of composite video.

None 

Disable all composite video effects. Output will be simple colours, the same as picking the “S-Video” TV input.

Simple (2-bit LUT) 

Gives a very course 4-colour rendition of NTSC artefact colours between black & white pixels only.

5-bit LUT 

A better set of NTSC artefact colours using a 5-bit LUT, but still only between black & white pixels.

Partial NTSC 

Performs a composite video encode/decode chain with filtering, taking lots of shortcuts. Pretty decent NTSC output, but doesn’t handle PAL.

Simulated 

Performs a more complete composite video encode/decode chain with filtering. This is the only renderer that will accurately reproduce PAL colour effects. It is also the most CPU-hungry.

---

3.6.3 TV controls ¶

Select View → TV controls or press CTRL+SHIFT+V to open the TV controls dialog. The dialog is divided into three sections. The first, Audio, only contains a gain control. The Video section has the following controls:

Brightness 

Or black level. 0–100, where 0 pulls everything to black, and 100 drives everything up to white, effectively adjusting the contrast of the picture.

Contrast 

Or gain. 0–100, with 50 meaning no gain. Scales the RGB output, affecting the overall brightness. See Charles Poynton on Brightness & Contrast for more on the labelling issue.

Colour 

Adjusts the saturation of colour without affecting the luminance. 0–100, where 0 yields a greyscale image.

Hue 

Adjusts the phase of a composite colour signal. -179–180, with the centre value of 0 being normal. A common control on NTSC displays. Not strictly necessary in an emulator, but it’s fun to spin it and watch the pretty colours.

Picture Area 

The picture area is the portion of the output signal that is rendered into the window, and this control lets you show more or less border around the active area (picking from four different crop regions).

60Hz Scaling 

When this is enabled, 60Hz output (NTSC, PAL-M) will be scaled vertically, to better represent the picture shape that would be seen on 60Hz CRTs. This scaling occurs because in a 60Hz TV system, fewer scanlines fill the same vertical space, yet the scanline duration is very similar.

Finally, the Composite Video section of the dialog includes more advanced control over the rendering when a composite signal is being simulated.

Renderer 

Another place to pick the composite renderer, described above.

F_S 

The video sample rate when using the “Simulated” renderer. The options here reflect the different crystals used as SAM oscillators in Dragons and CoCos.

F_SC 

The frequency of the colour subcarrier, either 4.43MHz (PAL-I) or 3.58MHz (NTSC, PAL-M). Together with F_S, this affects how the “Simulated” renderer tracks colour modulation and demodulation.

System 

The TV colour system in use, one of ‘PAL-I’ (e.g. UK), ‘PAL-M’ (e.g. Brazil) or ‘NTSC’ (e.g. USA or Canada). Setting only used by the “Simulated” renderer.

Colour Killer 

Television sets vary in how they react to a composite video signal that lacks a colourburst. The recommended approach is to disable colour processing and show a greyscale picture (to be backwards-compatible with black & white broadcasts), but many don’t bother and end up decoding luminance information as colour. This option lets you choose a behaviour.

---

3.7 Keyboard layout ¶

XRoar can operate in one of two keyboard modes. By default, it tries to map the key positions on the host keyboard to what you would expect using the emulated system. This is useful for games (where the relative physical positions of keys will be important), or to just satisfy muscle memory (even using an emulated Dragon, my hands expect to type in a certain way).

You can select a particular layout with Tool → Keyboard layout, though at time of writing, this doesn’t affect very much.

In translated mode (Tool → Keyboard translation, or CTRL+Z to toggle), XRoar instead tries to map the symbols on your host keyboard to the keystrokes required to produce that symbol on the emulated machine. For example, a UK PC keyboard typically has an unshifted apostrophe key, which XRoar can map to pressing SHIFT+7 on an emulated Dragon.

XRoar queries your operating system for information about which symbol is on which key, but in case it gets it wrong, you can pick from several built-in languages using Tool → Keyboard language.

3.8 Printer control ¶

Select File → Printer control or press CTRL+P to open the printer control dialog.

You can select between no printer, printing to file, or (only in the GTK+ interface under Linux/Unix), printing through a pipe to an external filter command.

When modifying the pipe configuration, your changes will not take effect until you press Apply.

The amount of characters printed since the last time the buffer was flushed is shown. Pressing the Flush button (or pressing CTRL+SHIFT+P) will flush output to file, or close and reopen the pipe. The act of closing the pipe will cause the running filter to complete, e.g. sending a job to your network printer.

4.1 Machine architectures ¶

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

4.2 Cartridge types ¶

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

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

load-hd0 "~/sdcard.img"

machine coco
  machine-cart mpi

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

4.3 Keyboard ¶

The Dragon keyboard (and those of all the machines XRoar emulates) is a typical crosspoint matrix with rows and columns connected to an internal interface. BASIC or other programs detect keypresses by strobing values to one port and seeing whether those values can be seen at another.

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 the terms “key rollover” or “NKRO”).

By default, XRoar maps host keys to emulated keys based on their position. By enabling keyboard translation (Tool → Keyboard translation or CTRL+Z to toggle), it will instead press the emulated keys required to generate the appropriate symbol. Be aware that this only works in BASIC; OS-9 uses different chords for some characters. Use the -kbd-translate option to default to this mode.

Where a PC keyboard doesn’t typically have a good equivalent of an emulated key, some substitutions are made: Escape maps to the Dragon’s BREAK key, and Home maps to CLEAR. Cursor keys are mapped directly, although they are in different places on a PC keyboard.

Sometimes software written for the Dragon or Tandy CoCo is run on the other machine without fully adapting it to the different keyboard matrix layouts. In this case, you can toggle to the “other” machine’s keyboard layout by pressing CTRL+K or selecting one from Hardware → Keyboard type.

See Keyboard for more details on configuring keyboard handling, including some options that may help if XRoar was unable to properly identify your host keyboard.

4.4 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 Dragon and CoCo 1/2/3, 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 use physical gamepads and joysticks, or simulate them using mouse or keyboard. Here are the built-in joystick profiles, including several different keyboard layouts for convenience:

In addition, XRoar should automatically detect attached gamepads or joysticks and add them as named profiles called ‘joy0’, ‘joy1’, etc. If the device is able to provide its own description, that will be included in the menu text. If a gamepad has two sticks, two more automatic profiles will be created, e.g. ‘joy0/l’ and ‘joy0/r’ so you can choose between them.

By default, XRoar will map the first physical joystick found (‘joy0’) to the right hand port, and the second (‘joy1’) to the left hand port. If only one device is present, but has two sticks, the left stick (‘joy0/l’) is mapped to the right hand port and vice-versa. Slightly confusing, but this is because people usually assume the left stick to be active, while the right hand port on a Dragon is the first in hardware, thus usually the “primary” control assumed by software.

A preselected 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, and pressing a third time unmaps it. You can change which virtual joystick is cycled in this way with the -joy-virtual name option, defaulting to ‘kjoy0’ from the table above.

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.

See Joysticks for information on configuring your own joystick profiles.

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

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.

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

5.1 Cassettes ¶

Cassette tape was the primary method of loading software until floppy disk drives became available, but has remained popular for games distribution even since, as it serves 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.

5.2 Floppy disks ¶

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

To use floppy disk images, an emulated disk controller will need to be configured. XRoar will usually try to do this automatically if it finds the appropriate ROMs for a disk controller suited to the machine you’ve chosen.

These floppy disk image formats are supported:

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.

XRoar supports these types of hard disk image:

IDE images with header information should have a .ide extension. This is necessary to distinguish them from images with no header. These images contain metadata describing an IDE drive, and are the only ones usable in CHS mode. Starting with 512 bytes of “magic” and 512 bytes of IDENTIFY DEVICE information, sector data follows in LSN order, 512 bytes per sector.

Raw images with 512 byte sectors should have a .img extension. Previous versions of XRoar would create IDE images with this file extension, and you should rename them to .ide. Unfortunately this is necessary to support raw images without a header: if you happened to write the “magic” identifying information to the start of it, any attempt to be clever about file contents would fail.

Finally, files with the .vhd extension are assumed to be 256 bytes per sector with no header information.

When no IDE metadata is present, XRoar will fake some up so that raw images can still be used with the IDE controller emulation. This means VHD images containing RSDOS filesystems are usable with YA-DOS or HDBDOS.

6.1 Startup options ¶

These may only be used on the command line, and must be specified before any other option, as they affect how the rest are treated.

6.2 Machines ¶

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 -default-machine name option, 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 Machine architectures for descriptions of the supported architectures, and which machine profiles are built-in.

Here is a configuration example, approximating the prototype that led to the Dragon 32:

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

‘pippin’ is the short name used to refer to the profile. The argument to machine-desc is the longer descriptive name that would appear in menus or help text. The rest of the section configures the new machine to have a base architecture the same as a Dragon 32, but with only 16K of RAM.

6.3 Cartridges ¶

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

Built-in cartridge profiles exist 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.

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

Here is an example profile, replicating the modified DragonDOS cartridge I used to use:

cart mydos
  cart-desc "My SuperDOS E6 Cart"
  cart-type dragondos
  cart-rom sdose6.rom
  cart-rom2 dosdream.rom

‘mydos’ is the short name used to refer to the profile. The argument to cart-desc is the longer descriptive name that would appear in menus or help text. The rest of the section defines a cartridge with DragonDOS hardware but with the DOS ROM replaced by sdose6.rom (SuperDOS E6, a common upgrade). The extra 8K of cartridge address space is used for dosdream.rom (DOS-Dream, an editor/assembler/debugger package designed to coexist with DragonDOS).

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

6.5 Cassettes ¶

Dragon cassettes are typically recorded in mono. If you are having trouble loading from an audio file recorded in stereo, it may be useful to pan it hard to the left or right with -tape-pan 0.0 or -tape-pan 1.0.

A small amount of hysteresis in the zero crossing detector simulates the same effect in hardware, and helps greatly with loading from some audio files. If you’re having difficulties with a recording, adjusting this valie with -tape-hysteresis may help.

Tape padding defaults to on: A lot of old CAS tape images were created with their leaders truncated, and this option tries to account for that automatically. It may be useful to try turning this option off (from the UI, or with -no-tape-pad-auto) if you are having trouble loading something.

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.

6.6 Floppy disks ¶

Warning: The default of write back being enabled can lead to accidental modification of your disk images. You can use the option -no-disk-write-back in your configuration file to protect them by default, though be aware that this also means anything “saved” to disk will be lost if you forget to re-enable it when required.

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.

6.7 Hard disks ¶

6.8 Keyboard ¶

Specifying a keyboard layout (-kbd-layout) doesn’t achieve much yet. In future, it may map certain extra keys from the Unix or JIS layouts to similarly positioned emulated keys.

The -kbd-translate option can be used to default to translated mode, where XRoar translates keypresses to reproduce the correct symbol in the emulated machine (only under BASIC; OS-9 uses different chords for some characters).

Specifying a keyboard language (-kbd-lang) overrides any key symbol mapping gleaned from the OS with a built-in table. If translated mode isn’t working well for you, this option may help. -kbd-lang help for a list.

When binding keys with -kbd-bind, if the emulated key ekey is prefixed with ‘preempt:’ or ‘pre:’, this binding preempts translation; useful for modifier keys. To get hkey names, run with -debug-ui 1 to enable keypress debugging and see what it reports as you type.

Special values for ekey 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’.

6.9 Joysticks ¶

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.

The ‘-’ before the axis index when configuring a physical joystick will invert that axis. 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. Those screen offsets are relative to a 256x192 active area (the dimensions were chosen when that was the only output), but will be scaled to the currently displayed active area.

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.9.1 Gamepad mapping ¶

Although there is an approximation of consensus on what sort of controls go where on modern gamepads, they still tend to report their inputs in different orders. SDL supports user-provided mappings of reported axes, buttons and hat inputs to a set of named controls, and XRoar can process a file containing these mappings one per line, even when not built using SDL (e.g. when using evdev under Linux). Point XRoar to such a file with the -joy-db-file option. At time of writing, SDL_GameControllerDB contains a comprehensive list of mappings.

This diagram shows the controls that can be mapped:

The short codes in this diagram correspond to these control names, used in SDL mapping database lines:

Input	Short	SDL	Input	Short	SDL
Axis 0	LX	leftx	Button 0	A	a
Axis 1	LY	lefty	Button 1	B	b
Axis 2	RX	rightx	Button 2	X	x
Axis 3	RY	righty	Button 3	Y	y
Axis 4	LT	lefttrigger	Button 4	BACK	back
Axis 5	RT	righttrigger	Button 5	GUIDE	guide
			Button 6	START	start
D-pad Left	DL	dpleft	Button 7	LB	leftstick
D-pad Right	DR	dpright	Button 8	RB	rightstick
D-pad Up	DU	dpup	Button 9	LS	leftshoulder
D-pad Down	DD	dpdown	Button 10	RS	rightshoulder

Using the evdev support under Linux, for gamepads, whatever is mapped to the D-pad acts as an alternative to axes 0 & 1. For joysticks, it provides an extra pair of axis controls.

---

6.10 Printers ¶

6.11 Files ¶

Many of these are mentioned in their appropriate section, but are collected here for reference.

6.12 Firmware ROM images ¶

6.13 User interface ¶

The pixel format, specified with -vo-pixel-fmt, defaults to RGBA with 8 bits per channel, but you may find other pixel layouts or lower bit depths render faster on your machine.

The default picture area is 640x480 (emulated) pixels, equivalent to -vo-picture title, which is enough to show normal VDG output with a reasonable border. You can change this to one of a set of defined areas: -vo-picture action and -vo-picture underscan show more of the picture, and may be more suitable when emulating a CoCo 3 which has some larger video modes. -vo-picture zoomed crops to 512x384; enough to show standard VDG output with no borders at all. CTRL+comma and CTRL+fullstop zoom the picture area out and in where supported.

By default, 60Hz video is scaled vertically to give a 1:1.2 pixel aspect ratio. This more closely approximates the look of a real CRT (fewer scanlines mean each scanline appears taller within the same aspect ratio overall display). This can be disabled with -no-vo-scale-60hz to return to more square pixels. 50Hz displays tend to yield near-enough-square pixels anyway.

Various levels of composite video rendering precision can be selected with -ccr, trading off CPU with accuracy. -ccr simulated is the only option that tackles PAL video. -ccr partial does pretty well for NTSC. -ccr 5bit and -ccr simple both use LUTs to convert sequences of black & white into NTSC cross-colour.

When the VDG is configured to generate black & white (resolution) graphics, it stops emitting a colourburst signal. Colour displays may (but not always) recognise the lack of burst and stop trying to decode colour, giving a crisper display. You can enable this behaviour with -vo-colour-killer. NTSC machines add circuitry to reintroduce a (modified) burst to enable cross-colour in high resolution black & white, so enabling the colour killer would not prevent colour in these modes.

A quirk of the VDG is that it can operate in-phase or 180° out of phase with its clock signal, and how it starts up is essentially random. This clock signal is also used in NTSC machines to generate the colour subcarrier, which leads to machines generating the blue and red artefact colours randomly (but consistently, once running) swapped. 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. In PAL machines, "Blue-red" and "Red-blue" also select the alternate line phase switch, allowing for correct colour in games such as Tetris by Ola Eldøy or Donut Dilemma by Nick Marentes.

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

In the GTK+ and Windows interfaces, View → TV Controls opens a control window allowing you to dynamically modify various display options. Pressing CTRL+SHIFT+V will also open this window.

6.14 Audio ¶

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

6.15 Debugging ¶

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

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

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:

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 with -C as the first option to attach to the parent console or create a new console window.

6.16 Other options ¶

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

7.1 Snapshots ¶

XRoar can save a snapshot of the emulated machine state and read it 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.

7.2 Screenshots ¶

XRoar can save a screenshot in PNG format. Press CTRL+SHIFT+S or select File → Screenshot to PNG.

7.3 Binary files ¶

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

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, 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 append .rom.
• 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, the primary examples being:

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.

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.