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