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