1HATARI(1) HATARI(1)
2
3
4
6 hatari - Atari ST/STE/TT/Falcon emulator
7
8
10 hatari [options] [directory|diskimage|program]
11
12
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
17 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
22 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
28 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
35 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
40
42 Hatari options are split into several categories:
43
44
46 -h, --help
47 Print command line options and terminate
48
49 -v, --version
50 Print version information and terminate
51
52 --confirm-quit <bool>
53 Whether Hatari confirms quitting
54
55 -c, --configfile <filename>
56 Read additional configuration values from <file>, these override
57 values read from the global and user configuration files
58
59 -k, --keymap <file>
60 Load keyboard mapping from <file>
61
62 --fast-forward <bool>
63 On fast machine helps skipping (fast forwarding) Hatari output
64
65 --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
72
74 -m, --mono
75 Start in monochrome mode instead of color
76
77 --monitor <x>
78 Select monitor type (x = mono/rgb/vga/tv)
79
80 --tos-res <x>
81 Select TOS resolution for color monitors (x =
82 low/med/high/ttlow/ttmed)
83
84 -f, --fullscreen
85 Start the emulator in fullscreen mode
86
87 -w, --window
88 Start the emulator in windowed mode
89
90 --grab Grab mouse (also) in windowed mode
91
92 --resizable <bool>
93 Allow window resizing
94
95 NOTE: this is supported only by Hatari SDL2 build
96
97 --borders <bool>
98 Show ST/STE/Falcon screen borders (for low/med resolution over‐
99 scan demos)
100
101 --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
106 --slowdown <x>
107 Slow down emulation by factor of x (used as multiplier for VBL
108 wait time)
109
110 --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
114 --statusbar <bool>
115 Show statusbar (with floppy leds etc etc)
116
117 --drive-led <bool>
118 Show overlay drive led when statusbar isn't shown
119
120 --max-width <x>
121 Preferred / maximum window width for borders / zooming
122
123 --max-height <x>
124 Preferred / maximum window height for borders / zooming
125
126 --bpp <bool>
127 Force internal bitdepth (x = 8/15/16/32, 0=disable)
128
129 --disable-video <bool>
130 Run emulation without displaying video (audio only)
131
132
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
138 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
145 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
153 --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
158 -z, --zoom <x>
159 Zoom (double) low resolution (1=no, 2=yes)
160
161 --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
170
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
176 --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
182 --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
188 --aspect <bool>
189 Whether to do monitor aspect ratio correction (enabled by
190 default)
191
192
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
199 --vdi-planes <x>
200 Use extended VDI resolution with bit depth <x> (x = 1, 2 or 4)
201
202 --vdi-width <w>
203 Use extended VDI resolution with width <w> (320 < w <= 2048)
204
205 --vdi-height <h>
206 Use extended VDI resolution with height <h> (200 < h <= 1280)
207
208 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
214 monochrome
215 FullHD (1920×1080), WUXGA (1920x1200) and QWXGA (2048x1152)
216
217 2 plane mode (4 colors)
218 HD (1280x720), WXGA (1280x768) and XGA+ (1152x864)
219
220 4 plane mode (16-colors)
221 qHD (960x540), DVGA (960x640) and WSVGA (1024x600)
222
223
225 --crop <bool>
226 Remove statusbar from the screen captures
227
228 --avirecord
229 Start AVI recording. Note: recording will automatically stop
230 when emulation resolution changes.
231
232 --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
237 --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
244 --avi-fps <x>
245 Force AVI frame rate (x = 50/60/71/...)
246
247 --avi-file <file>
248 Use <file> to record AVI
249
250
252 -j, --joystick <port>
253 Emulate joystick with cursor keys in given port (0-5)
254
255 --joy<port> <type>
256 Set joystick type (none/keys/real) for given port
257
258 --printer <file>
259 Enable printer support and write data to <file>
260
261 --midi <bool>
262 Whether to enable MIDI support (PortMidi only)
263
264 --midi-in <filename>
265 Enable MIDI support and write raw MIDI data to <file> (Linux
266 only)
267
268 --midi-out <filename>
269 Enable MIDI support and read raw MIDI data from <file> (Linux
270 only)
271
272 --rs232-in <filename>
273 Enable MFP serial port support and use <file> as the input
274 device
275
276 --rs232-out <filename>
277 Enable MFP serial port support and use <file> as the output
278 device
279
280 --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
284
286 --drive-a <bool>
287 Enable/disable drive A (default is on)
288
289 --drive-b <bool>
290 Enable/disable drive B (default is on)
291
292 --drive-a-heads <x>
293 Set number of heads for drive A (1=single sided, 2=double sided)
294
295 --drive-b-heads <x>
296 Set number of heads for drive B (1=single sided, 2=double sided)
297
298 --disk-a <file>
299 Set disk image for floppy drive A
300
301 --disk-b <file>
302 Set disk image for floppy drive B
303
304 --fastfdc <bool>
305 speed up FDC emulation (can cause incompatibilities)
306
307 --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
312
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
324 --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
330 --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
335 --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
345 --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
353 --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
360 --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
364 --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
368 --ide-master <file>
369 Emulate an IDE 0 (master) hard disk with an image <file>
370
371 --ide-slave <file>
372 Emulate an IDE 1 (slave) hard disk with an image <file>
373
374 --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
378
380 --memstate <file>
381 Load memory snap-shot <file>
382
383 -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
387 -s, --ttram <x>
388 Set amount of emulated TT RAM, x = 0 to 512 MiB (in 4MB steps)
389
390
392 -t, --tos <imagefile>
393 Specify TOS ROM image to use
394
395 --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
399 --cartridge <imagefile>
400 Use ROM cartridge image <file> (only works if GEMDOS HD emula‐
401 tion and extended VDI resolution are disabled)
402
403
405 --cpulevel <x>
406 Specify CPU (680x0) to use (use x >= 1 with EmuTOS or TOS >=
407 2.06 only!)
408
409 --cpuclock <x>
410 Set the CPU clock (8, 16 or 32 Mhz)
411
412 --compatible <bool>
413 Use a more compatible, but slower 68000 CPU mode with better
414 prefetch accuracy and cycle counting
415
416
418 --cpu-exact <bool>
419 Use cycle exact CPU emulation (cache emulation)
420
421 --addr24 <bool>
422 Use 24-bit instead of 32-bit addressing mode (24-bit is enabled
423 by default)
424
425 --fpu <x>
426 FPU type (x=none/68881/68882/internal)
427
428 --fpu-softfloat <bool>
429 Use full software FPU emulation (Softfloat library)
430
431 --mmu <bool>
432 Use MMU emulation
433
434
436 --machine <x>
437 Select machine type (x = st, megast, ste, megaste, tt or falcon)
438
439 --blitter <bool>
440 Enable blitter emulation (ST only)
441
442 --dsp <x>
443 Falcon DSP emulation (x = none, dummy or emu, Falcon only)
444
445 --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
450 --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
455
457 --mic <bool>
458 Enable/disable (Falcon only) microphone
459
460 --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
468 --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
480 --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
490 --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
496
498 -W, --wincon
499 Open console window (Windows only)
500
501 -D, --debug
502 Toggle whether CPU exceptions invoke the debugger
503
504 --debug-except <flags>
505 Specify which exceptions invoke debugger, see --debug-except
506 help for available (comma separated) exception flags.
507
508 --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
515 --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
522 --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
527 --natfeats <bool>
528 Enable/disable (basic) Native Features support. E.g. EmuTOS
529 uses it for debug output.
530
531 --trace <flags>
532 Activate debug traces, see --trace help for available (comma
533 separated) tracing flags
534
535 --trace-file <file>
536 Save trace output to <file> (default=stderr)
537
538 --parse <file>
539 Parse/execute debugger commands from <file>
540
541 --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
546 --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
551 --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
556 --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
562 --log-file <file>
563 Save log output to <file> (default=stderr)
564
565 --log-level <x>
566 Log output level (x=debug/todo/info/warn/error/fatal)
567
568 --alert-level <x>
569 Show dialog for log messages above given level
570
571 --run-vbls <x>
572 Exit after X VBLs
573
574 --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
580
582 Hatari provides special input handling for different purposes.
583
584
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
590
592 Middle button mouse click is interpreted as double click, this is espe‐
593 cially useful in Fast Forward mode.
594
595 Mouse scrollwheel will act as cursor up and down keys.
596
597
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
604 The following keys have special meanings:
605
606 Alt will act as the ST's ALTERNATE key
607
608 left Ctrl
609 will act as the ST's CONTROL key
610
611 Print will emulate the ST's HELP key
612
613 Scroll lock
614 will emulate the ST's UNDO key
615
616 AltGr will act as Alternate as well as long as you do not press it
617 together with a Hatari hotkey combination.
618
619 The right Ctrl key is used as the fire button of the emulated joystick
620 when you turn on joystick emulation via keyboard.
621
622 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
625
627 The shortcut keys can be configured in the configuration file. The
628 default settings are:
629
630 AltGr + a
631 record animation
632
633 AltGr + g
634 grab a screenshot
635
636 AltGr + i
637 boss key: leave full screen mode and iconify window
638
639 AltGr + m
640 (un-)lock the mouse into the window
641
642 AltGr + r
643 warm reset the ST (same as the reset button)
644
645 AltGr + c
646 cold reset the ST (same as the power switch)
647
648 AltGr + d
649 open dialog to select/change disk A
650
651 AltGr + s
652 enable/disable sound
653
654 AltGr + q
655 quit the emulator
656
657 AltGr + x
658 toggle normal/max speed
659
660 AltGr + y
661 enable/disable sound recording
662
663 AltGr + k
664 save memory snapshot
665
666 AltGr + l
667 load memory snapshot
668
669 AltGr + j
670 toggle joystick emulation via cursor keys
671
672 AltGr + F1
673 switch joystick type on joy port 0
674
675 AltGr + F2
676 switch joystick type on joy port 1
677
678 AltGr + F3
679 switch joystick type for joypad A
680
681 AltGr + F4
682 switch joystick type for joypad B
683
684 AltGr + b
685 toggle borders on/off
686
687 AltGr + f or F11
688 toggle between fullscreen and windowed mode
689
690 AltGr + o or F12
691 activate the Hatari options GUI
692 You may need to hold SHIFT down while in windowed mode.
693
694 Pause Pauses the emulation
695
696 AltGr + Pause
697 Invokes the internal Hatari debugger
698
699
701 There are multiple ways to interact with the SDL GUI.
702
703 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
710 Most importantly:
711
712 Options GUI main view
713 Enter accepts configuration, ESC cancels it.
714
715 Options GUI dialogs
716 Enter (or End+Enter if focus was moved) returns back to main
717 view.
718
719 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
724 Alert dialogs
725 Enter accepts and ESC cancels the dialog.
726
727
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
733 The homepage of Hatari: http://hatari.tuxfamily.org/
734
735 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
739
741 /etc/hatari.cfg (or /usr/local/etc/hatari.cfg)
742 The global configuration file of Hatari.
743
744 ~/.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
753 /usr/share/hatari/ (or /usr/local/share/hatari/)
754 The global data directory of Hatari.
755
756 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
761
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.
766
767
768
769Hatari 2014-05-08 HATARI(1)