xroar

NAME

xroar—Dragon and Tandy 8-bit computer emulator

SYNOPSIS

xroar [-c conffile] [OPTION]… [FILENAME]…

DESCRIPTION

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.

OPTIONS

Options are first read from a configuration file (by default, $HOME/.xroar/xroar.conf). Options on the command line override any found in the configuration file.

-C

Allocate a console window (Windows only).

-c conffile

Specify a configuration file.

Machines:

-m name, -default-machine name

Default machine profile to select on startup.

-machine name

Create or modify named machine profile. -machine help lists currently defined profiles.

The remaining options configure the currently selected machine:

-machine-desc text

Machine description shown in -machine help and menu options.

-machine-arch arch

Machine architecture (dragon64, dragon32, coco, coco3 or mc10).

-machine-keyboard layout

Keyboard layout (dragon, dragon200e, coco or coco3).

-machine-cpu cpu

Machine CPU (6809 or 6309). Not applicable to the MC-10.

-bas rom

ROM image for Colour BASIC (CoCo) or Microcolour BASIC (MC-10).

-extbas rom

ROM image for Extended BASIC (Super Extended BASIC on the CoCo 3).

-altbas rom

ROM image for 64K-mode Extended BASIC (Dragon 64, Dragon 200-E).

-nobas, -noextbas, -noaltbas

Indicate the corresponding ROM is not fitted in this machine.

-ext-charset rom

External character generator ROM to use.

-tv-type type

TV type (pal, ntsc or pal-m).

-tv-input input

One 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 type

Indicate the VDG variant fitted. One of 6847 or 6847t1.

-ram-org organisation

RAM organisation (-ram-org help for list).

-ram kbytes

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

-ram-init pattern

RAM start pattern (-ram-init help for list).

-machine-cart name

Default cartridge to attach. -no-machine-cart to inhibit the default behaviour of searching for a workign DOS cartridge.

Cartridges:

-cart name

Create or modify named cartridge profile. -cart help lists currently defined profiles.

The remaining options configure the currently selected cartridge:

-cart-desc text

Cartridge description shown in -cart help and menu options.

-cart-type type

Cartridge base type (-cart-type help for list).

-cart-rom rom

ROM image to load ($C000-).

-cart-rom2 rom

Second ROM image to load ($E000-).

-cart-autorun

Autorun cartridge.

-cart-becker

Enable becker port where supported.

-mpi-slot slot

(MPI) initially select slot (0–3).

-mpi-load-cart [slot=]name

(MPI) insert cartridge into next or numbered slot.

When configuring a Multi-Pak Interface (MPI), only the last configured DOS cartridge will end up connected to the virtual drives. MPI options also apply to the similar RACE Computer Expansion Cage.

Becker port:

-becker

Prefer becker-enabled DOS cartridge when picked automatically.

-becker-ip address

Address or hostname of DriveWire server [127.0.0.1]

-becker-port port

Port of DriveWire server [65504]

Cassettes:

-load-tape file

Attach file as tape image for reading.

-tape-write file

Open file for tape writing.

-tape-pan panning

Pan stereo input (0.0 = full left, 1.0 = full right) [0.5]

-tape-hysteresis percent

Read hysteresis as percentage of full scale [1]

-no-tape-fast

Disable fast tape loading.

-no-tape-pad-auto

Disable automatic leader padding.

-tape-rewrite

Enable tape rewriting.

-tape-rewrite-gap-ms ms

Gap length in milliseconds to write in rewrite mode (1–5000ms, default 500ms).

-tape-rewrite-leader bytes

Length of leaders in bytes to write in rewrite mode (1–2048 bytes, default 256).

-tape-ao-rate hz

Set tape writing frame rate [9600]

Floppy disks:

-load-fdX file

Insert disk image file into floppy drive X (0–3).

-no-disk-write-back

Don't default to enabling write-back for disk images.

-no-disk-auto-os9

Don't try to detect headerless OS-9 JVC disk images.

-no-disk-auto-sd

Don't assume single density for 10 sec/track disks.

Hard disks:

-load-hdX file

Use file as the hard disk image for drive X (0–1).

-load-sd file

Use file as the SD card image (e.g. for mooh, nx32).

Keyboard:

-kbd-layout layout

Host keyboard layout (-kbd-layout help for list).

-kbd-lang lang

Host keyboard language (-kbd-lang help for list).

-kbd-bind hostkey=[pre:]emukey

Map host key to emulated key. Prefixing emulated key name with 'pre:' disables translation for the bind (the bind "preempts" translation). Host key names can be determined by running with -debug-ui 1, which will log keypresses.

-kbd-translate

Enable keyboard translation.

-type string

Intercept ROM calls to type string into BASIC.

-load-text file

Type file into BASIC.

Joysticks:

-joy-db-file file

Load gamepad mappings from file.

-joy-right name

Map right joystick.

-joy-left name

Map left joystick.

-joy-virtual name

Specify the 'virtual' joystick to cycle [kjoy0]

-joy name

Configure named joystick (-joy help for list).

The remaining options configure the currently selected joystick:

-joy-desc text

Joystick description.

-joy-axis axis=spec

Configure joystick axis.

-joy-button btn=spec

Configure joystick button.

Joystick specs are of the form [module:][arg[,arg]…], from:

For physical joysticks a '-' before the axis index inverts the axis. Axis 0 is the X-axis, and axis 1 the Y-axis. Buttons are numbered 0 or 1 (the second is only used when connected to a CoCo 3).

Printers:

-lp-file file

Append printer output to file.

-lp-pipe command

Pipe printer output to command.

Files:

-load file

Load or attach file

-run file

Load or attach file and attempt autorun

-load-fdX file

Insert disk image file into floppy drive X (0–3).

-load-hdX file

Use file as the hard disk image for drive X (0–1).

-load-sd file

Use file as the SD card image (e.g. for mooh, nx32).

-load-tape file

Attach file as tape image for reading.

-tape-write file

Open file for tape writing.

-load-text file

Type file into BASIC.

Firmware ROM images:

-rompath path

ROM search path (colon-separated list).

-romlist name=list

Define a ROM list.

-romlist-print

Print defined ROM lists.

-crclist name=list

Define a ROM CRC list.

-crclist-print

Print defined ROM CRC lists.

-force-crc-match

Force per-architecture CRC matches.

User interface:

-ui module

User-interface module (-ui help for list).

Video:

-fs

Start emulator full-screen if possible.

-fskip frames

Frameskip (default: 0).

-ccr renderer

Cross-colour renderer (simple, 5bit, partial or simulated).

-gl-filter filter

OpenGL texture filter (auto, nearest or linear).

-vo-vsync

Start with vsync enabled.

-vo-pixel-fmt format

Pixel format (-vo-pixel-fmt help for list).

-geometry wxh+x+y

Initial emulator geometry.

-vo-picture p

Initial picture area (-vo-picture help for list).

-no-vo-scale-60hz

Disable vertical scaling for 60Hz video.

-invert-text

Start with text mode inverted.

-vo-brightness n

Set TV brightness (0–100) [50]

-vo-contrast n

Set TV contrast (0–100) [50]

-vo-colour n

Set TV colour saturation (0–100) [50]

-vo-hue n

Set TV hue control (-179 to +180) [0]

-vo-monochrome

Use a black-and-white display (disabled by default).

-no-vo-colour-killer

Disable colour killer (enabled by default).

Audio:

-ao module

Audio module (-ao help for list).

-ao-device string

Device to use for audio module.

-ao-format fmt

Set audio sample format (-ao-format help for list).

-ao-rate hz

Set audio frame rate (if supported by module).

-ao-channels n

Set number of audio channels, 1 or 2.

-ao-fragments n

Set number of audio fragments.

-ao-fragment-ms ms

Set audio fragment size in ms (if supported).

-ao-fragment-frames n

Set audio fragment size in samples (if supported).

-ao-buffer-ms ms

Set total audio buffer size in ms (if supported).

-ao-buffer-frames n

Set total audio buffer size in samples (if supported).

-ao-gain db

Audio gain in dB relative to 0 dBFS [-3.0]

-volume volume

Older way to specify audio volume, linear (0–100).

Debugging:

-gdb

Enable GDB target.

-gdb-ip address

Address of interface for GDB target [127.0.0.1]

-gdb-port port

Port for GDB target to listen on [65520]

-gdb-pseudo-regs

Enable pseudo-registers (e.g. SAM, PIA) for GDB.

-no-ratelimit

Run CPU as fast as possible.

-trace

Start with trace mode on.

-trace-timing

Print timings in trace mode.

-debug-fdc flags

FDC debugging (see manual, or -1 for all).

-debug-file flags

File debugging (see manual, or -1 for all).

-debug-gdb flags

GDB target debugging (see manual, or -1 for all).

-debug-ui flags

UI debugging (see manual, or -1 for all).

-v, -verbose level

General debug verbosity (0 to 3) [1]

-q, -quiet

Equivalent to -verbose 0.

-trap condition

Configure a trap to fire on condition.

These options affect the configured trap:

-trap-range m-n

Perform trap's action only on mth-nth trigger.

-trap-snap file

Write snapshot at trap.

-trap-timeout n

Quit emulator n seconds after trap.

-trap-trace

Start trace mode at trap.

-trap-trace-n n

Start trace mode at trap for n instructions.

-trap-no-trace

Stop trace mode at trap.

Trap conditions can be one of the following:

Older options remain that can be implemented using traps:

-timeout s

Run for s seconds then quit.

-timeout-motoroff s

Quit s seconds after tape motor switches off.

-snap-motoroff file

Write a snapshot each time tape motor switches off.

Other options:

-config-print

Print configuration to standard out, omitting (most) default options.

-config-print-all

Print configuration to standard out, including defaults.

-config-auto-save

Write configuration to $HOME/.xroar/xroar.conf on exit.

-h, --help

Display help and exit.

-V, --version

Output version information and exit.

KEYBOARD SHORTCUTS

LICENCE

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

FILES

$HOME/.xroar/xroar.conf

Configuration file.

$HOME/.xroar/roms/

Directory for firmware ROM images.

Here are some well-known filenames for firmware ROM images. Consult the full manual for more.