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