1HATARI(1) HATARI(1)
2
6 hatari - Atari ST/STE/TT/Falcon emulator
7
10 hatari [options] [directory|diskimage|program]
11
14 Hatari is an Atari ST/STE/TT/Falcon emulator for Linux, FreeBSD, BeOS
15 and other Systems which are supported by the SDL library.
16 With Hatari one can run games, demos or applications written for Atari
18 ST, STE or Falcon. Atari TT support is experimental. Hatari supports
19 the commonly used *.st, *.msa and *.stx disk images, and hard disk emu‐
20 lation.
21 To run the emulator a TOS ROM image is needed. EmuTOS, a free implemen‐
23 tation of TOS is shipped with Hatari. It boots faster than original TOS
24 versions, but some buggy (floppy only) programs won't work correctly
25 with it. For best compatibility, it is recommended to use a TOS ROM
26 from a real Atari.
27 As an argument, one can give either a name of a directory that should
29 be emulated as a virtual GEMDOS hard disk, a floppy disk image or an
30 Atari program that should be autostarted. In the last case the pro‐
31 gram's directory will be used as the C: drive from where this program
32 will be started. These shortcuts correspond to "-d <dir>", "--disk-a
33 <floppy image>" and "-d <dir> --auto C:<program>" options.
34 Booting will be done from the disk image or directory that's given last
36 on the command line as an option or the argument (and which corresponds
37 to A: or C:). If you want to give floppy image name with an autostart‐
38 ing program name, give it with --disk-a option before the program name.
39
42 Hatari options are split into several categories:
43
46 -h, --help
47 Print command line options and terminate
48 -v, --version
50 Print version information and terminate
51 --confirm-quit <bool>
53 Whether Hatari confirms quitting
54 -c, --configfile <filename>
56 Read additional configuration values from <file>, these override
57 values read from the global and user configuration files
58 -k, --keymap <file>
60 Load keyboard mapping from <file>
61 --fast-forward <bool>
63 On fast machine helps skipping (fast forwarding) Hatari output
64 --auto <program>
66 Autostarts given program, if TOS finds it. Program needs to be
67 given with full path it will have under emulation, for example
68 "C:\DIR\PROGRAM.PRG". This is implemented by providing TOS a
69 virtual INF file, including that path as what TOS should start
70 automatically
71
74 -m, --mono
75 Start in monochrome mode instead of color
76 --monitor <x>
78 Select monitor type (x = mono/rgb/vga/tv)
79 --tos-res <x>
81 Select TOS resolution for color monitors (x =
82 low/med/high/ttlow/ttmed)
83 -f, --fullscreen
85 Start the emulator in fullscreen mode
86 -w, --window
88 Start the emulator in windowed mode
89 --grab Grab mouse (also) in windowed mode
91 --resizable <bool>
93 Allow window resizing
94 NOTE: this is supported only by Hatari SDL2 build
96 --borders <bool>
98 Show ST/STE/Falcon screen borders (for low/med resolution over‐
99 scan demos)
100 --frameskips <x>
102 Skip <x> frames after each displayed frame to accelerate emula‐
103 tion (0=disabled, >4 uses automatic frameskip with given value
104 as maximum)
105 --slowdown <x>
107 Slow down emulation by factor of x (used as multiplier for VBL
108 wait time)
109 --mousewarp <bool>
111 To keep host mouse better in sync with Atari mouse pointer, cen‐
112 ter it to Hatari window on cold reset and resolution changes
113 --statusbar <bool>
115 Show statusbar (with floppy leds etc etc)
116 --drive-led <bool>
118 Show overlay drive led when statusbar isn't shown
119 --max-width <x>
121 Preferred / maximum window width for borders / zooming
122 --max-height <x>
124 Preferred / maximum window height for borders / zooming
125 --bpp <bool>
127 Force internal bitdepth (x = 8/15/16/32, 0=disable)
128 --disable-video <bool>
130 Run emulation without displaying video (audio only)
131
134 --desktop-st <bool>
135 NOTE: this has effect only for SDL1 Hatari build. In SDL2
136 build, --desktop option controls also ST/STe mode.
137 Whether to use desktop resolution on fullscreen to avoid issues
139 related to resolution switching (messing multi-screen setups,
140 several seconds delay needed for resolution switching by some
141 LCD monitors and the resulting sound break). Otherwise
142 fullscreen will use a resolution that is closest to the Hatari
143 window size.
144 As Hatari ST/STe display code doesn't support zooming (except
146 low-rez doubling), it doesn't get scaled (by Hatari or monitor)
147 when this is enabled, and you may get large black borders around
148 ST/STe screen. Therefore this is mainly useful only if you suf‐
149 fer from the described effects, but still want to grab mouse and
150 remove other distractions from the screen just by toggling
151 fullscreen mode. (disabled by default)
152 --spec512 <x>
154 Hatari uses this threshold to decide when to render a screen
155 with the slower but more accurate Spectrum512 screen conversion
156 functions (0 <= x <= 512, 0=disable)
157 -z, --zoom <x>
159 Zoom (double) low resolution (1=no, 2=yes)
160 --video-timing <x>
162 Wakeup State for MMU/GLUE (x=ws1/ws2/ws3/ws4/random, default
163 ws3). When powering on, the STF will randomly choose one of
164 these wake up states. The state will then affect the timings
165 where border removals and other video tricks should be made,
166 which can give different results on screen. For example, WS3 is
167 known to be compatible with many demos, while WS1 can show more
168 problems.
169
172 Zooming to sizes specified below is internally done using integer scal‐
173 ing factors. This means that different Atari resolutions may show up
174 with different sizes, but they are never blurry.
175 --desktop <bool>
177 Whether to use desktop resolution on fullscreen to avoid issues
178 related to resolution switching. Otherwise fullscreen will use a
179 resolution that is closest to the Hatari window size. (enabled
180 by default)
181 --force-max <bool>
183 Hatari window size is forced to specified maximum size and black
184 borders used when Atari resolution doesn't scale evenly to it.
185 This is most useful when recording videos of Falcon demos that
186 change their resolution. (disabled by default)
187 --aspect <bool>
189 Whether to do monitor aspect ratio correction (enabled by
190 default)
191
194 --vdi <bool>
195 Whether to use VDI screen mode. Doesn't work with TOS v4. TOS
196 v3 memory detection isn't compatible with larger VDI modes (i.e.
197 you need to skip the detection at boot)
198 --vdi-planes <x>
200 Use extended VDI resolution with bit depth <x> (x = 1, 2 or 4)
201 --vdi-width <w>
203 Use extended VDI resolution with width <w> (320 < w <= 2048)
204 --vdi-height <h>
206 Use extended VDI resolution with height <h> (200 < h <= 1280)
207 TOS and some popular GEM programs add extra restrictions for the VDI
209 screen size. In total screen can take at maximum 300kB, width needs to
210 be multiple of 128/planes, and height multiple of 16 pixels (or 8,
211 depending on system font height). That translates to following maximum
212 standard resolutions for the VDI mode:
213 monochrome
215 FullHD (1920×1080), WUXGA (1920x1200) and QWXGA (2048x1152)
216 2 plane mode (4 colors)
218 HD (1280x720), WXGA (1280x768) and XGA+ (1152x864)
219 4 plane mode (16-colors)
221 qHD (960x540), DVGA (960x640) and WSVGA (1024x600)
222
225 --crop <bool>
226 Remove statusbar from the screen captures
227 --avirecord
229 Start AVI recording. Note: recording will automatically stop
230 when emulation resolution changes.
231 --avi-vcodec <x>
233 Select AVI video codec (x = bmp/png). PNG compression can be
234 much slower than using the uncompressed BMP format, but uncom‐
235 pressed video content takes huge amount of space.
236 --png-level <x>
238 Select PNG compression level for AVI video (x = 0-9). Both com‐
239 pression efficiency and speed depend on the compressed screen
240 content. Highest compression level (9) can be really slow with
241 some content. Levels 3-6 should compress nearly as well with
242 clearly smaller CPU overhead.
243 --avi-fps <x>
245 Force AVI frame rate (x = 50/60/71/...)
246 --avi-file <file>
248 Use <file> to record AVI
249
252 -j, --joystick <port>
253 Emulate joystick with cursor keys in given port (0-5)
254 --joy<port> <type>
256 Set joystick type (none/keys/real) for given port
257 --printer <file>
259 Enable printer support and write data to <file>
260 --midi <bool>
262 Whether to enable MIDI support (PortMidi only)
263 --midi-in <filename>
265 Enable MIDI support and write raw MIDI data to <file> (Linux
266 only)
267 --midi-out <filename>
269 Enable MIDI support and read raw MIDI data from <file> (Linux
270 only)
271 --rs232-in <filename>
273 Enable MFP serial port support and use <file> as the input
274 device
275 --rs232-out <filename>
277 Enable MFP serial port support and use <file> as the output
278 device
279 --scc-b-out <filename>
281 Enable SCC channel B serial port support and use <file> for the
282 output (only for Mega-STE, TT and Falcon)
283
286 --drive-a <bool>
287 Enable/disable drive A (default is on)
288 --drive-b <bool>
290 Enable/disable drive B (default is on)
291 --drive-a-heads <x>
293 Set number of heads for drive A (1=single sided, 2=double sided)
294 --drive-b-heads <x>
296 Set number of heads for drive B (1=single sided, 2=double sided)
297 --disk-a <file>
299 Set disk image for floppy drive A
300 --disk-b <file>
302 Set disk image for floppy drive B
303 --fastfdc <bool>
305 speed up FDC emulation (can cause incompatibilities)
306 --protect-floppy <x>
308 Write protect floppy image contents (on/off/auto). With "auto"
309 option write protection is according to the disk image file
310 attributes
311
314 -d, --harddrive <dir>
315 GEMDOS HD emulation. Emulate harddrive partition(s) with <dir>
316 contents. If directory contains only single letter (C-Z) subdi‐
317 rectories, each of these subdirectories will be treated as a
318 separate partition, otherwise the given directory itself will be
319 assigned to drive "C:". In the multiple partition case, the let‐
320 ters used as the subdirectory names will determine to which
321 drives/partitions they are assigned. If <dir> is an empty
322 string, then harddrive's emulation is disabled
323 --protect-hd <x>
325 Write protect harddrive <dir> contents (on/off/auto). With
326 "auto" option the protection can be controlled by setting indi‐
327 vidual files attributes as it disables the file attribute modi‐
328 fications for the GEMDOS hard disk emulation
329 --gemdos-case <x>
331 Specify whether new dir/filenames are forced to be in upper or
332 lower case with the GEMDOS HD emulation. Off/upper/lower, off by
333 default
334 --gemdos-time <x>
336 Specify what file modification timestamps should be used, emula‐
337 tion internal (atari) ones, or ones from the machine (host) on
338 which the machine is running. While Atari emulation and host
339 clocks are in sync at Hatari startup, they will diverge while
340 emulation is running, especially if you use fast forward.
341 Default is "atari". If you modify files accessed by the Atari
342 side, directly from the host side while Hatari is already run‐
343 ning, you may want to use "host" option
344 --gemdos-conv <bool>
346 Whether GEMDOS file names with 8-bit (non-ASCII) characters are
347 converted between Atari and host character sets. On Linux, host
348 file name character set is assumed to be UTF-8. This option is
349 disabled by default, in case you have transferred files from
350 Atari machine without proper file name conversion (e.g. by zip‐
351 ping them on Atari and unzipping on PC)
352 --gemdos-drive <drive>
354 Assign (separately specified) GEMDOS HD to given drive letter
355 (C-Z) instead of default C:, or use "skip" to specify that
356 Hatari should add GEMDOS HD after IDE and ACSI drives (assumes
357 Hatari and native HD driver parse same number of partitions from
358 the partition tables in HD images)
359 --acsi <id>=<file>
361 Emulate an ACSI hard disk with given BUS ID (0-7) using image
362 <file>. If just a filename is given, it is assigned to BUS ID 0
363 --scsi <id>=<file>
365 Emulate a SCSI hard disk with given BUS ID (0-7) using image
366 <file>. If just a filename is given, it is assigned to BUS ID 0
367 --ide-master <file>
369 Emulate an IDE 0 (master) hard disk with an image <file>
370 --ide-slave <file>
372 Emulate an IDE 1 (slave) hard disk with an image <file>
373 --ide-swap <id>=<x>
375 Set byte-swap option <x> (off/on/auto) for given IDE <id> (0/1).
376 If just option is given, it is applied to IDE 0
377
380 --memstate <file>
381 Load memory snap-shot <file>
382 -s, --memsize <x>
384 Set amount of emulated ST RAM, x = 1 to 14 MiB, or 0 for 512
385 KiB. Other values are considered as a size in KiB
386 -s, --ttram <x>
388 Set amount of emulated TT RAM, x = 0 to 512 MiB (in 4MB steps)
389
392 -t, --tos <imagefile>
393 Specify TOS ROM image to use
394 --patch-tos <bool>
396 Use this option to enable/disable TOS ROM patching. Experts
397 only! Leave this enabled unless you know what you are doing!
398 --cartridge <imagefile>
400 Use ROM cartridge image <file> (only works if GEMDOS HD emula‐
401 tion and extended VDI resolution are disabled)
402
405 --cpulevel <x>
406 Specify CPU (680x0) to use (use x >= 1 with EmuTOS or TOS >=
407 2.06 only!)
408 --cpuclock <x>
410 Set the CPU clock (8, 16 or 32 Mhz)
411 --compatible <bool>
413 Use a more compatible, but slower 68000 CPU mode with better
414 prefetch accuracy and cycle counting
415
418 --cpu-exact <bool>
419 Use cycle exact CPU emulation (cache emulation)
420 --addr24 <bool>
422 Use 24-bit instead of 32-bit addressing mode (24-bit is enabled
423 by default)
424 --fpu <x>
426 FPU type (x=none/68881/68882/internal)
427 --fpu-softfloat <bool>
429 Use full software FPU emulation (Softfloat library)
430 --mmu <bool>
432 Use MMU emulation
433
436 --machine <x>
437 Select machine type (x = st, megast, ste, megaste, tt or falcon)
438 --blitter <bool>
440 Enable blitter emulation (ST only)
441 --dsp <x>
443 Falcon DSP emulation (x = none, dummy or emu, Falcon only)
444 --timer-d <bool>
446 Patch redundantly high Timer-D frequency set by TOS. This about
447 doubles Hatari speed (for ST/e emulation) as the original Timer-
448 D frequency causes most of the interrupts.
449 --fast-boot <bool>
451 Patch TOS and initialize the so-called "memvalid" system vari‐
452 ables to by-pass the memory test of TOS, so that the system
453 boots faster.
454
457 --mic <bool>
458 Enable/disable (Falcon only) microphone
459 --sound <x>
461 Sound frequency: 6000-50066. "off" disables the sound and speeds
462 up the emulation. To prevent extra sound artifacts, the fre‐
463 quency should be selected so that it either matches evenly with
464 the STE/TT/Falcon sound DMA (6258, 12517, 250033, 50066 Hz) or
465 your sound card frequencies (11025, 22050, 44100 or 6000...48000
466 Hz). Check what your sound card supports.
467 --sound-buffer-size <x>
469 SDL's sound buffer size: 10-100, or 0 to use default buffer
470 size. By default Hatari uses an SDL buffer size of 1024 sam‐
471 ples, which gives approximatively 20-30 ms of sound depending on
472 the chosen sound frequency. Under some OS or with not fully sup‐
473 ported sound card, this default setting can cause a bigger delay
474 at lower frequency (nearly 0.5 sec). In that case, you can use
475 this option to force the size of the sound buffer to a fixed
476 number of milliseconds of sound (using 20 is often a good choice
477 if you have such problems). Most users will not need this
478 option.
479 --sound-sync <bool>
481 The emulation rate is nudged by +100 or 0 or -100 micro-seconds
482 on occasion. This prevents the sound buffer from overflowing
483 (long latency and lost samples) or underflowing (short latency
484 and repeated samples). The emulation rate smoothly deviates by
485 a maximum of 0.58% until synchronized, while the emulator con‐
486 tinuously generates every sound sample and the crystal con‐
487 trolled sound system consumes every sample.
488 (on|off, off=default)
489 --ym-mixing <x>
491 Select a method for mixing the three YM2149 voice volumes
492 together. "model" uses a mathematical model of the YM voices,
493 "table" uses a lookup table of audio output voltage values mea‐
494 sured on STF and "linear" just averages the 3 YM voices.
495
498 -W, --wincon
499 Open console window (Windows only)
500 -D, --debug
502 Toggle whether CPU exceptions invoke the debugger
503 --debug-except <flags>
505 Specify which exceptions invoke debugger, see --debug-except
506 help for available (comma separated) exception flags.
507 --bios-intercept <bool>
509 Enable/Disable XBios command parsing. Allows Atari programs to
510 use all Hatari functionality and change Hatari state through
511 Hatari specific XBios(255) calls. XBios(20) printscreen calls
512 produce also Hatari screenshots. XBios(11) Dbmsg call can be
513 used to invoke the debugger.
514 --conout <device>
516 Enable console (xconout vector functions) output redirection for
517 given <device> to host terminal. Device 2 is for the (CON:)
518 VT52 console, which vector function catches also EmuTOS panic
519 messages and MiNT console output, not just normal BIOS console
520 output.
521 --disasm <x>
523 Set disassembly options. 'uae' and 'ext' select the dissasembly
524 engine to use, bitmask sets output options for the external dis‐
525 assembly engine and 'help' lists them.
526 --natfeats <bool>
528 Enable/disable (basic) Native Features support. E.g. EmuTOS
529 uses it for debug output.
530 --trace <flags>
532 Activate debug traces, see --trace help for available (comma
533 separated) tracing flags
534 --trace-file <file>
536 Save trace output to <file> (default=stderr)
537 --parse <file>
539 Parse/execute debugger commands from <file>
540 --saveconfig
542 Save Hatari configuration and exit. Hatari UI needs Hatari con‐
543 figuration file to start, this can be used to create it automat‐
544 ically.
545 --no-parachute
547 Disable SDL parachute to get Hatari core dumps. SDL parachute is
548 enabled by default to restore video mode in case Hatari termi‐
549 nates abnormally while using non-standard screen resolution.
550 --control-socket <path>
552 Hatari connects to given local socket file and reads commands
553 from it. Use when the control process life-time is longer than
554 Hatari's, or control process needs response from Hatari
555 --cmd-fifo <path>
557 Hatari creates the indicated FIFO file and reads commands from
558 it. Commands can be echoed to FIFO file, and are same as with
559 the control socket. Hatari outputs help for unrecognized com‐
560 mands and subcommands
561 --log-file <file>
563 Save log output to <file> (default=stderr)
564 --log-level <x>
566 Log output level (x=debug/todo/info/warn/error/fatal)
567 --alert-level <x>
569 Show dialog for log messages above given level
570 --run-vbls <x>
572 Exit after X VBLs
573 --benchmark
575 Start in benchmark mode (use with --run-vbls). This allows to
576 measure the speed of the emulation in frames per second by run‐
577 ning at maximum speed (don't wait for VBL). Disable audio/video
578 output to have as little OS overhead as possible
579
582 Hatari provides special input handling for different purposes.
583
586 Joystick can be emulated either with keyboard or any real joystick sup‐
587 ported by your kernel / SDL library. First joystick button acts as
588 FIRE, second as SPACE key.
589
592 Middle button mouse click is interpreted as double click, this is espe‐
593 cially useful in Fast Forward mode.
594 Mouse scrollwheel will act as cursor up and down keys.
596
599 Keys on the keyboard act as the normal Atari ST keys so pressing SPACE
600 on your PC will result in an emulated press of the SPACE key on the ST.
601 How the PC keys are mapped to Atari key codes, can be changed with key‐
602 board config file (-k option).
603 The following keys have special meanings:
605 Alt will act as the ST's ALTERNATE key
607 left Ctrl
609 will act as the ST's CONTROL key
610 Print will emulate the ST's HELP key
612 Scroll lock
614 will emulate the ST's UNDO key
615 AltGr will act as Alternate as well as long as you do not press it
617 together with a Hatari hotkey combination.
618 The right Ctrl key is used as the fire button of the emulated joystick
620 when you turn on joystick emulation via keyboard.
621 The cursor keys will act as the cursor keys on the Atari ST as long as
623 joystick emulation via keyboard has been turned off.
624
627 The shortcut keys can be configured in the configuration file. The
628 default settings are:
629 AltGr + a
631 record animation
632 AltGr + g
634 grab a screenshot
635 AltGr + i
637 boss key: leave full screen mode and iconify window
638 AltGr + m
640 (un-)lock the mouse into the window
641 AltGr + r
643 warm reset the ST (same as the reset button)
644 AltGr + c
646 cold reset the ST (same as the power switch)
647 AltGr + d
649 open dialog to select/change disk A
650 AltGr + s
652 enable/disable sound
653 AltGr + q
655 quit the emulator
656 AltGr + x
658 toggle normal/max speed
659 AltGr + y
661 enable/disable sound recording
662 AltGr + k
664 save memory snapshot
665 AltGr + l
667 load memory snapshot
668 AltGr + j
670 toggle joystick emulation via cursor keys
671 AltGr + F1
673 switch joystick type on joy port 0
674 AltGr + F2
676 switch joystick type on joy port 1
677 AltGr + F3
679 switch joystick type for joypad A
680 AltGr + F4
682 switch joystick type for joypad B
683 AltGr + b
685 toggle borders on/off
686 AltGr + f or F11
688 toggle between fullscreen and windowed mode
689 AltGr + o or F12
691 activate the Hatari options GUI
692 You may need to hold SHIFT down while in windowed mode.
693 Pause Pauses the emulation
695 AltGr + Pause
697 Invokes the internal Hatari debugger
698
701 There are multiple ways to interact with the SDL GUI.
702 TAB and cursor keys change focus between UI elements. Additionally
704 Home key moves focus to first item, End key to last one. Initially
705 focus is on default UI element, but focus changes are remembered
706 between dialog invocations. Enter and Space invoke focused item. UI
707 elements with underlined characters can be invoked directly with Alt +
708 key with that character. Alt + arrow keys will act on arrow buttons.
709 Most importantly:
711 Options GUI main view
713 Enter accepts configuration, ESC cancels it.
714 Options GUI dialogs
716 Enter (or End+Enter if focus was moved) returns back to main
717 view.
718 Fileselector
720 Page up and down keys scroll the file list. Enter on focused
721 file name selects it. Enter on OK button accepts the selected
722 file. ESC cancels the dialog/selection.
723 Alert dialogs
725 Enter accepts and ESC cancels the dialog.
726
729 The main program documentation, usually in /usr/share/doc/. Among
730 other things it contains an extensive usage manual, software compati‐
731 bility list and release notes.
732 The homepage of Hatari: http://hatari.tuxfamily.org/
734 Other Hatari programs and utilities:
736 hmsa(1), zip2st(1), atari-convert-dir(1), atari-hd-image(1), hatar‐
737 iui(1), hconsole(1), gst2ascii(1), hatari_profile(1)
738
741 /etc/hatari.cfg (or /usr/local/etc/hatari.cfg)
742 The global configuration file of Hatari.
743 ~/.hatari/
745 The (default) directory for user's personal Hatari files;
746 hatari.cfg (configuration file), hatari.nvram (NVRAM content
747 file), hatari.sav (Hatari memory state snapshot file which
748 Hatari can load/save automatically when it starts/exits),
749 hatari.prn (printer output file), hatari.wav (recorded sound
750 output in WAV format), hatari.ym (recorded sound output in YM
751 format).
752 /usr/share/hatari/ (or /usr/local/share/hatari/)
754 The global data directory of Hatari.
755 tos.img
757 The TOS ROM image will be loaded from the data directory of
758 Hatari unless it is specified on the command line or the config‐
759 uration file.
760
763 This manual page was written by Marco Herrn <marco@mherrn.de> for the
764 Debian project and later modified by Thomas Huth and Eero Tamminen to
765 suit the latest version of Hatari.
766Hatari 2014-05-08 HATARI(1)