Provided by: hatari_2.1.0+dfsg-1_amd64 bug


       hatari - Atari ST/STE/TT/Falcon emulator


       hatari [options] [directory|diskimage|program]


       Hatari  is  an  Atari ST/STE/TT/Falcon emulator for Linux, FreeBSD, BeOS and other Systems
       which are supported by the SDL 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, but some buggy (floppy
       only) programs won't work correctly with it.  For best compatibility, it's 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 as an option or the argument (and which corresponds to A: or C:). If you want to give
       floppy  image  name with an autostarting program name, give it with --disk-a option before
       the program name.


       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>
              On fast machine helps skipping (fast forwarding) Hatari output

       --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, including that path as what TOS
              should start automatically

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 window width for borders / zooming

       --max-height <x>
              Preferred / maximum window height for borders / zooming

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

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

       -z, --zoom <x>
              Zoom (double) low resolution (1=no, 2=yes)

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

       --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 <= 1280)

       --vdi-height <h>
              Use extended VDI resolution with height <h> (200 < h <= 960)

Screen capture options

       --crop <bool>
              Remove statusbar from the screen captures

              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

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 support (PortMidi only)

       --midi-in <filename>
              Enable MIDI support and write raw MIDI data to <file> (Linux only)

       --midi-out <filename>
              Enable MIDI support and read raw MIDI data from <file> (Linux only)

       --rs232-in <filename>
              Enable serial port support and use <file> as the input device

       --rs232-out <filename>
              Enable serial port support and use <file> as the output device

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're 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've 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  (seprately  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 HD images partition tables)

       --acsi <id>=<file>
              Emulate an ACSI hard disk with given BUS ID (0-7)  using  image  <file>.   If  just
              filename is given, it's assigned to BUS ID 0

       --ide-master <file>
              Emulate an IDE master hard disk with an image <file>

       --ide-slave <file>
              Emulate an IDE slave hard disk with an image <file>

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

       -s, --ttram <x>
              Set amount of emulated TT RAM, x = 0 to 256 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)

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

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

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

              Toggle XBios command parsing. Allows Atari programs to use all Hatari functionality
              and change  Hatari  state  through  Hatari  specifit  XBios(255)  calls.  XBios(20)
              printscreen calls produce also Hatari screenshots.

       --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  dissasembly  engine  to  use,
              bitmask  sets  output  options for the external disassembly engine and 'help' lists

       --natfeats <bool>
              Enable/disable (basic) Native Features support.  E.g.  EmuTOS  uses  it  for  debug

       --trace <flags>
              Activate  debug  traces,  see  --trace help for available (comma separated) tracing

       --trace-file <file>
              Save trace output to <file> (default=stderr)

       --parse <file>
              Parse/execute debugger commands from <file>

              Save Hatari configuration and exit. Hatari UI needs Hatari  configuration  file  to
              start, this can be used to create it automatically.

              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 <file>
              Hatari reads options from given socket at run-time

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

              Start  in  benchmark mode (use with --run-vbls).  Allows measuring the speed of the
              emulation in frames per second by running at maximum speed (don't  wait  for  VBL).
              Disable audio/video output to have as little OS overhead as possible


       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.

              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.


       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:

       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)


       /etc/hatari.cfg (or /usr/local/etc/hatari.cfg)
              The global configuration file of 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), hatari.wav (recorded sound output in WAV format),  hatari.ym
              (recorded sound output in YM format).

       /usr/share/hatari/ (or /usr/local/share/hatari/)
              The global data directory of Hatari.

              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.


       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.