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