Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
HATARI(1)							     HATARI(1)

       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 and *.msa	disk images and	hard disk emulation.

       To run the emulator a TOS ROM image is needed. EmuTOS, a	free implemen-
       tation of TOS is	shipped	with hatari. Since it is not yet fully compat-
       ible with the original TOS, some	programs won't run correctly with  it.
       Because of this 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 di-
       rectory will be used as the C: drive from where this  program  will  be

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

Common display options
       -m, --mono
	      Start in monochrome mode instead of color

       --monitor <x>
	      Select monitor type (x = mono/rgb/vga/tv)

       -f, --fullscreen
	      Start the	emulator in fullscreen mode

       -w, --window
	      Start the	emulator in windowed mode

       --grab Grab mouse (also)	in windowed mode

       --borders <bool>
	      Show  ST/STE/Falcon screen borders (for low/med resolution over-
	      scan demos)

       --frameskips <x>
	      Skip <x> frames after each displayed frame to accelerate	emula-
	      tion  (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, cen-
	      ter 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)

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

       -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

TT/Falcon specific display options
       Zooming to sizes	specified below	is internally done using integer scal-
       ing  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  de-

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)

       --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	uncom-
	      pressed video content takes huge amount of space.

       --png-level <x>
	      Select PNG compression level for AVI video (x = 0-9).  Both com-
	      pression	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-in <filename>
	      Enable MIDI support and write MIDI data to <file>

       --midi-out <filename>
	      Enable MIDI support and read MIDI	data from <file>

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

Hard drive options
       -d, --harddrive <dir>
	      Emulate harddrive	partition(s) with <dir>	contents.   If	direc-
	      tory  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	 indi-
	      vidual  files attributes as it disables the file attribute modi-
	      fications	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

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

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

       -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	emula-
	      tion 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, ste,	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 vari-
	      ables to by-pass the memory test of  TOS,	 so  that  the	system
	      boots faster.

       --rtc <bool>
	      Enable real-time clock

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  fre-
	      quency  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 sam-
	      ples, which gives	approximatively	20-30 ms of sound depending on
	      the chosen sound frequency. Under	some OS	or with	not fully sup-
	      ported 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  op-

       --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 con-
	      tinuously	generates every	sound  sample  and  the	 crystal  con-
	      trolled sound system consumes every sample.
	      (on|off, off=default)

       --ym-mixing <x>
	      Select  a	 method	 for mixing the	three YM2149 voice volumes to-
	      gether.  "model" uses a mathematical model  of  the  YM  voices,
	      "table"  uses a lookup table of audio output voltage values mea-
	      sured 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

       --disasm	<x>
	      Set disassembly options.	'uae' and 'ext'	select the dissasembly
	      engine to	use, bitmask sets output options for the external dis-
	      assembly engine and 'help' lists them.

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

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

	      Save Hatari configuration	and exit. Hatari UI needs Hatari  con-
	      figuration file to start,	this can be used to create it automat-

	      Disable SDL parachute to get Hatari core dumps. SDL parachute is
	      enabled  by  default to restore video mode in case Hatari	termi-
	      nates 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

       Hatari provides special input handling for different purposes.

Emulated Atari ST joystick
       Joystick	can be emulated	either with keyboard or	any real joystick sup-
       ported  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 espe-
       cially 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 key-
       board 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  to-
       gether 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 de-
       fault 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

       F11    toggle between fullscreen	and windowed mode

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

	      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/local/share/doc/.
       Among other things it contains an extensive usage manual, software com-
       patibility 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),	hatar-
       iui(1), hconsole(1), gst2ascii(1), hatari_profile(1)

	      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

       /usr/local/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 config-
	      uration 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.

Hatari				  2014-05-08			     HATARI(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | General options | Common display options | ST/STE specific display options | TT/Falcon specific display options | VDI options | Screen capture options | Devices options | Floppy drive options | Hard drive options | Memory options | ROM options | Common CPU options | WinUAE CPU core options | Misc system options | Sound options | Debug options | INPUT HANDLING | Emulated Atari ST joystick | Emulated Atari ST mouse | Emulated Atari ST keyboard | Keyboard shortcuts during emulation | Keyboard shortcuts for the SDL GUI | SEE ALSO | FILES AND DIRECTORIES | AUTHOR

Want to link to this manual page? Use this URL:

home | help