XRoar is a Dragon emulator that runs on a wide variety of platforms. Due to hardware similarities, XRoar also emulates the Tandy Colour Computer (CoCo) models 1 & 2. Some features are:
To start, you will need to acquire (and maybe build) the software and install it. Pre-built binary packages are available from the XRoar home page. If one is not available for your architecture, you will have to build from source. XRoar should build and run on any POSIX-like system for which SDL is available.
You'll also need to get hold of ROM images for the machine you wish to emulate. As Microsoft wrote the BASIC ROM, I don't feel comfortable offering them up myself, but they may well be obtainable elsewhere on the Web.
For instructions on installing from source or binary package, and where to put ROM images, see Installation.
Once you've installed XRoar, run it and an emulator screen should appear. Depending on which ROM images are found, XRoar will attempt to emulate a Dragon 64, a Dragon 32 and a CoCo, in that order. If you just get a strange checkerboard pattern of orange and inverse ‘@’ signs, it probably failed to find any ROM images - check that first.
From here you can attach tapes (.cas or .wav files) with Control+L. To load a program from tape, type CLOADM (machine code) or CLOAD (BASIC). If the program does not start automatically when it has loaded (i.e., returns you to the “OK” prompt), you will have to type EXEC (machine code) or RUN (BASIC) to start it.
XRoar will make use of attached joysticks, but can also emulate them with the cursor keys and Left Alt. Press Control+J to cycle through three emulation modes: No joystick emulation (default), Left joystick, Right joystick.
First, unpack the downloaded ZIP file. A subdirectory should be created containing the main binary, supporting DLL files and documentation.
ROM images can be copied to this directory, or to a directory called USERPROFILE/Application Data/XRoar/roms/. USERPROFILE is usually something like C:/Documents and Settings/username or C:/Users/username. ROM images in these locations with standard filenames will be found automatically. See ROM lists for information on filenames, and modifying the search lists.
XRoar can be started by running xroar.exe either from a file browser or the command line.
Mount the downloaded disk image and drag the XRoar application icon into your Applications directory.
ROM images can be copied either to ~/Library/XRoar/Roms/ or ~/.xroar/roms/. ROM images in these locations with standard filenames will be found automatically. See ROM lists for information on filenames, and modifying the search lists.
XRoar can be started by double-clicking the application icon.
If there is no binary package for your system, you will have to build from source. Before doing so, you should ensure you have the dependencies required to build:
If you use a modern Linux or Unix distribution, it's likely that most of these packages will be installed by default, or easily available through its package management system.
The actual build process should be fairly straightforward and follows the same steps as many other software packages. Unpack the source code, change into the created source directory, run configure and then if everything looks good, run make. Example:
$ gzip -dc xroar-0.29.2.tar.gz | tar xvf -
$ cd xroar-0.29.2
$ ./configure
$ make
configure will detect any optionally supported drivers like Sun audio, OpenGL video, etc.
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 to install the binary and info documentation on your system. ROM images should be placed either in your home directory under .xroar/roms/, or under the installation directory at PREFIX/share/xroar/roms/.
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 --target=TARGET argument to configure. For example, to build for Windows, you might use ‘./configure --target=i586-mingw32’. configure will detect Windows headers and configure the build accordingly.
XRoar has built-in definitions for the following machines, selectable with the -machine NAME option:
If no machine is specified on the command line (with -machine NAME), XRoar will try and find a good default machine to emulate based on which ROM images you have installed (see ROM lists). Alternatively, once started, pressing Control+M cycles through all the supported machine types.
Additionally extra machines can be configured, or existing ones reconfigured, with the following options:
Dragon machines all contain a complete version of Extended BASIC; CoCos are able to run with a much reduced Color BASIC, with Extended BASIC being optional.
Defining extra machines is most usefully done in the configuration file. For example:
machine pippin
machine-desc Dragon Pippin (prototype)
machine-arch dragon32
ram 16
This will define a machine named “pippin” that is basically a Dragon 32 with only 16K or RAM.
UK machines generate a 50Hz PAL display, whereas US machines output 60Hz NTSC. XRoar will emulate the appropriate mode depending on the machine chosen (see Emulated machines), but you can force one or the other with the -pal or -ntsc command line options.
Many programs employ a trick with cross-colour on NTSC televisions to generate a colour display from an otherwise black & white video mode. XRoar can approximate the colours generated in these modes to varying levels of detail. The default approach is to use a 5 bit lookup table, but a faster four colour mode can be selected by running with -ccr simple.
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) to identify which state the machine started in. You can adjust which state it's in by pressing Control+A, which cycles through three artifacted colour modes: Off, Blue-red and Red-blue.
The Dragon can route analogue audio from three different sources: attached cartridges, the cassette port and an internal 6-bit DAC. Additionally, a PIA line is connected to the audio output stage, so manipulating that gives a single-bit sound source. XRoar supports the DAC, single bit audio, and will approximate cassette audio input.
Rarely, a game generates audio by toggling the analogue sound select source rapidly. XRoar will cope with this, but needs to work harder. Disable support for this with the -fast-sound command line option.
The layout of the Dragon's keyboard is a little different to that of modern PCs, so XRoar tries to approximate the Dragon's layout on your PC keyboard as closely as possible, so that game controls will remain in usable positions. That said, they are different, so some compromises need to be made: Escape is mapped to the Dragon's BREAK key and ` (grave / back-tick) maps to the Dragon's CLEAR key. There are no good nearby PC keys that directly correspond to the Dragon's cursor keys, so the PC's cursors are used for these.
If you don't use a UK keyboard, but want a close Dragon keyboard layout, you can run with the -keymap CODE command-line option, where CODE is a country code: “uk” (British), “us” (American), “fr” (French AZERTY), “fr_CA” (Canadian French QWERTY) or “de” (German QWERTZ).
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. Run with the -kbd-translate option to start with this enabled. Press Control+Z to toggle this mode.
The keyboards of the Dragon and Tandy CoCo are connected in the same way, but the matrix is laid out slightly differently. When you select a machine (see Emulated machines), the appropriate matrix layout is selected for you, but you can toggle between the two layouts by pressing Control+K.
Additionally, most emulator functions are currently accessed through key combinations. See Keyboard commands for a list.
XRoar supports attached joysticks, or can emulate them from the keyboard.
Joystick emulation starts off disabled, but you can cycle through three states by pressing Control+J: Off, Left Joystick and Right Joystick. When emulating a joystick, the cursor keys control the axes and Left Alt maps to the fire button.
By default, the first real joystick found is mapped to the Dragon's left joystick port, and the second real joystick to the right port. Left and right joystick mapping can be easily swapped by pressing Control+Shift+J.
More fine-grained mappings can be specified with the -joy-left and -joy-right command line options. The argument to these command consists of three pairs of numbers in the format JOYSTICK-NUMBER,INDEX. The pairs map the X axis, Y axis and fire button respectively, and the joystick number is optional if previously specified. For example, -joy-left 0,1:0:0 maps axes 1 and 0 on joystick 0 to the X and Y axis on the left emulated joystick respectively. Button 2 of joystick 0 is mapped to the left fire button.
Previous versions defaulted to a mapping suitable for using a PS2 adaptor. To get this old behaviour, use the command line options -joy-left 0,3:2:0 -joy-right 0,0:1:1.
XRoar supports three types of cassette image: .cas files, audio files such as .wav and ASCII text files containing BASIC programs (.bas or .asc). .cas files contain a binary representation of what would be loaded from tape, audio files are a recording of the tape itself, and ASCII files contain plain text that is automatically wrapped up as an ASCII BASIC file for loading.
To attach a cassette image for reading, use the -load or -run command line options, or press Control+L and select it from the file requester (hold Shift as well to attempt to autorun).
To create a cassette image for writing (with the CSAVE or CSAVEM BASIC commands, for example), use the -tape-write command line option, or press Control+W and enter a filename. Created files will be truncated to zero length, so be careful not to overwrite any existing files with this command.
The currently open tape files used for reading and writing are distinct.
Four command line options affect how tapes are read:
The -tape-fast option accelerates tape loading by intercepting ROM calls. Disable with -no-tape-fast. On by default.
The -tape-pad option tries to make loading more reliable by intercepting ROM calls and inserting extra leader bytes where appropriate. Disable with -no-tape-pad.
The -tape-pad-auto option will, for .cas files, automatically switch on leader padding when insufficient initial leader bytes are found. Disable with -no-tape-pad-auto. On by default.
The -tape-rewrite option enables rewriting of anything read from the input tape to the output tape. This is useful for creating “well formed” cassette images.
Where available, these options can be changed on the fly in the GUI. See Tape control.
XRoar has built-in definitions for three cartridges, selectable with the -cart NAME option:
Additionally extra cartridges can be configured, or existing ones reconfigured, with the following options:
If no ROM is configured for a cartridge, there is a built-in list to search for each of the disk controller types. A ROM image will be required if you want to use virtual disks.
Defining extra cartridges is most usefully done in the configuration file, for example:
cart sdose6
cart-desc SuperDOS E6
cart-type dragondos
cart-rom sdose6
cart-rom2 dosdream
This will define a cartridge called “sdose6” as a DragonDOS cartridge with its ROM replaced with sdose6, and an additional ROM called dosdream.
XRoar will automatically attempt to find a disk controller cartridge relevant to the current machine unless the -nodos option is specified.
Selecting a ROM image file with the -load or -run command line options, or with Control+L or Control+Shift+L, will attach a ROM cartridge.
Within the emulator, cartridges can be enabled or disabled by pressing Control+E. You will almost certainly want to follow this with a hard reset (Control+Shift+R).
XRoar is able to connect to a DriveWire server using a TCP connection, simulating the "becker port", a memory-mapped address that provides a simple command protocol for accessing devices. Running with the -becker option will enable this port when automatically selecting a DOS cartridge, or it can be enabled when defining a cartridge with -cart-becker.
The IP and port to connect to can be specified with the -becker-ip and -becker-port options respectively. These default to “localhost” and “65504” respectively, which corresponds to the DriveWire 4 defaults.
If a disk controller cartridge is selected, XRoar supports virtual disks.
Three virtual disk formats are supported (see Supported file types). Of these, DMK retains the most information about the actual layout of the floppy disk, and is the only one that XRoar will recognise as containing single-density data (as used by the Delta system).
When you attach a disk, it is read into memory, and subsequent disk operations are performed on this in-memory copy. Write enable defaults to on (so write operations on the copy will work), but write back defaults to off, so updates will not be written to the disk image file. To toggle write enable, press Control+[5-8], where the number to press is the drive number plus 4. To toggle write back, press Control+Shift+[5-8]. Even with write back enabled, image files will not be updated until the disk in a virtual drive is changed, or you quit the emulator.
Where available, these options can also be changed on the fly in the GUI. See Drive control.
Write back can be set to default to on with the -disk-write-back command line option.
You can create a new blank disk in a virtual drive by pressing Control+Shift+[1-4]. You will be a prompted for a filename, and the extension determines which type of file will be written.
Under the SDL user interface, three video output modules are available, selectable with the -vo MODULE command line option:
When using OpenGL output, the -gl-filter option selects a filtering method when scaling the image. -gl-filter linear averages nearby pixels (blur), -gl-filter nearest selects nearest neighbour pixels (hard edges) and -gl-filter auto (the default) selects nearest when the image size is an exact integer multiple of the base size, otherise selects linear.
OpenGL output might not be available if you built from source without the appropriate support. Use -vo help for a list of available modules.
On slower machines, you can specify a value for frameskip with -fskip FRAMES. For every frame drawn to screen this amount of frames are then skipped before the next one is drawn, reducing the amount of work needed. The default is -fskip 0, meaning no frames are skipped.
XRoar can be started full-screen by specifying -fs.
Specific audio modules exist for OSS, ALSA, Sun audio, Mac OS X coreaudio and PulseAudio. If none of these are available, generic SDL audio will be used.
Use of a specific module can be forced using -ao MODULE. Use -ao null to disable audio, or -ao help for a list of available modules.
For most audio modules, the -ao-rate HZ option can be used to specify a sample rate in Hz. The default will usually be 44100. The -ao-buffer-ms MS or -ao-buffer-samples N options may be used (where supported) to set an audio buffer size, either in milliseconds or number of samples.
Currently only available in the GTK+ interface. Pressing Control+D, or selecting “Drive Control” from the “Tool” menu will open the drive control window.
This window allows you to insert and eject disk images, and toggle their write-enable and write-back states. See Disks.
Currently only available in the GTK+ interface. Pressing Control+T, or selecting “Tape Control” from the “Tool” menu will open the tape control window.
This window shows the current tape image filename and position. The input tape image is scanned, and any recognised file header blocks listed, along with their position within the image. Double clicking a filename will seek to that point in the tape image.
Certain tape options can be configured here. See Cassettes.
XRoar supports redirecting Dragon printer output to a file or pipe with the -lp-file or -lp-pipe option. Printed data will be sent to the appropriate stream. Pressing Control+Shift+P will flush the current stream by closing it (so if the stream is a pipe, the filter will complete). The stream will be re-opened when any new data is sent.
The pipe feature allows you to use useful print filters such as enscript, e.g., -lp-pipe ``enscript -B -N r -d printer-name''. This will send a job to your printer, using carriage returns as line feeds (the Dragon default), each time you press Control+Shift+P (or exit the emulator).
XRoar's user interface is currently based around either GTK+ or SDL. The emulator video output window is shown, and all operations are performed with keyboard combinations, usually accessed as Control+KEY. Under Mac OS X, most functions will be accessible as Command+KEY.
When using Control+L or Control+Shift+L to load a file, the action to be taken is determined by its extension. See Supported file types for details.
XRoar still supports the use of some old keyboard commands that were used to attach specific types of file. Control+B and Control+H are synonymous with Control+L.
XRoar can save out a snapshot of the emulated machine state and read such snapshots back in later. To save a snapshot, press Control+S. When using Control+L to load a file, anything ending in .sna will be recognised as a snapshot.
What is included in snapshots: Selected machine architecture, complete hardware state, current keyboard map, filenames of attached disk image files.
What is not (yet) included: Actual disk image data (only where to find it), attached cassettes or cartridges.
XRoar contains a “trace mode”, where it will dump a disassembly of every instruction it executes to the console. Trace mode defaults to off unless you run with -trace. Toggle trace mode on or off with Control+V.
Many emulator functions can be changed using keyboard shortcuts (see Keyboard commands), but some behaviour can also be changed from the command line.
If you run the Windows pre-built binary, you might find that emulator output gets written to a file called stderr.txt instead of to the console.
See Emulated machines for more information.
See Cartridges for more information.
XRoar can do useful things with a variety of file types. The type of a file is determined by its extension. Supported file extensions are:
| Extension | Description | Read/write?
|
|---|---|---|
| .dmk | Disk image file in a format defined by David Keil. They store a lot of information about the structure of a disk and support both single and double density data. All disk images are manipulated internally in (near enough) this format. See Disks. | Read & write
|
| .jvc .dsk | Disk image file in a basic sector-by-sector format with optional header information. See Disks. | Read-only
|
| .vdk | Another disk image file format. See Disks. | Read-only
|
| .bin | Binary file (DragonDOS or CoCo). XRoar can load these directly into memory and optionally autorun them. | Read-only
|
| .sna | XRoar snapshot. Contains a complete dump of RAM from a running emulator session along with information like which machine was being emulated, what DOS was attached, etc. See Snapshots. | Read & write
|
| .hex | Intel hex record. An ASCII format that encodes binary data and where in memory to load it. | Read-only
|
| .cas | Cassette file. Simple binary representation of data contained on a tape. Cannot represent silence, or some custom encodings. See Cassettes. | Read & write
|
| .wav | Cassette audio file. XRoar can read sampled audio from original cassettes. Actually, as audio input uses libsndfile, any file with an unknown extension is passed to libsndfile to see if it recognises it as an audio file. See Cassettes. | Read-only
|
| .rom | This represents two things: when starting, XRoar looks for ROM images with this extension. When subsequently told to load one, however, they are assumed to be dumps of cartridge ROMs. See Cartridges. | Read-only
|
In general, to load or attach a file, press Control+L and choose a file from the requester that appears. What XRoar does with it will depend on its file extension. You can also automatically attach (and optionally start) files from the command line by using the -load FILE or -run FILE options. If you -load or -run a cassette image, XRoar will automatically disable any DOS cartridge emulation for you, as this can interfere with some cassette-based games. In addition, the first non-option argument to XRoar is taken as a filename and treated as though it were the argument to the -run option.
XRoar searches for ROM images in a variety of locations. See Installation for where your particular platform will search. The search path can be overridden by including a colon-separated list of paths in the XROAR_ROM_PATH environment variable.
Images are expected to have certain names. There are a set of built-in lists which can be modified using the -romlist option. List elements are comma-separated, and an element prefixed with an ‘@’ character indicates a nested list. As an example, to append the ROM image “d64extended” to the “d64_1” list, use -romlist d64_1=@d64_1,d64extended.
ROM images are searched for with either a .rom or a .dgn extension. .dgn files contain a 16 byte header, which is ignored.
View the currently defined ROM lists with the -romlist-print option, but here are the canonical names for BASIC ROM images:
| Machine | ROM image name | Description
|
|---|---|---|
| dragon32 | d32 | Dragon 32 BASIC.
|
| dragon64 tano | d64_1 d64_2 | 32K-mode Dragon 64 BASIC. 64K-mode Dragon 64 BASIC. |
| coco cocous | bas13 bas12 bas11 bas10 | Color BASIC 1.3, 1.2, 1.1 or 1.0.
|
| extbas11 extbas10 | Extended Color BASIC 1.1 or 1.0.
|
Emulating a floppy drive controller cartridge requires that you have an image of the DOS ROM that would have been part of it. The same ROM lists are consulted, but here are the canonical names for DOS ROM images:
| Controller type | ROM image name | Description
|
|---|---|---|
| dragondos | dplus49b dplus48 sdose6 sdose5 sdose4 ddos40 ddos15 ddos10 | DragonDOS (using DOSplus, SuperDOS or original DragonDOS ROM).
|
| delta | delta | Delta System.
|
| rsdos | disk11 disk10 | Disk Extended Color BASIC 1.1 or 1.0.
|
| hdbdw3bck | HDB-DOS 1.4 with DriveWire support
|
A CRC32 value is calculated (and reported) for BASIC ROMs loaded - this is used 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 option - you might do this if you have a modified version of a BASIC ROM that maintains compatible entry points with an original. View the current list 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.
All command-line options can also be used as directives in a configuration file called xroar.conf. This file is searched for in a variety of locations:
| System | Search order
|
|---|---|
| Unix Mac OS X | Current working directory ~/.xroar/ ~/Library/XRoar/ PREFIX/share/xroar/ |
| Windows | Current working directory ~/Local Settings/Application Data/XRoar/ ~/Application Data/XRoar/ |
‘~’ indicates the user's home directory. On Unix systems this is held in the HOME environment variable (often /home/username), on Windows systems it is in the USERPROFILE environment variable (often c:/Documents and Settings/username or c:/Users/username). PREFIX is the installation prefix, usually /usr/local.
Directives are listed one per line without the leading dashes of the command line option.
I made reference to the MAME 6809 core for clues on how the overflow bit in the condition code register was handled.
Thanks to all the people on the Dragon Archive Forums for helpful feedback and insight.
Darren Atkinson's “Motorola 6809 and Hitachi 6309 Programmers Reference” has been very useful for 6309 support and fleshing out the illegal instructions on the 6809.