![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to manual.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [HATARI the Atari ST Emulator] / hatari / doc|
Return to manual.html CVS log | Up to [HATARI the Atari ST Emulator] / hatari / doc |
1.1 root 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2: <html>
3: <head>
4: <title>Hatari User's Manual</title>
1.1.1.3 root 5: <meta name="description"
6: content="User's manual for the Atari ST emulator Hatari">
1.1.1.8 root 7: <meta name="author" content="Hatari development team">
1.1 root 8: <meta name="keywords" content="hatari, documentation, manual, linux">
9: <meta name="resource-type" content="document">
10: <meta name="distribution" content="global">
1.1.1.5 root 11: <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15">
1.1 root 12: <meta http-equiv="Content-Style-Type" content="text/css">
13: <style type="text/css">
14: <!--
1.1.1.11 root 15: body { background:#FFFFFF;
1.1.1.2 root 16: color:#000000;
1.1.1.7 root 17: margin-left:10px;
1.1.1.2 root 18: margin-right:10px;
1.1.1.8 root 19: font-family:Verdana,Arial,Helvetica,sans-serif;
1.1.1.2 root 20: }
1.1 root 21:
1.1.1.8 root 22: h2 { border-bottom:solid thin black;}
23: h4.gui { clear:right }
1.1.1.10 root 24: h5 { margin-bottom:2px; margin-left:1em; }
25:
26: pre { color: black;
1.1.1.11 root 27: background:#eeeeee;
1.1.1.10 root 28: margin: 0px 20px 8px 20px;
29: padding: 2px 8px 1px 8px;
30: border: solid thin #ccaa88;
31: }
1.1 root 32:
1.1.1.8 root 33: td { font-family:Verdana,Arial,Helvetica,sans-serif; }
1.1 root 34:
1.1.1.11 root 35: a:link { color:#000099; background:#ffffff; text-decoration:none; }
36: a:visited { color:#cc0000; background:#ffffff; text-decoration:none;}
37: a:hover { color:#0000ff; background:#ffffff; text-decoration:none; }
38: a:active { color:#993399; background:#ffffff; text-decoration:none; }
39:
1.1.1.12 root 40: .pageheader { text-align:center; }
1.1.1.11 root 41: .commandline { font-family:Courier,monospace; font-size:90% }
42: .file { color: #000088;}
43: .button { color:#000000; background:#c0c0c0; border:outset thin gray; font-family:Courier,monospace; padding-left:1em; padding-right:1em;}
44: .key { color:#550000; font-family:Courier,monospace; font-size:90% }
45: .backdropped { background:#ffffee; }
46: .image {margin-left: 5px; margin-right: 5px; border-width:2px; border-style:solid; border-color:#eeeeff; padding:1cm; text-align:center; }
47: .floatimage { clear:right; float:right; margin-left:0.5cm; border-width:2px; border-style:solid; border-color:#eeeeff; padding:0.5cm; }
1.1 root 48:
49: -->
50: </style>
51: </head>
1.1.1.5 root 52:
53: <body>
54:
1.1.1.12 root 55: <h1 class="pageheader">Hatari User's Manual</h1>
1.1.1.5 root 56:
1.1.1.12 root 57: <p class="pageheader">
1.1.1.13! root 58: Version 1.5
1.1.1.3 root 59: </p>
1.1.1.12 root 60: <p class="pageheader">
1.1.1.8 root 61: Manual written by: <strong>Thomas Huth</strong>, <strong>Matthias Arndt</strong>
1.1.1.10 root 62: & <strong>Eero Tamminen</strong>
1.1.1.2 root 63: </p>
1.1.1.12 root 64: <p class="pageheader">
1.1.1.9 root 65: Hatari on the WWW: <strong><a href="http://hatari.berlios.de/"
66: target="_blank">http://hatari.berlios.de/</a></strong>
1.1.1.2 root 67: </p>
1.1 root 68:
1.1.1.5 root 69: <h2>Index</h2>
70: <ul>
71: <li><a href="#Introduction">Introduction</a>
72: <ul>
73: <li><a href="#General description">General description</a>
74: <li><a href="#Features">Features</a>
1.1.1.7 root 75: <li><a href="#STE hardware emulation">STE hardware emulation</a>
1.1.1.12 root 76: <li><a href="#TT hardware emulation">Experimental TT hardware emulation</a>
77: <li><a href="#Falcon hardware emulation">Falcon hardware emulation</a>
1.1.1.5 root 78: <li><a href="#System requirements">System requirements</a>
79: </ul>
80: <li><a href="#Compiling and running">Compiling and running</a>
81: <ul>
82: <li><a href="#Compiling Hatari">Compiling Hatari</a>
83: <li><a href="#Installation of a TOS ROM">Installation of a TOS ROM</a>
84: <li><a href="#Installation of the binary">Installation of the binary</a>
85: <li><a href="#Running Hatari for the first time">Running Hatari for the first time</a>
86: </ul>
1.1.1.13! root 87: <li><a href="#Command line options">Command line options and arguments</a>
1.1.1.5 root 88: <li><a href="#Using the emulated system">Using the emulated system</a>
89: <ul>
90: <li><a href="#The GUI">The GUI</a>
91: <ul>
92: <li><a href="#The Main Menu">The Main Menu</a>
1.1.1.10 root 93: <li><a href="#The File Selector Dialog">The File Selector Dialog</a>
1.1.1.5 root 94: <li><a href="#The System Dialog">The System Dialog</a>
1.1.1.10 root 95: <li><a href="#The Floppy Disks Dialog">The Floppy Disks Dialog</a>
96: <li><a href="#The Hard Disks Dialog">The Hard Disks Dialog</a>
1.1.1.5 root 97: <li><a href="#The Memory Dialog">The Memory Dialog</a>
98: <li><a href="#The ROM Dialog">The ROM Dialog</a>
99: <li><a href="#The Joystick Dialog">The Joystick Dialog</a>
1.1.1.12 root 100: <li><a href="#The Atari Monitor Dialog">The Atari Monitor Dialog</a>
101: <li><a href="#The Hatari Screen Dialog">The Hatari Screen Dialog</a>
1.1.1.5 root 102: <li><a href="#The Keyboard Dialog">The Keyboard Dialog</a>
103: <li><a href="#The Sound Dialog">The Sound Dialog</a>
104: <li><a href="#The Devices Dialog">The Devices Dialog</a>
105: </ul>
106: <li><a href="#Keyboard shortcuts">Keyboard shortcuts</a>
107: <li><a href="#Emulated Atari ST keyboard">Emulated Atari ST keyboard</a>
108: <li><a href="#Emulated mouse">Emulated mouse</a>
109: <li><a href="#Emulated joystick">Emulated joystick</a>
110: <li><a href="#Emulated video">Emulated video</a>
111: <li><a href="#Emulated printer">Emulated printer</a>
112: <li><a href="#Emulated RS232">Emulated RS232</a>
113: </ul>
114: <li><a href="#Floppy disk images">Floppy disk images</a>
115: <li><a href="#Hard disk support">Hard disk support</a>
1.1.1.6 root 116: <ul>
117: <li><a href="#GEMDOS based hard disk emulation">GEMDOS based hard disk emulation</a></li>
1.1.1.10 root 118: <li><a href="#ACSI hard disk emulation">ACSI hard disk emulation</a></li>
119: <li><a href="#IDE hard disk emulation">IDE hard disk emulation</a></li>
1.1.1.12 root 120: </ul>
121: <li><a href="#Moving files to/from hard disk images">Moving files to/from hard disk images</a>
122: <ul>
123: <li><a href="#Using HD Driver with GEMDOS partitions">Using HD Driver with GEMDOS partitions</a></li>
124: <li><a href="#Accessing HDD image partitions outside of Hatari">Accessing HDD image partitions outside of Hatari</a></li>
1.1.1.10 root 125: </ul>
126: <li><a href="#The debugger">The debugger</a>
1.1.1.12 root 127: <ul>
128: <li><a href="#General debugger use">General debugger use</a>
129: <li><a href="#Inspecting emulation state">Inspecting emulation state</a>
130: <li><a href="#Debug symbols">Debug symbols</a>
131: <li><a href="#Breakpoints">Breakpoints</a>
132: <li><a href="#Tracing">Tracing</a>
1.1.1.13! root 133: <li><a href="#Profiling">Profiling</a>
! 134: <li><a href="#Usage examples">Usage examples</a>
1.1.1.12 root 135: <li><a href="#Build notes">Build notes</a>
136: </ul>
1.1.1.10 root 137: <li><a href="#Performance">Performance</a>
138: <ul>
139: <li><a href="#Improving Hatari performance">Improving Hatari performance</a>
1.1.1.13! root 140: <li><a href="#Emulation options">Emulation options</a>
! 141: <li><a href="#Emulator options">Emulator options</a>
1.1.1.10 root 142: <li><a href="#Measuring the performance">Measuring the performance</a>
1.1.1.6 root 143: </ul>
1.1.1.5 root 144: <li><a href="#Appendix">Appendix</a>
145: <ul>
146: <li><a href="#Copying">Copying</a>
147: <li><a href="#Introduction to Emulation">Introduction to Emulation</a>
148: </ul>
149: </ul>
150:
151:
152: <a name="Introduction"></a><h2>Introduction</h2>
1.1 root 153:
1.1.1.5 root 154: <a name="General description"></a><h3>General description</h3>
1.1 root 155: <p>
1.1.1.13! root 156: Hatari is an Atari ST, STE, TT and Falcon emulator for Linux, OSX,
! 157: Windows and other Systems which are supported by the SDL library.
1.1.1.4 root 158: The emulator is open source software and is distributed under the terms of the
1.1.1.7 root 159: <a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU General
160: Public License (GPL)</a>.
1.1.1.4 root 161: </p>
162: <p>
1.1.1.3 root 163: The Atari ST was a 16/32 bit computer system which was first released by Atari
1.1.1.4 root 164: in 1985. Using the Motorola 68000 CPU, it was a very popular computer having
165: quite a lot of CPU power at that time. See Appendix B for details on emulation
166: in general.
1.1.1.3 root 167: </p>
168: <p>
1.1.1.4 root 169: Unlike many other Atari ST emulators which try to give you a good
170: environment for running GEM applications, Hatari tries to emulate the hardware
171: of a ST as close as possible so that it is able to run most of the old ST games
172: and demos. Of course you can run normal GEM applications with Hatari, too.
1.1.1.13! root 173: Recent versions of Hatari even feature STE, Falcon and basic TT emulation.
1.1 root 174: </p>
175:
1.1.1.5 root 176: <a name="Features"></a><h3>Features</h3>
1.1 root 177: <ul>
1.1.1.7 root 178: <li>68000 - 68040 emulation via the UAE CPU core (no PMMU support though)</li>
179: <li>ST RAM size variable (from 512kiB up to 14MiB are possible)</li>
1.1.1.3 root 180: <li>optional cartridge images for the ST ROM port</li>
1.1.1.2 root 181: <li>most of the ST specific hardware</li>
1.1 root 182: <li>ST Shifter with ST-High, ST-Medium and ST-Low resolutions,
1.1.1.7 root 183: overscan effects for all borders in color resolutions</li>
1.1.1.6 root 184: <li>512 color ST palette</li>
1.1.1.13! root 185: <li>Spec512 mode support for low and medium resolutions</li>
1.1.1.7 root 186: <li>many raster effects </li>
1.1.1.8 root 187: <li>scaling of low resolutions by factor two</li>
1.1.1.7 root 188: <li>interleaved lines rendering of ST-medium and (scaled) ST-low
189: resolutions for the TV "monitor type"</li>
1.1.1.8 root 190: <li>Blitter chip emulation</li>
1.1.1.2 root 191: <li>PSG YM2149 emulation (soundchip) including STFM samples</li>
1.1.1.8 root 192: <li>Printer port emulation on hardware level (print to file)</li>
1.1.1.10 root 193: <li>RS232 emulation</li>
194: <li>MIDI input/output/through emulation</li>
1.1 root 195: <li>Mega ST real time clock</li>
1.1.1.3 root 196: <li>IKBD emulation (keyboard, mouse and joystick) with custom
1.1.1.7 root 197: keyboard mapping</li>
1.1 root 198: <li>joystick emulation via cursor keys and joystick emulation via a
1.1.1.7 root 199: connected PC joystick</li>
1.1.1.3 root 200: <li>FDC emulation using floppy disk images in standard formats (*.ST,
1.1.1.7 root 201: *.MSA and *.DIM)</li>
1.1.1.5 root 202: <li>support for packed disk images (PkZip and Gzip)</li>
1.1.1.12 root 203: <li>optional write-protection for floppy disk images</li>
1.1.1.2 root 204: <li>partial ACSI emulation for harddisk support</li>
1.1.1.12 root 205: <li>GEMDOS interface driver to mount directories as harddrives
206: with optional write-protection</li>
1.1.1.7 root 207: <li>support for memory snapshots (save whole system state)</li>
1.1.1.2 root 208: <li>driver for extended VDI resolutions</li>
209: <li>recording of sound as .WAV and .YM files</li>
1.1.1.8 root 210: <li>screenshots in PNG or BMP format</li>
1.1.1.12 root 211: <li>AVI animation capturing with sound</li>
1.1.1.8 root 212: <li>TOS versions 1.00, 1.02, 1.04 and 2.06 (and EmuTOS) can be used in ST mode.</li>
1.1 root 213: </ul>
1.1.1.5 root 214:
1.1.1.7 root 215: <a name="STE hardware emulation"></a>
216: <h4>STE hardware emulation</h4>
1.1.1.13! root 217: <p>There is support for following additional STE features:</p>
1.1.1.5 root 218: <ul>
219: <li>horizontal and vertical hardware fine scrolling</li>
220: <li>split screen techniques / in-screen video address manipulations</li>
1.1.1.8 root 221: <li>(STE specific) left border opening</li>
1.1.1.5 root 222: <li>4096 colors STE palette</li>
1.1.1.12 root 223: <li>Stereo DMA sample sound</li>
224: <li>Experimental Microwire/LMC1992 emulation</li>
1.1.1.7 root 225: <li>STE joypads</li>
1.1.1.8 root 226: <li>TOS versions 1.06, 1.62, 2.05 and 2.06 (and EmuTOS) can be used in STE mode.</li>
1.1.1.5 root 227: </ul>
228:
1.1.1.12 root 229: <a name="TT hardware emulation"></a>
230: <h4>Experimental TT hardware emulation</h4>
1.1.1.13! root 231: <p>There is support for following additional TT features:</p>
1.1.1.7 root 232: <ul>
233: <li>TT low/med/high resolution support</li>
234: <li>ST/TT palette switching and video shifter</li>
235: <li>RAM upto 14MiB (ST-RAM only, there is no support for TT-RAM yet)</li>
1.1.1.8 root 236: <li>Only TOS version 3.06 (and EmuTOS) can be used in TT mode.</li>
1.1.1.7 root 237: </ul>
238:
1.1.1.12 root 239: <a name="Falcon hardware emulation"></a>
240: <h4>Falcon hardware emulation</h4>
1.1.1.13! root 241: <p>There is support for following additional Falcon features:</p>
1.1.1.7 root 242: <ul>
1.1.1.12 root 243: <li>Partial Videl emulation for all Falcon screen modes</li>
244: <li>Aspect correction and scaling of small resolutions by an integer factor</li>
1.1.1.7 root 245: <li>STE/Falcon palette switching and shifter</li>
246: <li>Mono/RGB/VGA/TV monitor types</li>
1.1.1.12 root 247: <li>DSP co-processor emulation</li>
248: <li>Experimental microphone (jack) emulation</li>
249: <li>Experimental Crossbar sound matrix (ADC (mic & PSG), DAC, DMA, DSP)
250: interconnect emulation + support for the additional DMA sound
251: sample rates</li>
252: <li>Experimental IDE master and slave emulation for harddisk support</li>
1.1.1.8 root 253: <li>TOS versions 4.00, 4.02, 4.04 and 4.92 (and EmuTOS) can be used in Falcon mode.</li>
1.1.1.7 root 254: </ul>
255:
1.1.1.12 root 256: <p>See the developers' <span class="file">doc/todo.txt</span> file
257: (included with Hatari sources) for the details on the few remaining
258: emulation gaps and the <a href="compatibility.html">Hatari Atari
259: Software Compatibility List</a> for which Atari programs are known
260: to be affected by them.</p>
1.1.1.5 root 261:
262:
263: <a name="System requirements"></a><h3>System requirements</h3>
264:
1.1.1.13! root 265: <p> Hatari currently has the following minimum system requirements:</p>
1.1 root 266: <ul>
1.1.1.12 root 267: <li>a fast PC (>500MHz, for Falcon and TT emulation
268: <a href="#Performance">even faster</a>)</li>
1.1.1.3 root 269: <li>some sort of Unix (preferable <a href="http://www.linux.org/">GNU/Linux</a>)
270: </li>
1.1 root 271: <li>the SDL library (<a href="http://www.libsdl.org/">http://www.libsdl.org/</a>)</li>
1.1.1.3 root 272: <li>the zLib (<a href="http://www.gzip.org/zlib/">http://www.gzip.org/zlib/</a>)
1.1.1.12 root 273: for support of ZIP-packed disk images (*.zip and *.gz)</li>
1.1 root 274: </ul>
1.1.1.5 root 275:
276: <p>
1.1.1.13! root 277: Earlier versions of Hatari have successfully been tested by various people on
1.1.1.5 root 278: the following systems:
279: </p>
1.1 root 280: <ul>
1.1.1.8 root 281: <li>Linux/i86 with Kernel 2.4.x and 2.6.x</li>
282: <li>Linux/PPC with Kernel 2.4.x and 2.6.x</li>
1.1.1.2 root 283: <li>BeOS/i86 </li>
1.1.1.13! root 284: <li>Apple Mac OS X on PowerPC and i86</li>
1.1 root 285: <li>NetBSD 1.6 </li>
1.1.1.4 root 286: <li>NetBSD on a Digital Alpha</li>
1.1.1.8 root 287: <li>FreeBSD 4.1 on an i486, FreeBSD 4.8 on a Pentium 4 and FreeBSD 5.1</li>
1.1.1.2 root 288: <li>OpenBSD 3.5 </li>
1.1.1.4 root 289: <li>Solaris 8 on a SUN UltraSparc 1</li>
1.1.1.8 root 290: <li>Linux/ARM (oabi) on Sharp Zaurus SL-C760 PDA</li>
1.1.1.12 root 291: <li>Linux/ARM (eabi) on Nokia Maemo Internet Tablets and N900 phone</li>
1.1 root 292: </ul>
1.1.1.5 root 293:
294: <a name="Compiling and running"></a><h2>Compiling and running</h2>
295:
296: <a name="Compiling Hatari"></a><h3>Compiling Hatari</h3>
297:
1.1.1.13! root 298: <p>Required:</p>
! 299: <ul>
! 300: <li>A C compiler. Preferably GCC, but others have worked too.</li>
! 301: <li>A working CMake installation. See
! 302: <a href="http://www.cmake.org/">http://www.cmake.org/</a> for details.
! 303: <li>The SDL library v1.2.10 or newer. You can get it from
! 304: <a href="http://www.libsdl.org/">http://www.libsdl.org/</a>.
! 305: </li>
! 306: <li>The zLib compression library. You can get it from
! 307: <a href="http://www.gzip.org/zlib/">http://www.gzip.org/zlib/</a>.
! 308: </li>
! 309: </ul>
! 310:
! 311: <p>Optional:</p>
! 312: <ul>
! 313: <li>The PNG image library for PNG format screenshots and to
! 314: decrease AVI video recording file sizes. You can get it from
! 315: <a href="http://www.libpng.org/">http://www.libpng.org/</a>.</li>
! 316: <li>The GNU Readline library for Hatari debugger command line editing.</li>
! 317: <li>The Xlib library to support Hatari Python UI window embedding
! 318: on systems with the X window system (Linux and other unixes).</li>
! 319: <li>The portaudio library for Falcon microphone recording support</li>
! 320: </ul>
! 321: <p>
! 322: The versions available in your Linux distribution will be sufficient
! 323: in most cases, but make sure you have also the header files installed
! 324: for the libraries as well! Typically they're in a corresponding -dev
! 325: package.
1.1.1.3 root 326: </p>
1.1.1.13! root 327:
! 328: <p>
! 329: After you've verified that you have the required libraries and their
! 330: development files, change to the <span class="file">hatari/</span>
! 331: directory. Create a <span class="file">build/</span> directory under
! 332: it and configure the build system for your environment:
1.1.1.10 root 333: <pre>
1.1.1.13! root 334: mkdir -p build
! 335: cd build
! 336: cmake ..
1.1.1.10 root 337: </pre>
1.1.1.3 root 338: <p>
339: Then compile Hatari by typing <span class="commandline">make</span>.
1.1.1.13! root 340: If all works fine, you'll get the executable <span class="commandline">hatari</span>
1.1.1.3 root 341: in the src/ subdirectory.
1.1.1.2 root 342: </p>
1.1.1.13! root 343: <p>
! 344: Note: Instead of calling CMake directly, you can also use the supplied
! 345: configure script to run CMake and to give the arguments (like install
! 346: prefix) in a format familiar from GNU Autotools using programs. Type
! 347: "<span class="commandline">./configure --help</span>"
! 348: to see all the options supported by this script.
! 349: </p>
1.1.1.5 root 350:
351: <a name="Installation of a TOS ROM"></a><h3>Installation of a TOS ROM</h3>
352:
1.1.1.6 root 353: <p>
354: Before you can start Hatari, you have to copy a TOS ROM image to the data
1.1.1.13! root 355: directory (<span class="file"><prefix>/share/hatari/</span>, by
! 356: default <span class="file">/usr/local/share/hatari/</span>) and
1.1.1.3 root 357: rename it to <span class="commandline">tos.img</span>, or use the
358: <span class="commandline">--tos</span> command line option to tell
359: Hatari where to find a TOS ROM.
1.1 root 360: Hatari needs a TOS ROM image because this contains the operating system
1.1.1.6 root 361: of the emulated Atari.
362: </p>
363: <p>
364: Unfortunately it is not possible to ship an original ROM
1.1.1.5 root 365: image with the Hatari package since these images are still copyrighted.
366: But you can easily create an image with a real ST and one of those various
1.1.1.12 root 367: ROM-image programs for the ST (search for "TOSDUMP" with your
1.1.1.5 root 368: favourite internet search engine). If your old ST does not work anymore, you
369: can also try to search the internet directly for corresponding TOS ROM image,
370: but don't ask the Hatari team where to get one. </p>
371: <p> Another solution is EmuTOS, which is also shipped with the official
372: release versions of Hatari. EmuTOS is an open-source TOS clone. You can find
373: it at:
374: <a href="http://emutos.sourceforge.net/">http://emutos.sourceforge.net/</a>.
375: It is not the best solution for playing games or running other old software
1.1.1.8 root 376: due to compatibility issues (see <span class="file">emutos.txt</span> for
377: more details), but it's free and compatible with Hatari.</p>
1.1 root 378: <p>If you do not specify a TOS image on the commandline nor can Hatari
379: find a suitable TOS image in the default dir, you'll get the chance to
380: select a TOS image file from the GUI. </p>
1.1.1.5 root 381:
382: <a name="Installation of the binary"></a><h3>Installation of the binary</h3>
383:
1.1.1.13! root 384: <p> Type <span class="commandline">make install</span> as "root" user to
! 385: do a systemwide installation.</p>
! 386: <p>Assuming you didn't change the default installation prefix and that
! 387: <span class="file">/usr/local/bin/</span> is in your PATH, you should
! 388: be now able to start the Hatari executable from anywhere.</p>
1.1 root 389: <p> When you finally have got a TOS image, try starting Hatari with the
1.1.1.3 root 390: option <span class="commandline">--help</span> to find out more about
391: its command line parameters. </p>
1.1.1.5 root 392:
393: <a name="Running Hatari for the first time"></a><h3>Running Hatari for the first time</h3>
394:
1.1.1.3 root 395: <p> Now type <span class="commandline">hatari</span> to run the
396: emulator for the first time. If all goes
397: well, you should now be presented with a window showing you the
398: familiar
399: little green desktop of the Atari ST. Press <span class="key">F12</span>
400: to turn on the GUI to
401: configure Hatari to suit your needs, press <span class="key">F11</span>
402: to toggle windowed and fullscreen mode. </p>
1.1.1.5 root 403:
1.1.1.13! root 404: <a name="Command line options"></a><h2>Command line options
! 405: and arguments</h2>
1.1.1.5 root 406:
1.1.1.7 root 407: <p>Usage:</p>
408: <pre>
1.1.1.13! root 409: hatari [options] [disk image | directory | Atari program ]
1.1.1.7 root 410: </pre>
411:
1.1.1.13! root 412: <p>As an argument one can give either a name of:</p>
! 413: <ul>
! 414: <li>A floppy disk image,
! 415: <li>A directory that should be emulated as a virtual GEMDOS hard disk, or</li>
! 416: <li>An Atari program that should be autostarted. In this case
! 417: the program's directory will be used as the C: drive from
! 418: where this program will be started.
! 419: (Note that autostarting a program might not work if you've also
! 420: specified a floppy image for drive A: on command line or in config
! 421: file which contains a desktop.inf/newdesk.inf/emutos.inf file on
! 422: it.)</li>
! 423: </ul>
! 424:
! 425: <p>Booting will be done from the disk image or directory that's given
! 426: last on the command line as an option or the argument (and which
! 427: corresponds to A: or C:).</p>
! 428:
1.1.1.8 root 429: <p>Hatari command line options are split into several categories:</p>
1.1.1.7 root 430:
1.1.1.8 root 431: <!--
432: Generated from hatari.1 options section by changing subheaders to h3
433: and removing extra paragraphs:
434: groff -man -Thtml hatari.1 | awk '
435: /OPTIONS<\/h/ { out = 1; next }
436: /INDENTATION/ { next }
437: /COMMANDS/ { out = 0; next }
438: { if(out) print }' | sed -e 's/h2/h3/g' -e 's/<\/*p>//g'
439: -->
440:
441: <a name="General options"></a>
442: <h3>General options</h3>
443: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 444: cellspacing="0" cellpadding="0">
1.1.1.8 root 445: <tr valign="top" align="left">
446: <td width="10%"></td>
447: <td width="89%">
1.1.1.12 root 448: <b>-h, --help</b></td>
1.1.1.8 root 449: </table>
450: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 451: cellspacing="0" cellpadding="0">
1.1.1.8 root 452: <tr valign="top" align="left">
453: <td width="21%"></td>
454: <td width="77%">
455: Print command line options and terminate
456: </td>
457: </table>
458: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 459: cellspacing="0" cellpadding="0">
1.1.1.8 root 460: <tr valign="top" align="left">
461: <td width="10%"></td>
462: <td width="89%">
1.1.1.12 root 463: <b>-v, --version</b></td>
1.1.1.8 root 464: </table>
465: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 466: cellspacing="0" cellpadding="0">
1.1.1.8 root 467: <tr valign="top" align="left">
468: <td width="21%"></td>
469: <td width="77%">
470: Print version information and terminate
471: </td>
472: </table>
473: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 474: cellspacing="0" cellpadding="0">
1.1.1.8 root 475: <tr valign="top" align="left">
476: <td width="10%"></td>
477: <td width="89%">
1.1.1.12 root 478: <b>--confirm-quit <bool></b></td>
1.1.1.8 root 479: </table>
480: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 481: cellspacing="0" cellpadding="0">
1.1.1.8 root 482: <tr valign="top" align="left">
483: <td width="21%"></td>
484: <td width="77%">
485: Whether Hatari confirms quitting
486: </td>
487: </table>
488: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 489: cellspacing="0" cellpadding="0">
1.1.1.8 root 490: <tr valign="top" align="left">
491: <td width="10%"></td>
492: <td width="89%">
1.1.1.12 root 493: <b>-c, --configfile
1.1.1.8 root 494: <filename></b></td>
495: </table>
496: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 497: cellspacing="0" cellpadding="0">
1.1.1.8 root 498: <tr valign="top" align="left">
499: <td width="21%"></td>
500: <td width="77%">
501: use the given file as configuration file instead of
502: ~/.hatari/hatari.cfg
503: </td>
504: </table>
505: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 506: cellspacing="0" cellpadding="0">
1.1.1.8 root 507: <tr valign="top" align="left">
508: <td width="10%"></td>
509: <td width="89%">
1.1.1.13! root 510: <b>-k, --keymap
! 511: <file></b></td>
1.1.1.8 root 512: </table>
513: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 514: cellspacing="0" cellpadding="0">
1.1.1.8 root 515: <tr valign="top" align="left">
516: <td width="21%"></td>
517: <td width="77%">
1.1.1.13! root 518: load keyboard mapping from <file>
1.1.1.8 root 519: </td>
520: </table>
1.1.1.13! root 521:
! 522: <a name="Common display options"></a>
! 523: <h3>Common display options</h3>
1.1.1.8 root 524: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 525: cellspacing="0" cellpadding="0">
1.1.1.8 root 526: <tr valign="top" align="left">
527: <td width="10%"></td>
528: <td width="89%">
1.1.1.12 root 529: <b>-m, --mono</b></td>
1.1.1.8 root 530: </table>
531: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 532: cellspacing="0" cellpadding="0">
1.1.1.8 root 533: <tr valign="top" align="left">
534: <td width="21%"></td>
535: <td width="77%">
536: Start in monochrome mode instead of color
537: </td>
538: </table>
539: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 540: cellspacing="0" cellpadding="0">
1.1.1.8 root 541: <tr valign="top" align="left">
542: <td width="10%"></td>
543: <td width="89%">
1.1.1.12 root 544: <b>--monitor <x></b></td>
1.1.1.8 root 545: </table>
546: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 547: cellspacing="0" cellpadding="0">
1.1.1.8 root 548: <tr valign="top" align="left">
549: <td width="21%"></td>
550: <td width="77%">
551: Select monitor type (x = mono/rgb/vga/tv)
552: </td>
553: </table>
554: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 555: cellspacing="0" cellpadding="0">
1.1.1.8 root 556: <tr valign="top" align="left">
557: <td width="10%"></td>
558: <td width="89%">
1.1.1.12 root 559: <b>-f, --fullscreen</b></td>
1.1 root 560: </table>
1.1.1.8 root 561: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 562: cellspacing="0" cellpadding="0">
1.1.1.8 root 563: <tr valign="top" align="left">
564: <td width="21%"></td>
565: <td width="77%">
566: Start the emulator in fullscreen mode
567: </td>
568: </table>
569: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 570: cellspacing="0" cellpadding="0">
1.1.1.8 root 571: <tr valign="top" align="left">
572: <td width="10%"></td>
573: <td width="89%">
1.1.1.12 root 574: <b>-w, --window</b></td>
1.1.1.8 root 575: </table>
576: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 577: cellspacing="0" cellpadding="0">
1.1.1.8 root 578: <tr valign="top" align="left">
579: <td width="21%"></td>
580: <td width="77%">
581: Start the emulator in window mode
582: </td>
583: </table>
584: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 585: cellspacing="0" cellpadding="0">
1.1.1.8 root 586: <tr valign="top" align="left">
587: <td width="10%"></td>
588: <td width="89%">
1.1.1.12 root 589: <b>--grab</b></td>
1.1.1.10 root 590: </table>
591: <table width="100%" border=0 rules="none" frame="void"
592: cellspacing="0" cellpadding="0">
593: <tr valign="top" align="left">
594: <td width="21%"></td>
595: <td width="77%">
596: Grab mouse (also) in window mode
597: </td>
598: </table>
599: <table width="100%" border=0 rules="none" frame="void"
600: cellspacing="0" cellpadding="0">
601: <tr valign="top" align="left">
602: <td width="10%"></td>
603: <td width="89%">
1.1.1.13! root 604: <b>--fast-forward <bool></b></td>
1.1.1.8 root 605: </table>
606: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 607: cellspacing="0" cellpadding="0">
1.1.1.8 root 608: <tr valign="top" align="left">
609: <td width="21%"></td>
610: <td width="77%">
1.1.1.13! root 611: On fast machine helps skipping (fast forwarding) Hatari
! 612: output
1.1.1.8 root 613: </td>
614: </table>
615: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 616: cellspacing="0" cellpadding="0">
1.1.1.8 root 617: <tr valign="top" align="left">
618: <td width="10%"></td>
619: <td width="89%">
1.1.1.13! root 620: <b>--frameskips <x></b></td>
1.1.1.8 root 621: </table>
622: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 623: cellspacing="0" cellpadding="0">
1.1.1.8 root 624: <tr valign="top" align="left">
625: <td width="21%"></td>
626: <td width="77%">
1.1.1.13! root 627: Skip <x> frames after each displayed frame to
! 628: accelerate emulation (0=disabled, >4 uses automatic
! 629: frameskip with given value as maximum)
1.1.1.12 root 630: </td>
631: </table>
632: <table width="100%" border=0 rules="none" frame="void"
633: cellspacing="0" cellpadding="0">
634: <tr valign="top" align="left">
635: <td width="10%"></td>
636: <td width="89%">
1.1.1.13! root 637: <b>--statusbar <bool></b></td>
1.1.1.12 root 638: </table>
639: <table width="100%" border=0 rules="none" frame="void"
640: cellspacing="0" cellpadding="0">
641: <tr valign="top" align="left">
642: <td width="21%"></td>
643: <td width="77%">
1.1.1.13! root 644: Show statusbar (with floppy leds etc etc)
1.1.1.12 root 645: </td>
646: </table>
647: <table width="100%" border=0 rules="none" frame="void"
648: cellspacing="0" cellpadding="0">
649: <tr valign="top" align="left">
650: <td width="10%"></td>
651: <td width="89%">
1.1.1.13! root 652: <b>--drive-led <bool></b></td>
! 653: </table>
! 654: <table width="100%" border=0 rules="none" frame="void"
! 655: cellspacing="0" cellpadding="0">
! 656: <tr valign="top" align="left">
! 657: <td width="21%"></td>
! 658: <td width="77%">
! 659: Show overlay drive led when statusbar isn’t shown
! 660: </td>
! 661: </table>
! 662: <table width="100%" border=0 rules="none" frame="void"
! 663: cellspacing="0" cellpadding="0">
! 664: <tr valign="top" align="left">
! 665: <td width="10%"></td>
! 666: <td width="89%">
! 667: <b>--bpp <bool></b></td>
1.1.1.12 root 668: </table>
669: <table width="100%" border=0 rules="none" frame="void"
670: cellspacing="0" cellpadding="0">
671: <tr valign="top" align="left">
672: <td width="21%"></td>
673: <td width="77%">
1.1.1.13! root 674: Force internal bitdepth (x = 8/15/16/32, 0=disable)
1.1.1.8 root 675: </td>
676: </table>
1.1.1.13! root 677:
! 678: <a name="ST/STE specific display options"></a>
! 679: <h3>ST/STE specific display options</h3>
1.1.1.8 root 680: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 681: cellspacing="0" cellpadding="0">
1.1.1.8 root 682: <tr valign="top" align="left">
683: <td width="10%"></td>
684: <td width="89%">
1.1.1.12 root 685: <b>--borders <bool></b></td>
1.1.1.8 root 686: </table>
687: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 688: cellspacing="0" cellpadding="0">
1.1.1.8 root 689: <tr valign="top" align="left">
690: <td width="21%"></td>
691: <td width="77%">
1.1.1.13! root 692: Show screen borders (for low/med resolution overscan demos)
1.1.1.8 root 693: </td>
694: </table>
695: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 696: cellspacing="0" cellpadding="0">
1.1.1.8 root 697: <tr valign="top" align="left">
698: <td width="10%"></td>
699: <td width="89%">
1.1.1.13! root 700: <b>--spec512 <x></b></td>
1.1.1.12 root 701: </table>
702: <table width="100%" border=0 rules="none" frame="void"
703: cellspacing="0" cellpadding="0">
704: <tr valign="top" align="left">
705: <td width="21%"></td>
706: <td width="77%">
1.1.1.13! root 707: Hatari uses this threshold to decide when to render a
! 708: screen with the slower but more accurate Spectrum512 screen
! 709: conversion functions (0 <= x <= 512, 0=disable)
1.1.1.12 root 710: </td>
711: </table>
712: <table width="100%" border=0 rules="none" frame="void"
713: cellspacing="0" cellpadding="0">
714: <tr valign="top" align="left">
715: <td width="10%"></td>
716: <td width="89%">
1.1.1.13! root 717: <b>-z, --zoom <x></b></td>
1.1.1.8 root 718: </table>
719: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 720: cellspacing="0" cellpadding="0">
1.1.1.8 root 721: <tr valign="top" align="left">
722: <td width="21%"></td>
723: <td width="77%">
1.1.1.13! root 724: Zoom low resolution (1=no, 2=yes)
1.1.1.8 root 725: </td>
726: </table>
1.1.1.13! root 727:
! 728: <a name="Falcon/TT specific display options"></a>
! 729: <h3>Falcon/TT specific display options</h3>
! 730: <p>
! 731: Zooming to sizes specified below is internally done using integer
! 732: scaling factors. This means that different Atari resolutions may show
! 733: up with different sizes, but they are never blurry.
! 734: </p>
1.1.1.8 root 735: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 736: cellspacing="0" cellpadding="0">
1.1.1.8 root 737: <tr valign="top" align="left">
738: <td width="10%"></td>
739: <td width="89%">
1.1.1.13! root 740: <b>--desktop <bool></b></td>
1.1.1.8 root 741: </table>
742: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 743: cellspacing="0" cellpadding="0">
1.1.1.8 root 744: <tr valign="top" align="left">
745: <td width="21%"></td>
746: <td width="77%">
1.1.1.13! root 747: Whether to use desktop resolution on fullscreen to avoid issues
! 748: related to resolution switching. Otherwise fullscreen will use
! 749: a resolution that is closest to the Hatari window size
1.1.1.8 root 750: </td>
751: </table>
752: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 753: cellspacing="0" cellpadding="0">
1.1.1.8 root 754: <tr valign="top" align="left">
755: <td width="10%"></td>
756: <td width="89%">
1.1.1.13! root 757: <b>--max-width <x></b></td>
1.1.1.8 root 758: </table>
759: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 760: cellspacing="0" cellpadding="0">
1.1.1.8 root 761: <tr valign="top" align="left">
762: <td width="21%"></td>
763: <td width="77%">
1.1.1.13! root 764: Maximum window width for zooming
1.1.1.8 root 765: </td>
766: </table>
767: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 768: cellspacing="0" cellpadding="0">
1.1.1.8 root 769: <tr valign="top" align="left">
770: <td width="10%"></td>
771: <td width="89%">
1.1.1.13! root 772: <b>--max-height <x></b></td>
1.1.1.8 root 773: </table>
774: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 775: cellspacing="0" cellpadding="0">
1.1.1.8 root 776: <tr valign="top" align="left">
777: <td width="21%"></td>
778: <td width="77%">
1.1.1.13! root 779: Maximum window height for zooming
! 780: </td>
! 781: </table>
! 782: <table width="100%" border=0 rules="none" frame="void"
! 783: cellspacing="0" cellpadding="0">
! 784: <tr valign="top" align="left">
! 785: <td width="10%"></td>
! 786: <td width="89%">
! 787: <b>--aspect <bool></b></td>
! 788: </table>
! 789: <table width="100%" border=0 rules="none" frame="void"
! 790: cellspacing="0" cellpadding="0">
! 791: <tr valign="top" align="left">
! 792: <td width="21%"></td>
! 793: <td width="77%">
! 794: Whether to do monitor aspect ratio correction
1.1.1.8 root 795: </td>
796: </table>
1.1.1.13! root 797:
1.1.1.8 root 798: <a name="VDI options"></a>
799: <h3>VDI options</h3>
800: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 801: cellspacing="0" cellpadding="0">
1.1.1.8 root 802: <tr valign="top" align="left">
803: <td width="10%"></td>
804: <td width="89%">
1.1.1.12 root 805: <b>--vdi <bool></b></td>
1.1.1.8 root 806: </table>
807: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 808: cellspacing="0" cellpadding="0">
1.1.1.8 root 809: <tr valign="top" align="left">
810: <td width="21%"></td>
811: <td width="77%">
812: Whether to use VDI screen mode
813: </td>
814: </table>
815: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 816: cellspacing="0" cellpadding="0">
1.1.1.8 root 817: <tr valign="top" align="left">
818: <td width="10%"></td>
819: <td width="89%">
1.1.1.12 root 820: <b>--vdi-planes <x></b></td>
1.1.1.8 root 821: </table>
822: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 823: cellspacing="0" cellpadding="0">
1.1.1.8 root 824: <tr valign="top" align="left">
825: <td width="21%"></td>
826: <td width="77%">
1.1.1.12 root 827: Use extended VDI resolution with bit depth <x> (x = 1, 2 or 4)
1.1.1.8 root 828: </td>
829: </table>
830: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 831: cellspacing="0" cellpadding="0">
1.1.1.8 root 832: <tr valign="top" align="left">
833: <td width="10%"></td>
834: <td width="89%">
1.1.1.12 root 835: <b>--vdi-width <w></b></td>
1.1.1.8 root 836: </table>
837: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 838: cellspacing="0" cellpadding="0">
1.1.1.8 root 839: <tr valign="top" align="left">
840: <td width="21%"></td>
841: <td width="77%">
1.1.1.12 root 842: Use extended VDI resolution with width <w> (320 < w <= 1280)
1.1.1.8 root 843: </td>
844: </table>
845: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 846: cellspacing="0" cellpadding="0">
1.1.1.8 root 847: <tr valign="top" align="left">
848: <td width="10%"></td>
849: <td width="89%">
1.1.1.12 root 850: <b>--vdi-height <h></b></td>
1.1.1.8 root 851: </table>
852: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 853: cellspacing="0" cellpadding="0">
1.1.1.8 root 854: <tr valign="top" align="left">
855: <td width="21%"></td>
856: <td width="77%">
1.1.1.12 root 857: Use extended VDI resolution with height <h> (200 < h <= 960)
858: </td>
859: </table>
1.1.1.13! root 860:
! 861: <a name="Screen capture options"></a>
! 862: <h3>Screen capture options</h3>
1.1.1.12 root 863: <table width="100%" border=0 rules="none" frame="void"
864: cellspacing="0" cellpadding="0">
865: <tr valign="top" align="left">
866: <td width="10%"></td>
867: <td width="89%">
1.1.1.13! root 868: <b>--crop <bool></b></td>
1.1.1.12 root 869: </table>
870: <table width="100%" border=0 rules="none" frame="void"
871: cellspacing="0" cellpadding="0">
872: <tr valign="top" align="left">
873: <td width="21%"></td>
874: <td width="77%">
1.1.1.13! root 875: Remove statusbar from the screen captures
1.1.1.12 root 876: </td>
877: </table>
878: <table width="100%" border=0 rules="none" frame="void"
879: cellspacing="0" cellpadding="0">
880: <tr valign="top" align="left">
881: <td width="10%"></td>
882: <td width="89%">
1.1.1.13! root 883: <b>--avirecord</b></td>
1.1.1.12 root 884: </table>
885: <table width="100%" border=0 rules="none" frame="void"
886: cellspacing="0" cellpadding="0">
887: <tr valign="top" align="left">
888: <td width="21%"></td>
889: <td width="77%">
1.1.1.13! root 890: Start AVI recording
1.1.1.12 root 891: </td>
892: </table>
893: <table width="100%" border=0 rules="none" frame="void"
894: cellspacing="0" cellpadding="0">
895: <tr valign="top" align="left">
896: <td width="10%"></td>
897: <td width="89%">
1.1.1.13! root 898: <b>--avi-vcodec <x></b></td>
1.1.1.12 root 899: </table>
900: <table width="100%" border=0 rules="none" frame="void"
901: cellspacing="0" cellpadding="0">
902: <tr valign="top" align="left">
903: <td width="21%"></td>
904: <td width="77%">
1.1.1.13! root 905: Select avi video codec (x = bmp/png)
1.1.1.12 root 906: </td>
907: </table>
908: <table width="100%" border=0 rules="none" frame="void"
909: cellspacing="0" cellpadding="0">
910: <tr valign="top" align="left">
911: <td width="10%"></td>
912: <td width="89%">
1.1.1.13! root 913: <b>--avi-fps <x></b></td>
1.1.1.12 root 914: </table>
915: <table width="100%" border=0 rules="none" frame="void"
916: cellspacing="0" cellpadding="0">
917: <tr valign="top" align="left">
918: <td width="21%"></td>
919: <td width="77%">
1.1.1.13! root 920: Force avi frame rate (x = 50/60/71/...)
1.1.1.12 root 921: </td>
922: </table>
923: <table width="100%" border=0 rules="none" frame="void"
924: cellspacing="0" cellpadding="0">
925: <tr valign="top" align="left">
926: <td width="10%"></td>
927: <td width="89%">
928: <b>--avi-file <file></b></td>
929: </table>
930: <table width="100%" border=0 rules="none" frame="void"
931: cellspacing="0" cellpadding="0">
932: <tr valign="top" align="left">
933: <td width="21%"></td>
934: <td width="77%">
935: Use <file> to record avi
1.1.1.8 root 936: </td>
937: </table>
1.1.1.13! root 938:
1.1.1.8 root 939: <a name="Devices options"></a>
940: <h3>Devices options</h3>
941: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 942: cellspacing="0" cellpadding="0">
1.1.1.8 root 943: <tr valign="top" align="left">
944: <td width="10%"></td>
945: <td width="89%">
1.1.1.12 root 946: <b>-j, --joystick
1.1.1.8 root 947: <port></b></td>
948: </table>
949: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 950: cellspacing="0" cellpadding="0">
1.1.1.8 root 951: <tr valign="top" align="left">
952: <td width="21%"></td>
953: <td width="77%">
954: Emulate joystick with cursor keys in given port (0-5)
955: </td>
956: </table>
957: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 958: cellspacing="0" cellpadding="0">
1.1.1.8 root 959: <tr valign="top" align="left">
960: <td width="10%"></td>
961: <td width="89%">
1.1.1.12 root 962: <b>--joy<port>
1.1.1.8 root 963: <type></b></td>
964: </table>
965: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 966: cellspacing="0" cellpadding="0">
1.1.1.8 root 967: <tr valign="top" align="left">
968: <td width="21%"></td>
969: <td width="77%">
970: Set joystick type (none/keys/real) for given port
971: </td>
972: </table>
973: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 974: cellspacing="0" cellpadding="0">
1.1.1.8 root 975: <tr valign="top" align="left">
976: <td width="10%"></td>
977: <td width="89%">
1.1.1.12 root 978: <b>--printer <file></b></td>
1.1.1.8 root 979: </table>
980: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 981: cellspacing="0" cellpadding="0">
1.1.1.8 root 982: <tr valign="top" align="left">
983: <td width="21%"></td>
984: <td width="77%">
985: Enable printer support and write data to <file>
986: </td>
987: </table>
988: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 989: cellspacing="0" cellpadding="0">
1.1.1.8 root 990: <tr valign="top" align="left">
991: <td width="10%"></td>
992: <td width="89%">
1.1.1.12 root 993: <b>--midi-in <filename></b></td>
1.1.1.8 root 994: </table>
995: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 996: cellspacing="0" cellpadding="0">
1.1.1.8 root 997: <tr valign="top" align="left">
998: <td width="21%"></td>
999: <td width="77%">
1.1.1.9 root 1000: Enable MIDI support and write MIDI data to <file>
1.1.1.8 root 1001: </td>
1002: </table>
1003: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1004: cellspacing="0" cellpadding="0">
1.1.1.8 root 1005: <tr valign="top" align="left">
1006: <td width="10%"></td>
1007: <td width="89%">
1.1.1.12 root 1008: <b>--midi-out <filename></b></td>
1.1.1.8 root 1009: </table>
1010: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1011: cellspacing="0" cellpadding="0">
1.1.1.8 root 1012: <tr valign="top" align="left">
1013: <td width="21%"></td>
1014: <td width="77%">
1.1.1.9 root 1015: Enable MIDI support and read MIDI data from <file>
1016: </td>
1017: </table>
1018: <table width="100%" border=0 rules="none" frame="void"
1019: cellspacing="0" cellpadding="0">
1020: <tr valign="top" align="left">
1021: <td width="10%"></td>
1022: <td width="89%">
1.1.1.12 root 1023: <b>--rs232-in <filename></b></td>
1.1.1.9 root 1024: </table>
1025: <table width="100%" border=0 rules="none" frame="void"
1026: cellspacing="0" cellpadding="0">
1027: <tr valign="top" align="left">
1028: <td width="21%"></td>
1029: <td width="77%">
1030: Enable serial port support and use <file> as the input device
1031: </td>
1032: </table>
1033: <table width="100%" border=0 rules="none" frame="void"
1034: cellspacing="0" cellpadding="0">
1035: <tr valign="top" align="left">
1036: <td width="10%"></td>
1037: <td width="89%">
1.1.1.12 root 1038: <b>--rs232-out <filename></b></td>
1.1.1.9 root 1039: </table>
1040: <table width="100%" border=0 rules="none" frame="void"
1041: cellspacing="0" cellpadding="0">
1042: <tr valign="top" align="left">
1043: <td width="21%"></td>
1044: <td width="77%">
1045: Enable serial port support and use <file> as the output device
1.1.1.8 root 1046: </td>
1047: </table>
1.1.1.13! root 1048:
1.1.1.8 root 1049: <a name="Disk options"></a>
1050: <h3>Disk options</h3>
1051: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1052: cellspacing="0" cellpadding="0">
1.1.1.8 root 1053: <tr valign="top" align="left">
1054: <td width="10%"></td>
1055: <td width="89%">
1.1.1.12 root 1056: <b>--disk-a <file></b></td>
1.1.1.8 root 1057: </table>
1058: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1059: cellspacing="0" cellpadding="0">
1.1.1.8 root 1060: <tr valign="top" align="left">
1061: <td width="21%"></td>
1062: <td width="77%">
1063: Set disk image for floppy drive A
1064: </td>
1065: </table>
1066: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1067: cellspacing="0" cellpadding="0">
1.1.1.8 root 1068: <tr valign="top" align="left">
1069: <td width="10%"></td>
1070: <td width="89%">
1.1.1.12 root 1071: <b>--disk-b <file></b></td>
1.1.1.8 root 1072: </table>
1073: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1074: cellspacing="0" cellpadding="0">
1.1.1.8 root 1075: <tr valign="top" align="left">
1076: <td width="21%"></td>
1077: <td width="77%">
1078: Set disk image for floppy drive B
1079: </td>
1080: </table>
1081: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1082: cellspacing="0" cellpadding="0">
1.1.1.8 root 1083: <tr valign="top" align="left">
1084: <td width="10%"></td>
1085: <td width="89%">
1.1.1.12 root 1086: <b>--protect-floppy <x></b></td>
1.1.1.8 root 1087: </table>
1088: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1089: cellspacing="0" cellpadding="0">
1.1.1.8 root 1090: <tr valign="top" align="left">
1091: <td width="21%"></td>
1092: <td width="77%">
1.1.1.12 root 1093: Write protect floppy image contents (on/off/auto). With "auto" option
1094: write protection is according to the disk image file attributes.
1.1.1.8 root 1095: </td>
1096: </table>
1097: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1098: cellspacing="0" cellpadding="0">
1.1.1.8 root 1099: <tr valign="top" align="left">
1100: <td width="10%"></td>
1101: <td width="89%">
1.1.1.12 root 1102: <b>--protect-hd <x></b></td>
1103: </table>
1104: <table width="100%" border=0 rules="none" frame="void"
1105: cellspacing="0" cellpadding="0">
1106: <tr valign="top" align="left">
1107: <td width="21%"></td>
1108: <td width="77%">
1109: Write protect harddrive <dir> contents (on/off/auto). With "auto"
1110: option the protection can be controlled by setting individual files
1111: attributes as it disables the file attribute modifications for
1112: the GEMDOS hard disk emulation.
1113: </td>
1114: </table>
1115: <table width="100%" border=0 rules="none" frame="void"
1116: cellspacing="0" cellpadding="0">
1117: <tr valign="top" align="left">
1118: <td width="10%"></td>
1119: <td width="89%">
1120: <b>-d, --harddrive <dir></b></td>
1121: </table>
1122: <table width="100%" border=0 rules="none" frame="void"
1123: cellspacing="0" cellpadding="0">
1124: <tr valign="top" align="left">
1125: <td width="21%"></td>
1126: <td width="77%">
1127: Emulate harddrive partition(s) with <dir> contents
1128: </td>
1129: </table>
1130: <table width="100%" border=0 rules="none" frame="void"
1131: cellspacing="0" cellpadding="0">
1132: <tr valign="top" align="left">
1133: <td width="10%"></td>
1134: <td width="89%">
1135: <b>--acsi <file></b></td>
1.1.1.8 root 1136: </table>
1137: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1138: cellspacing="0" cellpadding="0">
1.1.1.8 root 1139: <tr valign="top" align="left">
1140: <td width="21%"></td>
1141: <td width="77%">
1142: Emulate an ACSI hard disk with an image <file>
1143: </td>
1144: </table>
1145: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1146: cellspacing="0" cellpadding="0">
1.1.1.8 root 1147: <tr valign="top" align="left">
1148: <td width="10%"></td>
1149: <td width="89%">
1.1.1.12 root 1150: <b>--ide-master <file></b></td>
1151: </table>
1152: <table width="100%" border=0 rules="none" frame="void"
1153: cellspacing="0" cellpadding="0">
1154: <tr valign="top" align="left">
1155: <td width="21%"></td>
1156: <td width="77%">
1157: Emulate an IDE master hard disk with an image <file>
1158: </td>
1159: </table>
1160: <table width="100%" border=0 rules="none" frame="void"
1161: cellspacing="0" cellpadding="0">
1162: <tr valign="top" align="left">
1163: <td width="10%"></td>
1164: <td width="89%">
1165: <b>--ide-slave <file></b></td>
1.1.1.8 root 1166: </table>
1167: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1168: cellspacing="0" cellpadding="0">
1.1.1.8 root 1169: <tr valign="top" align="left">
1170: <td width="21%"></td>
1171: <td width="77%">
1.1.1.12 root 1172: Emulate an IDE slave hard disk with an image <file>
1.1.1.8 root 1173: </td>
1174: </table>
1175: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1176: cellspacing="0" cellpadding="0">
1.1.1.8 root 1177: <tr valign="top" align="left">
1178: <td width="10%"></td>
1179: <td width="89%">
1.1.1.12 root 1180: <b>--slowfdc <bool></b></td>
1.1.1.8 root 1181: </table>
1182: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1183: cellspacing="0" cellpadding="0">
1.1.1.8 root 1184: <tr valign="top" align="left">
1185: <td width="21%"></td>
1186: <td width="77%">
1187: slow down FDC emulation (deprecated)
1188: </td>
1189: </table>
1.1.1.13! root 1190:
1.1.1.8 root 1191: <a name="Memory options"></a>
1192: <h3>Memory options</h3>
1193: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1194: cellspacing="0" cellpadding="0">
1.1.1.8 root 1195: <tr valign="top" align="left">
1196: <td width="10%"></td>
1197: <td width="89%">
1.1.1.12 root 1198: <b>-s, --memsize <x></b></td>
1.1.1.8 root 1199: </table>
1200: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1201: cellspacing="0" cellpadding="0">
1.1.1.8 root 1202: <tr valign="top" align="left">
1203: <td width="21%"></td>
1204: <td width="77%">
1205: Set amount of emulated RAM, x = 1 to 14 MiB, or 0 for 512
1206: KiB
1207: </td>
1208: </table>
1209: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1210: cellspacing="0" cellpadding="0">
1.1.1.8 root 1211: <tr valign="top" align="left">
1212: <td width="10%"></td>
1213: <td width="89%">
1.1.1.12 root 1214: <b>-t, --tos
1.1.1.8 root 1215: <imagefile></b></td>
1216: </table>
1217: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1218: cellspacing="0" cellpadding="0">
1.1.1.8 root 1219: <tr valign="top" align="left">
1220: <td width="21%"></td>
1221: <td width="77%">
1222: Specify TOS ROM image to use
1223: </td>
1224: </table>
1225: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1226: cellspacing="0" cellpadding="0">
1.1.1.8 root 1227: <tr valign="top" align="left">
1228: <td width="10%"></td>
1229: <td width="89%">
1.1.1.12 root 1230: <b>--cartridge <imagefile></b></td>
1.1.1.8 root 1231: </table>
1232: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1233: cellspacing="0" cellpadding="0">
1.1.1.8 root 1234: <tr valign="top" align="left">
1235: <td width="21%"></td>
1236: <td width="77%">
1237: Use ROM cartridge image <file> (only works if
1238: GEMDOS HD emulation and extended VDI resolution are
1239: disabled)
1240: </td>
1241: </table>
1242: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1243: cellspacing="0" cellpadding="0">
1.1.1.8 root 1244: <tr valign="top" align="left">
1245: <td width="10%"></td>
1246: <td width="89%">
1.1.1.12 root 1247: <b>--memstate <file></b></td>
1.1.1.8 root 1248: </table>
1249: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1250: cellspacing="0" cellpadding="0">
1.1.1.8 root 1251: <tr valign="top" align="left">
1252: <td width="21%"></td>
1253: <td width="77%">
1254: Load memory snap-shot <file>
1255: </td>
1256: </table>
1.1.1.13! root 1257:
1.1.1.8 root 1258: <a name="CPU options"></a>
1259: <h3>CPU options</h3>
1260: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1261: cellspacing="0" cellpadding="0">
1.1.1.8 root 1262: <tr valign="top" align="left">
1263: <td width="10%"></td>
1264: <td width="89%">
1.1.1.12 root 1265: <b>--cpulevel <x></b></td>
1.1.1.8 root 1266: </table>
1267: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1268: cellspacing="0" cellpadding="0">
1.1.1.8 root 1269: <tr valign="top" align="left">
1270: <td width="21%"></td>
1271: <td width="77%">
1272: Specify CPU (680x0) to use (use x >= 1 with EmuTOS or
1273: TOS >= 2.06 only!)
1274: </td>
1275: </table>
1276: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1277: cellspacing="0" cellpadding="0">
1.1.1.8 root 1278: <tr valign="top" align="left">
1279: <td width="10%"></td>
1280: <td width="89%">
1.1.1.12 root 1281: <b>--cpuclock <x></b></td>
1.1.1.8 root 1282: </table>
1283: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1284: cellspacing="0" cellpadding="0">
1.1.1.8 root 1285: <tr valign="top" align="left">
1286: <td width="21%"></td>
1287: <td width="77%">
1288: Set the CPU clock (8, 16 or 32 Mhz)
1289: </td>
1290: </table>
1291: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1292: cellspacing="0" cellpadding="0">
1.1.1.8 root 1293: <tr valign="top" align="left">
1294: <td width="10%"></td>
1295: <td width="89%">
1.1.1.12 root 1296: <b>--compatible <bool></b></td>
1.1.1.8 root 1297: </table>
1298: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1299: cellspacing="0" cellpadding="0">
1.1.1.8 root 1300: <tr valign="top" align="left">
1301: <td width="21%"></td>
1302: <td width="77%">
1303: Use a more compatible but slower 68000 CPU mode
1304: </td>
1305: </table>
1.1.1.13! root 1306:
1.1.1.8 root 1307: <a name="Misc system options"></a>
1308: <h3>Misc system options</h3>
1309: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1310: cellspacing="0" cellpadding="0">
1.1.1.8 root 1311: <tr valign="top" align="left">
1312: <td width="10%"></td>
1313: <td width="89%">
1.1.1.12 root 1314: <b>--machine <x></b></td>
1.1.1.8 root 1315: </table>
1316: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1317: cellspacing="0" cellpadding="0">
1.1.1.8 root 1318: <tr valign="top" align="left">
1319: <td width="21%"></td>
1320: <td width="77%">
1.1.1.13! root 1321: Select machine type (x = st, ste, tt or falcon)
1.1.1.8 root 1322: </td>
1323: </table>
1324: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1325: cellspacing="0" cellpadding="0">
1.1.1.8 root 1326: <tr valign="top" align="left">
1327: <td width="10%"></td>
1328: <td width="89%">
1.1.1.12 root 1329: <b>--blitter <bool></b></td>
1.1.1.8 root 1330: </table>
1331: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1332: cellspacing="0" cellpadding="0">
1.1.1.8 root 1333: <tr valign="top" align="left">
1334: <td width="21%"></td>
1335: <td width="77%">
1336: Enable blitter emulation (ST only)
1337: </td>
1338: </table>
1339: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1340: cellspacing="0" cellpadding="0">
1.1.1.8 root 1341: <tr valign="top" align="left">
1342: <td width="10%"></td>
1343: <td width="89%">
1.1.1.13! root 1344: <b>--dsp <x></b></td>
1.1.1.10 root 1345: </table>
1346: <table width="100%" border=0 rules="none" frame="void"
1347: cellspacing="0" cellpadding="0">
1348: <tr valign="top" align="left">
1349: <td width="21%"></td>
1350: <td width="77%">
1.1.1.13! root 1351: Falcon DSP emulation (x = none, dummy or emu, Falcon only)
1.1.1.10 root 1352: </td>
1353: </table>
1354: <table width="100%" border=0 rules="none" frame="void"
1355: cellspacing="0" cellpadding="0">
1356: <tr valign="top" align="left">
1357: <td width="10%"></td>
1358: <td width="89%">
1.1.1.13! root 1359: <b>--mic <bool></b></td>
1.1.1.8 root 1360: </table>
1361: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1362: cellspacing="0" cellpadding="0">
1.1.1.8 root 1363: <tr valign="top" align="left">
1364: <td width="21%"></td>
1365: <td width="77%">
1.1.1.13! root 1366: Enable/disable (Falcon only) microphone
1.1.1.8 root 1367: </td>
1368: </table>
1369: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1370: cellspacing="0" cellpadding="0">
1.1.1.8 root 1371: <tr valign="top" align="left">
1372: <td width="10%"></td>
1373: <td width="89%">
1.1.1.12 root 1374: <b>--sound <x></b></td>
1.1.1.8 root 1375: </table>
1376: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1377: cellspacing="0" cellpadding="0">
1.1.1.8 root 1378: <tr valign="top" align="left">
1379: <td width="21%"></td>
1380: <td width="77%">
1.1.1.10 root 1381: Sound frequency: 6000-50066. "off" disables the sound and speeds up
1382: the emulation. To prevent extra sound artifacts, the frequency should be
1383: selected so that it either matches evenly with the STE/TT/Falcon sound
1384: DMA (6258, 12517, 250033, 50066 Hz) or your sound card frequencies
1385: (11025, 22050, 44100 or 6000...48000 Hz). Check what your sound card
1386: supports.
1.1.1.8 root 1387: </td>
1388: </table>
1.1.1.12 root 1389: <table width="100%" border=0 rules="none" frame="void"
1390: cellspacing="0" cellpadding="0">
1391: <tr valign="top" align="left">
1392: <td width="10%"></td>
1393: <td width="89%">
1394: <b>--sound-buffer-size <x></b></td>
1395: </table>
1396: <table width="100%" border=0 rules="none" frame="void"
1397: cellspacing="0" cellpadding="0">
1398: <tr valign="top" align="left">
1399: <td width="21%"></td>
1400: <td width="77%">
1401: SDL's sound buffer size : 10-100, or 0 to use default buffer size.
1402: By default Hatari uses an SDL buffer size of 1024 samples, which
1403: gives approximatively 20-30 ms of sound depending on the chosen sound
1404: frequency. Under some OS or with not fully supported sound card, this
1405: default setting can cause a bigger delay at lower frequency (nearly 0.5 sec).
1406: In that case, you can use this option to force the size of the sound
1407: buffer to a fixed number of milliseconds of sound (using 20 is often
1408: a good choice if you have such problems). Most users will not need this option.
1409: </td>
1410: </table>
1.1.1.8 root 1411: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1412: cellspacing="0" cellpadding="0">
1.1.1.8 root 1413: <tr valign="top" align="left">
1414: <td width="10%"></td>
1415: <td width="89%">
1.1.1.13! root 1416: <b>--ym-mixing <x></b></td>
1.1.1.8 root 1417: </table>
1418: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1419: cellspacing="0" cellpadding="0">
1.1.1.8 root 1420: <tr valign="top" align="left">
1421: <td width="21%"></td>
1422: <td width="77%">
1.1.1.13! root 1423: Select a method for mixing the three YM2149 voice volumes together.
! 1424: "table" uses a lookup table of audio output voltage values measured
! 1425: on STF and "linear" just averages the 3 YM voices.
! 1426: </td>
! 1427: </table>
! 1428: <table width="100%" border=0 rules="none" frame="void"
! 1429: cellspacing="0" cellpadding="0">
! 1430: <tr valign="top" align="left">
! 1431: <td width="10%"></td>
! 1432: <td width="89%">
! 1433: <b>--timer-d <bool></b></td>
! 1434: </table>
! 1435: <table width="100%" border=0 rules="none" frame="void"
! 1436: cellspacing="0" cellpadding="0">
! 1437: <tr valign="top" align="left">
! 1438: <td width="21%"></td>
! 1439: <td width="77%">
! 1440: Patch redundantly high Timer-D frequency set by TOS. This about doubles
! 1441: Hatari speed (for ST/e emulation) as the original Timer-D frequency causes
! 1442: most of the interrupts.
! 1443: </td>
! 1444: </table>
! 1445: <table width="100%" border=0 rules="none" frame="void"
! 1446: cellspacing="0" cellpadding="0">
! 1447: <tr valign="top" align="left">
! 1448: <td width="10%"></td>
! 1449: <td width="89%">
! 1450: <b>--rtc <bool></b></td>
! 1451: </table>
! 1452: <table width="100%" border=0 rules="none" frame="void"
! 1453: cellspacing="0" cellpadding="0">
! 1454: <tr valign="top" align="left">
! 1455: <td width="21%"></td>
! 1456: <td width="77%">
! 1457: Enable real-time clock
1.1.1.8 root 1458: </td>
1459: </table>
1.1.1.13! root 1460:
1.1.1.8 root 1461: <a name="Debug options"></a>
1462: <h3>Debug options</h3>
1463: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1464: cellspacing="0" cellpadding="0">
1.1.1.8 root 1465: <tr valign="top" align="left">
1466: <td width="10%"></td>
1467: <td width="89%">
1.1.1.12 root 1468: <b>-D, --debug</b></td>
1.1.1.8 root 1469: </table>
1470: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1471: cellspacing="0" cellpadding="0">
1.1.1.8 root 1472: <tr valign="top" align="left">
1473: <td width="21%"></td>
1474: <td width="77%">
1.1.1.10 root 1475: Toggle whether CPU exceptions invoke the debugger
1.1.1.8 root 1476: </td>
1477: </table>
1478: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1479: cellspacing="0" cellpadding="0">
1.1.1.8 root 1480: <tr valign="top" align="left">
1481: <td width="10%"></td>
1482: <td width="89%">
1.1.1.12 root 1483: <b>--bios-intercept</b></td>
1.1.1.8 root 1484: </table>
1485: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1486: cellspacing="0" cellpadding="0">
1.1.1.8 root 1487: <tr valign="top" align="left">
1488: <td width="21%"></td>
1489: <td width="77%">
1.1.1.13! root 1490: Toggle Bios/XBios call interception and BIOS CON: output
! 1491: (e.g. EmuTOS console) redidirection to host terminal.
! 1492: Needed for Bios/XBios call tracing. Allows Atari programs
! 1493: to modify Hatari state through XBios 255 calls.
1.1.1.8 root 1494: </td>
1495: </table>
1496: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1497: cellspacing="0" cellpadding="0">
1.1.1.8 root 1498: <tr valign="top" align="left">
1499: <td width="10%"></td>
1500: <td width="89%">
1.1.1.12 root 1501: <b>--trace <trace1,...></b></td>
1.1.1.8 root 1502: </table>
1503: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1504: cellspacing="0" cellpadding="0">
1.1.1.8 root 1505: <tr valign="top" align="left">
1506: <td width="21%"></td>
1507: <td width="77%">
1508: Activate debug traces, see <b>--trace help</b> for available tracing options
1509: </td>
1510: </table>
1511: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1512: cellspacing="0" cellpadding="0">
1.1.1.8 root 1513: <tr valign="top" align="left">
1514: <td width="10%"></td>
1515: <td width="89%">
1.1.1.12 root 1516: <b>--trace-file <file></b></td>
1517: </table>
1518: <table width="100%" border=0 rules="none" frame="void"
1519: cellspacing="0" cellpadding="0">
1520: <tr valign="top" align="left">
1521: <td width="21%"></td>
1522: <td width="77%">
1523: Save trace output to <file> (default=stderr)
1524: </td>
1525: </table>
1526: <table width="100%" border=0 rules="none" frame="void"
1527: cellspacing="0" cellpadding="0">
1528: <tr valign="top" align="left">
1529: <td width="10%"></td>
1530: <td width="89%">
1531: <b>--parse <file></b></td>
1532: </table>
1533: <table width="100%" border=0 rules="none" frame="void"
1534: cellspacing="0" cellpadding="0">
1535: <tr valign="top" align="left">
1536: <td width="21%"></td>
1537: <td width="77%">
1538: Parse/execute debugger commands from <file>
1539: </td>
1540: </table>
1541: <table width="100%" border=0 rules="none" frame="void"
1542: cellspacing="0" cellpadding="0">
1543: <tr valign="top" align="left">
1544: <td width="10%"></td>
1545: <td width="89%">
1546: <b>--control-socket <file></b></td>
1.1.1.8 root 1547: </table>
1548: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1549: cellspacing="0" cellpadding="0">
1.1.1.8 root 1550: <tr valign="top" align="left">
1551: <td width="21%"></td>
1552: <td width="77%">
1553: Hatari reads options from given socket at run-time
1554: </td>
1555: </table>
1556: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1557: cellspacing="0" cellpadding="0">
1.1.1.8 root 1558: <tr valign="top" align="left">
1559: <td width="10%"></td>
1560: <td width="89%">
1.1.1.12 root 1561: <b>--log-file <file></b></td>
1.1.1.8 root 1562: </table>
1563: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1564: cellspacing="0" cellpadding="0">
1.1.1.8 root 1565: <tr valign="top" align="left">
1566: <td width="21%"></td>
1567: <td width="77%">
1568: Save log output to <file> (default=stderr)
1569: </td>
1570: </table>
1571: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1572: cellspacing="0" cellpadding="0">
1.1.1.8 root 1573: <tr valign="top" align="left">
1574: <td width="10%"></td>
1575: <td width="89%">
1.1.1.12 root 1576: <b>--log-level <x></b></td>
1.1.1.8 root 1577: </table>
1578: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1579: cellspacing="0" cellpadding="0">
1.1.1.8 root 1580: <tr valign="top" align="left">
1581: <td width="21%"></td>
1582: <td width="77%">
1583: Log output level (x=debug/todo/info/warn/error/fatal)
1584: </td>
1585: </table>
1586: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1587: cellspacing="0" cellpadding="0">
1.1.1.8 root 1588: <tr valign="top" align="left">
1589: <td width="10%"></td>
1590: <td width="89%">
1.1.1.12 root 1591: <b>--alert-level <x></b></td>
1.1.1.8 root 1592: </table>
1593: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1594: cellspacing="0" cellpadding="0">
1.1.1.8 root 1595: <tr valign="top" align="left">
1596: <td width="21%"></td>
1597: <td width="77%">
1598: Show dialog for log messages above given level
1599: </td>
1600: </table>
1.1.1.10 root 1601: <table width="100%" border=0 rules="none" frame="void"
1602: cellspacing="0" cellpadding="0">
1603: <tr valign="top" align="left">
1604: <td width="10%"></td>
1605: <td width="89%">
1.1.1.12 root 1606: <b>--run-vbls <x></b></td>
1.1.1.10 root 1607: </table>
1608: <table width="100%" border=0 rules="none" frame="void"
1609: cellspacing="0" cellpadding="0">
1610: <tr valign="top" align="left">
1611: <td width="21%"></td>
1612: <td width="77%">
1613: Exit after X VBLs
1614: </td>
1615: </table>
1.1.1.8 root 1616:
1.1.1.5 root 1617:
1.1.1.7 root 1618: <p>Type <span class="commandline">hatari --help</span> to list all
1619: the command line options supported by a given version of Hatari.</p>
1620:
1.1.1.5 root 1621: <a name="Using the emulated system"></a><h2>Using the emulated system</h2>
1622:
1.1 root 1623: <p> Once you've started Hatari succesfully, you can use the emulator as
1.1.1.10 root 1624: an almost complete Atari ST computer system. </p>
1.1.1.5 root 1625:
1626: <a name="The GUI"></a><h3>The GUI</h3>
1627:
1.1.1.3 root 1628: <p>Press <span class="key">F12</span> to enter the GUI. Navigate it
1629: with the mouse.
1.1 root 1630: The GUI is rather self explanatory.</p>
1.1.1.5 root 1631:
1.1.1.8 root 1632: <a name="The Main Menu"></a><h4 class="gui">The Main Menu</h4>
1.1.1.5 root 1633:
1634: <div class="floatimage">
1.1.1.10 root 1635: <img src="images/main.png" width="500" height="304" alt="Hatari's GUI - the main menu">
1.1.1.5 root 1636: </div>
1637:
1.1.1.12 root 1638: <p>
1639: You can reach the other setup dialogs from the main menu by clicking on
1640: the appropriate buttons.
1641: </p>
1642: <p>
1643: You can load the current settings from a configuration file by clicking
1644: on <span class="button">Load config.</span> and you can save
1645: the current settings to a configuration file by clicking on
1646: <span class="button">Save config.</span>.
1647: </p>
1648: <p>
1649: Click <span class="button">OK</span> to go back and continue the emulation.
1650: All changed options will be applied.
1651: </p>
1652: <p>
1653: Select the <span class="button">Reset machine</span> option if you
1654: want the emulated machine to perform a cold reset. This is equal to
1655: switching the power off and on again on a real Atari machine.
1656: </p>
1657: <p>
1658: Click <span class="button">Quit</span> to terminate Hatari
1659: and return to the host OS.
1660: </p>
1661: <p>
1662: Click <span class="button">Cancel</span> to abandon any
1663: changes that you have made.
1664: </p>
1.1.1.5 root 1665:
1.1.1.10 root 1666:
1667: <a name="The File Selector Dialog"></a><h4 class="gui">The File Selector Dialog</h4>
1668:
1669: <div class="floatimage">
1670: <img src="images/fileselector.png" width="640" height="399" alt="Hatari's GUI - the fileselector">
1671: </div>
1672:
1673: <p>
1674: The file selector dialog appears whenever you are prompted to choose a file
1675: or folder.
1676: </p>
1677: <p>
1678: To enter a folder or choose a file, simply click on the entry in the main box
1679: of the dialog. You can use the arrows at the right, the cursor up and down
1680: keys and the page up and down keys to navigate through the list.
1681: </p>
1682: <p>
1683: You can use the three buttons in the upper right corner for additional folder
1684: navigation. Use the <span class="button">..</span> button to go up one level
1685: in the directory tree. Use the <span class="button">~</span> button to return
1686: to your home directory. The <span class="button">/</span> button can be used
1687: to go to the root directory of the file system.
1688: </p>
1689:
1690:
1.1.1.8 root 1691: <a name="The System Dialog"></a><h4 class="gui">The System Dialog</h4>
1.1.1.5 root 1692:
1693: <div class="floatimage">
1.1.1.10 root 1694: <img src="images/system.png" width="360" height="384" alt="Hatari's GUI - the system dialog">
1.1.1.5 root 1695: </div>
1696:
1.1.1.7 root 1697: <p>
1698: First you can select the CPU type here. Here are some important hints for
1699: choosing the correct CPU type:
1700: </p>
1701: <ul>
1702: <li>
1703: Atari ST and STE have only been shipped with a 68000 CPU, so for best
1704: compatibility with old programs, choose this CPU type.
1705: </li>
1706: <li>
1707: Atari TT and Falcon computers were using the 68030 CPU, so you should switch
1.1.1.12 root 1708: use 68EC030+FPU (Hatari doesn't support 030 with MMU and some programs don't
1709: work with 68020 so this is the best choice).
1.1.1.7 root 1710: </li>
1711: <li>
1712: TOS 1.0x only works with 68000, while TOS 3.0x and 4.0x work only with a CPU
1713: >= 68020.
1714: </li>
1715: <li>
1716: 68010 and 68040 have never been used in official Atari computers, so don't
1717: use these CPU types unless you've got some good reasons.
1718: </li>
1719: </ul>
1720:
1721: <p>
1722: Beside the CPU type, you can also choose the machine type to emulate.
1723: The ST was the very first 16/32-bit computer from Atari. Most older games
1724: and demos require an ST. The STE was introduced some years later and had
1725: some more advanced hardware features. There are not that many demos or
1726: games that really require an STE but since most normal ST games/demos also
1727: work with an STE, it's normally safe to always work in STE mode.
1728: <br>
1729: TT and Falcon are more advanced, but they are not as compatible to the ST as
1.1.1.8 root 1730: the STE was. Therefore many old games and demos do not work with these machine
1731: types anymore. There were only very few programs that were made for the TT
1.1.1.7 root 1732: exclusively, while there were some interesting games and demos specially made
1733: for the Falcon.
1.1.1.12 root 1734: <em>Note:</em> TT and Falcon emulation are incomplete. They may not work
1.1.1.7 root 1735: very well.
1736: </p>
1737: <p>
1738: For STE emulation a STE compatible TOS image, e.q. version 1.06, 1.62 or
1739: 2.x, is strongly recommended. For TT emulation you need TOS 3.0x and for Falcon
1740: emulation you need TOS 4.0x. EmuTOS can be used on all machine types.
1741: </p>
1742: <p>
1743: Select the CPU clock you want to use. 8Mhz is ST standard and the most
1744: compatible. Use 16MHz for Mega STE and Falcon emulation.
1745: The CPU in the TT was clocked with 32 MHz.
1746: </p>
1.1.1.12 root 1747: <p>With the "Slower but more compatible CPU" option, you can enable
1.1.1.5 root 1748: the emulation of 68k address errors and the CPU prefetch buffer. This is needed
1749: for best compatibility, but it slows down emulation a little bit so you can
1750: disable it if you don't need it.</p>
1.1.1.10 root 1751: <p>
1752: For Falcon mode, you can choose whether you want to enable DSP emulation,
1753: fake it or completely disable it. Most Falcon programs only play sound or work
1754: correctly when you enable the DSP emulation, but it needs a lot of host CPU
1755: power (more than 2 GHz). So if you have a slow host CPU, you can try if your
1.1.1.12 root 1756: Falcon program also runs with DSP disabled or in "dummy" mode.
1.1.1.10 root 1757: Note that you can not change this option while the DSP based program already
1758: runs.
1759: </p>
1.1.1.5 root 1760: <p>You can also enable/disable Blitter emulation here. The Blitter is a custom
1761: chip that accelerates some graphical operations. This switch only toggles the
1762: Blitter in plain ST mode. In STE mode, the Blitter is always enabled (since all
1763: STEs have been sold with a Blitter chip).</p>
1.1.1.12 root 1764: <p>If you enable the "Real time clock emulation" switch, a RTC will
1.1.1.5 root 1765: be emulated based on the time of the host computer. Note that you need at least
1766: TOS 1.02 for proper RTC emulation, TOS 1.00 does not support this.</p>
1767: <p>The Timer-D patch changes the Timer-D initialization from TOS. TOS uses
1768: the MFP timer D as a baudrate generator for RS232. However, the TOS default
1769: value slows down the emulation. The patch gives you a better performance.
1.1.1.7 root 1770: It is normally safe to enable the patch, but if you encounter a program that
1.1.1.5 root 1771: does not work, you can try to disable the patch to see if it works then.</p>
1.1.1.12 root 1772: <p><em>NOTE:</em> The emulated Atari is very very sensitive to these options
1773: and it is strongly recommended to reset the emulation after changing
1774: them (for most things that's done automatically). The correct
1775: CPU type and clock are automatically selected when one uses the
1776: <span class="commandline">--machine</span> command line option.</p>
1.1.1.5 root 1777:
1778:
1.1.1.10 root 1779: <a name="The Floppy Disks Dialog"></a><h4 class="gui">The Floppy Disks Dialog</h4>
1.1.1.5 root 1780:
1.1.1.10 root 1781: <div class="floatimage">
1782: <img src="images/floppydisks.png" width="640" height="320" alt="Hatari's GUI - the floppy disks dialog">
1.1.1.5 root 1783: </div>
1784:
1.1.1.10 root 1785: <p>
1786: This dialog can be used to choose which floppy disks should be emulated
1787: in the disk drives. You can use most standard Atari ST disk image files.
1788: You may select and browse also zipped disk images. See the chapter
1.1.1.12 root 1789: <a href="#Floppy disk images">"Floppy disk images"</a> for details.
1.1.1.10 root 1790: </p>
1791: <p>
1792: Click on the button <span class="button">Browse</span> next to the
1793: A: and B: option to go to the fileselector to choose a disk image for the
1794: corresponding drive.
1795: </p>
1.1.1.3 root 1796: <p>Click on <span class="button">Eject</span> to eject a disk image
1797: from the emulated drive. The emulated ST will act as if had no floppy
1798: disk in its drive.</p>
1799: <p>You can specify a default directory where Hatari will start to
1800: browse the filesystem.</p>
1.1.1.2 root 1801: <p>
1.1.1.6 root 1802: Check the "Auto insert B" option if you want Hatari to be smart and
1803: insert the second disk of a two disk game automatically.
1804: Some games then use the second drive automatically.
1805: In the case that a game is not able to find the disk in the second drive,
1806: you have to insert the second disk in drive A: manually when prompted.
1807: <br>
1808: <em>NOTE:</em> This option only works properly if the file name of the
1809: first disks ends with an 'a' before the extension and the second disk name
1810: ends with a 'b'.
1.1.1.2 root 1811: </p>
1.1.1.10 root 1812: <p>
1813: Select if you want to use slow FDC (Floppy Disk Controller) emulation.
1.1.1.12 root 1814: "Slow floppy access" is normally not required, except for some few
1.1.1.10 root 1815: slideshows / intros which run too fast without this option.
1816: </p>
1817: <p>
1818: You can choose if you want Hatari to write-protect your disks. Atari ST virii
1819: can spread on disk images too so it might be a good idea to enable the write
1820: protection option. However you can't save highscores or games to your disk
1821: images in that case.
1822: </p>
1823:
1824: <div class="floatimage">
1.1.1.12 root 1825: <img src="images/newfloppy.png" width="290" height="224" alt="Hatari's GUI - the new floppy dialog">
1.1.1.10 root 1826: </div>
1827:
1828: <p>
1829: If you need to create a new blank disk image, click on
1830: <span class="button">Create blank image</span>.
1831: Parameters for the new image can be set in the following dialog.
1.1.1.12 root 1832: HD and ED disk sector counts are for non-Atari disk sizes, but such
1833: disks are useful for programs that don't work with GEMDOS emulation.
1.1.1.10 root 1834: Click on <span class="button">Create</span> to save the new image or on
1835: <span class="button">Back</span> to return to the disk dialog.
1836: </p>
1837: <p>
1838: After clicking <span class="button">Create</span>, a fileselector
1839: appears. You can browse the filesystem now. Select the target directory,
1.1.1.12 root 1840: click beside "File:" and type in a name for the new disk image.
1.1.1.10 root 1841: The name should terminate with .st or .msa.
1842: </p>
1843: <p>
1844: Hatari can currently create plain .ST and .MSA disk images exclusively.
1.1.1.12 root 1845: <span class="commandline">hmsa</span> command line utility can be used
1846: to convert disk images between .ST and .MSA formats.
1.1.1.10 root 1847: </p>
1848:
1849:
1850: <a name="The Hard Disks Dialog"></a><h4 class="gui">The Hard Disks Dialog</h4>
1851:
1852: <div class="floatimage">
1.1.1.12 root 1853: <img src="images/harddisks.png" width="640" height="304" alt="Hatari's GUI - the hard disks dialog">
1.1.1.10 root 1854: </div>
1855:
1856: <p>
1857: This dialog can be used to change the harddisk settings.
1858: </p>
1859: <p>
1.1.1.12 root 1860: You can select a harddrive image for ACSI, IDE master or slave hard drive
1861: emulation via image file here or you may select a directory of your local
1862: filesystem to be emulated as the harddrive of the emulated system.
1.1.1.10 root 1863: </p>
1864: <p>
1865: Check "Boot from HD" if you want Hatari to execute the AUTO folder
1866: on the harddrive.
1.1.1.12 root 1867: This option is checked by default if you specify a harddrive image or
1868: a directory via the command line.
1869: </p>
1870: <p>
1871: Removing the check from the "Allow GEMDOS drive modification" option
1872: will prevent Atari programs from modifying the files in GEMDOS HDD
1873: emulation directory or creating new files under it.
1.1.1.10 root 1874: </p>
1875: <p>
1876: Note that for IDE hard disk emulation you also need a TOS version >= 2.05.
1877: And ACSI hard disk emulation does not work with TOS 4.0x in Falcon mode.
1878: </p>
1879:
1.1.1.5 root 1880:
1.1.1.8 root 1881: <a name="The Memory Dialog"></a><h4 class="gui">The Memory Dialog</h4>
1.1.1.5 root 1882:
1.1.1.8 root 1883: <div class="floatimage">
1884: <img src="images/memory.png" width="398" height="349" alt="Hatari's GUI - the memory dialog">
1.1.1.5 root 1885: </div>
1886:
1.1.1.3 root 1887: <p>You can select the amount of RAM for the emulated ST here. Only
1888: amounts that were valid on a real unmodified STFM can be selected.</p>
1889: <p><em>Note:</em> This option is critical and you are strongly advised
1890: to reset the emulated ST
1.1 root 1891: when changing this option.</p>
1.1.1.2 root 1892: <p>Here you will find the options to save memory snapshots as well.</p>
1.1.1.3 root 1893: <p>Click on <span class="button">Save</span> to save a memory snapshot
1894: to file. You can select a new filename here.</p>
1895: <p>Click on <span class="button">Restore</span> to restore a memory
1896: snapshot from a file. Use the fileselector to select the snapshot to be
1897: restored.</p>
1898: <p><em>NOTE:</em> Memory snapshots are not interchangeable between
1899: different versions of Hatari. E.q. if you compile a newer Hatari, you
1900: cannot load your old memory snapshots back.</p>
1901:
1.1.1.5 root 1902:
1.1.1.8 root 1903: <a name="The ROM Dialog"></a><h4 class="gui">The ROM Dialog</h4>
1904:
1905: <div class="floatimage">
1906: <img src="images/tos.png" width="519" height="367" alt="Hatari's GUI - the ROM dialog">
1.1.1.5 root 1907: </div>
1908:
1.1.1.3 root 1909: <p>Here you can select the TOS image to use. Click on <span
1.1.1.5 root 1910: class="button">Browse</span> to select it via the fileselector.
1.1.1.3 root 1911: You can also select an optional cartridge image to use. Click on <span
1.1.1.4 root 1912: class="button">Browse</span> to select one via the fileselector. Click on <span
1.1.1.5 root 1913: class="button">Eject</span> to disconnect the custom cartridge image.
1914: </p>
1.1.1.7 root 1915: <p>
1916: For ST mode, use TOS 1.00, 1.02, 1.04 or 2.06.
1917: For STE mode, use TOS 1.06, 1.62, 2.05 or 2.06.
1918: If you want to use the TT mode, you must specify a TOS 3.06 image here.
1919: And in Falcon mode, you have to use either TOS 4.00, 4.02, 4.04 or 4.92.
1920: However, you should always use TOS 4.04 for Falcon mode, it's the most common one.
1921: Also note that TOS 4.92 can not be booted from a boot disk (like it's done on a
1922: real Falcon), you have to specify it directly in the TOS ROM setup dialog here.
1923: </p>
1924: <p>
1925: Keep in mind that any custom cartridge image will not work together with
1.1.1.5 root 1926: GEMDOS hard disk emulation or the VDI extended resolution emulation
1.1.1.3 root 1927: since some additional driver code will be used in the cartridge memory
1.1.1.7 root 1928: space for these emulations.
1929: </p>
1930: <p>
1931: <em>Note:</em> These options are critical and you are strongly
1.1.1.3 root 1932: advised to reset the emulated ST
1.1.1.7 root 1933: when changing one of these option.
1934: </p>
1.1.1.5 root 1935:
1.1.1.8 root 1936:
1937: <a name="The Joystick Dialog"></a><h4 class="gui">The Joystick Dialog</h4>
1.1.1.5 root 1938:
1939: <div class="floatimage">
1940: <img src="images/joystick.png" width="320" height="288" alt="Hatari's GUI - the joystick dialog">
1941: </div>
1942:
1943: <p>In this dialog, you can configure the emulated joysticks.
1944: With the upper two arrows, you can choose the joystick which you want to
1945: configure.</p>
1.1.1.3 root 1946: <p>Joystick 1 is the normal ST joystick port and 99.9% of all ST games
1.1.1.5 root 1947: use this port.
1948: Joystick 0 emulates a joystick plugged into the ST mouse port
1949: and is often used in games for two players.</p>
1950: <p>With STE joypad A and B, you can enable the emulation of Jaguar joypads
1951: which are plugged in the enhanced joystick ports of the Atari STE.
1952: Only very few STE games support these joypads, so you often won't need this.</p>
1953: <p>Finally, Hatari also emulates joysticks which were plugged on the parallel
1954: port with a special adapter on a real ST. These were used in some few
1.1.1.12 root 1955: multi-player games like "Gauntlet 2".</p>
1.1.1.5 root 1956: <p>For each ST joystick, choose whether you want to disable it,
1957: use the keyboard for emulation or use a real PC joystick.</p>
1958: <p>For keyboard emulation, you can select the keys by pressing the
1.1.1.10 root 1959: <span class="button">Define keys</span> button. You will be prompted to press
1.1.1.5 root 1960: the keys for up, down, left, right and fire.</p>
1961: <p>If you want to use a real PC joystick for the emulation, you should connect
1962: it to your PC before you start Hatari. Then you can choose the joystick with
1963: the two lower arrows.</p>
1.1.1.12 root 1964: <p>Check the "Enable autofire" option if you are too lazy to pound
1.1.1.5 root 1965: on the fire button in shoot'em-up games. However, this option only works with
1966: certain games. In some other games, it gets worse if you enable this option.</p>
1967: <p>See also the chapter "Emulated Joystick" for details.</p>
1968:
1.1.1.8 root 1969:
1.1.1.12 root 1970: <a name="The Atari Monitor Dialog"></a><h4 class="gui">The Atari Monitor Dialog</h4>
1.1.1.5 root 1971:
1.1.1.7 root 1972: <div class="floatimage">
1.1.1.12 root 1973: <img src="images/monitor.png" width="340" height="304" alt="Hatari's
1974: GUI - the Atari monitor dialog">
1.1.1.5 root 1975: </div>
1.1 root 1976:
1.1.1.7 root 1977: <p>
1978: Here you control the video output of the emulated Atari.
1979: </p>
1980: <p>
1.1.1.12 root 1981: You can select which sort of monitor to use. This option depends on
1982: the machine type which you have selected in the "System options"
1983: dialog. In ST and STE mode, you can choose between monochrome mode
1984: (select "Mono") and color mode (select one of the other monitor types).
1985: Note that when you select "TV" and use zoomed low resolution or
1986: switch to ST medium resolution, you will get a TV-like screen rendering
1987: which is a little bit faster but darker compared to the normal "RGB"
1988: monitor mode. Switching between mono and a color monitor acts like a monitor
1989: switch on a real ST - so beware, this will reboot your emulated system!<br>
1990: In TT mode, you can only choose between TT-high resolution ("Mono")
1991: and normal modes (select one of the other monitor types).
1992: Finally the Falcon mode supports all four types of monitors. Note that most
1993: Falcon demos/games require a RGB or TV mode and do not work with VGA.
1.1.1.7 root 1994: </p>
1995: <p>
1.1.1.12 root 1996: "Show ST/STE borders" toggles the displaying of the borders around the ST /
1997: STE screen. Some demos and games use the screen borders for displaying
1998: additional graphics. As enabling this option increases CPU computing time,
1999: don't enable it if you have a very slow computer.
2000: This option affects only the ST and STE modes, TT and Falcon modes are
2001: always displayed without borders.
1.1.1.7 root 2002: </p>
2003: <p>
1.1.1.12 root 2004: Extended VDI resolutions will emulate a sort of extended graphics
2005: card in the emulated ST which give you larger resolutions with a higher
2006: colordepth for GEM. Select a resolution and color depth. Check to
2007: activate. It will disable all other video options mentioned above.
2008: Uncheck to get back to a normal ST behaviour.<br>
2009: <em>Note:</em> Using an extended resolution will only work with GEM
2010: conformant applications. 99% of all games and demos will not run if you
2011: activate any extended resolution here.
1.1.1.7 root 2012: </p>
1.1.1.12 root 2013:
2014:
2015: <a name="The Hatari Screen Dialog"></a><h4 class="gui">The Hatari
2016: Screen Dialog</h4>
2017:
2018: <div class="floatimage">
1.1.1.13! root 2019: <img src="images/screen.png" width="520" height="320" alt="Hatari's
1.1.1.12 root 2020: GUI - the Hatari screen dialog">
2021: </div>
2022:
1.1.1.7 root 2023: <p>
1.1.1.12 root 2024: Here you control how the video output of the emulated Atari appears
2025: on your screen.
2026: </p>
2027:
2028: <p>
2029: Check "Fullscreen" to run Hatari in fullscreen. By default Hatari
2030: runs in windowed mode.
1.1.1.7 root 2031: </p>
2032: <p>
1.1.1.12 root 2033: The "Frame Skip" option can be used to speed up the emulator
1.1.1.8 root 2034: if it is running too slow on your system. Disable frame-skip if you have
2035: a fast computer. When selecting 1, 2 or 4, drawing of corresponding number
2036: of frames will be skipped after each frame actually shown by Hatari.
1.1.1.12 root 2037: Select "Auto" to let the emulator to decide whether, and
1.1.1.8 root 2038: how many frames will be skipped.<br>
2039: <em>Note:</em> The frameskip option also affects the frame rate of the
2040: screen animation recording!
1.1.1.7 root 2041: </p>
2042: <p>
1.1.1.13! root 2043: Indicators that you can have on the Hatari window:
1.1.1.7 root 2044: </p>
1.1.1.13! root 2045: <ul>
! 2046: <li>"Statusbar" at the bottom of the screen.
! 2047: The statusbar shows the floppy drive LEDs, the current frameskip value,
! 2048: the machine type including TOS version and memory size, and whether
! 2049: recording is currently active.</li>
! 2050: <li>"Drive led" is a colored rectangle shown on top of the Hatari window
! 2051: contents. It will show any disk (floppy or hard disk) activity.</li>
! 2052: <li>"None" turns both of above options off.</li>
! 2053: </ul>
! 2054: <p>
! 2055: "Keep desktop resolution" option will use your desktop resolution
! 2056: for fullscreen to avoid issues related to resolution switching,
! 2057: especially on LCD monitors (they're slow). If this isn't enabled,
! 2058: values from the "Max zoomed win" option are used in selecting
! 2059: a suitable resolution.
1.1.1.7 root 2060: <p>
1.1.1.13! root 2061: "Max zoomed win" option controls up to which size Hatari tries to scale
1.1.1.12 root 2062: the Atari resolutions and how much of the borders (enabled in Atari
1.1.1.13! root 2063: Monitor dialog) will be shown. Note that there are several limitations
! 2064: in this and the "Keep desktop resolution" option, partly because Hatari
! 2065: has different implementations for different video modes:
1.1.1.7 root 2066: </p>
1.1.1.12 root 2067: <ul>
2068: <li>VDI resolutions (selectable in Atari Monitor dialog) aren't scaled.</li>
2069: <li>ST and STE video emulation supports only doubling of the ST-low
2070: resolution.</li>
2071: <li>Hatari doesn't support downscaling. If the original Atari resolution
1.1.1.13! root 2072: is larger than the specified size (e.g. TT-high), the Hatari screen
! 2073: size will also be larger than requested. Hatari Falcon/TT window size
! 2074: will be limited to the Desktop size though.</li>
1.1.1.12 root 2075: <li>TT and Falcon resolutions support only <em>integer</em> scaling ratios.
2076: If the scaling ratio cannot match the requested size exactly, Hatari
2077: will use a ratio that will produce smaller size closest to the
2078: requested one.</li>
2079: </ul>
2080: <p>
2081: You should set these values to a size that suits best your monitor
2082: resolution. It's intended to help in getting Hatari to best use your
2083: monitor space on a windowed mode and in fullscreen avoiding "fuzzy"
1.1.1.13! root 2084: scaling done by your LCD monitor.
1.1.1.12 root 2085: </p>
2086: <p>
2087: Giving "-z 2" option on command line will reset max zoomed size to
2088: default values and "-z 1" will disable all zooming.
2089: Note that zooming takes additional CPU computing time and should
2090: not be enabled on very slow computers.
2091: </p>
2092: <p>Click the <span class="button">Screenshot</span> button to create
2093: a screenshot in PNG (or BMP) format to the current working directory
2094: or click the <span class="button">Record AVI</span> button to
1.1.1.13! root 2095: record an AVI format video of Hatari screen (and audio) output.
! 2096: </p>
! 2097: <p>
! 2098: Selecting "Crop statusbar" option will leave statusbar out from
! 2099: the screenshots and recorded videos.
1.1 root 2100: </p>
1.1.1.8 root 2101:
2102: <a name="The Keyboard Dialog"></a><h4 class="gui">The Keyboard Dialog</h4>
1.1.1.5 root 2103:
2104: <div class="floatimage">
1.1.1.8 root 2105: <img src="images/keyboard.png" width="459" height="223" alt="Hatari's GUI - the keyboard dialog">
1.1.1.5 root 2106: </div>
2107:
2108: <p>Here you can select the keyboard mapping to use. Two different mappings
1.1.1.12 root 2109: called "Symbolic" and "Scancode" are predefined.</p>
2110: <p>"Symbolic" tries to map the symbolic values of your PC keys
1.1.1.5 root 2111: to the ST keys. It should be working pretty good on all systems as long
2112: as your keyboard layout looks close to the standard english keyboard
2113: layout. However, you might experience some problems with special keys like
2114: brackets etc.</p>
1.1.1.12 root 2115: <p>"Scancode" uses the scancode values of your PC keys for keyboard
1.1.1.5 root 2116: mapping. This only works on certain architectures like Linux where the
2117: scancodes are similar to the ST scancodes (e.g. it does not work on Mac OS X).
2118: If it works on your system, this often gives better results than the symbolic
2119: mapping. Note that you also need a TOS version with the right language
2120: (e.g. use a French TOS if you are using a French keyboard).</p>
2121: <p>You can also load a custom keyboard mapping file here if you wish. Please
1.1.1.12 root 2122: note that the custom keyboard mapping will use the "symbolic"
1.1.1.6 root 2123: mapping for all keys that are not defined by your map file. Have a look
2124: at the supplied example mapfile (keymap-sample.txt) to see how to create
2125: your own keyboard mapping.</p>
1.1.1.8 root 2126: <p>
2127: When the emulator runs in fast forward mode, and you want to type text,
2128: it can be annoying that the emulated system detects multiple key events
2129: due to the key repetition of the emulated system. To avoid this you can
2130: disable the key repetition in fast forward mode here.
2131: </p>
1.1.1.5 root 2132:
2133:
1.1.1.8 root 2134: <a name="The Sound Dialog"></a><h4 class="gui">The Sound Dialog</h4>
2135:
2136: <div class="floatimage">
1.1.1.13! root 2137: <img src="images/sound.png" width="380" height="383" alt="Hatari's GUI - the sound dialog">
1.1.1.5 root 2138: </div>
2139:
1.1.1.2 root 2140: <p>Here you can control the sound subsystem.</p>
1.1.1.3 root 2141: <p>Check if you want emulated sound at all. Emulation is faster if
2142: sound emulation is turned off.</p>
1.1.1.10 root 2143: <p>
2144: Nine frequencies from low to high quality are available. Experiment a
2145: little bit to find out which fits best for your setup.
2146: For most modern computers, 44100 Hz or 48000 Hz should be fine.
2147: For older or slower host systems, you should use a lower frequency.
2148: 12517, 250033 and 50066 Hz are frequencies supported by
2149: the STE/TT/Falcon sound DMA.
2150: </p>
2151: <p>
1.1.1.13! root 2152: YM voice volume mixing "ST table" method uses a lookup table of audio output
! 2153: voltage values measured on STF and "Linear" just averages the 3 YM voices.
! 2154: </p>
! 2155: <p>
1.1.1.10 root 2156: You can select to record a piece of sound here.
2157: Use the <span class="button">Browse</span> button to choose a file.
2158: The file name extension that you use (.WAV or .YM) determines in which format
2159: the sound is recorded in. The <span class="button">Record sound</span> button
2160: is a toggle so you will need to return to the GUI to switch sound recording off
2161: again (or to use the keyboard shortcut for that).
2162: </p>
1.1.1.5 root 2163:
2164:
1.1.1.8 root 2165: <a name="The Devices Dialog"></a><h4 class="gui">The Devices Dialog</h4>
1.1.1.5 root 2166:
1.1.1.8 root 2167: <div class="floatimage">
1.1.1.10 root 2168: <img src="images/devices.png" width="520" height="383" alt="Hatari's GUI - the device dialog">
1.1.1.5 root 2169: </div>
2170:
1.1.1.10 root 2171: <p>Check the first checkmark to enable experimental printer support.
2172: See the <a href="#Emulated printer">Emulated printer</a> section for
2173: details.</p>
1.1.1.8 root 2174:
1.1.1.3 root 2175: <p>As Hatari currently only supports printing to file, click on <span
1.1.1.10 root 2176: class="button">Browse</span> to select the file to print to. You can
1.1.1.3 root 2177: enter a new filename as well.</p>
1.1.1.10 root 2178: <p>Check the second checkmark to enable experimental RS232 support.
2179: The RS232 device is configured according to the settings of
1.1.1.3 root 2180: the emulated RS232 of the Atari ST. This means Hatari will
2181: automatically use baudrate and handshaking as configured for the
2182: emulated ST.</p>
1.1.1.10 root 2183: <p>Click on <span class="button">Browse</span> to select suitable
2184: device files for serial input and output. On Linux a good choice is
2185: /dev/ttyS0 or /dev/ttyS1.
2186: </p>
2187: <p>Check the third checkmark to enable experimental MIDI support.
2188: Click on <span class="button">Browse</span> to select a suitable
2189: MIDI device files for MIDI input and output.</p>
2190: <p><span class="file">midi-linux.txt</span> file explains how to
1.1.1.12 root 2191: select the correct MIDI device file, how to set up software sound
2192: synthetizing on Linux (using Alsa) if your sound card/driver doesn't
2193: support MIDI, and how to set up MIDI networking e.g. between multiple
1.1.1.10 root 2194: Hatari instances.
1.1.1.2 root 2195: </p>
1.1.1.5 root 2196:
1.1.1.8 root 2197:
2198: <a name="Keyboard shortcuts"></a><h3 style="clear:both;">Keyboard shortcuts</h3>
1.1.1.5 root 2199:
1.1 root 2200: <p> While the emulator is running, you can activate or toggle various
1.1.1.6 root 2201: features via Hatari keyboard shortcuts. Below are listed the default
2202: shortcut key bindings:</p>
1.1.1.3 root 2203: <table border="1" cellpadding="3">
1.1 root 2204: <tbody>
2205: <tr class="backdropped">
2206: <td align="center">Shortcut</td>
2207: <td align="center">Purpose</td>
2208: </tr>
2209: <tr>
1.1.1.2 root 2210: <td align="center"><span class="key">ALTGR+a</span></td>
2211: <td align="center">record animation</td>
2212: </tr>
2213: <tr>
1.1 root 2214: <td align="center"><span class="key">ALTGR+g</span></td>
1.1.1.8 root 2215: <td align="center">grab a screenshot</td>
1.1 root 2216: </tr>
2217: <tr>
1.1.1.2 root 2218: <td align="center"><span class="key">ALTGR+i</span></td>
1.1.1.8 root 2219: <td align="center">boss key: leave full screen mode, pause Hatari
2220: and iconify its window</td>
1.1.1.2 root 2221: </tr>
2222: <tr>
1.1 root 2223: <td align="center"><span class="key">ALTGR+j</span></td>
1.1.1.8 root 2224: <td align="center">toggle joystick emulation via cursor keys
2225: on/off between ports 0 and 1</td>
1.1 root 2226: </tr>
2227: <tr>
2228: <td align="center"><span class="key">ALTGR+m</span></td>
1.1.1.8 root 2229: <td align="center">(un-)lock the mouse into the window</td>
1.1 root 2230: </tr>
2231: <tr>
2232: <td align="center"><span class="key">ALTGR+r</span></td>
1.1.1.2 root 2233: <td align="center">(warm) reset the ST</td>
1.1 root 2234: </tr>
2235: <tr>
2236: <td align="center"><span class="key">ALTGR+c</span></td>
1.1.1.3 root 2237: <td align="center">coldreset the ST (same as the original power
2238: switch)</td>
1.1 root 2239: </tr>
2240: <tr>
1.1.1.8 root 2241: <td align="center"><span class="key">ALTGR+d</span></td>
2242: <td align="center">open dialog to select/change disk A</td>
2243: </tr>
2244: <tr>
1.1.1.2 root 2245: <td align="center"><span class="key">ALTGR+s</span></td>
2246: <td align="center">enable/disable sound</td>
2247: </tr>
2248: <tr>
1.1 root 2249: <td align="center"><span class="key">ALTGR+q</span></td>
2250: <td align="center">quit the emulator</td>
2251: </tr>
2252: <tr>
1.1.1.2 root 2253: <td align="center"><span class="key">ALTGR+x</span></td>
1.1.1.10 root 2254: <td align="center">toggle normal speed/fast forward</td>
1.1.1.2 root 2255: </tr>
2256: <tr>
2257: <td align="center"><span class="key">ALTGR+y</span></td>
2258: <td align="center">enable/disable sound recording</td>
2259: </tr>
2260: <tr>
1.1.1.7 root 2261: <td align="center"><span class="key">ALTGR+k</span></td>
2262: <td align="center">save memory snapshot</td>
2263: </tr>
2264: <tr>
2265: <td align="center"><span class="key">ALTGR+l</span></td>
2266: <td align="center">load memory snapshot</td>
2267: </tr>
2268: <tr>
1.1.1.5 root 2269: <td align="center"><span class="key">ALTGR+f or F11</span></td>
1.1.1.8 root 2270: <td align="center">toggle between fullscreen and windowed mode</td>
1.1 root 2271: </tr>
2272: <tr>
1.1.1.5 root 2273: <td align="center"><span class="key">ALTGR+o or F12</span></td>
1.1.1.8 root 2274: <td align="center">activate the options GUI</td>
1.1 root 2275: </tr>
2276: <tr>
2277: <td align="center"><span class="key">PAUSE</span></td>
1.1.1.10 root 2278: <td align="center">pause emulation</td>
2279: </tr>
2280: <tr>
2281: <td align="center"><span class="key">AltGr+PAUSE</span></td>
2282: <td align="center">invoke the internal Hatari debugger</td>
1.1 root 2283: </tr>
2284: </tbody>
2285: </table>
1.1.1.5 root 2286:
1.1.1.6 root 2287: <p>You can change the key bindings from the Hatari configuration file.
1.1.1.10 root 2288: The required key values can be seen in the SDL_keysym.h include file
1.1.1.8 root 2289: (usually in /usr/include/SDL/).</p>
1.1.1.6 root 2290:
2291:
1.1.1.5 root 2292: <a name="Emulated Atari ST keyboard"></a><h3>Emulated Atari ST keyboard</h3>
2293:
1.1 root 2294: <p> All other keys on the keyboard act as the normal Atari ST keys so
2295: pressing SPACE on your PC will result in an emulated press of the SPACE
2296: key on the ST. The following keys have special meanings: </p>
1.1.1.3 root 2297: <table border="1" cellpadding="3">
1.1 root 2298: <tbody>
2299: <tr class="backdropped">
2300: <td align="center">Key</td>
2301: <td align="center">Meaning</td>
2302: </tr>
2303: <tr>
2304: <td align="center"><span class="key">Alt</span></td>
2305: <td align="center">will act as the ST's ALTERNATE key</td>
2306: </tr>
2307: <tr>
2308: <td align="center"><span class="key">left CTRL</span></td>
2309: <td align="center">will act as the ST's CONTROL key</td>
2310: </tr>
2311: <tr>
1.1.1.2 root 2312: <td align="center"><span class="key">Print Screen</span></td>
1.1 root 2313: <td align="center">will emulate the ST's HELP key</td>
2314: </tr>
2315: <tr>
1.1.1.2 root 2316: <td align="center"><span class="key">Scroll Lock</span></td>
1.1 root 2317: <td align="center">will emulate the ST's UNDO key</td>
2318: </tr>
1.1.1.2 root 2319: <tr>
2320: <td align="center"><span class="key">Page Up</span></td>
2321: <td align="center">will emulate the ST's ( key in the keypad</td>
2322: </tr>
2323: <tr>
2324: <td align="center"><span class="key">Page Down</span></td>
2325: <td align="center">will emulate the ST's ) in the keypad</td>
2326: </tr>
1.1 root 2327: </tbody>
2328: </table>
1.1.1.5 root 2329:
1.1.1.8 root 2330: <p>If joystick emulation via keyboard is enabled, by default cursor keys
2331: are used for the directions and <span class="key">right CTRL</span> key
2332: as the fire button. Otherwise they act as corresponding keys of the emulated
2333: Atari ST.</p>
2334:
1.1.1.12 root 2335: <p>NOTE: Problems with simultenous keypresses most likely aren't an
2336: issue in Hatari as many modern keyboards report/support only three
2337: simultenous key presses (or even just two depending on which keys
2338: are in question). Expensive gaming keyboards support more.</p>
2339:
1.1.1.5 root 2340:
2341: <a name="Emulated mouse"></a><h3>Emulated mouse</h3>
2342:
1.1 root 2343: <p>For obvious reasons your PC mouse will act as the emulated Atari ST
2344: mouse. In fullscreen mode it will act as expected, directly controlling
2345: the ST mouse pointer. </p>
2346: <p>However it is a little bit different in windowed mode. To make the
2347: mouse work there as expected you need to grab it first or lock it into
1.1.1.3 root 2348: the Hatari window. Do this by pressing the <span class="key">ALTGR+m</span>
1.1.1.10 root 2349: hotkey combination or starting Hatari with the
2350: <span class="commandline">--grab</span> command line option.
2351: Press the shortcut key (again) to go back to normal mouse behaviour
2352: which allows you to move mouse outside outside the Hatari window while
2353: Hatari is up and running. Note: pausing the emulation will also
2354: (temporarily) release the mouse grab.</p>
1.1.1.6 root 2355: <p>Mouse scrollwheel will act as cursor up and down keys. </p>
1.1.1.5 root 2356:
2357: <a name="Emulated joystick"></a><h3>Emulated joystick</h3>
2358:
1.1 root 2359: <p>The Atari ST joysticks are emulated ofcourse allowing you to play
2360: your favourite games with Hatari. </p>
2361: <p>The default mode is to use a connected PC joystick. You can use any
2362: joystick that is supported by your kernel. If your joystick works with
2363: other applications, it will likely work with Hatari as well. Make sure
2364: it is calibrated and then off you go. Move the stick to point into the
2365: desired direction. Please note that Hatari will not detect analogue
2366: movement as the Atari ST only had digital joysticks. The first
1.1.1.3 root 2367: firebutton will act as the normal firebutton on the Atari ST while the
2368: second
2369: firebutton will emulate a keypress of the <span class="key">SPACE</span>
2370: key on the ST as many ST
1.1.1.8 root 2371: games utilize the SPACE bar for secondary game functions. (Xenon for
1.1.1.3 root 2372: example)</p>
1.1 root 2373: <p>If you do not have a PC joystick or joypad, then you do not need to
2374: desperate. You can emulate one of the two Atari ST joysticks via the
2375: cursor keys. Just activate it in the GUI. Then the cursor keys will act
2376: as the joystick directions, the right CTRL key will act as the
2377: firebutton. You can still use the cursor keys as the ST's
1.1.1.3 root 2378: cursorkeys in this mode as long as you press <span class="key">SHIFT</span>
1.1.1.8 root 2379: along with the cursorkeys. You can also configure these keys from the
2380: joystick options.</p>
1.1.1.5 root 2381:
2382: <a name="Emulated video"></a><h3>Emulated video</h3>
2383:
1.1.1.8 root 2384: <p>Hatari emulates all screen modes of the original machine.</p>
2385: <p>
2386: ST/STE shifter overscan effects are emulated, but due to the fact
2387: that these effects are achieved by using quirks and glitches in the
2388: original chips to do things beyond their specification, emulation is
2389: a bit tricky for these effects. As a result, some demos using these
2390: techniques might not be displayed correctly in Hatari, known ones are
2391: listed in the <span class="file">compatibility.html</span> file.
1.1.1.3 root 2392: </p>
2393: <p>Beside that you can setup extended VDI modes. These only work with
2394: GEM-compliant applications and they are equal to fitting a videocard
2395: into your Mega ST.</p>
2396: <p>Make sure to disable extended VDI modes for playing games as 99% of
2397: all ST games will not be able to make use of higher resolutions.</p>
1.1.1.5 root 2398:
2399: <a name="Emulated printer"></a><h3>Emulated printer</h3>
2400:
1.1.1.3 root 2401: <p>Due to the fact that printer handling is very different between Unix
2402: style machines and the Atari ST, emulation
1.1.1.2 root 2403: of the printer is achieved by writing all printer output to a file.</p>
1.1.1.3 root 2404: <p>The file will contain a sequence of data, the same that would appear
2405: on the data pins of the Atari ST printer port.
2406: That would include control characters and commands for graphic
2407: printing. Clicking "Print desktop" on the GEM desktop would result
1.1.1.2 root 2408: in a messy data dump in the printer output.</p>
1.1.1.3 root 2409: <p>Printer emulation works best for plain text files or programs that
2410: do not format the output for a specific printer.
2411: The file contents can be used with your favourite text editor for
2412: further processing and printing to a real printer.</p>
2413: <p>To get real direct printing out of Hatari on a PostScript printer,
2414: you may set up a GDOS printer with a PostScript driver on the emulated
2415: Atari and set your printer device file as Hatari's printer output.<br>
2416: <em>NOTE:</em> This has not been tested yet and the Hatari team cannot
2417: guarantee that it will work.</p>
1.1.1.5 root 2418:
2419: <a name="Emulated RS232"></a><h3>Emulated RS232</h3>
2420:
1.1.1.3 root 2421: <p>Serial communications in Hatari is designed to directly use a serial
2422: port on your PC.</p>
2423: <p>Communications parameters are set automatically upon the settings of
2424: the emulated ST. This means all you do is to set
2425: the communication parameters like baudrate from your ST communications
2426: software. Hatari will do the rest and handle
1.1.1.2 root 2427: the serial input and output for you.</p>
1.1.1.5 root 2428:
2429: <a name="Floppy disk images"></a><h2>Floppy disk images</h2>
2430:
1.1 root 2431: <p>Hatari does not use floppy disks directly but disk images due to
2432: differences between the floppy disk controllers of the ST and the PC.
1.1.1.3 root 2433: Three types of disk images are currently supported: The raw "ST" type,
2434: the similar "DIM" type and
1.1.1.2 root 2435: the compressed "MSA" (Magic-Shadow-Archiver) type. </p>
1.1 root 2436: <p> The raw type (file suffix should be "*.st") is simply a sector by
2437: sector image of a real floppy disk. You can easily create such an image
1.1.1.3 root 2438: with the <span class="commandline">dd</span> program which should
2439: normally be pre-installed on every
2440: Unix-like system. Simply type something like <span class="commandline">dd
2441: if=/dev/fd0 of=myimage.st</span> to create a disk image. Of course you
2442: need access to
1.1 root 2443: /dev/fd0, and depending on your system and the type of floppy disk you
2444: might have to use another device name here (for example I use
1.1.1.3 root 2445: /dev/fd0u720 for 720kB disks). However, if the disk is copy-protected
2446: or
1.1 root 2447: doesn't use a MSDOS compatible file system, this might fail. So be very
1.1.1.10 root 2448: careful if you are not sure about the disk format. </p>
1.1.1.3 root 2449: <p> The other possibility is to image the disk on a real Atari ST.
2450: There
1.1 root 2451: are programs like the Magic Shadow Archiver for this task. Hatari
1.1.1.3 root 2452: supports this slightly compressed MSA disk images, too. Note that
2453: Hatari
2454: only supports the "old" MSA format, there are some Magic Shadow
2455: Archiver
1.1 root 2456: clones (like Jay-MSA) that create better compressed but
1.1.1.2 root 2457: Hatari-incompatible disk images. However, if you have got such a MSA
1.1.1.3 root 2458: disk and want to use it with Hatari, you can still run the
2459: corresponding
1.1.1.2 root 2460: MSA program within Hatari to extract the incompatible disk image to a
2461: normal floppy disk image. </p>
1.1 root 2462: <p> While *.ST and *.MSA are more or less the "standard" types of Atari
1.1.1.2 root 2463: disk images, you might sometimes also find STT or ADF images on the
1.1.1.3 root 2464: internet. These currently do not work with Hatari. </p>
2465: <p>Hatari can now also utilize *.DIM images just as *.ST ones without
2466: any problems.
1.1.1.2 root 2467: Note that DIM images are nearly the same as the raw ST images
1.1.1.3 root 2468: (they only have an additional 32 bytes header), so you can easily
2469: transform
1.1.1.2 root 2470: the DIM images into ST images by stripping the header from the files.
2471: For example try something like:
2472: <span class="commandline">dd if=input.dim of=output.st bs=32 skip=1</span>
2473: </p>
1.1 root 2474: <p> If you've got a disk image that has been created with the old ST
2475: emulator PaCifiST (for DOS) or with early versions of the program
2476: Makedisk, and the disk image does not work with Hatari, then the disk
1.1.1.3 root 2477: probably suffers from the "PaCifiST bootsector bug" (Hatari will
2478: display a
1.1 root 2479: warning message then). In this case, the bootsector of the disk
2480: contains some illegal data, so that the disk even does not work on a
2481: real ST any more. However, if it is a .ST and not a .MSA disk, you can
1.1.1.3 root 2482: easily fix it by using a hex-editor to change the byte at offset $D
2483: (13)
1.1 root 2484: from 0 to 1 (don't forget to backup your disk image first, since you
2485: can also easily destroy your disk image when changing a wrong byte
2486: there). If the disk contains a bootsector program, you probably have to
2487: adjust the boot sector check sum, too (it can be found at offset $1FE +
2488: $1FF). </p>
1.1.1.2 root 2489: <p>Hatari supports disk images that are compressed with (Pk-)ZIP
2490: (file suffix must be ".zip") or GZip (file suffix must be ".st.gz" or
1.1.1.3 root 2491: ".msa.gz"), so you can archive your disk images into zip archives.
1.1.1.2 root 2492: You can also directly run the zip archives you may download from the
2493: net as long as the archive contains a disk image in .ST or .MSA format.</p>
1.1.1.3 root 2494: <p><em>Note:</em> Hatari does not save disk images back to *.ZIP files
2495: so
1.1.1.2 root 2496: your highscores and savegames are lost if you load the game from such
2497: a zipped disk image.</p>
1.1.1.5 root 2498:
1.1.1.10 root 2499:
1.1.1.5 root 2500: <a name="Hard disk support"></a><h2>Hard disk support</h2>
2501:
1.1.1.8 root 2502: <p>
1.1.1.10 root 2503: Hatari supports three ways of emulating Atari hard drives: The low-level
2504: ACSI and IDE hard disk emulation and a GEMDOS based drive emulation.
2505: In most cases the GEMDOS based hard disk emulation is best as it allows
2506: exchanging files easily between the emulated and the host environment.
2507: </p>
2508: <p>
2509: Please note that changing the HD-image or the GEMDOS HD-folder will reset
1.1.1.8 root 2510: the emulated Atari since it is not possible to switch the hard disk
2511: while the emulator is running.
2512: </p>
1.1.1.12 root 2513: <p>
2514: On a 32-bit host system, the size of a hard disk image is limited to 2 GB.
2515: On 64-bit host systems, bigger images might be possible but the support for
2516: bigger images is not tested very well yet.
2517: </p>
1.1.1.6 root 2518:
2519:
2520: <a name="GEMDOS based hard disk emulation"></a><h3>GEMDOS based hard disk emulation</h3>
1.1.1.12 root 2521: <p>
2522: With the GEMDOS based drive emulation, you can easily "mount" a
1.1 root 2523: folder from the host file system to a drive of the emulated Atari. To
2524: use the GEMDOS based drive emulation, you should use a folder on your
1.1.1.3 root 2525: hard disk that only contains files and folders with valid TOS
1.1.1.12 root 2526: filenames i.e. file and folders names shouldn't contain invalid GEMDOS
2527: filename characters and their length shouldn't exceed the 8+3 file name
2528: length limit.
2529: </p>
2530: <p>
2531: If you provide <span class="commandline">--harddisk</span> option
2532: a directory containing only single letter subdirectories, each of
2533: these subdirectories will be treated as a separate partition, otherwise
2534: the given directory itself will be assigned to drive "C:". In the
2535: multiple partition case, the letters used as the subdirectory names
2536: will determine to which drives/partitions they're assigned.
2537: </p>
2538: <p>
2539: GEMDOS drive emulation is an easy way to share files between the
2540: host system and the emulated Atari, but there are also some known
2541: limitations which are due to the way the GEMDOS drive emulation is
2542: implemented:
2543: </p>
2544: <ul>
2545: <li>It is not possible to use a cartridge image at the same time
2546: with the GEMDOS drive emulation (Hatari has it's own cartridge code
2547: that is used for GEMDOS emulation).</li>
2548: <li>As MiNT installs its own GEMDOS handler, it doesn't work with
2549: the GEMDOS drive emulation. MiNT needs to be booted from a real hard
2550: disk image.</li>
2551: <li>GEMDOS drive emulation conflicts with the ACSI and IDE harddisk images.
2552: If you want to use GEMDOS HD emulation and ACSI/IDE disk images together,
2553: use a multiple partition GEMDOS emulation setup and select the partition
2554: subdirectories (letters) so that they don't conflict with the ACSI/IDE
2555: drive partitions (letters). With HD Driver you have also another option,
2556: see <a href="#Using HD Driver with GEMDOS partitions">Using HD Driver
2557: with GEMDOS partitions</a>.</li>
2558: <li><em>The GEMDOS drive emulation does not work (very well) with TOS
2559: 1.00 and 1.02</em>. Use at least TOS 1.04 if you want the GEMDOS drive
2560: emulation to work properly.</li>
2561: </ul>
2562: <p>
2563: So, if your programs complain that they could not find/read/write
2564: files on the GEMDOS emulated drive, you should try to copy them to a
2565: floppy disk image or a real hard disk image!
1.1.1.6 root 2566: </p>
1.1.1.8 root 2567:
1.1.1.10 root 2568: <a name="ACSI hard disk emulation"></a><h3>ACSI hard disk emulation</h3>
2569: <p>
2570: To use the ACSI hard disk emulation, you need a hard disk image file
1.1.1.12 root 2571: with a pre-installed HD driver in it. You can try to get an image of
2572: your old ST hard disk or grab one from the internet (e.g. from the
2573: Hatari website).
2574: </p>
2575: <p>
2576: To create a <em>new</em> ACSI hard disk image, you can start with an empty
2577: image that you have created for example with the following command:
2578: <span class="commandline">dd if=/dev/zero of=hd.img bs=512 count=xxx</span>
2579: (where 'xxx' is size in 512 byte blocks). Copy the complete AHDI 5.0
2580: package to a floppy disk image, then boot Hatari with this floppy disk
2581: image and the fresh hard disk image like this:
2582: <span class="commandline">--acsi hd.img ahdi.st</span>.
2583: Then start HDX.PRG from the floppy disk and format + partition the hard
2584: disk image with it.
2585: </p>
2586: <p>
2587: Formatting and partitioning works currently only with AHDI 5, but you
2588: can install the AHDI 6 driver to the hard disk after it's formatted.
2589: Restart the emulated system, run AHDI.PRG from the floppy disk to access
2590: the hard disk image from the emulated Atari and then run HINSTALL.PRG.
2591: After installing the hard disk driver to the fresh HD image with
2592: HINSTALL.PRG, you can boot directly from the hard disk image.
1.1.1.10 root 2593: </p>
2594:
2595: <a name="IDE hard disk emulation"></a><h3>IDE hard disk emulation</h3>
2596: <p>
1.1.1.12 root 2597: <p>
2598: As the IDE disk format (little endian) differs from the ACSI disk format
2599: (big endian), you need separate disk images for them. Hatari doesn't
2600: currently support formatting IDE disks with AHDI, but you can do it with
2601: <em>Cecile</em>.
2602: </p>
2603: <p>
2604: First create an empty image file with the size of your choice with:
1.1.1.10 root 2605: <span class="commandline">dd if=/dev/zero of=hd.img bs=1k count=xxx</span>.
2606: Then get the Cecile hard disk driver from
2607: <a href="http://centek.free.fr/atari/softs/s_cecile.htm">http://centek.free.fr/atari/softs/s_cecile.htm</a>
1.1.1.12 root 2608: and put it on a floppy disk image (e.g. to one named "cecile.st" using:
2609: <span class="commandline">zip2st.sh cecile.zip</span>).
1.1.1.10 root 2610: </p>
2611: <p>
2612: Run Hatari with
1.1.1.12 root 2613: <span class="commandline">hatari --machine falcon --tos tos404.rom
2614: --ide-master hd.img cecile.st</span>, switch to larger color resolution
2615: and warm up your French language skills. Then start the Cecile hard
2616: disk driver CECILE.PRG and run CC_TOOLS.APP to partition your hard
2617: disk image. Click the "Partition" button, select "Hatari IDE disk" and set
2618: suitable partition size with the arrows (below type field). Then click
2619: "Valider".
1.1.1.10 root 2620: </p>
2621: <p>
2622: If you only want to use your HD image in Falcon mode, you can install
2623: the Cecile hard disk driver to the image from the Cecile CC_TOOLS.APP:
1.1.1.12 root 2624: Click the "Installer" button and save the Cecile driver to the
1.1.1.10 root 2625: 1st partition on "Hatari IDE disk". If you want to also use your HD
2626: image in ST/STE mode, you need to get and install AHDI 6 driver on it
1.1.1.13! root 2627: instead (see <a href="#ACSI hard disk emulation">ASCI hard disk
1.1.1.12 root 2628: emulation</a> section).
1.1.1.10 root 2629: </p>
2630: <p>
2631: Then you can boot from your hard disk image by simply specifying it
1.1.1.12 root 2632: with the <span class="commandline">--ide-master</span> parameter.
1.1.1.10 root 2633: </p>
2634:
2635:
1.1.1.12 root 2636: <a name="Moving files to/from hard disk images"></a><h2>Moving files
2637: to/from hard disk images</h2>
2638:
2639: <p>Moving files to and from Atari hard disk images can be done
2640: either through GEMDOS partitions (host directories mounted inside
2641: Hatari emulation) or accessing the images directly on the host
2642: (outside the emulation). Both have their own limitations.</p>
2643:
2644: <p>If it's fine for the IDE/ACSI partitions to be first, you can use
2645: hard disk images with AHDI or Cecile driver and a multipartition
2646: GEMDOS setup as described in above sections. If you want to boot from
2647: a GEMDOS partition i.e. such to be before hard disk image partitions,
2648: and still to be able to access all the IDE/ACSI partitions, you need to
2649: use HD Driver.</p>
2650:
2651: <a name="Using HD Driver with GEMDOS partitions"></a><h3>Using HD Driver
2652: with GEMDOS partitions</h3>
2653:
2654: <p>Uwe Seimet's <a href="http://www.seimet.de/atari/en/hddriver.html">HD
2655: Driver</a> works fine with both the Hatari GEMDOS partitions and normal
2656: hard disk images. However, it doesn't work with EmuTOS so you need
2657: real TOS (at least version v1.04).
2658: </p>
2659:
2660: <p>First copy the HDDRIVER.PRG binary into your GEMDOS drive emulation
2661: directory AUTO folder. Then start the HDDRUTIL.APP configuration utility,
2662: locate HDDRIVER.PRG, open the
2663: <a href="http://www.seimet.de/atari/en/hddriverscreenshots.html">"Devices
2664: and Partitions" dialog</a> and select the "Preserve Existing Partitions"
2665: option. Then you can just start Hatari with your hard disk image and
2666: this GEMDOS directory, for example like this:
2667: "<span class="commandline">hatari --harddisk gemdos-hd/ --ide-master
2668: ide-hd.image</span>".</p>
2669:
2670: <p>If you're using the <em>demo</em> version of HD Driver, you can
2671: write files only to the C: partition, i.e. in above case only copy
2672: files from the hard disk image partition to the GEMDOS partition (with
2673: some write slowndowns included into the demo version). If you want to
2674: copy files to the hard disk image with the <em>demo</em> version of
2675: the HD Driver, you need to set the hard disk image as drive C:.</p>
2676:
2677: <p>To accomplish this, set the GEMDOS partitions to be from D: forward,
2678: i.e. have a directory which contains only single letter subdirectories,
2679: starting from "D" like in "<span class="commandline">mkdir gemdos-hd;
2680: mkdir gemdos-hd/D</span>". Then give Hatari (as the last parameter)
2681: a boot floppy image containing the demo version of HDDRIVER.PRG in
2682: its AUTO folder, like this: "<span class="commandline">hatari
2683: --ide-master ide-hd.image --harddisk gemdos-hd/ hd-driver-floppy.st</span>".
2684: </p>
2685:
2686:
2687: <a name="Accessing HDD image partitions outside of Hatari"></a><h3>Accessing
2688: HDD image partitions outside of Hatari</h3>
2689:
1.1.1.10 root 2690: <p>
1.1.1.12 root 2691: If you want to access the harddisk image partitions also outside
2692: the emulation, the disk image needs to have a DOS partition table.
2693: The <span class="commandline">atari-hd-image</span> script included
1.1.1.10 root 2694: with Hatari can be used to create such an image.
2695: </p>
2696: <p>
2697: Inside the Hatari emulator, EmuTOS can access partition(s) on these
2698: kind of images directly without any driver software. Of the Atari HD
1.1.1.12 root 2699: drivers mentioned above, Centek's Cecile and Uwe Seimet's HD Driver
2700: (demo) work fine with these partitions. E.g. AHDI and CBHD don't.
1.1.1.10 root 2701: </p>
2702: <p>
1.1.1.12 root 2703: Note that plain EmuTOS supports only ACSI and the listed HD drivers
2704: support only IDE (emulation). Cecile needs TT or Falcon and HD Driver
2705: doesn't work with EmuTOS. To summarise; if ASCI emulation and
2706: EmuTOS are enough, use those. Otherwise, if you want to use TT or
2707: Falcon emulation, use Cecile (or full HD Driver version if you have
2708: it), otherwise use HD Driver (demo).
1.1.1.10 root 2709: </p>
2710: <p>
2711: To access the content of the partitions on Linux host, there are two
2712: possibilities:
2713:
2714: <h4>Using Mtools</h4>
2715: <p>
2716: For this you need to add an entry for the hard disk
2717: image to your <span class="commandline">~/.mtoolsrc</span> and
2718: specify which partition you want to access from the image. For
2719: an image created with the above mentioned script, the line in
2720: the configuration file should look something like this:
2721: </p>
2722: <pre>
2723: MTOOLS_NO_VFAT=1
2724: drive c: file="/home/user/hatari/hd.img" partition=1
2725: </pre>
2726: <p>
2727: Note that Mtools is instructed to use FAT compatibility mode because
2728: EmuTOS cannot deal properly with VFAT file information. If you don't
2729: want this setting for all your Mtools drives, you can set it also via
1.1.1.12 root 2730: the environment like this ("::" refers to the drive image given with
2731: the "-i" option):
1.1.1.10 root 2732: </p>
2733: <pre>
1.1.1.12 root 2734: MTOOLS_NO_VFAT=1 mcopy -spmv -i hd.img files/* ::
1.1.1.10 root 2735: </pre>
2736:
2737: <h4>Using a loopback device</h4>
2738: <p>
2739: This is recommended even by Mtools documentation, but it's less
2740: convenient as it requires root rights. First you need to "loop"
2741: mount the image:
2742: </p>
2743: <pre>
2744: $ su
2745: # image="hd.img"; mountdir="hd"
2746: # start=$(parted $image unit s print | awk '/ 1 /{print $2}' | tr -d s)
2747: # losetup -f $image -o $((512*$start))
2748: # loop=$(losetup -a | tail -1 | cut -d: -f1)
2749: # mkdir -p $mountdir
2750: # mount -t msdos $loop $mountdir
2751: </pre>
2752: <p>
2753: This uses <span class="commandline">parted</span> to find out the first
2754: partition offset in sectors and then tells <span class="commandline">losetup</span>
2755: to bind the first free loop device to a corresponding offset from
2756: the <span class="commandline">hd.img</span> image.
2757: <span class="commandline">mount</span> is then used to mount the file system
2758: from the loop device on top of the "hd" directory.
2759: </p>
2760: <p>
2761: After you've copied the relevant files to the "hd" directory, you need
2762: unmount the file system and remove the loop device binding before using
2763: the disk image from Hatari:
2764: </p>
2765: <pre>
2766: # umount $mountdir
2767: # losetup -d $loop
2768: </pre>
2769:
2770: <a name="The debugger"></a><h2>The debugger</h2>
2771:
2772: <p>
2773: Hatari has a built-in debugging interface which can be used for
1.1.1.12 root 2774: analyzing code that runs in the emulated system. To invoke the
2775: debugger, press the <span class="key">AltGr + Pause</span>
2776: key combination.
2777: </p>
1.1.1.10 root 2778:
2779: <p>
1.1.1.12 root 2780: If you start Hatari with the "-D" command line option, m68k
2781: exceptions will automatically invoke the debugger. You can
2782: toggle this also later from the debugger with the "setopt -D"
1.1.1.10 root 2783: command.
2784: </p>
2785:
2786: <p>
1.1.1.13! root 2787: To run debugger commands at Hatari startup, one can use the "--parse
! 2788: <file>" command line option. This is useful e.g. for debugging
! 2789: TOS or some demo startup code, or if you always want to use some
! 2790: specific debugger setup (breakpoints etc).
! 2791: </p>
! 2792:
! 2793: <p>
1.1.1.12 root 2794: The debugger uses Hatari's parent console window, so make sure you run
2795: Hatari from the command line when you want to use the debugger. On
1.1.1.13! root 2796: Linux you can add for example an icon to your desktop that does it
! 2797: with something like this (replace "xterm" with your favorite terminal
! 2798: program):
1.1.1.10 root 2799: </p>
1.1.1.13! root 2800: <pre>
! 2801: xterm -T "Hatari debug window" -e hatari
! 2802: </pre>
1.1.1.10 root 2803:
1.1.1.12 root 2804:
2805: <a name="General debugger use"></a><h3>General debugger use</h3>
2806:
1.1.1.10 root 2807: <p>
1.1.1.12 root 2808: At the debugger prompt, type "help" to get a list of all
1.1.1.10 root 2809: the available commands and their shortcuts:
2810: </p>
2811: <pre>
1.1.1.12 root 2812: Generic commands:
2813: cd ( ) : change directory
2814: evaluate ( e) : evaluate an expression
2815: help ( h) : print help
2816: info ( i) : show machine/OS information
1.1.1.13! root 2817: lock ( ) : specify information to show on entering the debugger
1.1.1.12 root 2818: logfile ( f) : open or close log file
2819: parse ( p) : get debugger commands from file
2820: setopt ( o) : set Hatari command line and debugger options
2821: stateload ( ) : restore emulation state
2822: statesave ( ) : save emulation state
2823: trace ( t) : select Hatari tracing settings
2824: quit ( q) : quit emulator
2825:
2826: CPU commands:
2827: address ( a) : set CPU PC address breakpoints
2828: breakpoint ( b) : set/remove/list conditional CPU breakpoints
1.1.1.10 root 2829: disasm ( d) : disassemble from PC, or given address
1.1.1.13! root 2830: profile ( ) : profile CPU code
1.1.1.10 root 2831: cpureg ( r) : dump register values or set register to value
2832: memdump ( m) : dump memory
2833: memwrite ( w) : write bytes to memory
2834: loadbin ( l) : load a file into memory
2835: savebin ( s) : save memory to a file
1.1.1.12 root 2836: symbols ( ) : load CPU symbols & their addresses
1.1.1.10 root 2837: cont ( c) : continue emulation / CPU single-stepping
1.1.1.12 root 2838:
2839: DSP commands:
2840: dspaddress (da) : set DSP PC address breakpoints
2841: dspbreak (db) : set/remove/list conditional DSP breakpoints
2842: dspdisasm (dd) : disassemble DSP code
2843: dspmemdump (dm) : dump DSP memory
2844: dspsymbols ( ) : load DSP symbols & their addresses
1.1.1.13! root 2845: dspprofile (dp) : profile DSP code
1.1.1.12 root 2846: dspreg (dr) : read/write DSP registers
2847: dspcont (dc) : continue emulation / DSP single-stepping
1.1.1.10 root 2848: </pre>
2849:
1.1.1.13! root 2850: <a name="Entering arguments to debugger commands">
! 2851: </a><h4>Entering arguments to debugger commands</h4>
! 2852:
! 2853: <p>
! 2854: After writing (with TAB completion) one of the above command names,
! 2855: pressing TAB will (for most commands) show all the available subcommands.
! 2856: </p>
! 2857:
1.1.1.10 root 2858: <p>
1.1.1.13! root 2859: If you want to give numbers in other number bases
1.1.1.12 root 2860: than the default/selected one, they need to be prefixed with a
2861: character indicating this. For decimals this prefix is "#" (#15),
2862: for hexadecimals "$" ($F), and for binary values it's "%" (%1111).
1.1.1.13! root 2863: </p>
! 2864:
! 2865: <p>
! 2866: By default debugger expects all numbers without a prefix to be
1.1.1.12 root 2867: decimals, but you can change the default number base with the "setopt"
2868: command, just give it the desired default number base (bin/dec/hex).
1.1.1.13! root 2869: <em>When using the hexadecimal number base, remember still to prefix
! 2870: hexadecimal numbers with '$' if they could be confused with register
! 2871: names (a0-7, d0-7)!</em> Otherwise results from expressions and
! 2872: conditional breakpoints can be unexpected.
1.1.1.12 root 2873: </p>
2874:
1.1.1.13! root 2875:
! 2876: <h4>Calculations and immediate evaluation</h4>
! 2877:
1.1.1.12 root 2878: <p>
1.1.1.13! root 2879: Instead of a number, you can also use an arithmetic expression, by
! 2880: surrounding it with quotes (""). An expression can contain
! 2881: calculations with CPU and DSP register, symbol and Hatari variable
! 2882: values in addition to numbers. For example to give a sum of A0 and
! 2883: D0 register values to a command, use "a0+d0".
1.1.1.12 root 2884: </p>
2885:
2886: <p>
1.1.1.13! root 2887: Within arithmetic expressions parenthesis are used both to change
! 2888: the order of precendence <em>and</em> to indicate indirect addressing.
! 2889: Unlike with conditional breakpoint expressions (explained below), you
! 2890: cannot give size for the indirect addressing, a long value is always
! 2891: read from the RAM address given within parenthesis. For example to
! 2892: get a long value pointed by stack pointer + 2, use "(a7+2)".
1.1.1.12 root 2893: </p>
2894:
2895: <p>
1.1.1.13! root 2896: Values of arithmetic expressions are always evaluated before being
! 2897: given to a command. Except for "evaluate" and "address" commands,
! 2898: they always need to be marked with quotes (""). Besides arithmetics,
! 2899: this can be used also to give symbol/register/variable values to
! 2900: commands that don't otherwise interpret them. If command complains
! 2901: that it didn't recognize e.g. a register name, just put it to quotes
! 2902: and it will be "evaluated" before being given to the command.
1.1.1.12 root 2903: </p>
2904:
2905: <p>
2906: With command argument completion (see <a href="#Build notes">build
1.1.1.13! root 2907: notes</a>), result from the last "evaluate" command can be inserted
! 2908: by typing '$' and pressing TAB.
1.1.1.12 root 2909: </p>
2910:
2911:
2912: <a name="Inspecting emulation state"></a><h3>Inspecting emulation state</h3>
2913:
2914: <p>
2915: In the beginning, probably the most interesting commands are "m" and "d"
2916: for dumping and disassembling memory regions. You can use "dm" and "dd"
2917: commands to do the same for the DSP.
1.1.1.10 root 2918: </p>
2919: <pre>
2920: > help memdump
2921: 'memdump' or 'm' - dump memory
1.1.1.12 root 2922: Usage: m [start address-[end address]]
1.1.1.10 root 2923: dump memory at address or continue dump from previous address.
2924: </pre>
2925: <pre>
2926: > help disasm
2927: 'disasm' or 'd' - disassemble from PC, or given address
1.1.1.12 root 2928: Usage: d [start address-[end address]]
1.1.1.10 root 2929: If no address is given, this command disassembles from the last
1.1.1.12 root 2930: position or from current PC if no last position is available.
1.1.1.10 root 2931: </pre>
2932: <pre>
1.1.1.13! root 2933: > disasm pc
! 2934: $00aa6e : 2f08 move.l a0,-(sp)
! 2935: $00aa70 : 0241 0fff andi.w #$fff,d1
! 2936: $00aa74 : 207c 00fe 78c0 movea.l #$fe78c0,a0
! 2937: $00aa7a : 2070 1000 movea.l (a0,d1.w),a0
! 2938: $00aa7e : 4ed0 jmp (a0)
1.1.1.10 root 2939: </pre>
2940:
2941: <p>
1.1.1.13! root 2942: Both commands accept in addition to numeric addresses also register
! 2943: and symbol names, like in above example. If you don't specify an
! 2944: address, the commands continue showing from an address that comes
! 2945: after the previously shown data. "disasm" command default address
! 2946: will be reseted to PC address everytime you re-enter the debugger.
! 2947: </p>
! 2948:
! 2949: <p>
1.1.1.12 root 2950: You can use the "info" command to see state of specific sets of HW
1.1.1.13! root 2951: registers (e.g. "info videl") and Atari OS structures (e.g. "info gemdos").
! 2952: </p>
! 2953:
! 2954:
! 2955: <h4>Selecting what information is shown on entering the debugger</h4>
! 2956:
! 2957: <p>
! 2958: By using the "lock" command, you can ask Hatari to show specific
! 2959: information whenever you enter the debugger / hit a breakpoint. For
! 2960: example to see disassembly from current PC address, use "lock disasm".
! 2961: </p>
! 2962:
! 2963: <p>
! 2964: With the "regaddr" subcommand, you see disassembly or memory
! 2965: dump of an address pointed by a given register ("lock regaddr disasm
! 2966: a0"). Of the DSP registers, only Rx ones are valid for this
! 2967: subcommand.
! 2968: </p>
! 2969:
! 2970: <p>
! 2971: "file" subcommand can be used to get (arbitrary number of) commands
! 2972: parsed and executed from a given debugger input file whenever debugger
! 2973: is entered. With this you can output any information you need:
1.1.1.12 root 2974: </p>
1.1.1.13! root 2975: <pre>
! 2976: lock file debugger.ini
! 2977: </pre>
1.1.1.12 root 2978:
2979: <p>
1.1.1.13! root 2980: To disable showing of this extra information, use "lock default".
! 2981: Without arguments "lock" command will show the available options
! 2982: (like the "info" command does).
1.1.1.12 root 2983: </p>
2984:
1.1.1.13! root 2985:
1.1.1.12 root 2986: <a name="Debug symbols"></a><h3>Debug symbols</h3>
2987:
2988: <p>
2989: You can load symbol name/address information from a file to the
2990: debugger with the "symbols" command (and with "dspsymbols" for DSP).
1.1.1.13! root 2991: These symbolic names can be used in arithmetic expressions and
! 2992: conditional breakpoint expressions. They also show up in the "disasm"
! 2993: command output.
1.1.1.12 root 2994: </p>
2995:
2996: <p>The symbols file format is following:</p>
2997: <pre>
2998: e01034 T random
2999: e01076 T kbdvbase
3000: e0107e T supexec
3001: </pre>
3002: <p>
1.1.1.13! root 3003: Where 'T' means text (code), 'D' means data and 'B' means BSS section
! 3004: type of address. The hexadecimal address, address type letter and the
! 3005: symbol name are separated by white space. Empty lines and lines
! 3006: starting with '#' (comments) are ignored.
1.1.1.12 root 3007: </p>
3008:
3009: <p>
3010: AHCC C-compiler can provide a symbol file suitable for this with its
1.1.1.13! root 3011: "-n" 'nm' list option (not enabled by default). If you're reverse
1.1.1.12 root 3012: engineering some code, you could just create your own symbols file to
3013: help in debugging it later.
3014: </p>
3015:
3016: <p>
3017: If you're debugging normal TOS/GEM programs instead of code loaded
1.1.1.13! root 3018: into a fixed address (like e.g. EmuTOS is), after the program has been
! 3019: loaded, load the symbols with the program text segment address offset:
! 3020: </p>
! 3021: <pre>
! 3022: symbols calc.sym "TEXT"
1.1.1.12 root 3023: </pre>
1.1.1.13! root 3024: <p>
! 3025: (The value of the above virtual "TEXT" debugger variable comes from a
! 3026: program basepage, it's set after the program is loaded by TOS, see
! 3027: "info basepage" output.)
! 3028: </p>
! 3029:
1.1.1.12 root 3030:
3031: <a name="Breakpoints"></a><h3>Breakpoints</h3>
3032:
3033: <p>
3034: There are two ways to specify breakpoints for Hatari. First, there are
3035: the simple address breakpoints which trigger when the CPU (or DSP)
3036: program counter hits a given address. Use "a" (or "da" for the DSP)
3037: to create them, for example:
3038: </p>
3039: <pre>
1.1.1.13! root 3040: a $e01034
! 3041: a some_symbol
1.1.1.12 root 3042: </pre>
3043:
3044: <p>
1.1.1.13! root 3045: Note that address breakpoints are just wrappers for conditional
! 3046: breakpoints so you need to use "b" command to remove or list them.
1.1.1.12 root 3047: </p>
3048:
3049: <p>
3050: Then there are the conditional breakpoints which can handle much more
1.1.1.13! root 3051: complex break condition expressions; they can track changes to
! 3052: register and memory values with bitmasks, include multiple conditions
! 3053: for triggering a breakpoint and so on. Use "b" (or "db" for the DSP)
! 3054: to manage them.
1.1.1.10 root 3055: </p>
3056:
1.1.1.13! root 3057: <p>Help explains the general syntax:</p>
1.1.1.10 root 3058: <pre>
1.1.1.13! root 3059: > help b
! 3060: 'breakpoint' or 'b' - set/remove/list conditional CPU breakpoints
! 3061: Usage: b <condition> [&& <condition> ...] [:<option>] | <index> | help | all
! 3062:
! 3063: Set breakpoint with given <conditions>, remove breakpoint with
! 3064: given <index>, remove all breakpoints with 'all' or output
! 3065: breakpoint condition syntax with 'help'. Without arguments,
! 3066: lists currently active breakpoints.
! 3067: </pre>
! 3068:
! 3069: <p>
! 3070: Unless you give breakpoint one of the pre-defined subcommands ('all',
! 3071: 'help'), index for a breakpoint to remove or no arguments (to list
! 3072: breakpoints), the arguments are interpreted as a new breakpoint
! 3073: definition.
! 3074: </p>
! 3075:
! 3076: <p>
! 3077: Each conditional breakpoint can have (currently up to 4) conditions
! 3078: which are separated by "&&". All of the breakpoint's
! 3079: conditions need to be true for a breakpoint to trigger.
! 3080: </p>
! 3081:
! 3082:
! 3083: <a name="Breakpoint options"></a><h4>Breakpoint options</h4>
! 3084:
! 3085: <p>
! 3086: Normally when a breakpoint is triggered, emulation is stopped and you
! 3087: get to the debugger. Breakpoint options can be used to affect what
! 3088: happens when a breakpoint is triggered. These options are given after
! 3089: the conditions and are prefixed with ':'.
! 3090: </p>
! 3091:
! 3092: <dl>
! 3093: <dt><em><count></em></dt>
! 3094: <dd>Break only on every <count> hit. For example, to stop
! 3095: on every other time PC is at given address, use:
! 3096: <pre>
! 3097: a $1234 :2
! 3098: </pre>
! 3099: </dd>
! 3100:
! 3101: <dt><em>once</em></dt>
! 3102: <dd>
! 3103: Delete the breakpoint when it's hit i.e. trigger it only once. It may
! 3104: be useful if you just want to get a specific address. Or if you're on
! 3105: an instruction that jumps back to a start of the loop and you want to
! 3106: finish the loop, you couuld use:
! 3107: <pre>
! 3108: b pc > "pc" :once
! 3109: continue
! 3110: </pre>
! 3111: </dd>
! 3112:
! 3113: <dt><em>trace</em></dt>
! 3114: <dd>
! 3115: Continue emulation without stopping after printing the value that
! 3116: triggered the breakpoint and doing other possible option actions.
! 3117: This is most useful when investigating memory or register value
! 3118: changes (explained below).
! 3119: </dd>
! 3120:
! 3121: <dt><em>lock</em></dt>
! 3122: <dd>
! 3123: Show the same information on breakpoint hit as you see when entering
! 3124: the debugger (see the "lock" command in
! 3125: <a href="#Inspecting emulation state">Inspecting emulation state</a>
! 3126: above). This enables also trace option as you would anyway see this
! 3127: information if debugger would be entered.
! 3128: </dd>
! 3129:
! 3130: <dt><em>file <file></em></dt>
! 3131: <dd>
! 3132: Execute debugger commands from given <file> when this breakpoint
! 3133: is hit. With this you have complete control over what information is
! 3134: show when the debugger is hit, you can even chain breakpoints (as
! 3135: explained in
! 3136: <a href="#Chaining breakpoints">Chaining breakpoints</a> later on)
! 3137: etc. Use this if "lock" option isn't enough or you want different
! 3138: information show on breakpoints and when entering the debugger.
! 3139: </dd>
! 3140: </dl>
! 3141:
! 3142: <p>
! 3143: Note: you can give multiple options for conditional breakpoints, but
! 3144: for address breakpoints you can give only one these options. And
! 3145: "file" option is supported only for conditional breakpoints.
! 3146: </p>
! 3147:
! 3148:
! 3149: <a name="Breakpoint conditions"></a><h4>Breakpoint conditions</h4>
! 3150:
! 3151: <p>
! 3152: "b help" explains very briefly the breakpoint condition syntax:
! 3153: </p>
! 3154: <pre>
! 3155: > b help
! 3156: condition = <value>[.mode] [& <mask>] <comparison> <value>[.mode]
1.1.1.10 root 3157:
3158: where:
1.1.1.12 root 3159: value = [(] <register/symbol/variable name | number> [)]
1.1.1.13! root 3160: number/mask = [#|$|%]<digits>
1.1.1.12 root 3161: comparison = '<' | '>' | '=' | '!'
3162: addressing mode (width) = 'b' | 'w' | 'l'
3163: addressing mode (space) = 'p' | 'x' | 'y'
1.1.1.13! root 3164: </pre>
! 3165:
! 3166: <p>
! 3167: For CPU breakpoints, mode is the address width; it can be byte ("b"),
! 3168: word ("w") or long ("l", default). For DSP breakpoints, mode specifies
! 3169: the address space: "P", "X" or "Y". Note that on DSP only R0-R7
! 3170: registers can be used for memory addressing. For example;
! 3171: <pre>
! 3172: db (r0).x = 1 && (r0).y = 2
1.1.1.10 root 3173: </pre>
3174:
3175: <p>
3176: If the value is in parenthesis like in '($ff820)' or '(a0)', then the
1.1.1.12 root 3177: used value will be read from the memory address pointed by it. Note
1.1.1.13! root 3178: that this conditional breakpoint expression value is checked at
! 3179: run-time whereas quoted arithmetic expressions (mentioned in
! 3180: <a href="#Entering arguments to debugger commands">Entering arguments
! 3181: to debugger commands</a> above) are evaluated already when
! 3182: adding a breakpoint. For example, to break when a value in an address
! 3183: (later) pointed by A0 matches the value <em>currently</em> in D0, one
! 3184: would use:
1.1.1.10 root 3185: </p>
1.1.1.12 root 3186: <pre>
1.1.1.13! root 3187: b (a0) = "d0"
1.1.1.12 root 3188: </pre>
3189:
1.1.1.10 root 3190: <p>
1.1.1.13! root 3191: If you're interested only on certain bits in the value, you can use
! 3192: '&' and a numeric mask on either side of comparison operator to
! 3193: mask the coresponding value, like this:
! 3194: <pre>
! 3195: b ($ff820).w & 3 = (a0) && (a1) = d0 & %1100
! 3196: </pre>
1.1.1.10 root 3197:
1.1.1.13! root 3198: <p>
! 3199: Comparison operators should be familiar and obvious, except for '!'
! 3200: which indicates inequality ("is not") comparison. For example:
! 3201: </p>
1.1.1.10 root 3202: <pre>
1.1.1.13! root 3203: b d0 > $20 && d0 < $40 && d0 ! $30
1.1.1.12 root 3204: </pre>
1.1.1.10 root 3205:
3206: <p>
1.1.1.13! root 3207: As a convenience, if the both sides of the comparison are exactly the
! 3208: same (i.e. condition is redundant as it's always either true or
! 3209: false), the <em>right side</em> of the comparison is replaced with
! 3210: its current value. This way you can give something like this:
1.1.1.12 root 3211: </p>
1.1.1.13! root 3212: <pre>
! 3213: b pc > "pc"
! 3214: </pre>
! 3215: <p>As:</p>
! 3216: <pre>
! 3217: b pc > pc
! 3218: </pre>
1.1.1.12 root 3219:
3220: <p>
1.1.1.13! root 3221: That in itself isn't so useful, but for inequality ('!') comparison,
! 3222: conditional breakpoint will additionally track and output all further
! 3223: changes for the given address/register expression. This can be used
! 3224: for example to find out all value changes in a given memory address,
! 3225: like this:
! 3226: </p>
! 3227: <pre>
! 3228: b ($ffff9202).w ! ($ffff9202).w :trace
! 3229: </pre>
! 3230: <p>
! 3231: Typically with this one would use the breakpoint "trace" option like
! 3232: above.
1.1.1.12 root 3233: </p>
1.1.1.10 root 3234:
1.1.1.13! root 3235:
! 3236: <a name="Breakpoint variables"></a><h4>Breakpoint variables</h4>
! 3237:
1.1.1.10 root 3238: <p>
1.1.1.13! root 3239: In addition to loaded symbols, the debugger supports also setting
! 3240: conditional breakpoints on values of some "virtual" variables listed
! 3241: by "b help". For example:
1.1.1.12 root 3242: </p>
1.1.1.13! root 3243: <ul>
! 3244: <li>If you want the emulation to stop on the first instruction of
! 3245: next program; after TOS desktop is up, set a breakpoint on
! 3246: the TEXT segment address given in a program basepage:
! 3247: <pre>
! 3248: b pc = TEXT :once
! 3249: </pre>
! 3250: Note1: It's better to trigger it only once because if you'd leave it on,
! 3251: during reboot you would get a warning for every instruction until TOS sets
! 3252: a valid basepage.
! 3253: <br>
! 3254: Note2: you cannot use an address breakpoint for this because value of a
! 3255: variable given to it is evaluated when the breakpoint is set, not at
! 3256: run-time, so it cannot get the new value that the TEXT variable gets
! 3257: when you start a program.
! 3258: </li>
! 3259: <li>To find out current program DATA and BSS segment contents,
! 3260: use the corresponding variables:
! 3261: <pre>
! 3262: m data
! 3263: m bss
! 3264: </pre>
! 3265: </li>
! 3266: <li>If you want to stop at a specific cycle within a frame (that is,
! 3267: PC relative to the current VBL/HBL in cycles), set breakpoints to
! 3268: specific "HBL" and "FrameCycles" variable values. If you for
! 3269: example want to break after 20 HBLs, use:
1.1.1.12 root 3270: <pre>
1.1.1.13! root 3271: b HBL = "HBL+20"
1.1.1.12 root 3272: </pre>
1.1.1.13! root 3273: </li>
! 3274: <li>Aes/Bios/Gemdos/LineA/LineF/Vdi/XbiosOpcode variables can be used
! 3275: to catch AES, BIOS, GEMDOS, Line-A, Line-F, VDI and XBIOS OS-calls.
! 3276: By default they contain the 0xffff value, so to trace e.g. AES calls,
! 3277: one needs to use something like this:
! 3278: <pre>
! 3279: b AesOpcode ! AesOpcode && AesOpcode < 0xffff :trace
! 3280: </pre>
! 3281: </li>
! 3282: <!--
! 3283: <li>"OSExitPC" variable can be used to catch exit from an OS call.
! 3284: <pre>
! 3285: b pc = OSExitPC :once
! 3286: </pre>
! 3287: It's valid after OS call breakpoint is triggered and before
! 3288: that call has finished.</li>
! 3289: -->
! 3290: </ul>
1.1.1.12 root 3291:
3292: <p>
1.1.1.13! root 3293: Hint: "info" command "aes", "gemdos" and "vdi" subcommands for can be
! 3294: used to list the corresponding OS-call opcodes. For example,
! 3295: to see the GEMDOS opcodes, use:</p>
! 3296: <pre>
! 3297: info gemdos 1
! 3298: </pre>
! 3299:
! 3300:
! 3301: <a name="Chaining breakpoints"></a>
! 3302: <h4>Chaining breakpoints and other actions</h4>
! 3303:
! 3304: <p>
! 3305: As the file pointed by the breakpoint ":file" option (see
! 3306: <a href="#Breakpoint options">Breakpoint options</a>) can contain any
! 3307: debugger commands, it can also be used to do automatic "chaining" of
! 3308: debugger and breakpoint actions so that after one breakpoint is hit,
! 3309: another one is set.
1.1.1.12 root 3310: </p>
1.1.1.13! root 3311:
! 3312: <p>For example if you have these input files:</p>
! 3313: <ul>
! 3314: <li>"break.ini":
! 3315: <pre>
! 3316: b GemdosOpcode = 0x3D :trace :file trace.ini
! 3317: </pre>
! 3318: </li>
! 3319: <li>"trace.ini":
! 3320: <pre>
! 3321: setopt --bios-intercept --trace gemdos,xbios,fdc,io_all
! 3322: b VBL = "VBL+4" :trace :file disable.ini
! 3323: </pre>
! 3324: </li>
! 3325: <li>"disable.ini":
1.1.1.12 root 3326: <pre>
1.1.1.13! root 3327: trace none
! 3328: b all
1.1.1.12 root 3329: </pre>
1.1.1.13! root 3330: </li>
! 3331: </ul>
1.1.1.12 root 3332:
3333: <p>
1.1.1.13! root 3334: And then start Hatari with the first debugger input file and a GEMDOS
! 3335: harddisk directory containing "desktop.inf" file:
! 3336: </p>
! 3337: <pre>
! 3338: hatari --parse break.ini -d testdir
! 3339: </pre>
! 3340:
! 3341: <ol>
! 3342: <li>"break.ini" input file will break when TOS opens
! 3343: the "desktop.inf" file (it's the first Fopen() i.e. GEMDOS call
! 3344: 0x3D done by TOS at boot) and the breakpoint will run
! 3345: the debugger commands from the "trace.ini" file
! 3346: <li>"trace.ini" input file sets Hatari to trace several things
! 3347: (see <a href="#Tracing">Tracing</a> section below) in the
! 3348: emulated system for few VBLs until breakpoint runs commands
! 3349: from the "disable.ini" file
! 3350: <li>"disable.ini" input file will disable tracing and remove
! 3351: all (remaining) breakpoints
! 3352: </ol>
! 3353:
! 3354: <p>
! 3355: <em>Note:</em> because debugger input files cannot "continue"
! 3356: emulation, ":trace" option needs to be used for the breakpoint(s)
! 3357: if you want emulation to continue after the breakpoint action(s).
1.1.1.12 root 3358: </p>
3359:
3360: <p>
1.1.1.13! root 3361: Hint: It's better to test each input file separate before testing the
! 3362: whole chain. Besides the ":file" breakpoint option, these debugger
! 3363: input files can be also read with the debugger "file" command, "lock"
! 3364: command "file" option and with the Hatari "--parse" command line
! 3365: option.
1.1.1.10 root 3366: </p>
3367:
1.1.1.13! root 3368:
1.1.1.12 root 3369: <a name="Tracing"></a><h3>Tracing</h3>
3370:
1.1.1.10 root 3371: <p>
1.1.1.13! root 3372: After analyzing the emulation state and/or setting new breakpoints,
! 3373: you can continue the emulation with the "c" command. You can continue
! 3374: for a given number of CPU instructions (or DSP instructions when "dc"
! 3375: is used), or you can continue forever (until a non-tracing breakpoint
! 3376: triggers) if you omit the instruction count.
! 3377: </p>
! 3378:
! 3379: <p>
! 3380: If you want to continue with real-time disassembling, you can enable
! 3381: it with "trace cpu_disasm" (or "trace dsp_disasm" for DSP) at the
! 3382: debugger prompt before continuing.
1.1.1.12 root 3383: </p>
3384: <p>
3385: Disable tracing with "trace none" when you enter the debugger again.
1.1.1.13! root 3386: "trace help" (or TAB) can be used to list all the (over 30) supported
! 3387: traceable things, from HW events to OS functions.
1.1.1.12 root 3388: </p>
3389: <p>
3390: Because Hatari normally emulates things at the hardware level, tracing
1.1.1.13! root 3391: certain Atari OS Traps requires setting additional Hatari options
! 3392: which tell it to intercept this higher level functionality:
1.1.1.12 root 3393: <ul>
1.1.1.13! root 3394: <li>BIOS and XBIOS tracing require enabling of the BIOS intercepting with
! 3395: the "--bios-intercept" option (which has also some other side-effects)
! 3396: </li>
! 3397: <li>GEMDOS tracing requires enabling the GEMDOS harddisk emulation
! 3398: (which doesn't work under MiNT because it re-implements GEMDOS)</li>
1.1.1.12 root 3399: </ul>
3400: <p>
1.1.1.13! root 3401: If use of above isn't possible for the things you'd like to track,
! 3402: you can use the OS call opcode breakpoints explained above with the
! 3403: ":trace" breakpoint option.
! 3404: </p>
! 3405: <p>
1.1.1.12 root 3406: Tracing options can be set even from a program within the emulation
1.1.1.13! root 3407: if you enable the Hatari "--bios-intercept" option and call XBios 255
! 3408: from the program with a suitable Hatari command line string. Bios
! 3409: interception will also show the (Bios level) CON: output on the host
! 3410: console.
1.1.1.12 root 3411: </p>
3412: <p>
3413: Note that the trace output file can be set only when Hatari starts,
3414: it cannot be changed from within the debugger (or emulation).
1.1.1.10 root 3415: </p>
3416:
1.1.1.13! root 3417:
! 3418: <a name="Profiling"></a><h3>Profiling</h3>
! 3419:
! 3420: <p>
! 3421: Profiling tells where the emulated code spends most of its (emulated)
! 3422: time. It can be used to find out where a program is (apparently)
! 3423: stuck or what are the largest performance bottlenecks for a program.
! 3424: </p>
! 3425:
! 3426: <p>
! 3427: Profiling is used by first enabling the profiler (use "dp" for DSP):
! 3428: </p>
! 3429: <pre>
! 3430: > profile on
! 3431: Profiling enabled.
! 3432: </pre>
! 3433: <p>
! 3434: And profiling will start once you continue the emulation:
! 3435: </p>
! 3436: <pre>
! 3437: > c
! 3438: Returning to emulation...
! 3439: Allocated CPU profile buffer (18 MB).
! 3440: </pre>
! 3441:
! 3442: <p>
! 3443: When you get back to the debugger, the collected profiling information
! 3444: is processed and a summary of in which parts of the RAM the execution
! 3445: happened is shown:
! 3446: </p>
! 3447: <pre>
! 3448: Allocated CPU profile address buffer (4 KB).
! 3449: Normal RAM (0-0x400000):
! 3450: - no activity
! 3451: Cartridge ROM (0xFA0000-0xFC0000):
! 3452: - no activity
! 3453: ROM TOS (0xE00000-0xE80000):
! 3454: - active address range:
! 3455: 0xe0014c-0xe23f02
! 3456: - active instruction addresses:
! 3457: 707 (100.00% of all)
! 3458: - executed instructions:
! 3459: 629144 (100.00% of all)
! 3460: - used cycles:
! 3461: 9408503 (100.00% of all)
! 3462: - address with most cycles:
! 3463: 0xe0dcca, 402628 cycles (4.28% of all in area)
! 3464: - address with most hits:
! 3465: 0xe004a4, 4900 hits (0.78% of all in area)
! 3466: </pre>
! 3467: <p>
! 3468: (DSP RAM will be shown only as single area in profile information.)
! 3469: </p>
! 3470:
! 3471: <p>
! 3472: After this you can request more detailed profiling information:
! 3473: </p>
! 3474: <pre>
! 3475: > profile
! 3476: 'profile' - profile CPU code
! 3477: Usage: profile <on|off|counts|cycles|symbols|stats> [show count]
! 3478: on & off enable and disable profiling. Data is collected
! 3479: until debugger is entered again after which you can view
! 3480: statistics about the data or view PC addresses that took
! 3481: most cycles or functions/symbols called most often.
! 3482: You can specify how many items are shown at most.
! 3483: </pre>
! 3484:
! 3485: <p>For example:</p>
! 3486: <pre>
! 3487: > profile counts 8
! 3488: addr: count:
! 3489: 0xe004a4 0.78% 4900
! 3490: 0xe004b6 0.78% 4896
! 3491: 0xe0dcbc 0.55% 3448
! 3492: 0xe0dcc6 0.55% 3448
! 3493: 0xe0f59e 0.55% 3446
! 3494: 0xe0dcce 0.55% 3445
! 3495: 0xe0dcd6 0.55% 3445
! 3496: 8 CPU addresses listed.
! 3497: </pre>
! 3498: <p>
! 3499: If you have loaded symbol information for code addresses, with the
! 3500: "profile symbols" command you get a list of how many times the code
! 3501: execution passed through the defined symbol addresses.
! 3502: </p>
! 3503:
! 3504: <p>
! 3505: After the profiling information has been post-processed, it will
! 3506: also be shown in the disassembly output.
! 3507: </p>
! 3508:
! 3509:
! 3510: <a name="Usage examples"></a><h3>Usage examples</h3>
! 3511:
! 3512: <p>
! 3513: Here's a list of some common debugging tasks and how to do them
! 3514: with the Hatari debugger:
! 3515: </p>
! 3516:
! 3517: <dl>
! 3518: <dt><em>Stopping on program startup and examining its data</em></dt>
! 3519: <dd>Please see <a href="#Breakpoint variables">Breakpoint variables</a>
! 3520: and <a href="#Inspecting emulation state">Inspecting emulation state</a>
! 3521: sections.
! 3522: </dd>
! 3523:
! 3524: <dt><em>Tracing specific things in the system</em></dt>
! 3525: <dd>To trace e.g. all GEMDOS calls and IO operations, use:
! 3526: <pre>
! 3527: trace gemdos,io_all
! 3528: </pre>
! 3529: Please see <a href="#Tracing">Tracing</a> section for more information
! 3530: on tracing, what's possible with in and what are its limitations.
! 3531: </dd>
! 3532:
! 3533: <dt><em>Stopping when certain PC address is passed Nth time</em></dt>
! 3534: <dd>To stop e.g. after function/subroutine at $12345 is called for
! 3535: the 6th time:
! 3536: <pre>
! 3537: a $12345 :6
! 3538: </pre>
! 3539: </dd>
! 3540:
! 3541: <dt><em>Stopping when register has a specific value</em></dt>
! 3542: <dd>To stop when e.g. D1 register contains value 5, set a breakpoint on:
! 3543: <pre>
! 3544: b d1 = 5
! 3545: </pre>
! 3546: </dd>
! 3547:
! 3548: <dt><em>Stopping when a register value changes</em></dt>
! 3549: <dd>To stop when e.g. D1 register value changes, set a breakpoint on:
! 3550: <pre>
! 3551: b d1 ! d1
! 3552: </pre>
! 3553: </dd>
! 3554:
! 3555: <dt><em>Stopping when register value is within some range</em></dt>
! 3556: <dd>To stop when e.g. D1 register value is within range of 10-30,
! 3557: set a breakpoint on:
! 3558: <pre>
! 3559: b d1 > 9 && d1 < 31
! 3560: </pre>
! 3561: </dd>
! 3562:
! 3563: <dt><em>Stopping when memory location has a specific value</em></dt>
! 3564: <dd>To stop when e.g. bit 1 of the Video Shifter Sync Mode byte at
! 3565: IO address $ff820a is set i.e. video frequency is 60Hz, set
! 3566: a breakpoint on:
! 3567: <pre>
! 3568: b ($ff820a).b & 2 = 2
! 3569: </pre>
! 3570: </dd>
! 3571:
! 3572: <dt><em>Stopping when a memory value changes</em></dt>
! 3573: <dd>To stop when above bit changes, set a breakpoint on its value
! 3574: being different from the current value ('!' compares for inequality):
! 3575: <pre>
! 3576: b ($ff820a).b & 2 ! ($ff820a).b & 2
! 3577: </pre>
! 3578: </dd>
! 3579:
! 3580: <dt><em>Tracing all changes in specific memory location</em></dt>
! 3581: <dd>To see the new values and continue without stopping, use
! 3582: the ":trace" breakpoint option:
! 3583: <pre>
! 3584: b ($ff820a).b & 2 ! ($ff820a).b & 2 :trace
! 3585: </pre>
! 3586: </dd>
! 3587:
! 3588: <dt><em>Stopping at specific screen position</em></dt>
! 3589: <dd>To stop e.g. when VBL is 100, HBL is 40 and line cycles is 5,
! 3590: use the corresponding debugger variables:
! 3591: <pre>
! 3592: b VBL = 100 && HBL = 40 && FrameCycles = 5
! 3593: </pre>
! 3594: </dd>
! 3595:
! 3596: <dt><em>Stopping after value increases/decreases by certain amount</em></dt>
! 3597: <dd>To stop e.g. after D0 value has increased by 10, set breakpoint on:
! 3598: <pre>
! 3599: b d0 = "d0 + 10"
! 3600: </pre>
! 3601: </dd>
! 3602:
! 3603: <dt><em>Single step so that new register values are shown after each step</em></dt>
! 3604: <dd>
! 3605: <pre>
! 3606: lock registers
! 3607: c 1
! 3608: [new register values]
! 3609: c 1
! 3610: [new register values]
! 3611: ...
! 3612: </pre>
! 3613: </dd>
! 3614:
! 3615: <dt><em>Showing current stack contents</em></dt>
! 3616: <dd>To see first 64 bytes on top of the stack, use:
! 3617: <pre>
! 3618: m "a7-64"-a7
! 3619: </pre>
! 3620: </dd>
! 3621:
! 3622: <dt><em>Seeing specific information each time debugger is entered</em></dt>
! 3623: <dd>To see above information whenever some breakpoint is hit,
! 3624: you enter debugger manually etc, write that command to e.g.
! 3625: <span class="file">stack.ini</span> file and then use:
! 3626: <pre>
! 3627: lock file stack.ini
! 3628: </pre>
! 3629: Please see also <a href="#Chaining breakpoints">Chaining breakpoints</a>
! 3630: section for more examples on what you can do with the debugger input files.
! 3631: </dd>
! 3632:
! 3633: <dt><em>Finding where program or OS is stuck</em></dt>
! 3634: <dd>Profiling tells from which addresses CPU is running
! 3635: executing the instructions:
! 3636: <pre>
! 3637: profile on
! 3638: c
! 3639: [after a while, use AltGr+Pause to get back to debugger]
! 3640: profile counts
! 3641: </pre>
! 3642: </dd>
! 3643:
! 3644: </dl>
! 3645:
! 3646: <p>
! 3647: Hint: for most of above commands, one just needs to prefix them with
! 3648: "d" (or "dsp" if using full command names) to do similar operation on
! 3649: DSP.
! 3650: </p>
! 3651:
! 3652:
1.1.1.12 root 3653: <a name="Build notes"></a><h3>Build notes</h3>
3654:
1.1.1.10 root 3655: <p>
3656: Lastly, the debugger is much nicer to use with the command line
1.1.1.12 root 3657: history, editing and especially with the command, command argument and
3658: symbol name completion support. If you're building Hatari yourself,
3659: please make sure that you have the GNU readline development files
3660: installed (on Debian / Ubuntu these come from the libreadline5-dev
1.1.1.13! root 3661: package). Otherwise completion doesn't get enabled when you configure
1.1.1.12 root 3662: Hatari.
3663: </p>
3664:
3665: <p>
3666: ENABLE_TRACING define needs to be set for tracing to work.
3667: By default it should be enabled.
1.1.1.10 root 3668: </p>
3669:
3670:
3671: <a name="Performance"></a><h2>Performance</h2>
1.1.1.12 root 3672:
3673: <p>Hatari performance varies between Atari programs, depending on what
3674: features Hatari needs to emulate for them. Less accurate Atari
3675: emulators may be faster as emulation accuracy has a performance
3676: overhead.</p>
3677:
1.1.1.13! root 3678: <p>The operating system and libraries below Hatari can also sometimes
! 3679: have a noticeable effect on performance.</p>
! 3680:
1.1.1.12 root 3681:
1.1.1.10 root 3682: <a name="Improving Hatari performance"></a><h3>Improving Hatari performance</h3>
3683:
3684: <p>
1.1.1.13! root 3685: Hatari currently runs best in 16 or 32 bits per pixel color depth
! 3686: mode, so try to avoid 24 bits per pixel display modes if possible.
! 3687: 16-bit mode is fastest.
! 3688: </p>
! 3689:
! 3690: <p>
! 3691: <em>On OSX, frame skipping, zooming and drive LED options (listed below)
! 3692: seem to have a large effect on performance in the windowed mode</em>.
! 3693: This is apparently due to issues in the SDL OSX backend and how OSX
! 3694: itself composites non-fullscreen window contents. OSX uses always
! 3695: 32-bit mode.
! 3696: </p>
! 3697:
! 3698: <p>
1.1.1.10 root 3699: Unless you've disabled compiler optimizations (like GCC's -O2 or -O3
3700: options) in the Hatari build, the extra optimization flags (like GCC's
3701: "-mtune=i686") don't seem to have very large effect on Hatari
1.1.1.12 root 3702: performance. Using GCC -O3 option instead of -O2 can give minor
3703: (5-10%) performance improvements for things (demos) that use very
3704: heavily interrupts.
1.1.1.10 root 3705: </p>
1.1.1.13! root 3706:
1.1.1.10 root 3707: <p>
3708: However, Hatari can be sped up considerably by giving up some
1.1.1.13! root 3709: emulation or emulator accuracy. Except for DSP, these options
! 3710: should be needed only on very slow devices like handhelds. See below.
! 3711: </p>
! 3712:
! 3713: <p>
! 3714: If nothing else helps, try an earlier Hatari version. More accurate
! 3715: emulation or emulator output in newer Hatari versions means that they
! 3716: can be slower despite optimizations.
1.1.1.10 root 3717: </p>
3718:
3719:
1.1.1.13! root 3720: <a name="Emulation options"></a><h3>Emulation options</h3>
1.1.1.10 root 3721:
3722: <p>
3723: Emulation options have the largest impact on performance.
3724: These options can be changed from the Hatari GUI System dialog and
3725: the emulation needs to be rebooted for any of these changes to take
3726: an effect!
3727: </p>
3728:
3729: <h5>DSP</h5>
3730: <p>
1.1.1.12 root 3731: Emulating the Falcon DSP is performance-wise several times more demanding
1.1.1.10 root 3732: than emulating the m68k; DSP runs at higher frequency, executes many
3733: instructions for each m68k instruction and emulation isn't as mature
3734: and optimized. Unless some program needs DSP, <em>none</em> or
3735: <em>dummy</em> DSP emulation mode could be used. Even of the programs
3736: that do use DSP, many use it only for background music and work
3737: fine without the real DSP emulation.
3738: </p>
1.1.1.12 root 3739:
1.1.1.10 root 3740: <h5>Timer-D</h5>
3741: <p>
3742: The single largest factor contributing to general Hatari emulation
3743: performance is the handling of interrupts. Enabling Timer-D patching
1.1.1.12 root 3744: option (about) doubles Hatari ST/STE emulation performance as it
3745: significantly reduces the number of interrupts generated by the emulated
3746: Atari machine. Using this has adverse effect only for very rare programs.
1.1.1.10 root 3747: </p>
1.1.1.12 root 3748:
1.1.1.10 root 3749: <h5>Compatible CPU</h5>
3750: <p>
1.1.1.12 root 3751: After the DSP and interrupts, m68k emulation takes most time.
1.1.1.10 root 3752: Disabling the "Slower but more compatible CPU" option will speed up
3753: the emulation a lot, but it won't anymore be cycle accurate. This can
3754: be fine for many games and other programs, but won't work e.g. for demos
3755: using overscan or rasters.
3756: </p>
3757:
3758: <p>
1.1.1.12 root 3759: Roughly speaking, for DSP emulation, one needs at least 2Ghz machine.
3760: For normal (unpatched) Timer-D frequency on some specific cases (like
1.1.1.10 root 3761: demos with overscan 512 color animations) one may need over 1GHz
1.1.1.12 root 3762: machine, but some rare ST/STE demos may require over 1GHz machine even
3763: with Timer-D patching. For "Compatible CPU" one needs at least 1/2Ghz
3764: machine.
1.1.1.10 root 3765: </p>
1.1.1.12 root 3766:
1.1.1.10 root 3767: <p>
1.1.1.12 root 3768: NOTE: Above options may cause some programs not to work correctly.
3769: The <a href="compatibility.html">Hatari Software Compatibility List</a>
3770: lists programs known to need real real Falcon DSP emulation or Timer-D
3771: frequency. Disabling "Compatible CPU" option is recommended only as
3772: a last resort.
1.1.1.10 root 3773: </p>
3774:
3775:
1.1.1.13! root 3776: <a name="Emulator options"></a><h3>Emulator options</h3>
1.1.1.10 root 3777:
3778: <p>
1.1.1.13! root 3779: Emulator options don't usually have as large effect on performance as
1.1.1.10 root 3780: emulation options, but they don't affect the emulated programs at all,
3781: just the quality of the emulation "output". These options can also
3782: be toggled at run-time without rebooting the emulation.
3783: </p>
3784:
3785: <h5>Sound</h5>
3786: <p>
3787: Internal Hatari sound handling and the SDL_mixer sound thread
3788: libALSA sound processing can account up to 1/3 of the Hatari CPU usage
1.1.1.12 root 3789: in normal ST/STE emulation. Disabling sound will get rid of that.
3790: Using low sound frequency or one matching your sound card may also help.
3791: Best is if you disable also background music from the programs you run
3792: in Hatari as this can significantly reduce the number of generated
3793: interrupts.
1.1.1.10 root 3794: </p>
1.1.1.12 root 3795:
1.1.1.10 root 3796: <h5>Frame skipping</h5>
3797: <p>
3798: Screen rendering can take noticeable amount of CPU time. The default
3799: Hatari "auto" frame skipping should be used unless there's a good
3800: reason not to. It will skip converting and showing some of the frames
1.1.1.13! root 3801: if there's not enough time for them.
! 3802: </p>
! 3803: <p>
! 3804: Also, if your monitor refresh frequency is lower than the selected
! 3805: Hatari monitor frequency (e.g. LCD monitors usually use 60Hz whereas
! 3806: Atari monochrome monitor uses 71Hz), you should use frameskip of one.
! 3807: The reason is that if your SDL library uses VSync to synchronize the
! 3808: output to screen (like OSX one?), with zero frame skip that forces the
! 3809: emulation to run slower than a real Atari. If SDL doesn't use VSync,
! 3810: Hatari does redundant work to convert frames you can't see.
1.1.1.10 root 3811: </p>
1.1.1.12 root 3812:
3813: <h5>Zooming</h5>
1.1.1.10 root 3814: <p>
3815: If you are not using frame skip, disabling zooming can have
1.1.1.12 root 3816: noticeable improvement on performance. You can do this by specifying
3817: suitably low "Max zoomed" resolution (<span class="commandline">--zoom
3818: 1</span> command line option sets it to 320x200). If you still want to
3819: have a nice fullscreen mode, you should rather add the right resolution
3820: mode-lines (e.g. "320x200") to your xorg.conf file. If you still want
3821: to use zooming, disabling borders may help a bit.
1.1.1.10 root 3822: </p>
1.1.1.12 root 3823:
1.1.1.10 root 3824: <h5>Spec512 color handling</h5>
3825: <p>
3826: Handling Spec512 color modes which change the ST/e palette constantly
3827: takes some extra CPU. If you have problems with CPU usage in such
3828: screens and you care more e.g. from the sound quality than visuals, you
3829: can disable the Spec512 mode handling by zeroing the threshold for that
3830: with the <span class="commandline">--spec512 0</span> option.
3831: </p>
1.1.1.12 root 3832:
1.1.1.10 root 3833: <h5>Statusbar and drive LED</h5>
3834: <p>
1.1.1.13! root 3835: If your version of libSDL uses VSync to synchronize the screen output,
! 3836: drawing of the statusbar or the drive LED may have some minor impact
! 3837: on performance too. Normally they shouldn't.
1.1.1.10 root 3838: </p>
3839:
3840:
3841: <a name="Measuring the performance"></a><h3>Measuring the performance</h3>
3842:
3843: <p>
3844: There are a couple of ways to monitor and measure Hatari performance.
3845: </p>
3846: <p>
3847: By default Hatari has Statusbar visible and automatic frameskip
3848: enabled. When Hatari has enough time that it can sleep a little each
3849: frame, the statusbar frame skip ("FS") value keeps at zero. If Hatari
3850: is completely busy, it will increase to the maximum specified
3851: (automatic) frame skip value.
3852: </p>
3853: <p>
3854: Hatari has also a facility to measure FPS i.e. Frames Per Second.
3855: Just enable the <span class="commandline">--fast-forward</span> option
3856: on command line (or use the corresponding keyboard shortcut), and
3857: after a while, press the "Pause" key. Whenever Hatari emulation is
1.1.1.12 root 3858: paused, Hatari will output on console how many VBLs it could show per
3859: second along with some other numbers.
1.1.1.10 root 3860: </p>
3861: <p>
3862: It depends on what you want to measure, but usually it's best to
3863: disable sound and set high frame skip like
3864: <span class="commandline">--sound off --frameskips 60</span> so that
3865: the associated external overheads are minimized. E.g. video output
3866: can on some platforms do VSync and measurements would then show
3867: your monitor refresh frequency instead of actual Hatari performance.
3868: </p>
3869: <p>
3870: On Unix systems with <span class="commandline">times()</span> function
3871: call, only the time spent by the Hatari process itself is measured.
3872: On other systems much less accurate SDL "wall clock" timings are
3873: used. To make latter more accurate you could use also
3874: <span class="commandline">--run-vbls</span> option to specify how many
1.1.1.12 root 3875: VBLs Hatari should run before it exits. In this case it's best to
3876: either have the test-case run automatically from the AUTO-folder or
3877: given as memory snapshot to Hatari with the frame skip set equal to
3878: the VBL count.
1.1.1.10 root 3879: </p>
3880: <p>
3881: Note that the numbers can fluctuate quite a bit, <em>especially</em>
3882: when the SDL timings are used, so for (statistically) reliable numbers
3883: you may need to repeat the measurement several times. You should of
3884: course make also sure that the system doesn't have any other activity
3885: at the same time you're making the measurements.
3886: </p>
3887:
3888:
1.1.1.5 root 3889: <a name="Appendix"></a><h2>Appendix</h2>
3890:
3891: <a name="Copying"></a><h3>Copying</h3>
1.1.1.4 root 3892:
1.1 root 3893: <div class="backdropped">
3894: <p>This program is free software; you can redistribute it and/or modify
1.1.1.3 root 3895: it under the terms of the GNU General Public License as published by
3896: the
1.1 root 3897: Free Software Foundation; either version 2 of the License, or (at your
3898: option) any later version. </p>
3899: <p>This program is distributed in the hope that it will be useful, but <em>WITHOUT
3900: ANY WARRANTY</em>; without even the implied warranty of <em>MERCHANTABILITY</em>
1.1.1.3 root 3901: or <em>FITNESS FOR A PARTICULAR PURPOSE</em>. See the GNU General
1.1.1.4 root 3902: Public License for more details. </p>
3903: <p>
3904: You should have received a copy of the GNU General Public License
3905: along with this program; if not, write to the Free Software Foundation,
3906: Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
3907: </p>
1.1 root 3908: </div>
1.1.1.3 root 3909: <p><a href="http://www.gnu.org/">The GNU Project and the Free Software
3910: Foundation</a> | <a href="http://www.fsf.org/licenses/gpl.html">The
3911: GNU General Public License</a></p>
1.1.1.4 root 3912:
1.1.1.5 root 3913: <a name="Introduction to Emulation"></a><h3>Introduction to Emulation</h3>
3914:
1.1 root 3915: <p>Emulation via software is an art and Hatari is an example of this.</p>
1.1.1.3 root 3916: <p>Emulation is to make a computer behave like a (probably) completely
3917: different machine on the lowest possible niveau.
3918: This includes CPU and custom chip emulation allowing software written
3919: for the emulated machine to be run without notice.
3920: A good emulator will run most of the software intended for the emulated
3921: platform without trouble.
1.1 root 3922: </p>
3923: <p>
1.1.1.3 root 3924: The key to emulation is to simply do those things with a software
3925: program, the emulator, that normally chips would perform.
3926: So you have an CPU emulator that basically consists of a large loop
3927: that does exactly what the real thing would do:
1.1 root 3928: </p>
3929: <ul>
1.1.1.3 root 3930: <li>fetch an instruction from virtual memory</li>
3931: <li>interpret this instruction</li>
3932: <li>fetch operands from the emulated registers and memory</li>
3933: <li>perform the operation like addition or changing the program
3934: counter on a jump instruction</li>
3935: <li>writes results back into the intended registers or memory
3936: locations</li>
3937: <li>increment of the program counter and loop</li>
1.1 root 3938: </ul>
3939: <p>
1.1.1.3 root 3940: The typical von-Neumann CPU can be emulated very fast, stable and
3941: error-free using such a simple loop system.
1.1 root 3942: </p>
3943: <p>
1.1.1.3 root 3944: But in most cases the CPU emulation is the simplest part. Correct
3945: emulation of the various custom chips and hardware
1.1 root 3946: parts of the emulated system is much trickier.
3947: </p>
3948:
1.1.1.6 root 3949: <br>
3950:
1.1.1.3 root 3951: <hr style="width: 100%; height: 2px;">
1.1 root 3952: <table border="0" width="100%">
1.1.1.3 root 3953: <tbody>
1.1 root 3954: <tr>
1.1.1.3 root 3955: <td align="left"><a href="http://validator.w3.org/check/referer"><img
3956: src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"
3957: border="0" height="31" width="88"></a></td>
3958: <td align="right">
1.1.1.13! root 3959: June 2011
1.1.1.3 root 3960: </td>
1.1 root 3961: </tr>
1.1.1.3 root 3962: </tbody>
1.1 root 3963: </table>
3964: </body>
3965: </html>
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.