Provided by: hatari_2.3.1+dfsg-1_amd64 
NAME
hatari - Atari ST/STE/TT/Falcon emulator
SYNOPSIS
hatari [options] [directory|diskimage|program]
DESCRIPTION
Hatari is an Atari ST/STE/TT/Falcon emulator for Linux and other Systems which are
supported by the SDL (cross-platform graphics, input and sound) library.
With Hatari one can run games, demos or applications written for Atari ST, STE or Falcon.
Atari TT support is experimental. Hatari supports the commonly used *.st, *.msa and *.stx
disk images, and hard disk emulation.
To run the emulator a TOS ROM image is needed. EmuTOS, a free implementation of TOS is
shipped with Hatari. It boots faster than original TOS versions and doesn't need separate
HD drivers, but some buggy (typically floppy only) programs won't work correctly with it.
For best compatibility, it is recommended to use a TOS ROM from a real Atari.
As an argument, one can give either a name of a directory that should be emulated as a
virtual GEMDOS hard disk, a floppy disk image or an Atari program that should be
autostarted. In the last case the program's directory will be used as the C: drive from
where this program will be started. These shortcuts correspond to "-d <dir>", "--disk-a
<floppy image>" and "-d <dir> --auto C:<program>" options.
Booting will be done from the disk image or directory that's given last on the command
line, either as an option or an argument (and which corresponds to A: or C:).
OPTIONS
Hatari options are split into several categories:
General options
-h, --help
Print command line options and terminate
-v, --version
Print version information and terminate
--confirm-quit <bool>
Whether Hatari confirms quitting
-c, --configfile <filename>
Read additional configuration values from <file>, these override values read from
the global and user configuration files
-k, --keymap <file>
Load keyboard mapping from <file>
--fast-forward <bool>
Fast-forward through the boring parts by running emulator at maximum speed. Done
by skipping frame update VBL waits. Upper limit for frame skipping is given with
the --frameskips option and shown in statusbar "FS" field
--auto <program>
Autostarts given program, if TOS finds it. Program needs to be given with full
path it will have under emulation, for example "C:\DIR\PROGRAM.PRG". This is
implemented by providing TOS a virtual INF file for the boot drive (A: or C:),
which tells TOS to start the given program
Common display options
-m, --mono
Start in monochrome mode instead of color
--monitor <x>
Select monitor type (x = mono/rgb/vga/tv)
--tos-res <x>
Select TOS resolution for color monitors (x = low/med/high/ttlow/ttmed)
-f, --fullscreen
Start the emulator in fullscreen mode
-w, --window
Start the emulator in windowed mode
--grab Grab mouse (also) in windowed mode
--resizable <bool>
Allow window resizing
NOTE: this is supported only by Hatari SDL2 build
--borders <bool>
Show ST/STE/Falcon screen borders (for low/med resolution overscan demos)
--frameskips <x>
Skip <x> frames after each displayed frame to accelerate emulation (0=disabled, >4
uses automatic frameskip with given value as maximum)
--slowdown <x>
Slow down emulation by factor of x (used as multiplier for VBL wait time)
--mousewarp <bool>
To keep host mouse better in sync with Atari mouse pointer, center it to Hatari
window on cold reset and resolution changes
--statusbar <bool>
Show statusbar (with floppy leds etc etc)
--drive-led <bool>
Show overlay drive led when statusbar isn't shown
--max-width <x>
Preferred / maximum Hatari screen width
--max-height <x>
Preferred / maximum Hatari screen height.
Maximum width and height options are part of Hatari's Atari monitor emulation. They
limit the size Hatari should aim for its internal SDL framebuffer, and how much of
the Atari screen borders are visible.
On an SDL2 build, framebuffer is then scaled to the Hatari output window based on
the specified Hatari zoom factor (see below).
Aim of this is to have all resolutions show up in approximately same size, like on
a real Atari monitor. Hatari's internal integer scaling support sets some limits on
this, so it's an expert option.
Note: Only reason to change the defaults, should be limiting this to a smaller
resolution for performance reasons, e.g. for video recording, or on really
underpowered systems, to make monitor do all of the ST-low resolution scaling by
forcing Hatari to ask SDL for CGA / QVGA resolution.
-z, --zoom <x>
With the Hatari SDL1 build, this is just a shortcut for overriding maximum screen
size settings with values that result in ST/STe low resolution being doubled or not
(1=no, 2=yes).
With the Hatari SDL2 build, this option overrides max width/height options so that
e.g. ST-low resolution gets always doubled, and all resolutions (except TT-high)
have approximately the same size, like on a real CRT monitor.
Zoom factor is then used to scale that up (or down) to the Hatari output window.
This way scaling results always in approximately same sized Hatari window.
With non-integer zoom factors, linear scaling is used to smooth out the output,
with integer zoom factors, scaling is done using nearest neighboring pixels for
sharper output. This applies also to window resizes.
To get SDL1 "-z 1" behavior with SDL2, use "--zoom 1 --max-width 416 --max-height
276" (if you don't need borders, 320x200 size is enough). Disabling low resolution
doubling like this is not recommended for Falcon emulation because TOS v4 bootup
and some demos switch resolutions frequently.
--bpp <bool>
Force internal bitdepth (x = 8/15/16/32, 0=disable)
--disable-video <bool>
Run emulation without displaying video (audio only)
ST/STE specific display options
--desktop-st <bool>
NOTE: this has effect only for SDL1 Hatari build. In SDL2 build, --desktop option
controls also ST/STe mode.
Whether to use desktop resolution on fullscreen to avoid issues related to
resolution switching (messing multi-screen setups, several seconds delay needed for
resolution switching by some LCD monitors and the resulting sound break). Otherwise
fullscreen will use a resolution that is closest to the Hatari window size.
As Hatari ST/STe display code doesn't support zooming (except low-rez doubling)
with SDL1, it doesn't get scaled (by Hatari or monitor) when this is enabled, and
you may get large black borders around ST/STe screen. Therefore this is mainly
useful only if you suffer from the described effects, but still want to grab mouse
and remove other distractions from the screen just by toggling fullscreen mode.
(disabled by default)
--spec512 <x>
Hatari uses this threshold to decide when to render a screen with the slower but
more accurate Spectrum512 screen conversion functions (0 <= x <= 512, 0=disable)
--video-timing <x>
Wakeup State for MMU/GLUE (x=ws1/ws2/ws3/ws4/random, default ws3). When powering
on, the STF will randomly choose one of these wake up states. The state will then
affect the timings where border removals and other video tricks should be made,
which can give different results on screen. For example, WS3 is known to be
compatible with many demos, while WS1 can show more problems.
TT/Falcon specific display options
Zooming to sizes specified below is internally done using integer scaling factors. This
means that different Atari resolutions may show up with different sizes, but they are
never blurry.
--desktop <bool>
Whether to use desktop resolution on fullscreen to avoid issues related to
resolution switching. Otherwise fullscreen will use a resolution that is closest to
the Hatari window size. (enabled by default)
--force-max <bool>
Hatari window size is forced to specified maximum size and black borders used when
Atari resolution doesn't scale evenly to it. This is most useful when recording
videos of Falcon demos that change their resolution. (disabled by default)
--aspect <bool>
Whether to do monitor aspect ratio correction (enabled by default)
VDI options
--vdi <bool>
Whether to use VDI screen mode. Doesn't work with TOS v4. TOS v3 memory detection
isn't compatible with larger VDI modes (i.e. you need to skip the detection at
boot). Original TOS desktops use wrong window size in 2-plane (4 color) VDI mode
when screen height >= 400 pixels. Because of these issues, using EmuTOS is
recommended for VDI mode
--vdi-planes <x>
Use extended VDI resolution with bit depth <x> (x = 1, 2 or 4)
--vdi-width <w>
Use extended VDI resolution with width <w> (320 < w <= 2048)
--vdi-height <h>
Use extended VDI resolution with height <h> (200 < h <= 1280)
Because TOS and popular GEM programs have problems with certain screen sizes, Hatari
enforces restrictions on VDI screen size. In total VDI screen size is limited to
32-300kB, width to multiple of 128/planes, and height to multiple of 16 pixels (or 8,
depending on system font height). That translates to following maximum standard
resolutions for the VDI mode:
monochrome
FullHD (1920×1080), WUXGA (1920x1200) and QWXGA (2048x1152)
2 plane mode (4 colors)
HD (1280x720), WXGA (1280x768) and XGA+ (1152x864)
4 plane mode (16-colors)
qHD (960x540), DVGA (960x640) and WSVGA (1024x600)
Screen capture options
--crop <bool>
Remove statusbar from the screen captures
--avirecord
Start AVI recording. Note: recording will automatically stop when emulation
resolution changes.
--avi-vcodec <x>
Select AVI video codec (x = bmp/png). PNG compression can be much slower than
using the uncompressed BMP format, but uncompressed video content takes huge amount
of space.
--png-level <x>
Select PNG compression level for AVI video (x = 0-9). Both compression efficiency
and speed depend on the compressed screen content. Highest compression level (9)
can be really slow with some content. Levels 3-6 should compress nearly as well
with clearly smaller CPU overhead.
--avi-fps <x>
Force AVI frame rate (x = 50/60/71/...)
--avi-file <file>
Use <file> to record AVI
--screenshot-dir <dir>
Save screenshots in the directory <dir>
Devices options
-j, --joystick <port>
Emulate joystick with cursor keys in given port (0-5)
--joy<port> <type>
Set joystick type (none/keys/real) for given port
--printer <file>
Enable printer support and write data to <file>
--midi <bool>
Whether to enable MIDI device support (when Hatari is built with PortMidi support)
--midi-in <filename>
Enable MIDI support and write raw MIDI data to <file> (when not built with PortMidi
support)
--midi-out <filename>
Enable MIDI support and read raw MIDI data from <file> (when not built with
PortMidi support)
--rs232-in <filename>
Enable MFP serial port support and use <file> as the input device
--rs232-out <filename>
Enable MFP serial port support and use <file> as the output device
--scc-b-out <filename>
Enable SCC channel B serial port support and use <file> for the output (only for
Mega-STE, TT and Falcon)
Floppy drive options
--drive-a <bool>
Enable/disable drive A (default is on)
--drive-b <bool>
Enable/disable drive B (default is on)
--drive-a-heads <x>
Set number of heads for drive A (1=single sided, 2=double sided)
--drive-b-heads <x>
Set number of heads for drive B (1=single sided, 2=double sided)
--disk-a <file>
Set disk image for floppy drive A
--disk-b <file>
Set disk image for floppy drive B
--fastfdc <bool>
speed up FDC emulation (can cause incompatibilities)
--protect-floppy <x>
Write protect floppy image contents (on/off/auto). With "auto" option write
protection is according to the disk image file attributes
Hard drive options
-d, --harddrive <dir>
GEMDOS HD emulation. Emulate harddrive partition(s) with <dir> contents. If
directory contains only single letter (C-Z) subdirectories, each of these
subdirectories will be treated as a separate partition, otherwise the given
directory itself will be assigned to drive "C:". In the multiple partition case,
the letters used as the subdirectory names will determine to which
drives/partitions they are assigned. If <dir> is an empty string, then harddrive's
emulation is disabled
--protect-hd <x>
Write protect harddrive <dir> contents (on/off/auto). With "auto" option the
protection can be controlled by setting individual files attributes as it disables
the file attribute modifications for the GEMDOS hard disk emulation
--gemdos-case <x>
Specify whether new dir/filenames are forced to be in upper or lower case with the
GEMDOS HD emulation. Off/upper/lower, off by default
--gemdos-time <x>
Specify what file modification timestamps should be used, emulation internal
(atari) ones, or ones from the machine (host) on which the machine is running.
While Atari emulation and host clocks are in sync at Hatari startup, they will
diverge while emulation is running, especially if you use fast forward. Default is
"atari". If you modify files accessed by the Atari side, directly from the host
side while Hatari is already running, you may want to use "host" option
--gemdos-conv <bool>
Whether GEMDOS file names with 8-bit (non-ASCII) characters are converted between
Atari and host character sets. On Linux, host file name character set is assumed to
be UTF-8. This option is disabled by default, in case you have transferred files
from Atari machine without proper file name conversion (e.g. by zipping them on
Atari and unzipping on PC)
--gemdos-drive <drive>
Assign (separately specified) GEMDOS HD to given drive letter (C-Z) instead of
default C:, or use "skip" to specify that Hatari should add GEMDOS HD after IDE and
ACSI drives (assumes Hatari and native HD driver parse same number of partitions
from the partition tables in HD images)
--acsi <id>=<file>
Emulate an ACSI hard disk with given BUS ID (0-7) using image <file>. If just a
filename is given, it is assigned to BUS ID 0
--scsi <id>=<file>
Emulate a SCSI hard disk with given BUS ID (0-7) using image <file>. If just a
filename is given, it is assigned to BUS ID 0
--ide-master <file>
Emulate an IDE 0 (master) hard disk with an image <file>
--ide-slave <file>
Emulate an IDE 1 (slave) hard disk with an image <file>
--ide-swap <id>=<x>
Set byte-swap option <x> (off/on/auto) for given IDE <id> (0/1). If just option is
given, it is applied to IDE 0
Memory options
--memstate <file>
Load memory snap-shot <file>
-s, --memsize <x>
Set amount of emulated ST RAM, x = 1 to 14 MiB, or 0 for 512 KiB. Other values are
considered as a size in KiB. While Hatari allows 14MB for all machine types, on
real HW, ST/STE can have up to 4MB, MegaSTE/TT up to 10MB and Falcon up to 14MB
RAM.
-s, --ttram <x>
Set amount of emulated TT RAM, x = 0 to 512 MiB (in 4MB steps)
ROM options
-t, --tos <imagefile>
Specify TOS ROM image to use
--patch-tos <bool>
Use this option to enable/disable TOS ROM patching. Experts only! Leave this
enabled unless you know what you are doing!
--cartridge <imagefile>
Use ROM cartridge image <file> (only works if GEMDOS HD emulation and extended VDI
resolution are disabled)
Common CPU options
--cpulevel <x>
Specify CPU (680x0) to use (use x >= 1 with EmuTOS or TOS >= 2.06 only!)
--cpuclock <x>
Set the CPU clock (8, 16 or 32 Mhz)
--compatible <bool>
Use a more compatible, but slower 68000 CPU mode with better prefetch accuracy and
cycle counting
WinUAE CPU core options
--cpu-exact <bool>
Use cycle exact CPU emulation (cache emulation)
--addr24 <bool>
Use 24-bit instead of 32-bit addressing mode (24-bit is enabled by default)
--fpu <x>
FPU type (x=none/68881/68882/internal)
--fpu-softfloat <bool>
Use full software FPU emulation (Softfloat library)
--mmu <bool>
Use MMU emulation
Misc system options
--machine <x>
Select machine type (x = st, megast, ste, megaste, tt or falcon)
--blitter <bool>
Enable blitter emulation (ST only)
--dsp <x>
Falcon DSP emulation (x = none, dummy or emu, Falcon only)
--timer-d <bool>
Patch redundantly high Timer-D frequency set by TOS. This about doubles Hatari
speed (for ST/e emulation) as the original Timer-D frequency causes most of the
interrupts.
--fast-boot <bool>
Patch TOS and initialize the so-called "memvalid" system variables to by-pass the
memory test of TOS, so that the system boots faster.
Sound options
--mic <bool>
Enable/disable (Falcon only) microphone
--sound <x>
Sound frequency: 6000-50066. "off" disables the sound and speeds up the emulation.
To prevent extra sound artifacts, the frequency should be selected so that it
either matches evenly with the STE/TT/Falcon sound DMA (6258, 12517, 250033, 50066
Hz) or your sound card frequencies (11025, 22050, 44100 or 6000...48000 Hz). Check
what your sound card supports.
--sound-buffer-size <x>
SDL's sound buffer size: 10-100, or 0 to use default buffer size. By default
Hatari uses an SDL buffer size of 1024 samples, which gives approximatively 20-30
ms of sound depending on the chosen sound frequency. Under some OS or with not
fully supported sound card, this default setting can cause a bigger delay at lower
frequency (nearly 0.5 sec). In that case, you can use this option to force the
size of the sound buffer to a fixed number of milliseconds of sound (using 20 is
often a good choice if you have such problems). Most users will not need this
option.
--sound-sync <bool>
The emulation rate is nudged by +100 or 0 or -100 micro-seconds on occasion. This
prevents the sound buffer from overflowing (long latency and lost samples) or
underflowing (short latency and repeated samples). The emulation rate smoothly
deviates by a maximum of 0.58% until synchronized, while the emulator continuously
generates every sound sample and the crystal controlled sound system consumes every
sample.
(on|off, off=default)
--ym-mixing <x>
Select a method for mixing the three YM2149 voice volumes together. "model" uses a
mathematical model of the YM voices, "table" uses a lookup table of audio output
voltage values measured on STF and "linear" just averages the 3 YM voices.
Debug options
-W, --wincon
Open console window (Windows only)
-D, --debug
Toggle whether CPU exceptions invoke the debugger
--debug-except <flags>
Specify which exceptions invoke debugger, see --debug-except help for available
(comma separated) exception flags.
--lilo <string>
Boot m68k Linux using kernel, ramdisk, and kernel arguments specified in the Hatari
configuration file [LILO] section. Hatari documentation folder contains an example
"lilo.cfg" config file for this. String given to the --lilo option is appended to
the kernel command line.
NOTE: This is Hatari (and Linux kernel) developer option to test Linux booting.
Unless you know how your kernel is configured, and the state of specific kernel and
Hatari features, don't expect m68k Linux to boot up successfully.
--bios-intercept <bool>
Enable/Disable XBios command parsing. XBios(11) Dbmsg call can be used to invoke
Hatari debugger. XBios(20) printscreen calls produce also Hatari screenshots.
XBios(255) allows Atari programs to use Hatari debugger functionality, which allows
e.g. invoking shortcuts and Hatari command line options. Last one is deprecated as
it gives too much control to emulated program, please use NatFeats and remote
control APIs (--natfeats, --cmd-fifo, hconsole) instead of XBios 11 and 255.
--conout <device>
Enable console (xconout vector functions) output redirection for given <device> to
host terminal. Device 2 is for the (CON:) VT52 console, which vector function
catches also EmuTOS panic messages and MiNT console output, not just normal BIOS
console output.
--disasm <x>
Set disassembly options. 'uae' and 'ext' select the disassembly engine to use,
bitmask sets output options for the external disassembly engine and 'help' lists
them.
--natfeats <bool>
Enable/disable (basic) Native Features support. EmuTOS uses it for debug output,
and it's supported also by the Aranym emulator. For more info, see example code
and readme.txt in tests/natfeats/ coming with Hatari sources.
--trace <flags>
Activate debug traces, see --trace help for available (comma separated) tracing
flags
--trace-file <file>
Save trace output to <file> (default=stderr)
--parse <file>
Parse/execute debugger commands from <file>
--saveconfig
Save Hatari configuration and exit. Hatari UI needs Hatari configuration file to
start, this can be used to create it automatically.
--no-parachute
Disable SDL parachute to get Hatari core dumps. SDL parachute is enabled by default
to restore video mode in case Hatari terminates abnormally while using non-standard
screen resolution.
--control-socket <path>
Hatari connects to given local socket file and reads commands from it. Use when
the control process life-time is longer than Hatari's, or control process needs
response from Hatari
--cmd-fifo <path>
Hatari creates the indicated FIFO file and reads commands from it. Commands can be
echoed to FIFO file, and are same as with the control socket. Hatari outputs help
for unrecognized commands and subcommands
--log-file <file>
Save log output to <file> (default=stderr)
--log-level <x>
Log output level (x=debug/todo/info/warn/error/fatal)
--alert-level <x>
Show dialog for log messages above given level
--run-vbls <x>
Exit after X VBLs. Often used with --benchmark option
--benchmark
Start in benchmark mode. Currently same as --fast-forward mode, except it can't be
disabled at run-time. Allows better measuring for the speed of the emulation in
frames per second. Unless you're specifically measuring emulator audio and screen
processing speed, disable them (--sound off/--disable-video on) to have as little
OS overhead as possible
INPUT HANDLING
Hatari provides special input handling for different purposes.
Emulated Atari ST joystick
Joystick can be emulated either with keyboard or any real joystick supported by your
kernel / SDL library. First joystick button acts as FIRE, second as SPACE key.
Emulated Atari ST mouse
Middle button mouse click is interpreted as double click, this is especially useful in
Fast Forward mode.
Mouse scrollwheel will act as cursor up and down keys.
Emulated Atari ST keyboard
Keys on the keyboard act as the normal Atari ST keys so pressing SPACE on your PC will
result in an emulated press of the SPACE key on the ST. How the PC keys are mapped to
Atari key codes, can be changed with keyboard config file (-k option).
The following keys have special meanings:
Alt will act as the ST's ALTERNATE key
left Ctrl
will act as the ST's CONTROL key
Print will emulate the ST's HELP key
Scroll lock
will emulate the ST's UNDO key
AltGr will act as Alternate as well as long as you do not press it together with a Hatari
hotkey combination.
The right Ctrl key is used as the fire button of the emulated joystick when you turn on
joystick emulation via keyboard.
The cursor keys will act as the cursor keys on the Atari ST as long as joystick emulation
via keyboard has been turned off.
Keyboard shortcuts during emulation
The shortcut keys can be configured in the configuration file. The default settings are:
AltGr + a
record animation
AltGr + g
grab a screenshot
AltGr + i
boss key: leave full screen mode and iconify window
AltGr + m
(un-)lock the mouse into the window
AltGr + r
warm reset the ST (same as the reset button)
AltGr + c
cold reset the ST (same as the power switch)
AltGr + d
open dialog to select/change disk A
AltGr + s
enable/disable sound
AltGr + q
quit the emulator
AltGr + x
toggle normal/max speed
AltGr + y
enable/disable sound recording
AltGr + k
save memory snapshot
AltGr + l
load memory snapshot
AltGr + j
toggle joystick emulation via cursor keys
AltGr + F1
switch joystick type on joy port 0
AltGr + F2
switch joystick type on joy port 1
AltGr + F3
switch joystick type for joypad A
AltGr + F4
switch joystick type for joypad B
AltGr + b
toggle borders on/off
AltGr + f or F11
toggle between fullscreen and windowed mode
AltGr + o or F12
activate the Hatari options GUI
You may need to hold SHIFT down while in windowed mode.
Pause Pauses the emulation
AltGr + Pause
Invokes the internal Hatari debugger
Keyboard shortcuts for the SDL GUI
There are multiple ways to interact with the SDL GUI.
TAB and cursor keys change focus between UI elements. Additionally Home key moves focus
to first item, End key to last one. Initially focus is on default UI element, but focus
changes are remembered between dialog invocations. Enter and Space invoke focused item. UI
elements with underlined characters can be invoked directly with Alt + key with that
character. Alt + arrow keys will act on arrow buttons.
Most importantly:
Options GUI main view
Enter accepts configuration, ESC cancels it.
Options GUI dialogs
Enter (or End+Enter if focus was moved) returns back to main view.
Fileselector
Page up and down keys scroll the file list. Enter on focused file name selects it.
Enter on OK button accepts the selected file. ESC cancels the dialog/selection.
Alert dialogs
Enter accepts and ESC cancels the dialog.
SEE ALSO
The main program documentation, usually in /usr/share/doc/. Among other things it
contains an extensive usage manual, software compatibility list and release notes.
The homepage of Hatari: http://hatari.tuxfamily.org/
Other Hatari programs and utilities:
hmsa(1), zip2st(1), atari-convert-dir(1), atari-hd-image(1), hatariui(1), hconsole(1),
gst2ascii(1), hatari_profile(1)
FILES AND DIRECTORIES
/etc/hatari.cfg (or /usr/local/etc/hatari.cfg)
The global configuration file of Hatari.
~/.config/hatari/
The (default) directory for user's personal Hatari files; hatari.cfg (configuration
file), hatari.nvram (NVRAM content file), hatari.sav (Hatari memory state snapshot
file which Hatari can load/save automatically when it starts/exits), hatari.prn
(printer output file),
/usr/share/hatari/ (or /usr/local/share/hatari/)
The global data directory of Hatari.
tos.img
The TOS ROM image will be loaded from the data directory of Hatari unless it is
specified on the command line or the configuration file.
AUTHOR
This manual page was written by Marco Herrn <marco@mherrn.de> for the Debian project and
later modified by Thomas Huth and Eero Tamminen to suit the latest version of Hatari.