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