HATARI(1) HATARI(1)
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
",
"--disk-a " and "-d --auto C:" 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
Whether Hatari confirms quitting
-c, --configfile
Read additional configuration values from , these override
values read from the global and user configuration files
-k, --keymap
Load keyboard mapping from . "Symbolic" mapping will be
used as fallback for keys not defined there
--country
Set EmuTOS ROM country code on Mega/ST/STe machines lacking
NVRAM, when EmuTOS indicates supporting multiple ones.
In 512k EmuTOS images, country code selects the TOS keyboard
layout and screen refresh (US = 60Hz NTSC, 50Hz PAL otherwise).
In 1024k EmuTOS images (coming with Hatari binaries and
supporting multiple languages), country code selects also TOS
language.
Alternatively, one can use "tos-lang-change" tool from EmuTOS
project to modify country code in the ROM image file itself.
That works also for TOS v4
--layout
Set NVRAM keyboard layout value. While both TT and Falcon
machines have NVRAM, only TOS v4 and EmuTOS 512k / 1024k ROM
versions support multiple layouts.
Regardless of whether keyboard layout change is done through the
ROM country code or NVRAM setting, it may impact your key
mappings in Hatari key mapping files, Hatari Python UI
arguments, or key injection in your automation scripts for
Hatari debugger, command FIFO or hconsole tool
--language
Set NVRAM language value. While both TT and Falcon machines have
NVRAM, only TOS v4 and EmuTOS 1024k ROM versions support
multiple languages. Default is taken from the LANG environment
variable
--fast-forward
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
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
Select monitor type (x = mono/rgb/vga/tv)
--tos-res
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
Allow window resizing
--borders
Show ST/STE/Falcon screen borders (for low/med resolution
overscan demos)
--frameskips
Skip frames after each displayed frame to accelerate
emulation (0=disabled, >4 uses automatic frameskip with given
value as maximum)
--slowdown
Slow down emulation by factor of x (used as multiplier for VBL
wait time)
--mousewarp
To keep host mouse better in sync with Atari mouse pointer,
center it to Hatari window on cold reset and resolution changes
--statusbar
Show statusbar (with floppy leds etc etc)
--drive-led
Show overlay drive led when statusbar isn't shown
--max-width
Preferred / maximum Hatari screen width
--max-height
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.
The 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
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 avoid zooming of low resolutions, 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
Force internal bitdepth (x = 8/15/16/32, 0=disable)
--disable-video
Run emulation without displaying video (audio only)
ST/STE specific display options
--spec512
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
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
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
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
Whether to do monitor aspect ratio correction (enabled by
default)
VDI options
--vdi
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
Use extended VDI resolution with bit depth (x = 1, 2 or 4)
--vdi-width
Use extended VDI resolution with width (320 < w <= 2048)
--vdi-height
Use extended VDI resolution with height (160 < 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 16/planes, and
height to multiple of 8 pixels (smaller system font height). That
translates to following maximum standard resolutions for the VDI mode:
monochrome
FullHD (1920x1080), 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
Remove statusbar from the screen captures
--avirecord
Start AVI recording. Note: recording will automatically stop
when emulation resolution changes.
--avi-vcodec
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
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
Force AVI frame rate (x = 50/60/71/...)
--avi-file
Use to record AVI
--screenshot-dir
Save screenshots in the directory
Devices options
-j, --joystick
Emulate joystick with cursor keys in given port (0-5)
--joy
Set joystick type (none/keys/real) for given port
--printer
Enable printer support and write data to
--midi
Whether to enable MIDI device support (when Hatari is built with
PortMidi support)
--midi-in
Enable MIDI support and write raw MIDI data to (when not
built with PortMidi support)
--midi-out
Enable MIDI support and read raw MIDI data from (when not
built with PortMidi support)
--rs232-in
Enable MFP serial port support and use as the input
device
--rs232-out
Enable MFP serial port support and use as the output
device
--scc-b-out
Enable SCC channel B serial port support and use for the
output (only for Mega-STE, TT and Falcon)
Floppy drive options
--drive-a
Enable/disable drive A (default is on)
--drive-b
Enable/disable drive B (default is on)
--drive-a-heads
Set number of heads for drive A (1=single sided, 2=double sided)
--drive-b-heads
Set number of heads for drive B (1=single sided, 2=double sided)
--disk-a
Set disk image for floppy drive A
--disk-b
Set disk image for floppy drive B
--fastfdc
speed up FDC emulation (can cause incompatibilities)
--protect-floppy
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
GEMDOS HD emulation. Emulate harddrive partition(s) with
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 is an empty
string, then harddrive's emulation is disabled
--protect-hd
Write protect harddrive 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
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
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
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
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 =
Emulate an ACSI hard disk with given BUS ID (0-7) using image
. If just a filename is given, it is assigned to BUS ID 0
--scsi =
Emulate a SCSI hard disk with given BUS ID (0-7) using image
. If just a filename is given, it is assigned to BUS ID 0
--ide-master
Emulate an IDE 0 (master) hard disk with an image
--ide-slave
Emulate an IDE 1 (slave) hard disk with an image
--ide-swap =
Set byte-swap option (off/on/auto) for given IDE (0/1).
If just option is given, it is applied to IDE 0
Memory options
--memstate
Load memory snap-shot
-s, --memsize
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 14 MiB for all machine types, on real HW, ST/STE
can have up to 4 MiB, MegaSTE/TT up to 10 MiB, and Falcon up to
14 MiB RAM.
-s, --ttram
Set amount of emulated TT RAM, x = 0 to 1024 MiB (in 4MiB steps)
ROM options
-t, --tos
Specify TOS ROM image to use
--patch-tos
Use this option to enable/disable TOS ROM patching. Experts
only! Leave this enabled unless you know what you are doing!
--cartridge
Use ROM cartridge image (only works if GEMDOS HD
emulation and extended VDI resolution are disabled)
CPU/FPU/bus options
--cpulevel
Specify CPU (680x0) to use (use x >= 1 with EmuTOS or TOS >=
2.06 only!)
--cpuclock
Set the CPU clock (8, 16 or 32 Mhz)
--compatible
Use a more compatible 68000 CPU mode with better prefetch
accuracy and cycle counting
--cpu-exact
Use cycle exact CPU emulation (cache emulation)
--addr24
Use 24-bit instead of 32-bit addressing mode (24-bit is enabled
by default)
--fpu
FPU type (x=none/68881/68882/internal)
--fpu-softfloat
Use full software FPU emulation (Softfloat library)
--mmu
Use MMU emulation
Misc system options
--machine
Select machine type (x = st, megast, ste, megaste, tt or falcon)
--blitter
Enable blitter emulation (ST only)
--dsp
Falcon DSP emulation (x = none, dummy or emu, Falcon only)
--vme
Hatari doesn't have proper MegaSTE/TT VME emulation yet, but
this controls access to related SCU registers (MegaSTE/TT only).
With "dummy", (no-op) access is allowed (=VME HW), otherwise TOS
v2 and v3 crash on bootup on MegaSTE and TT. Supports VME
tracing.
With "none", register access causes errors (=no VME HW), which
is needed for Linux to boot with TT emulation until there's full
SCU interrupt support. No VME tracing support.
--timer-d
Patch redundantly high Timer-D frequency set by TOS. This can
increase Hatari speed significantly (especially for ST/e
emulation) as the original Timer-D frequency causes large amount
of extra interrupts to emulate.
--fast-boot
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
Enable/disable (Falcon only) microphone
--sound
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
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
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
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
Specify which exceptions invoke debugger, see --debug-except
help for available (comma separated) exception flags.
--lilo
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
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
Enable console (xconout vector functions) output redirection for
given 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
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
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
Activate debug traces, see --trace help for available (comma
separated) tracing flags
--trace-file
Save trace output to (default=stderr)
--parse
Parse/execute debugger commands from
--saveconfig
Save Hatari configuration and exit. Hatari UI needs Hatari
configuration file to start, this can be used to create it
automatically.
--control-socket
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
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
Save log output to (default=stderr)
--log-level
Log output level (x=debug/todo/info/warn/error/fatal)
--alert-level
Show dialog for log messages above given level
--run-vbls
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 the focus between UI elements. Home key
moves focus to the first dialog item, End key to the last one.
Initially focus is on the default UI element, but focus changes are
remembered between dialog invocations.
Enter and Space invoke the focused item, ESC key invokes the dialog
cancel option (if there is one).
UI element which name has an underlined character can be invoked
directly by pressing Alt + key with that character. Alt + arrow keys
will act on dialog arrow buttons.
Main interactions:
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 move the file list by one page, mouse
wheel and Alt + cursor keys scroll it by one item. Enter on the
focused file name selects it. Enter on the 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 for the
Debian project and later modified by Thomas Huth and Eero Tamminen to
suit the latest version of Hatari.
Hatari 2020-11-27 HATARI(1)