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