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