![[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">
! 58: Version 1.4
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.9 root 65: Hatari on the WWW: <strong><a href="http://hatari.berlios.de/"
66: target="_blank">http://hatari.berlios.de/</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>
87: <li><a href="#Command line options">Command line options</a>
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>
! 133: <li><a href="#Build notes">Build notes</a>
! 134: </ul>
1.1.1.10 root 135: <li><a href="#Performance">Performance</a>
136: <ul>
137: <li><a href="#Improving Hatari performance">Improving Hatari performance</a>
138: <li><a href="#Measuring the performance">Measuring the performance</a>
1.1.1.6 root 139: </ul>
1.1.1.5 root 140: <li><a href="#Appendix">Appendix</a>
141: <ul>
142: <li><a href="#Copying">Copying</a>
143: <li><a href="#Introduction to Emulation">Introduction to Emulation</a>
144: </ul>
145: </ul>
146:
147:
148: <a name="Introduction"></a><h2>Introduction</h2>
1.1 root 149:
1.1.1.5 root 150: <a name="General description"></a><h3>General description</h3>
1.1 root 151: <p>
1.1.1.7 root 152: Hatari is an Atari ST, STE, TT and Falcon emulator for Linux, FreeBSD, BeOS and
153: other Systems which are supported by the SDL library.
1.1.1.4 root 154: The emulator is open source software and is distributed under the terms of the
1.1.1.7 root 155: <a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU General
156: Public License (GPL)</a>.
1.1.1.4 root 157: </p>
158: <p>
1.1.1.3 root 159: The Atari ST was a 16/32 bit computer system which was first released by Atari
1.1.1.4 root 160: in 1985. Using the Motorola 68000 CPU, it was a very popular computer having
161: quite a lot of CPU power at that time. See Appendix B for details on emulation
162: in general.
1.1.1.3 root 163: </p>
164: <p>
1.1.1.4 root 165: Unlike many other Atari ST emulators which try to give you a good
166: environment for running GEM applications, Hatari tries to emulate the hardware
167: of a ST as close as possible so that it is able to run most of the old ST games
168: and demos. Of course you can run normal GEM applications with Hatari, too.
1.1.1.7 root 169: Recent versions of Hatari even feature basic STE, TT and Falcon emulation.
1.1 root 170: </p>
171:
1.1.1.5 root 172: <a name="Features"></a><h3>Features</h3>
1.1 root 173: <ul>
1.1.1.7 root 174: <li>68000 - 68040 emulation via the UAE CPU core (no PMMU support though)</li>
175: <li>ST RAM size variable (from 512kiB up to 14MiB are possible)</li>
1.1.1.3 root 176: <li>optional cartridge images for the ST ROM port</li>
1.1.1.2 root 177: <li>most of the ST specific hardware</li>
1.1 root 178: <li>ST Shifter with ST-High, ST-Medium and ST-Low resolutions,
1.1.1.7 root 179: overscan effects for all borders in color resolutions</li>
1.1.1.6 root 180: <li>512 color ST palette</li>
1.1.1.7 root 181: <li>many raster effects </li>
1.1.1.8 root 182: <li>scaling of low resolutions by factor two</li>
1.1.1.7 root 183: <li>interleaved lines rendering of ST-medium and (scaled) ST-low
184: resolutions for the TV "monitor type"</li>
1.1.1.8 root 185: <li>Blitter chip emulation</li>
1.1.1.2 root 186: <li>PSG YM2149 emulation (soundchip) including STFM samples</li>
1.1.1.8 root 187: <li>Printer port emulation on hardware level (print to file)</li>
1.1.1.10 root 188: <li>RS232 emulation</li>
189: <li>MIDI input/output/through emulation</li>
1.1 root 190: <li>Mega ST real time clock</li>
1.1.1.3 root 191: <li>IKBD emulation (keyboard, mouse and joystick) with custom
1.1.1.7 root 192: keyboard mapping</li>
1.1 root 193: <li>joystick emulation via cursor keys and joystick emulation via a
1.1.1.7 root 194: connected PC joystick</li>
1.1.1.3 root 195: <li>FDC emulation using floppy disk images in standard formats (*.ST,
1.1.1.7 root 196: *.MSA and *.DIM)</li>
1.1.1.5 root 197: <li>support for packed disk images (PkZip and Gzip)</li>
1.1.1.12! root 198: <li>optional write-protection for floppy disk images</li>
1.1.1.2 root 199: <li>partial ACSI emulation for harddisk support</li>
1.1.1.12! root 200: <li>GEMDOS interface driver to mount directories as harddrives
! 201: with optional write-protection</li>
1.1.1.7 root 202: <li>support for memory snapshots (save whole system state)</li>
1.1.1.2 root 203: <li>driver for extended VDI resolutions</li>
204: <li>recording of sound as .WAV and .YM files</li>
1.1.1.8 root 205: <li>screenshots in PNG or BMP format</li>
1.1.1.12! root 206: <li>AVI animation capturing with sound</li>
1.1.1.8 root 207: <li>TOS versions 1.00, 1.02, 1.04 and 2.06 (and EmuTOS) can be used in ST mode.</li>
1.1 root 208: </ul>
1.1.1.5 root 209:
1.1.1.7 root 210: <a name="STE hardware emulation"></a>
211: <h4>STE hardware emulation</h4>
1.1.1.12! root 212: There is support for following additional STE features:
1.1.1.5 root 213: <ul>
214: <li>horizontal and vertical hardware fine scrolling</li>
215: <li>split screen techniques / in-screen video address manipulations</li>
1.1.1.8 root 216: <li>(STE specific) left border opening</li>
1.1.1.5 root 217: <li>4096 colors STE palette</li>
1.1.1.12! root 218: <li>Stereo DMA sample sound</li>
! 219: <li>Experimental Microwire/LMC1992 emulation</li>
1.1.1.7 root 220: <li>STE joypads</li>
1.1.1.8 root 221: <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 222: </ul>
223:
1.1.1.12! root 224: <a name="TT hardware emulation"></a>
! 225: <h4>Experimental TT hardware emulation</h4>
1.1.1.7 root 226: There is support for following additional TT features:
227: <ul>
228: <li>TT low/med/high resolution support</li>
229: <li>ST/TT palette switching and video shifter</li>
230: <li>RAM upto 14MiB (ST-RAM only, there is no support for TT-RAM yet)</li>
1.1.1.8 root 231: <li>Only TOS version 3.06 (and EmuTOS) can be used in TT mode.</li>
1.1.1.7 root 232: </ul>
233:
1.1.1.12! root 234: <a name="Falcon hardware emulation"></a>
! 235: <h4>Falcon hardware emulation</h4>
1.1.1.7 root 236: There is support for following additional Falcon features:
237: <ul>
1.1.1.12! root 238: <li>Partial Videl emulation for all Falcon screen modes</li>
! 239: <li>Aspect correction and scaling of small resolutions by an integer factor</li>
1.1.1.7 root 240: <li>STE/Falcon palette switching and shifter</li>
241: <li>Mono/RGB/VGA/TV monitor types</li>
1.1.1.12! root 242: <li>DSP co-processor emulation</li>
! 243: <li>Experimental microphone (jack) emulation</li>
! 244: <li>Experimental Crossbar sound matrix (ADC (mic & PSG), DAC, DMA, DSP)
! 245: interconnect emulation + support for the additional DMA sound
! 246: sample rates</li>
! 247: <li>Experimental IDE master and slave emulation for harddisk support</li>
1.1.1.8 root 248: <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 249: </ul>
250:
1.1.1.12! root 251: <p>See the developers' <span class="file">doc/todo.txt</span> file
! 252: (included with Hatari sources) for the details on the few remaining
! 253: emulation gaps and the <a href="compatibility.html">Hatari Atari
! 254: Software Compatibility List</a> for which Atari programs are known
! 255: to be affected by them.</p>
1.1.1.5 root 256:
257:
258: <a name="System requirements"></a><h3>System requirements</h3>
259:
1.1 root 260: <p> Hatari currently has the following system requirements: </p>
261: <ul>
1.1.1.12! root 262: <li>a fast PC (>500MHz, for Falcon and TT emulation
! 263: <a href="#Performance">even faster</a>)</li>
1.1.1.3 root 264: <li>some sort of Unix (preferable <a href="http://www.linux.org/">GNU/Linux</a>)
265: </li>
1.1 root 266: <li>the SDL library (<a href="http://www.libsdl.org/">http://www.libsdl.org/</a>)</li>
1.1.1.3 root 267: <li>the zLib (<a href="http://www.gzip.org/zlib/">http://www.gzip.org/zlib/</a>)
1.1.1.12! root 268: for support of ZIP-packed disk images (*.zip and *.gz)</li>
1.1 root 269: </ul>
1.1.1.5 root 270:
271: <p>
272: Certain versions of Hatari have successfully been tested by various people on
273: the following systems:
274: </p>
1.1 root 275: <ul>
1.1.1.8 root 276: <li>Linux/i86 with Kernel 2.4.x and 2.6.x</li>
277: <li>Linux/PPC with Kernel 2.4.x and 2.6.x</li>
1.1.1.2 root 278: <li>BeOS/i86 </li>
1.1 root 279: <li>Apple PowerMac with Mac OS X </li>
280: <li>NetBSD 1.6 </li>
1.1.1.4 root 281: <li>NetBSD on a Digital Alpha</li>
1.1.1.8 root 282: <li>FreeBSD 4.1 on an i486, FreeBSD 4.8 on a Pentium 4 and FreeBSD 5.1</li>
1.1.1.2 root 283: <li>OpenBSD 3.5 </li>
1.1.1.4 root 284: <li>Solaris 8 on a SUN UltraSparc 1</li>
1.1.1.8 root 285: <li>Linux/ARM (oabi) on Sharp Zaurus SL-C760 PDA</li>
1.1.1.12! root 286: <li>Linux/ARM (eabi) on Nokia Maemo Internet Tablets and N900 phone</li>
1.1 root 287: </ul>
1.1.1.5 root 288:
289: <a name="Compiling and running"></a><h2>Compiling and running</h2>
290:
291: <a name="Compiling Hatari"></a><h3>Compiling Hatari</h3>
292:
1.1 root 293: <p> First, you need the SDL library, you can get it at:
1.1.1.3 root 294: <a href="http://www.libsdl.org/">http://www.libsdl.org/</a>. Most
295: distributions already ship a suitable version.
296: Make sure to install the appropriate header files as well often called
297: "libsdl-dev" or the like.
298: </p>
299: <p> Second, you need the zLib compression library. You can get it from <a
300: href="http://www.gzip.org/zlib/">http://www.gzip.org/zlib/</a>
301: but the version shipped with your distribution will be sufficient in
302: most cases. Make sure to have the header files
1.1 root 303: for it installed as well.
304: </p>
305: <p>
1.1.1.8 root 306: For optional features like PNG format screenshots and Hatari window
307: embedding, you need to have the header files for libpng and libX11.
1.1.1.12! root 308: For Falcon microphone recording support portaudio library is needed.
1.1.1.8 root 309: </p>
310: <p>
1.1 root 311: Of course, you need the GNU C compiler and (GNU) Make, too!
312: </p>
1.1.1.8 root 313: <p> Change to the <span class="file">hatari/</span> directory, copy
314: <span class="file">Makefile-default.cnf</span> to
315: <span class="file">Makefile.cnf</span> and adapt the configuration file
316: to suite your system. Alternatively, you can use the supplied configure
317: script to auto-detect all parameters (type
318: "<span class="commandline">./configure --help</span>"
1.1.1.3 root 319: to see the options of the script).
320: Don't forget to use some good CFLAGS for the compiler optimizations, e.g.
321: run <span class="commandline">configure</span> in the following way:
322: </p>
1.1.1.10 root 323: <pre>
324: CFLAGS="-O3 -fomit-frame-pointer" ./configure
325: </pre>
1.1.1.3 root 326: <p>
327: Then compile Hatari by typing <span class="commandline">make</span>.
328: If all
329: works fine, you'll get the executable <span class="commandline">hatari</span>
330: in the src/ subdirectory.
1.1.1.2 root 331: </p>
1.1.1.5 root 332:
333: <a name="Installation of a TOS ROM"></a><h3>Installation of a TOS ROM</h3>
334:
1.1.1.6 root 335: <p>
336: Before you can start Hatari, you have to copy a TOS ROM image to the data
337: directory (the data directory is specified
1.1.1.3 root 338: in the configuration file <span class="file">Makefile.cnf</span>) and
339: rename it to <span class="commandline">tos.img</span>, or use the
340: <span class="commandline">--tos</span> command line option to tell
341: Hatari where to find a TOS ROM.
1.1 root 342: Hatari needs a TOS ROM image because this contains the operating system
1.1.1.6 root 343: of the emulated Atari.
344: </p>
345: <p>
346: Unfortunately it is not possible to ship an original ROM
1.1.1.5 root 347: image with the Hatari package since these images are still copyrighted.
348: But you can easily create an image with a real ST and one of those various
1.1.1.12! root 349: ROM-image programs for the ST (search for "TOSDUMP" with your
1.1.1.5 root 350: favourite internet search engine). If your old ST does not work anymore, you
351: can also try to search the internet directly for corresponding TOS ROM image,
352: but don't ask the Hatari team where to get one. </p>
353: <p> Another solution is EmuTOS, which is also shipped with the official
354: release versions of Hatari. EmuTOS is an open-source TOS clone. You can find
355: it at:
356: <a href="http://emutos.sourceforge.net/">http://emutos.sourceforge.net/</a>.
357: It is not the best solution for playing games or running other old software
1.1.1.8 root 358: due to compatibility issues (see <span class="file">emutos.txt</span> for
359: more details), but it's free and compatible with Hatari.</p>
1.1 root 360: <p>If you do not specify a TOS image on the commandline nor can Hatari
361: find a suitable TOS image in the default dir, you'll get the chance to
362: select a TOS image file from the GUI. </p>
1.1.1.5 root 363:
364: <a name="Installation of the binary"></a><h3>Installation of the binary</h3>
365:
1.1.1.3 root 366: <p> Type <span class="commandline">make install</span> as root to do a
367: systemwide installation. In this case it is recommended
368: to set the DATADIR variable in Makefile.cnf to a proper value. <tt>/usr/local/share/hatari</tt>
369: is a good value in that case.</p>
370: <p>The Hatari executable should now be in your PATH and accessible from
371: anywhere.</p>
1.1 root 372: <p> When you finally have got a TOS image, try starting Hatari with the
1.1.1.3 root 373: option <span class="commandline">--help</span> to find out more about
374: its command line parameters. </p>
1.1.1.5 root 375:
376: <a name="Running Hatari for the first time"></a><h3>Running Hatari for the first time</h3>
377:
1.1.1.3 root 378: <p> Now type <span class="commandline">hatari</span> to run the
379: emulator for the first time. If all goes
380: well, you should now be presented with a window showing you the
381: familiar
382: little green desktop of the Atari ST. Press <span class="key">F12</span>
383: to turn on the GUI to
384: configure Hatari to suit your needs, press <span class="key">F11</span>
385: to toggle windowed and fullscreen mode. </p>
1.1.1.5 root 386:
387: <a name="Command line options"></a><h2>Command line options</h2>
388:
1.1.1.7 root 389: <p>Usage:</p>
390: <pre>
391: hatari [options] [disk image name]
392: </pre>
393:
1.1.1.8 root 394: <p>Hatari command line options are split into several categories:</p>
1.1.1.7 root 395:
1.1.1.8 root 396: <!--
397: Generated from hatari.1 options section by changing subheaders to h3
398: and removing extra paragraphs:
399: groff -man -Thtml hatari.1 | awk '
400: /OPTIONS<\/h/ { out = 1; next }
401: /INDENTATION/ { next }
402: /COMMANDS/ { out = 0; next }
403: { if(out) print }' | sed -e 's/h2/h3/g' -e 's/<\/*p>//g'
404: -->
405:
406: <a name="General options"></a>
407: <h3>General options</h3>
408: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 409: cellspacing="0" cellpadding="0">
1.1.1.8 root 410: <tr valign="top" align="left">
411: <td width="10%"></td>
412: <td width="89%">
1.1.1.12! root 413: <b>-h, --help</b></td>
1.1.1.8 root 414: </table>
415: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 416: cellspacing="0" cellpadding="0">
1.1.1.8 root 417: <tr valign="top" align="left">
418: <td width="21%"></td>
419: <td width="77%">
420: Print command line options and terminate
421: </td>
422: </table>
423: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 424: cellspacing="0" cellpadding="0">
1.1.1.8 root 425: <tr valign="top" align="left">
426: <td width="10%"></td>
427: <td width="89%">
1.1.1.12! root 428: <b>-v, --version</b></td>
1.1.1.8 root 429: </table>
430: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 431: cellspacing="0" cellpadding="0">
1.1.1.8 root 432: <tr valign="top" align="left">
433: <td width="21%"></td>
434: <td width="77%">
435: Print version information and terminate
436: </td>
437: </table>
438: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 439: cellspacing="0" cellpadding="0">
1.1.1.8 root 440: <tr valign="top" align="left">
441: <td width="10%"></td>
442: <td width="89%">
1.1.1.12! root 443: <b>--confirm-quit <bool></b></td>
1.1.1.8 root 444: </table>
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="21%"></td>
449: <td width="77%">
450: Whether Hatari confirms quitting
451: </td>
452: </table>
453: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 454: cellspacing="0" cellpadding="0">
1.1.1.8 root 455: <tr valign="top" align="left">
456: <td width="10%"></td>
457: <td width="89%">
1.1.1.12! root 458: <b>-c, --configfile
1.1.1.8 root 459: <filename></b></td>
460: </table>
461: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 462: cellspacing="0" cellpadding="0">
1.1.1.8 root 463: <tr valign="top" align="left">
464: <td width="21%"></td>
465: <td width="77%">
466: use the given file as configuration file instead of
467: ~/.hatari/hatari.cfg
468: </td>
469: </table>
470: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 471: cellspacing="0" cellpadding="0">
1.1.1.8 root 472: <tr valign="top" align="left">
473: <td width="10%"></td>
474: <td width="89%">
1.1.1.12! root 475: <b>--fast-forward <bool></b></td>
1.1.1.8 root 476: </table>
477: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 478: cellspacing="0" cellpadding="0">
1.1.1.8 root 479: <tr valign="top" align="left">
480: <td width="21%"></td>
481: <td width="77%">
482: On fast machine helps skipping (fast forwarding) Hatari
483: output
484: </td>
485: </table>
486: <a name="Display options"></a>
487: <h3>Display options</h3>
488: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 489: cellspacing="0" cellpadding="0">
1.1.1.8 root 490: <tr valign="top" align="left">
491: <td width="10%"></td>
492: <td width="89%">
1.1.1.12! root 493: <b>-m, --mono</b></td>
1.1.1.8 root 494: </table>
495: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 496: cellspacing="0" cellpadding="0">
1.1.1.8 root 497: <tr valign="top" align="left">
498: <td width="21%"></td>
499: <td width="77%">
500: Start in monochrome mode instead of color
501: </td>
502: </table>
503: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 504: cellspacing="0" cellpadding="0">
1.1.1.8 root 505: <tr valign="top" align="left">
506: <td width="10%"></td>
507: <td width="89%">
1.1.1.12! root 508: <b>--monitor <x></b></td>
1.1.1.8 root 509: </table>
510: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 511: cellspacing="0" cellpadding="0">
1.1.1.8 root 512: <tr valign="top" align="left">
513: <td width="21%"></td>
514: <td width="77%">
515: Select monitor type (x = mono/rgb/vga/tv)
516: </td>
517: </table>
518: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 519: cellspacing="0" cellpadding="0">
1.1.1.8 root 520: <tr valign="top" align="left">
521: <td width="10%"></td>
522: <td width="89%">
1.1.1.12! root 523: <b>-f, --fullscreen</b></td>
1.1 root 524: </table>
1.1.1.8 root 525: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 526: cellspacing="0" cellpadding="0">
1.1.1.8 root 527: <tr valign="top" align="left">
528: <td width="21%"></td>
529: <td width="77%">
530: Start the emulator in fullscreen mode
531: </td>
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="10%"></td>
537: <td width="89%">
1.1.1.12! root 538: <b>-w, --window</b></td>
1.1.1.8 root 539: </table>
540: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 541: cellspacing="0" cellpadding="0">
1.1.1.8 root 542: <tr valign="top" align="left">
543: <td width="21%"></td>
544: <td width="77%">
545: Start the emulator in window mode
546: </td>
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="10%"></td>
552: <td width="89%">
1.1.1.12! root 553: <b>--grab</b></td>
1.1.1.10 root 554: </table>
555: <table width="100%" border=0 rules="none" frame="void"
556: cellspacing="0" cellpadding="0">
557: <tr valign="top" align="left">
558: <td width="21%"></td>
559: <td width="77%">
560: Grab mouse (also) in window mode
561: </td>
562: </table>
563: <table width="100%" border=0 rules="none" frame="void"
564: cellspacing="0" cellpadding="0">
565: <tr valign="top" align="left">
566: <td width="10%"></td>
567: <td width="89%">
1.1.1.12! root 568: <b>-z, --zoom <x></b></td>
1.1.1.8 root 569: </table>
570: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 571: cellspacing="0" cellpadding="0">
1.1.1.8 root 572: <tr valign="top" align="left">
573: <td width="21%"></td>
574: <td width="77%">
575: Zoom low resolution (1=no, 2=yes)
576: </td>
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="10%"></td>
582: <td width="89%">
1.1.1.12! root 583: <b>--max-width <x></b></td>
1.1.1.8 root 584: </table>
585: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 586: cellspacing="0" cellpadding="0">
1.1.1.8 root 587: <tr valign="top" align="left">
588: <td width="21%"></td>
589: <td width="77%">
1.1.1.12! root 590: Maximum window width for zooming (Falcon/TT only)
! 591: </td>
! 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="10%"></td>
! 597: <td width="89%">
! 598: <b>--max-height <x></b></td>
! 599: </table>
! 600: <table width="100%" border=0 rules="none" frame="void"
! 601: cellspacing="0" cellpadding="0">
! 602: <tr valign="top" align="left">
! 603: <td width="21%"></td>
! 604: <td width="77%">
! 605: Maximum window height for zooming (Falcon/TT only)
! 606: </td>
! 607: </table>
! 608: <table width="100%" border=0 rules="none" frame="void"
! 609: cellspacing="0" cellpadding="0">
! 610: <tr valign="top" align="left">
! 611: <td width="10%"></td>
! 612: <td width="89%">
! 613: <b>--aspect <bool></b></td>
! 614: </table>
! 615: <table width="100%" border=0 rules="none" frame="void"
! 616: cellspacing="0" cellpadding="0">
! 617: <tr valign="top" align="left">
! 618: <td width="21%"></td>
! 619: <td width="77%">
! 620: Whether to do monitor aspect ratio correction (Falcon/TT only)
1.1.1.8 root 621: </td>
622: </table>
623: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 624: cellspacing="0" cellpadding="0">
1.1.1.8 root 625: <tr valign="top" align="left">
626: <td width="10%"></td>
627: <td width="89%">
1.1.1.12! root 628: <b>--borders <bool></b></td>
1.1.1.8 root 629: </table>
630: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 631: cellspacing="0" cellpadding="0">
1.1.1.8 root 632: <tr valign="top" align="left">
633: <td width="21%"></td>
634: <td width="77%">
1.1.1.12! root 635: Show ST/STE screen borders (for low/med resolution overscan demos)
1.1.1.8 root 636: </td>
637: </table>
638: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 639: cellspacing="0" cellpadding="0">
1.1.1.8 root 640: <tr valign="top" align="left">
641: <td width="10%"></td>
642: <td width="89%">
1.1.1.12! root 643: <b>--frameskips <x></b></td>
! 644: </table>
! 645: <table width="100%" border=0 rules="none" frame="void"
! 646: cellspacing="0" cellpadding="0">
! 647: <tr valign="top" align="left">
! 648: <td width="21%"></td>
! 649: <td width="77%">
! 650: Skip <x> frames after each displayed frame to
! 651: accelerate emulation (0=disabled, >4 uses automatic
! 652: frameskip with given value as maximum)
! 653: </td>
! 654: </table>
! 655: <table width="100%" border=0 rules="none" frame="void"
! 656: cellspacing="0" cellpadding="0">
! 657: <tr valign="top" align="left">
! 658: <td width="10%"></td>
! 659: <td width="89%">
! 660: <b>--statusbar <bool></b></td>
1.1.1.8 root 661: </table>
662: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 663: cellspacing="0" cellpadding="0">
1.1.1.8 root 664: <tr valign="top" align="left">
665: <td width="21%"></td>
666: <td width="77%">
667: Show statusbar (with floppy leds etc etc)
668: </td>
669: </table>
670: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 671: cellspacing="0" cellpadding="0">
1.1.1.8 root 672: <tr valign="top" align="left">
673: <td width="10%"></td>
674: <td width="89%">
1.1.1.12! root 675: <b>--drive-led <bool></b></td>
1.1.1.8 root 676: </table>
677: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 678: cellspacing="0" cellpadding="0">
1.1.1.8 root 679: <tr valign="top" align="left">
680: <td width="21%"></td>
681: <td width="77%">
682: Show overlay drive led when statusbar isn’t
683: shown
684: </td>
685: </table>
686: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 687: cellspacing="0" cellpadding="0">
1.1.1.8 root 688: <tr valign="top" align="left">
689: <td width="10%"></td>
690: <td width="89%">
1.1.1.12! root 691: <b>--spec512 <x></b></td>
1.1.1.8 root 692: </table>
693: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 694: cellspacing="0" cellpadding="0">
1.1.1.8 root 695: <tr valign="top" align="left">
696: <td width="21%"></td>
697: <td width="77%">
698: Hatari uses this threshold to decide when to render a
699: screen with the slower but more accurate Spectrum512 screen
700: conversion functions (0 <= x <= 512, 0=disable)
701: </td>
702: </table>
703: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 704: cellspacing="0" cellpadding="0">
1.1.1.8 root 705: <tr valign="top" align="left">
706: <td width="10%"></td>
707: <td width="89%">
1.1.1.12! root 708: <b>--bpp <bool></b></td>
1.1.1.8 root 709: </table>
710: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 711: cellspacing="0" cellpadding="0">
1.1.1.8 root 712: <tr valign="top" align="left">
713: <td width="21%"></td>
714: <td width="77%">
715: Force internal bitdepth (x = 8/15/16/32, 0=disable)
716: </td>
717: </table>
718: <a name="VDI options"></a>
719: <h3>VDI options</h3>
720: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 721: cellspacing="0" cellpadding="0">
1.1.1.8 root 722: <tr valign="top" align="left">
723: <td width="10%"></td>
724: <td width="89%">
1.1.1.12! root 725: <b>--vdi <bool></b></td>
1.1.1.8 root 726: </table>
727: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 728: cellspacing="0" cellpadding="0">
1.1.1.8 root 729: <tr valign="top" align="left">
730: <td width="21%"></td>
731: <td width="77%">
732: Whether to use VDI screen mode
733: </td>
734: </table>
735: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 736: cellspacing="0" cellpadding="0">
1.1.1.8 root 737: <tr valign="top" align="left">
738: <td width="10%"></td>
739: <td width="89%">
1.1.1.12! root 740: <b>--vdi-planes <x></b></td>
1.1.1.8 root 741: </table>
742: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 743: cellspacing="0" cellpadding="0">
1.1.1.8 root 744: <tr valign="top" align="left">
745: <td width="21%"></td>
746: <td width="77%">
1.1.1.12! root 747: Use extended VDI resolution with bit depth <x> (x = 1, 2 or 4)
1.1.1.8 root 748: </td>
749: </table>
750: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 751: cellspacing="0" cellpadding="0">
1.1.1.8 root 752: <tr valign="top" align="left">
753: <td width="10%"></td>
754: <td width="89%">
1.1.1.12! root 755: <b>--vdi-width <w></b></td>
1.1.1.8 root 756: </table>
757: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 758: cellspacing="0" cellpadding="0">
1.1.1.8 root 759: <tr valign="top" align="left">
760: <td width="21%"></td>
761: <td width="77%">
1.1.1.12! root 762: Use extended VDI resolution with width <w> (320 < w <= 1280)
1.1.1.8 root 763: </td>
764: </table>
765: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 766: cellspacing="0" cellpadding="0">
1.1.1.8 root 767: <tr valign="top" align="left">
768: <td width="10%"></td>
769: <td width="89%">
1.1.1.12! root 770: <b>--vdi-height <h></b></td>
1.1.1.8 root 771: </table>
772: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 773: cellspacing="0" cellpadding="0">
1.1.1.8 root 774: <tr valign="top" align="left">
775: <td width="21%"></td>
776: <td width="77%">
1.1.1.12! root 777: Use extended VDI resolution with height <h> (200 < h <= 960)
! 778: </td>
! 779: </table>
! 780: <a name="Video recording options"></a>
! 781: <h3>Video recording options</h3>
! 782: <table width="100%" border=0 rules="none" frame="void"
! 783: cellspacing="0" cellpadding="0">
! 784: <tr valign="top" align="left">
! 785: <td width="10%"></td>
! 786: <td width="89%">
! 787: <b>--avirecord</b></td>
! 788: </table>
! 789: <table width="100%" border=0 rules="none" frame="void"
! 790: cellspacing="0" cellpadding="0">
! 791: <tr valign="top" align="left">
! 792: <td width="21%"></td>
! 793: <td width="77%">
! 794: Start AVI recording
! 795: </td>
! 796: </table>
! 797: <table width="100%" border=0 rules="none" frame="void"
! 798: cellspacing="0" cellpadding="0">
! 799: <tr valign="top" align="left">
! 800: <td width="10%"></td>
! 801: <td width="89%">
! 802: <b>--avi-vcodec <x></b></td>
! 803: </table>
! 804: <table width="100%" border=0 rules="none" frame="void"
! 805: cellspacing="0" cellpadding="0">
! 806: <tr valign="top" align="left">
! 807: <td width="21%"></td>
! 808: <td width="77%">
! 809: Select avi video codec (x = bmp/png)
! 810: </td>
! 811: </table>
! 812: <table width="100%" border=0 rules="none" frame="void"
! 813: cellspacing="0" cellpadding="0">
! 814: <tr valign="top" align="left">
! 815: <td width="10%"></td>
! 816: <td width="89%">
! 817: <b>--avi-fps <x></b></td>
! 818: </table>
! 819: <table width="100%" border=0 rules="none" frame="void"
! 820: cellspacing="0" cellpadding="0">
! 821: <tr valign="top" align="left">
! 822: <td width="21%"></td>
! 823: <td width="77%">
! 824: Force avi frame rate (x = 50/60/71/...)
! 825: </td>
! 826: </table>
! 827: <table width="100%" border=0 rules="none" frame="void"
! 828: cellspacing="0" cellpadding="0">
! 829: <tr valign="top" align="left">
! 830: <td width="10%"></td>
! 831: <td width="89%">
! 832: <b>--avi-crop <bool></b></td>
! 833: </table>
! 834: <table width="100%" border=0 rules="none" frame="void"
! 835: cellspacing="0" cellpadding="0">
! 836: <tr valign="top" align="left">
! 837: <td width="21%"></td>
! 838: <td width="77%">
! 839: Remove status bar from the recorded file
! 840: </td>
! 841: </table>
! 842: <table width="100%" border=0 rules="none" frame="void"
! 843: cellspacing="0" cellpadding="0">
! 844: <tr valign="top" align="left">
! 845: <td width="10%"></td>
! 846: <td width="89%">
! 847: <b>--avi-file <file></b></td>
! 848: </table>
! 849: <table width="100%" border=0 rules="none" frame="void"
! 850: cellspacing="0" cellpadding="0">
! 851: <tr valign="top" align="left">
! 852: <td width="21%"></td>
! 853: <td width="77%">
! 854: Use <file> to record avi
1.1.1.8 root 855: </td>
856: </table>
857: <a name="Devices options"></a>
858: <h3>Devices options</h3>
859: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 860: cellspacing="0" cellpadding="0">
1.1.1.8 root 861: <tr valign="top" align="left">
862: <td width="10%"></td>
863: <td width="89%">
1.1.1.12! root 864: <b>-j, --joystick
1.1.1.8 root 865: <port></b></td>
866: </table>
867: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 868: cellspacing="0" cellpadding="0">
1.1.1.8 root 869: <tr valign="top" align="left">
870: <td width="21%"></td>
871: <td width="77%">
872: Emulate joystick with cursor keys in given port (0-5)
873: </td>
874: </table>
875: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 876: cellspacing="0" cellpadding="0">
1.1.1.8 root 877: <tr valign="top" align="left">
878: <td width="10%"></td>
879: <td width="89%">
1.1.1.12! root 880: <b>--joy<port>
1.1.1.8 root 881: <type></b></td>
882: </table>
883: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 884: cellspacing="0" cellpadding="0">
1.1.1.8 root 885: <tr valign="top" align="left">
886: <td width="21%"></td>
887: <td width="77%">
888: Set joystick type (none/keys/real) for given port
889: </td>
890: </table>
891: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 892: cellspacing="0" cellpadding="0">
1.1.1.8 root 893: <tr valign="top" align="left">
894: <td width="10%"></td>
895: <td width="89%">
1.1.1.12! root 896: <b>--printer <file></b></td>
1.1.1.8 root 897: </table>
898: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 899: cellspacing="0" cellpadding="0">
1.1.1.8 root 900: <tr valign="top" align="left">
901: <td width="21%"></td>
902: <td width="77%">
903: Enable printer support and write data to <file>
904: </td>
905: </table>
906: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 907: cellspacing="0" cellpadding="0">
1.1.1.8 root 908: <tr valign="top" align="left">
909: <td width="10%"></td>
910: <td width="89%">
1.1.1.12! root 911: <b>--midi-in <filename></b></td>
1.1.1.8 root 912: </table>
913: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 914: cellspacing="0" cellpadding="0">
1.1.1.8 root 915: <tr valign="top" align="left">
916: <td width="21%"></td>
917: <td width="77%">
1.1.1.9 root 918: Enable MIDI support and write MIDI data to <file>
1.1.1.8 root 919: </td>
920: </table>
921: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 922: cellspacing="0" cellpadding="0">
1.1.1.8 root 923: <tr valign="top" align="left">
924: <td width="10%"></td>
925: <td width="89%">
1.1.1.12! root 926: <b>--midi-out <filename></b></td>
1.1.1.8 root 927: </table>
928: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 929: cellspacing="0" cellpadding="0">
1.1.1.8 root 930: <tr valign="top" align="left">
931: <td width="21%"></td>
932: <td width="77%">
1.1.1.9 root 933: Enable MIDI support and read MIDI data from <file>
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.12! root 941: <b>--rs232-in <filename></b></td>
1.1.1.9 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%">
948: Enable serial port support and use <file> as the input device
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.12! root 956: <b>--rs232-out <filename></b></td>
1.1.1.9 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%">
963: Enable serial port support and use <file> as the output device
1.1.1.8 root 964: </td>
965: </table>
966: <a name="Disk options"></a>
967: <h3>Disk options</h3>
968: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 969: cellspacing="0" cellpadding="0">
1.1.1.8 root 970: <tr valign="top" align="left">
971: <td width="10%"></td>
972: <td width="89%">
1.1.1.12! root 973: <b>--disk-a <file></b></td>
1.1.1.8 root 974: </table>
975: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 976: cellspacing="0" cellpadding="0">
1.1.1.8 root 977: <tr valign="top" align="left">
978: <td width="21%"></td>
979: <td width="77%">
980: Set disk image for floppy drive A
981: </td>
982: </table>
983: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 984: cellspacing="0" cellpadding="0">
1.1.1.8 root 985: <tr valign="top" align="left">
986: <td width="10%"></td>
987: <td width="89%">
1.1.1.12! root 988: <b>--disk-b <file></b></td>
1.1.1.8 root 989: </table>
990: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 991: cellspacing="0" cellpadding="0">
1.1.1.8 root 992: <tr valign="top" align="left">
993: <td width="21%"></td>
994: <td width="77%">
995: Set disk image for floppy drive B
996: </td>
997: </table>
998: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 999: cellspacing="0" cellpadding="0">
1.1.1.8 root 1000: <tr valign="top" align="left">
1001: <td width="10%"></td>
1002: <td width="89%">
1.1.1.12! root 1003: <b>--protect-floppy <x></b></td>
1.1.1.8 root 1004: </table>
1005: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1006: cellspacing="0" cellpadding="0">
1.1.1.8 root 1007: <tr valign="top" align="left">
1008: <td width="21%"></td>
1009: <td width="77%">
1.1.1.12! root 1010: Write protect floppy image contents (on/off/auto). With "auto" option
! 1011: write protection is according to the disk image file attributes.
1.1.1.8 root 1012: </td>
1013: </table>
1014: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1015: cellspacing="0" cellpadding="0">
1.1.1.8 root 1016: <tr valign="top" align="left">
1017: <td width="10%"></td>
1018: <td width="89%">
1.1.1.12! root 1019: <b>--protect-hd <x></b></td>
! 1020: </table>
! 1021: <table width="100%" border=0 rules="none" frame="void"
! 1022: cellspacing="0" cellpadding="0">
! 1023: <tr valign="top" align="left">
! 1024: <td width="21%"></td>
! 1025: <td width="77%">
! 1026: Write protect harddrive <dir> contents (on/off/auto). With "auto"
! 1027: option the protection can be controlled by setting individual files
! 1028: attributes as it disables the file attribute modifications for
! 1029: the GEMDOS hard disk emulation.
! 1030: </td>
! 1031: </table>
! 1032: <table width="100%" border=0 rules="none" frame="void"
! 1033: cellspacing="0" cellpadding="0">
! 1034: <tr valign="top" align="left">
! 1035: <td width="10%"></td>
! 1036: <td width="89%">
! 1037: <b>-d, --harddrive <dir></b></td>
! 1038: </table>
! 1039: <table width="100%" border=0 rules="none" frame="void"
! 1040: cellspacing="0" cellpadding="0">
! 1041: <tr valign="top" align="left">
! 1042: <td width="21%"></td>
! 1043: <td width="77%">
! 1044: Emulate harddrive partition(s) with <dir> contents
! 1045: </td>
! 1046: </table>
! 1047: <table width="100%" border=0 rules="none" frame="void"
! 1048: cellspacing="0" cellpadding="0">
! 1049: <tr valign="top" align="left">
! 1050: <td width="10%"></td>
! 1051: <td width="89%">
! 1052: <b>--acsi <file></b></td>
1.1.1.8 root 1053: </table>
1054: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1055: cellspacing="0" cellpadding="0">
1.1.1.8 root 1056: <tr valign="top" align="left">
1057: <td width="21%"></td>
1058: <td width="77%">
1059: Emulate an ACSI hard disk with an image <file>
1060: </td>
1061: </table>
1062: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1063: cellspacing="0" cellpadding="0">
1.1.1.8 root 1064: <tr valign="top" align="left">
1065: <td width="10%"></td>
1066: <td width="89%">
1.1.1.12! root 1067: <b>--ide-master <file></b></td>
! 1068: </table>
! 1069: <table width="100%" border=0 rules="none" frame="void"
! 1070: cellspacing="0" cellpadding="0">
! 1071: <tr valign="top" align="left">
! 1072: <td width="21%"></td>
! 1073: <td width="77%">
! 1074: Emulate an IDE master hard disk with an image <file>
! 1075: </td>
! 1076: </table>
! 1077: <table width="100%" border=0 rules="none" frame="void"
! 1078: cellspacing="0" cellpadding="0">
! 1079: <tr valign="top" align="left">
! 1080: <td width="10%"></td>
! 1081: <td width="89%">
! 1082: <b>--ide-slave <file></b></td>
1.1.1.8 root 1083: </table>
1084: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1085: cellspacing="0" cellpadding="0">
1.1.1.8 root 1086: <tr valign="top" align="left">
1087: <td width="21%"></td>
1088: <td width="77%">
1.1.1.12! root 1089: Emulate an IDE slave hard disk with an image <file>
1.1.1.8 root 1090: </td>
1091: </table>
1092: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1093: cellspacing="0" cellpadding="0">
1.1.1.8 root 1094: <tr valign="top" align="left">
1095: <td width="10%"></td>
1096: <td width="89%">
1.1.1.12! root 1097: <b>--slowfdc <bool></b></td>
1.1.1.8 root 1098: </table>
1099: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1100: cellspacing="0" cellpadding="0">
1.1.1.8 root 1101: <tr valign="top" align="left">
1102: <td width="21%"></td>
1103: <td width="77%">
1104: slow down FDC emulation (deprecated)
1105: </td>
1106: </table>
1107: <a name="Memory options"></a>
1108: <h3>Memory options</h3>
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>-s, --memsize <x></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 amount of emulated RAM, x = 1 to 14 MiB, or 0 for 512
1122: KiB
1123: </td>
1124: </table>
1125: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1126: cellspacing="0" cellpadding="0">
1.1.1.8 root 1127: <tr valign="top" align="left">
1128: <td width="10%"></td>
1129: <td width="89%">
1.1.1.12! root 1130: <b>-t, --tos
1.1.1.8 root 1131: <imagefile></b></td>
1132: </table>
1133: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1134: cellspacing="0" cellpadding="0">
1.1.1.8 root 1135: <tr valign="top" align="left">
1136: <td width="21%"></td>
1137: <td width="77%">
1138: Specify TOS ROM image to use
1139: </td>
1140: </table>
1141: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1142: cellspacing="0" cellpadding="0">
1.1.1.8 root 1143: <tr valign="top" align="left">
1144: <td width="10%"></td>
1145: <td width="89%">
1.1.1.12! root 1146: <b>--cartridge <imagefile></b></td>
1.1.1.8 root 1147: </table>
1148: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1149: cellspacing="0" cellpadding="0">
1.1.1.8 root 1150: <tr valign="top" align="left">
1151: <td width="21%"></td>
1152: <td width="77%">
1153: Use ROM cartridge image <file> (only works if
1154: GEMDOS HD emulation and extended VDI resolution are
1155: disabled)
1156: </td>
1157: </table>
1158: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1159: cellspacing="0" cellpadding="0">
1.1.1.8 root 1160: <tr valign="top" align="left">
1161: <td width="10%"></td>
1162: <td width="89%">
1.1.1.12! root 1163: <b>--memstate <file></b></td>
1.1.1.8 root 1164: </table>
1165: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1166: cellspacing="0" cellpadding="0">
1.1.1.8 root 1167: <tr valign="top" align="left">
1168: <td width="21%"></td>
1169: <td width="77%">
1170: Load memory snap-shot <file>
1171: </td>
1172: </table>
1173: <a name="CPU options"></a>
1174: <h3>CPU options</h3>
1175: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1176: cellspacing="0" cellpadding="0">
1.1.1.8 root 1177: <tr valign="top" align="left">
1178: <td width="10%"></td>
1179: <td width="89%">
1.1.1.12! root 1180: <b>--cpulevel <x></b></td>
1.1.1.8 root 1181: </table>
1182: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1183: cellspacing="0" cellpadding="0">
1.1.1.8 root 1184: <tr valign="top" align="left">
1185: <td width="21%"></td>
1186: <td width="77%">
1187: Specify CPU (680x0) to use (use x >= 1 with EmuTOS or
1188: TOS >= 2.06 only!)
1189: </td>
1190: </table>
1191: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1192: cellspacing="0" cellpadding="0">
1.1.1.8 root 1193: <tr valign="top" align="left">
1194: <td width="10%"></td>
1195: <td width="89%">
1.1.1.12! root 1196: <b>--cpuclock <x></b></td>
1.1.1.8 root 1197: </table>
1198: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1199: cellspacing="0" cellpadding="0">
1.1.1.8 root 1200: <tr valign="top" align="left">
1201: <td width="21%"></td>
1202: <td width="77%">
1203: Set the CPU clock (8, 16 or 32 Mhz)
1204: </td>
1205: </table>
1206: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1207: cellspacing="0" cellpadding="0">
1.1.1.8 root 1208: <tr valign="top" align="left">
1209: <td width="10%"></td>
1210: <td width="89%">
1.1.1.12! root 1211: <b>--compatible <bool></b></td>
1.1.1.8 root 1212: </table>
1213: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1214: cellspacing="0" cellpadding="0">
1.1.1.8 root 1215: <tr valign="top" align="left">
1216: <td width="21%"></td>
1217: <td width="77%">
1218: Use a more compatible but slower 68000 CPU mode
1219: </td>
1220: </table>
1221: <a name="Misc system options"></a>
1222: <h3>Misc system options</h3>
1223: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1224: cellspacing="0" cellpadding="0">
1.1.1.8 root 1225: <tr valign="top" align="left">
1226: <td width="10%"></td>
1227: <td width="89%">
1.1.1.12! root 1228: <b>--machine <x></b></td>
1.1.1.8 root 1229: </table>
1230: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1231: cellspacing="0" cellpadding="0">
1.1.1.8 root 1232: <tr valign="top" align="left">
1233: <td width="21%"></td>
1234: <td width="77%">
1235: select machine type (x = st, ste, tt or falcon)
1236: </td>
1237: </table>
1238: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1239: cellspacing="0" cellpadding="0">
1.1.1.8 root 1240: <tr valign="top" align="left">
1241: <td width="10%"></td>
1242: <td width="89%">
1.1.1.12! root 1243: <b>--blitter <bool></b></td>
1.1.1.8 root 1244: </table>
1245: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1246: cellspacing="0" cellpadding="0">
1.1.1.8 root 1247: <tr valign="top" align="left">
1248: <td width="21%"></td>
1249: <td width="77%">
1250: Enable blitter emulation (ST only)
1251: </td>
1252: </table>
1253: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1254: cellspacing="0" cellpadding="0">
1.1.1.8 root 1255: <tr valign="top" align="left">
1256: <td width="10%"></td>
1257: <td width="89%">
1.1.1.12! root 1258: <b>--timer-d <bool></b></td>
1.1.1.10 root 1259: </table>
1260: <table width="100%" border=0 rules="none" frame="void"
1261: cellspacing="0" cellpadding="0">
1262: <tr valign="top" align="left">
1263: <td width="21%"></td>
1264: <td width="77%">
1265: Patch redundantly high Timer-D frequency set by TOS. This about doubles
1266: Hatari speed as the original Timer-D frequency causes most of the
1267: interrupts.
1268: </td>
1269: </table>
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>--dsp <x></b></td>
1.1.1.8 root 1276: </table>
1277: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1278: cellspacing="0" cellpadding="0">
1.1.1.8 root 1279: <tr valign="top" align="left">
1280: <td width="21%"></td>
1281: <td width="77%">
1282: Falcon DSP emulation (x = none, dummy or emu, Falcon
1283: only)
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.12! root 1291: <b>--sound <x></b></td>
1.1.1.8 root 1292: </table>
1293: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1294: cellspacing="0" cellpadding="0">
1.1.1.8 root 1295: <tr valign="top" align="left">
1296: <td width="21%"></td>
1297: <td width="77%">
1.1.1.10 root 1298: Sound frequency: 6000-50066. "off" disables the sound and speeds up
1299: the emulation. To prevent extra sound artifacts, the frequency should be
1300: selected so that it either matches evenly with the STE/TT/Falcon sound
1301: DMA (6258, 12517, 250033, 50066 Hz) or your sound card frequencies
1302: (11025, 22050, 44100 or 6000...48000 Hz). Check what your sound card
1303: supports.
1.1.1.8 root 1304: </td>
1305: </table>
1.1.1.12! root 1306:
! 1307: <table width="100%" border=0 rules="none" frame="void"
! 1308: cellspacing="0" cellpadding="0">
! 1309: <tr valign="top" align="left">
! 1310: <td width="10%"></td>
! 1311: <td width="89%">
! 1312: <b>--sound-buffer-size <x></b></td>
! 1313: </table>
! 1314: <table width="100%" border=0 rules="none" frame="void"
! 1315: cellspacing="0" cellpadding="0">
! 1316: <tr valign="top" align="left">
! 1317: <td width="21%"></td>
! 1318: <td width="77%">
! 1319: SDL's sound buffer size : 10-100, or 0 to use default buffer size.
! 1320: By default Hatari uses an SDL buffer size of 1024 samples, which
! 1321: gives approximatively 20-30 ms of sound depending on the chosen sound
! 1322: frequency. Under some OS or with not fully supported sound card, this
! 1323: default setting can cause a bigger delay at lower frequency (nearly 0.5 sec).
! 1324: In that case, you can use this option to force the size of the sound
! 1325: buffer to a fixed number of milliseconds of sound (using 20 is often
! 1326: a good choice if you have such problems). Most users will not need this option.
! 1327: </td>
! 1328: </table>
! 1329:
! 1330:
! 1331:
! 1332:
1.1.1.8 root 1333: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1334: cellspacing="0" cellpadding="0">
1.1.1.8 root 1335: <tr valign="top" align="left">
1336: <td width="10%"></td>
1337: <td width="89%">
1.1.1.12! root 1338: <b>-k, --keymap
1.1.1.8 root 1339: <file></b></td>
1340: </table>
1341: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1342: cellspacing="0" cellpadding="0">
1.1.1.8 root 1343: <tr valign="top" align="left">
1344: <td width="21%"></td>
1345: <td width="77%">
1346: load keyboard mapping from <file>
1347: </td>
1348: </table>
1349: <a name="Debug options"></a>
1350: <h3>Debug options</h3>
1351: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1352: cellspacing="0" cellpadding="0">
1.1.1.8 root 1353: <tr valign="top" align="left">
1354: <td width="10%"></td>
1355: <td width="89%">
1.1.1.12! root 1356: <b>-D, --debug</b></td>
1.1.1.8 root 1357: </table>
1358: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1359: cellspacing="0" cellpadding="0">
1.1.1.8 root 1360: <tr valign="top" align="left">
1361: <td width="21%"></td>
1362: <td width="77%">
1.1.1.10 root 1363: Toggle whether CPU exceptions invoke the debugger
1.1.1.8 root 1364: </td>
1365: </table>
1366: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1367: cellspacing="0" cellpadding="0">
1.1.1.8 root 1368: <tr valign="top" align="left">
1369: <td width="10%"></td>
1370: <td width="89%">
1.1.1.12! root 1371: <b>--bios-intercept</b></td>
1.1.1.8 root 1372: </table>
1373: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1374: cellspacing="0" cellpadding="0">
1.1.1.8 root 1375: <tr valign="top" align="left">
1376: <td width="21%"></td>
1377: <td width="77%">
1378: Enable Bios/XBios interception
1379: </td>
1380: </table>
1381: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1382: cellspacing="0" cellpadding="0">
1.1.1.8 root 1383: <tr valign="top" align="left">
1384: <td width="10%"></td>
1385: <td width="89%">
1.1.1.12! root 1386: <b>--trace <trace1,...></b></td>
1.1.1.8 root 1387: </table>
1388: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1389: cellspacing="0" cellpadding="0">
1.1.1.8 root 1390: <tr valign="top" align="left">
1391: <td width="21%"></td>
1392: <td width="77%">
1393: Activate debug traces, see <b>--trace help</b> for available tracing options
1394: </td>
1395: </table>
1396: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1397: cellspacing="0" cellpadding="0">
1.1.1.8 root 1398: <tr valign="top" align="left">
1399: <td width="10%"></td>
1400: <td width="89%">
1.1.1.12! root 1401: <b>--trace-file <file></b></td>
! 1402: </table>
! 1403: <table width="100%" border=0 rules="none" frame="void"
! 1404: cellspacing="0" cellpadding="0">
! 1405: <tr valign="top" align="left">
! 1406: <td width="21%"></td>
! 1407: <td width="77%">
! 1408: Save trace output to <file> (default=stderr)
! 1409: </td>
! 1410: </table>
! 1411: <table width="100%" border=0 rules="none" frame="void"
! 1412: cellspacing="0" cellpadding="0">
! 1413: <tr valign="top" align="left">
! 1414: <td width="10%"></td>
! 1415: <td width="89%">
! 1416: <b>--parse <file></b></td>
! 1417: </table>
! 1418: <table width="100%" border=0 rules="none" frame="void"
! 1419: cellspacing="0" cellpadding="0">
! 1420: <tr valign="top" align="left">
! 1421: <td width="21%"></td>
! 1422: <td width="77%">
! 1423: Parse/execute debugger commands from <file>
! 1424: </td>
! 1425: </table>
! 1426: <table width="100%" border=0 rules="none" frame="void"
! 1427: cellspacing="0" cellpadding="0">
! 1428: <tr valign="top" align="left">
! 1429: <td width="10%"></td>
! 1430: <td width="89%">
! 1431: <b>--control-socket <file></b></td>
1.1.1.8 root 1432: </table>
1433: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1434: cellspacing="0" cellpadding="0">
1.1.1.8 root 1435: <tr valign="top" align="left">
1436: <td width="21%"></td>
1437: <td width="77%">
1438: Hatari reads options from given socket at run-time
1439: </td>
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="10%"></td>
1445: <td width="89%">
1.1.1.12! root 1446: <b>--log-file <file></b></td>
1.1.1.8 root 1447: </table>
1448: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1449: cellspacing="0" cellpadding="0">
1.1.1.8 root 1450: <tr valign="top" align="left">
1451: <td width="21%"></td>
1452: <td width="77%">
1453: Save log output to <file> (default=stderr)
1454: </td>
1455: </table>
1456: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1457: cellspacing="0" cellpadding="0">
1.1.1.8 root 1458: <tr valign="top" align="left">
1459: <td width="10%"></td>
1460: <td width="89%">
1.1.1.12! root 1461: <b>--log-level <x></b></td>
1.1.1.8 root 1462: </table>
1463: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1464: cellspacing="0" cellpadding="0">
1.1.1.8 root 1465: <tr valign="top" align="left">
1466: <td width="21%"></td>
1467: <td width="77%">
1468: Log output level (x=debug/todo/info/warn/error/fatal)
1469: </td>
1470: </table>
1471: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1472: cellspacing="0" cellpadding="0">
1.1.1.8 root 1473: <tr valign="top" align="left">
1474: <td width="10%"></td>
1475: <td width="89%">
1.1.1.12! root 1476: <b>--alert-level <x></b></td>
1.1.1.8 root 1477: </table>
1478: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1479: cellspacing="0" cellpadding="0">
1.1.1.8 root 1480: <tr valign="top" align="left">
1481: <td width="21%"></td>
1482: <td width="77%">
1483: Show dialog for log messages above given level
1484: </td>
1485: </table>
1.1.1.10 root 1486: <table width="100%" border=0 rules="none" frame="void"
1487: cellspacing="0" cellpadding="0">
1488: <tr valign="top" align="left">
1489: <td width="10%"></td>
1490: <td width="89%">
1.1.1.12! root 1491: <b>--run-vbls <x></b></td>
1.1.1.10 root 1492: </table>
1493: <table width="100%" border=0 rules="none" frame="void"
1494: cellspacing="0" cellpadding="0">
1495: <tr valign="top" align="left">
1496: <td width="21%"></td>
1497: <td width="77%">
1498: Exit after X VBLs
1499: </td>
1500: </table>
1.1.1.8 root 1501:
1.1.1.5 root 1502:
1.1.1.7 root 1503: <p>Type <span class="commandline">hatari --help</span> to list all
1504: the command line options supported by a given version of Hatari.</p>
1505:
1.1.1.5 root 1506: <a name="Using the emulated system"></a><h2>Using the emulated system</h2>
1507:
1.1 root 1508: <p> Once you've started Hatari succesfully, you can use the emulator as
1.1.1.10 root 1509: an almost complete Atari ST computer system. </p>
1.1.1.5 root 1510:
1511: <a name="The GUI"></a><h3>The GUI</h3>
1512:
1.1.1.3 root 1513: <p>Press <span class="key">F12</span> to enter the GUI. Navigate it
1514: with the mouse.
1.1 root 1515: The GUI is rather self explanatory.</p>
1.1.1.5 root 1516:
1.1.1.8 root 1517: <a name="The Main Menu"></a><h4 class="gui">The Main Menu</h4>
1.1.1.5 root 1518:
1519: <div class="floatimage">
1.1.1.10 root 1520: <img src="images/main.png" width="500" height="304" alt="Hatari's GUI - the main menu">
1.1.1.5 root 1521: </div>
1522:
1.1.1.12! root 1523: <p>
! 1524: You can reach the other setup dialogs from the main menu by clicking on
! 1525: the appropriate buttons.
! 1526: </p>
! 1527: <p>
! 1528: You can load the current settings from a configuration file by clicking
! 1529: on <span class="button">Load config.</span> and you can save
! 1530: the current settings to a configuration file by clicking on
! 1531: <span class="button">Save config.</span>.
! 1532: </p>
! 1533: <p>
! 1534: Click <span class="button">OK</span> to go back and continue the emulation.
! 1535: All changed options will be applied.
! 1536: </p>
! 1537: <p>
! 1538: Select the <span class="button">Reset machine</span> option if you
! 1539: want the emulated machine to perform a cold reset. This is equal to
! 1540: switching the power off and on again on a real Atari machine.
! 1541: </p>
! 1542: <p>
! 1543: Click <span class="button">Quit</span> to terminate Hatari
! 1544: and return to the host OS.
! 1545: </p>
! 1546: <p>
! 1547: Click <span class="button">Cancel</span> to abandon any
! 1548: changes that you have made.
! 1549: </p>
1.1.1.5 root 1550:
1.1.1.10 root 1551:
1552: <a name="The File Selector Dialog"></a><h4 class="gui">The File Selector Dialog</h4>
1553:
1554: <div class="floatimage">
1555: <img src="images/fileselector.png" width="640" height="399" alt="Hatari's GUI - the fileselector">
1556: </div>
1557:
1558: <p>
1559: The file selector dialog appears whenever you are prompted to choose a file
1560: or folder.
1561: </p>
1562: <p>
1563: To enter a folder or choose a file, simply click on the entry in the main box
1564: of the dialog. You can use the arrows at the right, the cursor up and down
1565: keys and the page up and down keys to navigate through the list.
1566: </p>
1567: <p>
1568: You can use the three buttons in the upper right corner for additional folder
1569: navigation. Use the <span class="button">..</span> button to go up one level
1570: in the directory tree. Use the <span class="button">~</span> button to return
1571: to your home directory. The <span class="button">/</span> button can be used
1572: to go to the root directory of the file system.
1573: </p>
1574:
1575:
1.1.1.8 root 1576: <a name="The System Dialog"></a><h4 class="gui">The System Dialog</h4>
1.1.1.5 root 1577:
1578: <div class="floatimage">
1.1.1.10 root 1579: <img src="images/system.png" width="360" height="384" alt="Hatari's GUI - the system dialog">
1.1.1.5 root 1580: </div>
1581:
1.1.1.7 root 1582: <p>
1583: First you can select the CPU type here. Here are some important hints for
1584: choosing the correct CPU type:
1585: </p>
1586: <ul>
1587: <li>
1588: Atari ST and STE have only been shipped with a 68000 CPU, so for best
1589: compatibility with old programs, choose this CPU type.
1590: </li>
1591: <li>
1592: Atari TT and Falcon computers were using the 68030 CPU, so you should switch
1.1.1.12! root 1593: use 68EC030+FPU (Hatari doesn't support 030 with MMU and some programs don't
! 1594: work with 68020 so this is the best choice).
1.1.1.7 root 1595: </li>
1596: <li>
1597: TOS 1.0x only works with 68000, while TOS 3.0x and 4.0x work only with a CPU
1598: >= 68020.
1599: </li>
1600: <li>
1601: 68010 and 68040 have never been used in official Atari computers, so don't
1602: use these CPU types unless you've got some good reasons.
1603: </li>
1604: </ul>
1605:
1606: <p>
1607: Beside the CPU type, you can also choose the machine type to emulate.
1608: The ST was the very first 16/32-bit computer from Atari. Most older games
1609: and demos require an ST. The STE was introduced some years later and had
1610: some more advanced hardware features. There are not that many demos or
1611: games that really require an STE but since most normal ST games/demos also
1612: work with an STE, it's normally safe to always work in STE mode.
1613: <br>
1614: TT and Falcon are more advanced, but they are not as compatible to the ST as
1.1.1.8 root 1615: the STE was. Therefore many old games and demos do not work with these machine
1616: types anymore. There were only very few programs that were made for the TT
1.1.1.7 root 1617: exclusively, while there were some interesting games and demos specially made
1618: for the Falcon.
1.1.1.12! root 1619: <em>Note:</em> TT and Falcon emulation are incomplete. They may not work
1.1.1.7 root 1620: very well.
1621: </p>
1622: <p>
1623: For STE emulation a STE compatible TOS image, e.q. version 1.06, 1.62 or
1624: 2.x, is strongly recommended. For TT emulation you need TOS 3.0x and for Falcon
1625: emulation you need TOS 4.0x. EmuTOS can be used on all machine types.
1626: </p>
1627: <p>
1628: Select the CPU clock you want to use. 8Mhz is ST standard and the most
1629: compatible. Use 16MHz for Mega STE and Falcon emulation.
1630: The CPU in the TT was clocked with 32 MHz.
1631: </p>
1.1.1.12! root 1632: <p>With the "Slower but more compatible CPU" option, you can enable
1.1.1.5 root 1633: the emulation of 68k address errors and the CPU prefetch buffer. This is needed
1634: for best compatibility, but it slows down emulation a little bit so you can
1635: disable it if you don't need it.</p>
1.1.1.10 root 1636: <p>
1637: For Falcon mode, you can choose whether you want to enable DSP emulation,
1638: fake it or completely disable it. Most Falcon programs only play sound or work
1639: correctly when you enable the DSP emulation, but it needs a lot of host CPU
1640: power (more than 2 GHz). So if you have a slow host CPU, you can try if your
1.1.1.12! root 1641: Falcon program also runs with DSP disabled or in "dummy" mode.
1.1.1.10 root 1642: Note that you can not change this option while the DSP based program already
1643: runs.
1644: </p>
1.1.1.5 root 1645: <p>You can also enable/disable Blitter emulation here. The Blitter is a custom
1646: chip that accelerates some graphical operations. This switch only toggles the
1647: Blitter in plain ST mode. In STE mode, the Blitter is always enabled (since all
1648: STEs have been sold with a Blitter chip).</p>
1.1.1.12! root 1649: <p>If you enable the "Real time clock emulation" switch, a RTC will
1.1.1.5 root 1650: be emulated based on the time of the host computer. Note that you need at least
1651: TOS 1.02 for proper RTC emulation, TOS 1.00 does not support this.</p>
1652: <p>The Timer-D patch changes the Timer-D initialization from TOS. TOS uses
1653: the MFP timer D as a baudrate generator for RS232. However, the TOS default
1654: value slows down the emulation. The patch gives you a better performance.
1.1.1.7 root 1655: It is normally safe to enable the patch, but if you encounter a program that
1.1.1.5 root 1656: does not work, you can try to disable the patch to see if it works then.</p>
1.1.1.12! root 1657: <p><em>NOTE:</em> The emulated Atari is very very sensitive to these options
! 1658: and it is strongly recommended to reset the emulation after changing
! 1659: them (for most things that's done automatically). The correct
! 1660: CPU type and clock are automatically selected when one uses the
! 1661: <span class="commandline">--machine</span> command line option.</p>
1.1.1.5 root 1662:
1663:
1.1.1.10 root 1664: <a name="The Floppy Disks Dialog"></a><h4 class="gui">The Floppy Disks Dialog</h4>
1.1.1.5 root 1665:
1.1.1.10 root 1666: <div class="floatimage">
1667: <img src="images/floppydisks.png" width="640" height="320" alt="Hatari's GUI - the floppy disks dialog">
1.1.1.5 root 1668: </div>
1669:
1.1.1.10 root 1670: <p>
1671: This dialog can be used to choose which floppy disks should be emulated
1672: in the disk drives. You can use most standard Atari ST disk image files.
1673: You may select and browse also zipped disk images. See the chapter
1.1.1.12! root 1674: <a href="#Floppy disk images">"Floppy disk images"</a> for details.
1.1.1.10 root 1675: </p>
1676: <p>
1677: Click on the button <span class="button">Browse</span> next to the
1678: A: and B: option to go to the fileselector to choose a disk image for the
1679: corresponding drive.
1680: </p>
1.1.1.3 root 1681: <p>Click on <span class="button">Eject</span> to eject a disk image
1682: from the emulated drive. The emulated ST will act as if had no floppy
1683: disk in its drive.</p>
1684: <p>You can specify a default directory where Hatari will start to
1685: browse the filesystem.</p>
1.1.1.2 root 1686: <p>
1.1.1.6 root 1687: Check the "Auto insert B" option if you want Hatari to be smart and
1688: insert the second disk of a two disk game automatically.
1689: Some games then use the second drive automatically.
1690: In the case that a game is not able to find the disk in the second drive,
1691: you have to insert the second disk in drive A: manually when prompted.
1692: <br>
1693: <em>NOTE:</em> This option only works properly if the file name of the
1694: first disks ends with an 'a' before the extension and the second disk name
1695: ends with a 'b'.
1.1.1.2 root 1696: </p>
1.1.1.10 root 1697: <p>
1698: Select if you want to use slow FDC (Floppy Disk Controller) emulation.
1.1.1.12! root 1699: "Slow floppy access" is normally not required, except for some few
1.1.1.10 root 1700: slideshows / intros which run too fast without this option.
1701: </p>
1702: <p>
1703: You can choose if you want Hatari to write-protect your disks. Atari ST virii
1704: can spread on disk images too so it might be a good idea to enable the write
1705: protection option. However you can't save highscores or games to your disk
1706: images in that case.
1707: </p>
1708:
1709: <div class="floatimage">
1.1.1.12! root 1710: <img src="images/newfloppy.png" width="290" height="224" alt="Hatari's GUI - the new floppy dialog">
1.1.1.10 root 1711: </div>
1712:
1713: <p>
1714: If you need to create a new blank disk image, click on
1715: <span class="button">Create blank image</span>.
1716: Parameters for the new image can be set in the following dialog.
1.1.1.12! root 1717: HD and ED disk sector counts are for non-Atari disk sizes, but such
! 1718: disks are useful for programs that don't work with GEMDOS emulation.
1.1.1.10 root 1719: Click on <span class="button">Create</span> to save the new image or on
1720: <span class="button">Back</span> to return to the disk dialog.
1721: </p>
1722: <p>
1723: After clicking <span class="button">Create</span>, a fileselector
1724: appears. You can browse the filesystem now. Select the target directory,
1.1.1.12! root 1725: click beside "File:" and type in a name for the new disk image.
1.1.1.10 root 1726: The name should terminate with .st or .msa.
1727: </p>
1728: <p>
1729: Hatari can currently create plain .ST and .MSA disk images exclusively.
1.1.1.12! root 1730: <span class="commandline">hmsa</span> command line utility can be used
! 1731: to convert disk images between .ST and .MSA formats.
1.1.1.10 root 1732: </p>
1733:
1734:
1735: <a name="The Hard Disks Dialog"></a><h4 class="gui">The Hard Disks Dialog</h4>
1736:
1737: <div class="floatimage">
1.1.1.12! root 1738: <img src="images/harddisks.png" width="640" height="304" alt="Hatari's GUI - the hard disks dialog">
1.1.1.10 root 1739: </div>
1740:
1741: <p>
1742: This dialog can be used to change the harddisk settings.
1743: </p>
1744: <p>
1.1.1.12! root 1745: You can select a harddrive image for ACSI, IDE master or slave hard drive
! 1746: emulation via image file here or you may select a directory of your local
! 1747: filesystem to be emulated as the harddrive of the emulated system.
1.1.1.10 root 1748: </p>
1749: <p>
1750: Check "Boot from HD" if you want Hatari to execute the AUTO folder
1751: on the harddrive.
1.1.1.12! root 1752: This option is checked by default if you specify a harddrive image or
! 1753: a directory via the command line.
! 1754: </p>
! 1755: <p>
! 1756: Removing the check from the "Allow GEMDOS drive modification" option
! 1757: will prevent Atari programs from modifying the files in GEMDOS HDD
! 1758: emulation directory or creating new files under it.
1.1.1.10 root 1759: </p>
1760: <p>
1761: Note that for IDE hard disk emulation you also need a TOS version >= 2.05.
1762: And ACSI hard disk emulation does not work with TOS 4.0x in Falcon mode.
1763: </p>
1764:
1.1.1.5 root 1765:
1.1.1.8 root 1766: <a name="The Memory Dialog"></a><h4 class="gui">The Memory Dialog</h4>
1.1.1.5 root 1767:
1.1.1.8 root 1768: <div class="floatimage">
1769: <img src="images/memory.png" width="398" height="349" alt="Hatari's GUI - the memory dialog">
1.1.1.5 root 1770: </div>
1771:
1.1.1.3 root 1772: <p>You can select the amount of RAM for the emulated ST here. Only
1773: amounts that were valid on a real unmodified STFM can be selected.</p>
1774: <p><em>Note:</em> This option is critical and you are strongly advised
1775: to reset the emulated ST
1.1 root 1776: when changing this option.</p>
1.1.1.2 root 1777: <p>Here you will find the options to save memory snapshots as well.</p>
1.1.1.3 root 1778: <p>Click on <span class="button">Save</span> to save a memory snapshot
1779: to file. You can select a new filename here.</p>
1780: <p>Click on <span class="button">Restore</span> to restore a memory
1781: snapshot from a file. Use the fileselector to select the snapshot to be
1782: restored.</p>
1783: <p><em>NOTE:</em> Memory snapshots are not interchangeable between
1784: different versions of Hatari. E.q. if you compile a newer Hatari, you
1785: cannot load your old memory snapshots back.</p>
1786:
1.1.1.5 root 1787:
1.1.1.8 root 1788: <a name="The ROM Dialog"></a><h4 class="gui">The ROM Dialog</h4>
1789:
1790: <div class="floatimage">
1791: <img src="images/tos.png" width="519" height="367" alt="Hatari's GUI - the ROM dialog">
1.1.1.5 root 1792: </div>
1793:
1.1.1.3 root 1794: <p>Here you can select the TOS image to use. Click on <span
1.1.1.5 root 1795: class="button">Browse</span> to select it via the fileselector.
1.1.1.3 root 1796: You can also select an optional cartridge image to use. Click on <span
1.1.1.4 root 1797: class="button">Browse</span> to select one via the fileselector. Click on <span
1.1.1.5 root 1798: class="button">Eject</span> to disconnect the custom cartridge image.
1799: </p>
1.1.1.7 root 1800: <p>
1801: For ST mode, use TOS 1.00, 1.02, 1.04 or 2.06.
1802: For STE mode, use TOS 1.06, 1.62, 2.05 or 2.06.
1803: If you want to use the TT mode, you must specify a TOS 3.06 image here.
1804: And in Falcon mode, you have to use either TOS 4.00, 4.02, 4.04 or 4.92.
1805: However, you should always use TOS 4.04 for Falcon mode, it's the most common one.
1806: Also note that TOS 4.92 can not be booted from a boot disk (like it's done on a
1807: real Falcon), you have to specify it directly in the TOS ROM setup dialog here.
1808: </p>
1809: <p>
1810: Keep in mind that any custom cartridge image will not work together with
1.1.1.5 root 1811: GEMDOS hard disk emulation or the VDI extended resolution emulation
1.1.1.3 root 1812: since some additional driver code will be used in the cartridge memory
1.1.1.7 root 1813: space for these emulations.
1814: </p>
1815: <p>
1816: <em>Note:</em> These options are critical and you are strongly
1.1.1.3 root 1817: advised to reset the emulated ST
1.1.1.7 root 1818: when changing one of these option.
1819: </p>
1.1.1.5 root 1820:
1.1.1.8 root 1821:
1822: <a name="The Joystick Dialog"></a><h4 class="gui">The Joystick Dialog</h4>
1.1.1.5 root 1823:
1824: <div class="floatimage">
1825: <img src="images/joystick.png" width="320" height="288" alt="Hatari's GUI - the joystick dialog">
1826: </div>
1827:
1828: <p>In this dialog, you can configure the emulated joysticks.
1829: With the upper two arrows, you can choose the joystick which you want to
1830: configure.</p>
1.1.1.3 root 1831: <p>Joystick 1 is the normal ST joystick port and 99.9% of all ST games
1.1.1.5 root 1832: use this port.
1833: Joystick 0 emulates a joystick plugged into the ST mouse port
1834: and is often used in games for two players.</p>
1835: <p>With STE joypad A and B, you can enable the emulation of Jaguar joypads
1836: which are plugged in the enhanced joystick ports of the Atari STE.
1837: Only very few STE games support these joypads, so you often won't need this.</p>
1838: <p>Finally, Hatari also emulates joysticks which were plugged on the parallel
1839: port with a special adapter on a real ST. These were used in some few
1.1.1.12! root 1840: multi-player games like "Gauntlet 2".</p>
1.1.1.5 root 1841: <p>For each ST joystick, choose whether you want to disable it,
1842: use the keyboard for emulation or use a real PC joystick.</p>
1843: <p>For keyboard emulation, you can select the keys by pressing the
1.1.1.10 root 1844: <span class="button">Define keys</span> button. You will be prompted to press
1.1.1.5 root 1845: the keys for up, down, left, right and fire.</p>
1846: <p>If you want to use a real PC joystick for the emulation, you should connect
1847: it to your PC before you start Hatari. Then you can choose the joystick with
1848: the two lower arrows.</p>
1.1.1.12! root 1849: <p>Check the "Enable autofire" option if you are too lazy to pound
1.1.1.5 root 1850: on the fire button in shoot'em-up games. However, this option only works with
1851: certain games. In some other games, it gets worse if you enable this option.</p>
1852: <p>See also the chapter "Emulated Joystick" for details.</p>
1853:
1.1.1.8 root 1854:
1.1.1.12! root 1855: <a name="The Atari Monitor Dialog"></a><h4 class="gui">The Atari Monitor Dialog</h4>
1.1.1.5 root 1856:
1.1.1.7 root 1857: <div class="floatimage">
1.1.1.12! root 1858: <img src="images/monitor.png" width="340" height="304" alt="Hatari's
! 1859: GUI - the Atari monitor dialog">
1.1.1.5 root 1860: </div>
1.1 root 1861:
1.1.1.7 root 1862: <p>
1863: Here you control the video output of the emulated Atari.
1864: </p>
1865: <p>
1.1.1.12! root 1866: You can select which sort of monitor to use. This option depends on
! 1867: the machine type which you have selected in the "System options"
! 1868: dialog. In ST and STE mode, you can choose between monochrome mode
! 1869: (select "Mono") and color mode (select one of the other monitor types).
! 1870: Note that when you select "TV" and use zoomed low resolution or
! 1871: switch to ST medium resolution, you will get a TV-like screen rendering
! 1872: which is a little bit faster but darker compared to the normal "RGB"
! 1873: monitor mode. Switching between mono and a color monitor acts like a monitor
! 1874: switch on a real ST - so beware, this will reboot your emulated system!<br>
! 1875: In TT mode, you can only choose between TT-high resolution ("Mono")
! 1876: and normal modes (select one of the other monitor types).
! 1877: Finally the Falcon mode supports all four types of monitors. Note that most
! 1878: Falcon demos/games require a RGB or TV mode and do not work with VGA.
1.1.1.7 root 1879: </p>
1880: <p>
1.1.1.12! root 1881: "Show ST/STE borders" toggles the displaying of the borders around the ST /
! 1882: STE screen. Some demos and games use the screen borders for displaying
! 1883: additional graphics. As enabling this option increases CPU computing time,
! 1884: don't enable it if you have a very slow computer.
! 1885: This option affects only the ST and STE modes, TT and Falcon modes are
! 1886: always displayed without borders.
1.1.1.7 root 1887: </p>
1888: <p>
1.1.1.12! root 1889: Extended VDI resolutions will emulate a sort of extended graphics
! 1890: card in the emulated ST which give you larger resolutions with a higher
! 1891: colordepth for GEM. Select a resolution and color depth. Check to
! 1892: activate. It will disable all other video options mentioned above.
! 1893: Uncheck to get back to a normal ST behaviour.<br>
! 1894: <em>Note:</em> Using an extended resolution will only work with GEM
! 1895: conformant applications. 99% of all games and demos will not run if you
! 1896: activate any extended resolution here.
1.1.1.7 root 1897: </p>
1.1.1.12! root 1898:
! 1899:
! 1900: <a name="The Hatari Screen Dialog"></a><h4 class="gui">The Hatari
! 1901: Screen Dialog</h4>
! 1902:
! 1903: <div class="floatimage">
! 1904: <img src="images/screen.png" width="350" height="336" alt="Hatari's
! 1905: GUI - the Hatari screen dialog">
! 1906: </div>
! 1907:
1.1.1.7 root 1908: <p>
1.1.1.12! root 1909: Here you control how the video output of the emulated Atari appears
! 1910: on your screen.
! 1911: </p>
! 1912:
! 1913: <p>
! 1914: Check "Fullscreen" to run Hatari in fullscreen. By default Hatari
! 1915: runs in windowed mode.
1.1.1.7 root 1916: </p>
1917: <p>
1.1.1.12! root 1918: The "Frame Skip" option can be used to speed up the emulator
1.1.1.8 root 1919: if it is running too slow on your system. Disable frame-skip if you have
1920: a fast computer. When selecting 1, 2 or 4, drawing of corresponding number
1921: of frames will be skipped after each frame actually shown by Hatari.
1.1.1.12! root 1922: Select "Auto" to let the emulator to decide whether, and
1.1.1.8 root 1923: how many frames will be skipped.<br>
1924: <em>Note:</em> The frameskip option also affects the frame rate of the
1925: screen animation recording!
1.1.1.7 root 1926: </p>
1927: <p>
1.1.1.12! root 1928: "Statusbar" toggles the statusbar at the bottom of the screen.
! 1929: The statusbar shows the floppy drive LEDs, the current frameskip value,
! 1930: the machine type including TOS version and memory size, and whether
! 1931: recording is currently active.
1.1.1.7 root 1932: </p>
1933: <p>
1.1.1.12! root 1934: "Max zoomed" option controls up to which size Hatari tries to scale
! 1935: the Atari resolutions and how much of the borders (enabled in Atari
! 1936: Monitor dialog) will be shown. There are several limitations in
! 1937: this:
1.1.1.7 root 1938: </p>
1.1.1.12! root 1939: <ul>
! 1940: <li>VDI resolutions (selectable in Atari Monitor dialog) aren't scaled.</li>
! 1941: <li>ST and STE video emulation supports only doubling of the ST-low
! 1942: resolution.</li>
! 1943: <li>Hatari doesn't support downscaling. If the original Atari resolution
! 1944: is larger (for example TT-high), the Hatari screen size will also be
! 1945: larger than requested.</li>
! 1946: <li>TT and Falcon resolutions support only <em>integer</em> scaling ratios.
! 1947: If the scaling ratio cannot match the requested size exactly, Hatari
! 1948: will use a ratio that will produce smaller size closest to the
! 1949: requested one.</li>
! 1950: </ul>
! 1951: <p>
! 1952: You should set these values to a size that suits best your monitor
! 1953: resolution. It's intended to help in getting Hatari to best use your
! 1954: monitor space on a windowed mode and in fullscreen avoiding "fuzzy"
! 1955: scaling either by Hatari or your LCD monitor.
! 1956: </p>
! 1957: <p>
! 1958: Giving "-z 2" option on command line will reset max zoomed size to
! 1959: default values and "-z 1" will disable all zooming.
! 1960: Note that zooming takes additional CPU computing time and should
! 1961: not be enabled on very slow computers.
! 1962: </p>
! 1963: <p>Click the <span class="button">Screenshot</span> button to create
! 1964: a screenshot in PNG (or BMP) format to the current working directory
! 1965: or click the <span class="button">Record AVI</span> button to
! 1966: record an AVI format video of Hatari screen (and audio) output. You
! 1967: can opt to record new movie frames only when the screen content really
! 1968: changed.
1.1 root 1969: </p>
1.1.1.5 root 1970:
1.1.1.8 root 1971:
1972: <a name="The Keyboard Dialog"></a><h4 class="gui">The Keyboard Dialog</h4>
1.1.1.5 root 1973:
1974: <div class="floatimage">
1.1.1.8 root 1975: <img src="images/keyboard.png" width="459" height="223" alt="Hatari's GUI - the keyboard dialog">
1.1.1.5 root 1976: </div>
1977:
1978: <p>Here you can select the keyboard mapping to use. Two different mappings
1.1.1.12! root 1979: called "Symbolic" and "Scancode" are predefined.</p>
! 1980: <p>"Symbolic" tries to map the symbolic values of your PC keys
1.1.1.5 root 1981: to the ST keys. It should be working pretty good on all systems as long
1982: as your keyboard layout looks close to the standard english keyboard
1983: layout. However, you might experience some problems with special keys like
1984: brackets etc.</p>
1.1.1.12! root 1985: <p>"Scancode" uses the scancode values of your PC keys for keyboard
1.1.1.5 root 1986: mapping. This only works on certain architectures like Linux where the
1987: scancodes are similar to the ST scancodes (e.g. it does not work on Mac OS X).
1988: If it works on your system, this often gives better results than the symbolic
1989: mapping. Note that you also need a TOS version with the right language
1990: (e.g. use a French TOS if you are using a French keyboard).</p>
1991: <p>You can also load a custom keyboard mapping file here if you wish. Please
1.1.1.12! root 1992: note that the custom keyboard mapping will use the "symbolic"
1.1.1.6 root 1993: mapping for all keys that are not defined by your map file. Have a look
1994: at the supplied example mapfile (keymap-sample.txt) to see how to create
1995: your own keyboard mapping.</p>
1.1.1.8 root 1996: <p>
1997: When the emulator runs in fast forward mode, and you want to type text,
1998: it can be annoying that the emulated system detects multiple key events
1999: due to the key repetition of the emulated system. To avoid this you can
2000: disable the key repetition in fast forward mode here.
2001: </p>
1.1.1.5 root 2002:
2003:
1.1.1.8 root 2004: <a name="The Sound Dialog"></a><h4 class="gui">The Sound Dialog</h4>
2005:
2006: <div class="floatimage">
1.1.1.10 root 2007: <img src="images/sound.png" width="380" height="384" alt="Hatari's GUI - the sound dialog">
1.1.1.5 root 2008: </div>
2009:
1.1.1.2 root 2010: <p>Here you can control the sound subsystem.</p>
1.1.1.3 root 2011: <p>Check if you want emulated sound at all. Emulation is faster if
2012: sound emulation is turned off.</p>
1.1.1.10 root 2013: <p>
2014: Nine frequencies from low to high quality are available. Experiment a
2015: little bit to find out which fits best for your setup.
2016: For most modern computers, 44100 Hz or 48000 Hz should be fine.
2017: For older or slower host systems, you should use a lower frequency.
2018: 12517, 250033 and 50066 Hz are frequencies supported by
2019: the STE/TT/Falcon sound DMA.
2020: </p>
2021: <p>
2022: You can select to record a piece of sound here.
2023: Use the <span class="button">Browse</span> button to choose a file.
2024: The file name extension that you use (.WAV or .YM) determines in which format
2025: the sound is recorded in. The <span class="button">Record sound</span> button
2026: is a toggle so you will need to return to the GUI to switch sound recording off
2027: again (or to use the keyboard shortcut for that).
2028: </p>
1.1.1.5 root 2029:
2030:
1.1.1.8 root 2031: <a name="The Devices Dialog"></a><h4 class="gui">The Devices Dialog</h4>
1.1.1.5 root 2032:
1.1.1.8 root 2033: <div class="floatimage">
1.1.1.10 root 2034: <img src="images/devices.png" width="520" height="383" alt="Hatari's GUI - the device dialog">
1.1.1.5 root 2035: </div>
2036:
1.1.1.10 root 2037: <p>Check the first checkmark to enable experimental printer support.
2038: See the <a href="#Emulated printer">Emulated printer</a> section for
2039: details.</p>
1.1.1.8 root 2040:
1.1.1.3 root 2041: <p>As Hatari currently only supports printing to file, click on <span
1.1.1.10 root 2042: class="button">Browse</span> to select the file to print to. You can
1.1.1.3 root 2043: enter a new filename as well.</p>
1.1.1.10 root 2044: <p>Check the second checkmark to enable experimental RS232 support.
2045: The RS232 device is configured according to the settings of
1.1.1.3 root 2046: the emulated RS232 of the Atari ST. This means Hatari will
2047: automatically use baudrate and handshaking as configured for the
2048: emulated ST.</p>
1.1.1.10 root 2049: <p>Click on <span class="button">Browse</span> to select suitable
2050: device files for serial input and output. On Linux a good choice is
2051: /dev/ttyS0 or /dev/ttyS1.
2052: </p>
2053: <p>Check the third checkmark to enable experimental MIDI support.
2054: Click on <span class="button">Browse</span> to select a suitable
2055: MIDI device files for MIDI input and output.</p>
2056: <p><span class="file">midi-linux.txt</span> file explains how to
1.1.1.12! root 2057: select the correct MIDI device file, how to set up software sound
! 2058: synthetizing on Linux (using Alsa) if your sound card/driver doesn't
! 2059: support MIDI, and how to set up MIDI networking e.g. between multiple
1.1.1.10 root 2060: Hatari instances.
1.1.1.2 root 2061: </p>
1.1.1.5 root 2062:
1.1.1.8 root 2063:
2064: <a name="Keyboard shortcuts"></a><h3 style="clear:both;">Keyboard shortcuts</h3>
1.1.1.5 root 2065:
1.1 root 2066: <p> While the emulator is running, you can activate or toggle various
1.1.1.6 root 2067: features via Hatari keyboard shortcuts. Below are listed the default
2068: shortcut key bindings:</p>
1.1.1.3 root 2069: <table border="1" cellpadding="3">
1.1 root 2070: <tbody>
2071: <tr class="backdropped">
2072: <td align="center">Shortcut</td>
2073: <td align="center">Purpose</td>
2074: </tr>
2075: <tr>
1.1.1.2 root 2076: <td align="center"><span class="key">ALTGR+a</span></td>
2077: <td align="center">record animation</td>
2078: </tr>
2079: <tr>
1.1 root 2080: <td align="center"><span class="key">ALTGR+g</span></td>
1.1.1.8 root 2081: <td align="center">grab a screenshot</td>
1.1 root 2082: </tr>
2083: <tr>
1.1.1.2 root 2084: <td align="center"><span class="key">ALTGR+i</span></td>
1.1.1.8 root 2085: <td align="center">boss key: leave full screen mode, pause Hatari
2086: and iconify its window</td>
1.1.1.2 root 2087: </tr>
2088: <tr>
1.1 root 2089: <td align="center"><span class="key">ALTGR+j</span></td>
1.1.1.8 root 2090: <td align="center">toggle joystick emulation via cursor keys
2091: on/off between ports 0 and 1</td>
1.1 root 2092: </tr>
2093: <tr>
2094: <td align="center"><span class="key">ALTGR+m</span></td>
1.1.1.8 root 2095: <td align="center">(un-)lock the mouse into the window</td>
1.1 root 2096: </tr>
2097: <tr>
2098: <td align="center"><span class="key">ALTGR+r</span></td>
1.1.1.2 root 2099: <td align="center">(warm) reset the ST</td>
1.1 root 2100: </tr>
2101: <tr>
2102: <td align="center"><span class="key">ALTGR+c</span></td>
1.1.1.3 root 2103: <td align="center">coldreset the ST (same as the original power
2104: switch)</td>
1.1 root 2105: </tr>
2106: <tr>
1.1.1.8 root 2107: <td align="center"><span class="key">ALTGR+d</span></td>
2108: <td align="center">open dialog to select/change disk A</td>
2109: </tr>
2110: <tr>
1.1.1.2 root 2111: <td align="center"><span class="key">ALTGR+s</span></td>
2112: <td align="center">enable/disable sound</td>
2113: </tr>
2114: <tr>
1.1 root 2115: <td align="center"><span class="key">ALTGR+q</span></td>
2116: <td align="center">quit the emulator</td>
2117: </tr>
2118: <tr>
1.1.1.2 root 2119: <td align="center"><span class="key">ALTGR+x</span></td>
1.1.1.10 root 2120: <td align="center">toggle normal speed/fast forward</td>
1.1.1.2 root 2121: </tr>
2122: <tr>
2123: <td align="center"><span class="key">ALTGR+y</span></td>
2124: <td align="center">enable/disable sound recording</td>
2125: </tr>
2126: <tr>
1.1.1.7 root 2127: <td align="center"><span class="key">ALTGR+k</span></td>
2128: <td align="center">save memory snapshot</td>
2129: </tr>
2130: <tr>
2131: <td align="center"><span class="key">ALTGR+l</span></td>
2132: <td align="center">load memory snapshot</td>
2133: </tr>
2134: <tr>
1.1.1.5 root 2135: <td align="center"><span class="key">ALTGR+f or F11</span></td>
1.1.1.8 root 2136: <td align="center">toggle between fullscreen and windowed mode</td>
1.1 root 2137: </tr>
2138: <tr>
1.1.1.5 root 2139: <td align="center"><span class="key">ALTGR+o or F12</span></td>
1.1.1.8 root 2140: <td align="center">activate the options GUI</td>
1.1 root 2141: </tr>
2142: <tr>
2143: <td align="center"><span class="key">PAUSE</span></td>
1.1.1.10 root 2144: <td align="center">pause emulation</td>
2145: </tr>
2146: <tr>
2147: <td align="center"><span class="key">AltGr+PAUSE</span></td>
2148: <td align="center">invoke the internal Hatari debugger</td>
1.1 root 2149: </tr>
2150: </tbody>
2151: </table>
1.1.1.5 root 2152:
1.1.1.6 root 2153: <p>You can change the key bindings from the Hatari configuration file.
1.1.1.10 root 2154: The required key values can be seen in the SDL_keysym.h include file
1.1.1.8 root 2155: (usually in /usr/include/SDL/).</p>
1.1.1.6 root 2156:
2157:
1.1.1.5 root 2158: <a name="Emulated Atari ST keyboard"></a><h3>Emulated Atari ST keyboard</h3>
2159:
1.1 root 2160: <p> All other keys on the keyboard act as the normal Atari ST keys so
2161: pressing SPACE on your PC will result in an emulated press of the SPACE
2162: key on the ST. The following keys have special meanings: </p>
1.1.1.3 root 2163: <table border="1" cellpadding="3">
1.1 root 2164: <tbody>
2165: <tr class="backdropped">
2166: <td align="center">Key</td>
2167: <td align="center">Meaning</td>
2168: </tr>
2169: <tr>
2170: <td align="center"><span class="key">Alt</span></td>
2171: <td align="center">will act as the ST's ALTERNATE key</td>
2172: </tr>
2173: <tr>
2174: <td align="center"><span class="key">left CTRL</span></td>
2175: <td align="center">will act as the ST's CONTROL key</td>
2176: </tr>
2177: <tr>
1.1.1.2 root 2178: <td align="center"><span class="key">Print Screen</span></td>
1.1 root 2179: <td align="center">will emulate the ST's HELP key</td>
2180: </tr>
2181: <tr>
1.1.1.2 root 2182: <td align="center"><span class="key">Scroll Lock</span></td>
1.1 root 2183: <td align="center">will emulate the ST's UNDO key</td>
2184: </tr>
1.1.1.2 root 2185: <tr>
2186: <td align="center"><span class="key">Page Up</span></td>
2187: <td align="center">will emulate the ST's ( key in the keypad</td>
2188: </tr>
2189: <tr>
2190: <td align="center"><span class="key">Page Down</span></td>
2191: <td align="center">will emulate the ST's ) in the keypad</td>
2192: </tr>
1.1 root 2193: </tbody>
2194: </table>
1.1.1.5 root 2195:
1.1.1.8 root 2196: <p>If joystick emulation via keyboard is enabled, by default cursor keys
2197: are used for the directions and <span class="key">right CTRL</span> key
2198: as the fire button. Otherwise they act as corresponding keys of the emulated
2199: Atari ST.</p>
2200:
1.1.1.12! root 2201: <p>NOTE: Problems with simultenous keypresses most likely aren't an
! 2202: issue in Hatari as many modern keyboards report/support only three
! 2203: simultenous key presses (or even just two depending on which keys
! 2204: are in question). Expensive gaming keyboards support more.</p>
! 2205:
1.1.1.5 root 2206:
2207: <a name="Emulated mouse"></a><h3>Emulated mouse</h3>
2208:
1.1 root 2209: <p>For obvious reasons your PC mouse will act as the emulated Atari ST
2210: mouse. In fullscreen mode it will act as expected, directly controlling
2211: the ST mouse pointer. </p>
2212: <p>However it is a little bit different in windowed mode. To make the
2213: mouse work there as expected you need to grab it first or lock it into
1.1.1.3 root 2214: the Hatari window. Do this by pressing the <span class="key">ALTGR+m</span>
1.1.1.10 root 2215: hotkey combination or starting Hatari with the
2216: <span class="commandline">--grab</span> command line option.
2217: Press the shortcut key (again) to go back to normal mouse behaviour
2218: which allows you to move mouse outside outside the Hatari window while
2219: Hatari is up and running. Note: pausing the emulation will also
2220: (temporarily) release the mouse grab.</p>
1.1.1.6 root 2221: <p>Mouse scrollwheel will act as cursor up and down keys. </p>
1.1.1.5 root 2222:
2223: <a name="Emulated joystick"></a><h3>Emulated joystick</h3>
2224:
1.1 root 2225: <p>The Atari ST joysticks are emulated ofcourse allowing you to play
2226: your favourite games with Hatari. </p>
2227: <p>The default mode is to use a connected PC joystick. You can use any
2228: joystick that is supported by your kernel. If your joystick works with
2229: other applications, it will likely work with Hatari as well. Make sure
2230: it is calibrated and then off you go. Move the stick to point into the
2231: desired direction. Please note that Hatari will not detect analogue
2232: movement as the Atari ST only had digital joysticks. The first
1.1.1.3 root 2233: firebutton will act as the normal firebutton on the Atari ST while the
2234: second
2235: firebutton will emulate a keypress of the <span class="key">SPACE</span>
2236: key on the ST as many ST
1.1.1.8 root 2237: games utilize the SPACE bar for secondary game functions. (Xenon for
1.1.1.3 root 2238: example)</p>
1.1 root 2239: <p>If you do not have a PC joystick or joypad, then you do not need to
2240: desperate. You can emulate one of the two Atari ST joysticks via the
2241: cursor keys. Just activate it in the GUI. Then the cursor keys will act
2242: as the joystick directions, the right CTRL key will act as the
2243: firebutton. You can still use the cursor keys as the ST's
1.1.1.3 root 2244: cursorkeys in this mode as long as you press <span class="key">SHIFT</span>
1.1.1.8 root 2245: along with the cursorkeys. You can also configure these keys from the
2246: joystick options.</p>
1.1.1.5 root 2247:
2248: <a name="Emulated video"></a><h3>Emulated video</h3>
2249:
1.1.1.8 root 2250: <p>Hatari emulates all screen modes of the original machine.</p>
2251: <p>
2252: ST/STE shifter overscan effects are emulated, but due to the fact
2253: that these effects are achieved by using quirks and glitches in the
2254: original chips to do things beyond their specification, emulation is
2255: a bit tricky for these effects. As a result, some demos using these
2256: techniques might not be displayed correctly in Hatari, known ones are
2257: listed in the <span class="file">compatibility.html</span> file.
1.1.1.3 root 2258: </p>
2259: <p>Beside that you can setup extended VDI modes. These only work with
2260: GEM-compliant applications and they are equal to fitting a videocard
2261: into your Mega ST.</p>
2262: <p>Make sure to disable extended VDI modes for playing games as 99% of
2263: all ST games will not be able to make use of higher resolutions.</p>
1.1.1.5 root 2264:
2265: <a name="Emulated printer"></a><h3>Emulated printer</h3>
2266:
1.1.1.3 root 2267: <p>Due to the fact that printer handling is very different between Unix
2268: style machines and the Atari ST, emulation
1.1.1.2 root 2269: of the printer is achieved by writing all printer output to a file.</p>
1.1.1.3 root 2270: <p>The file will contain a sequence of data, the same that would appear
2271: on the data pins of the Atari ST printer port.
2272: That would include control characters and commands for graphic
2273: printing. Clicking "Print desktop" on the GEM desktop would result
1.1.1.2 root 2274: in a messy data dump in the printer output.</p>
1.1.1.3 root 2275: <p>Printer emulation works best for plain text files or programs that
2276: do not format the output for a specific printer.
2277: The file contents can be used with your favourite text editor for
2278: further processing and printing to a real printer.</p>
2279: <p>To get real direct printing out of Hatari on a PostScript printer,
2280: you may set up a GDOS printer with a PostScript driver on the emulated
2281: Atari and set your printer device file as Hatari's printer output.<br>
2282: <em>NOTE:</em> This has not been tested yet and the Hatari team cannot
2283: guarantee that it will work.</p>
1.1.1.5 root 2284:
2285: <a name="Emulated RS232"></a><h3>Emulated RS232</h3>
2286:
1.1.1.3 root 2287: <p>Serial communications in Hatari is designed to directly use a serial
2288: port on your PC.</p>
2289: <p>Communications parameters are set automatically upon the settings of
2290: the emulated ST. This means all you do is to set
2291: the communication parameters like baudrate from your ST communications
2292: software. Hatari will do the rest and handle
1.1.1.2 root 2293: the serial input and output for you.</p>
1.1.1.5 root 2294:
2295: <a name="Floppy disk images"></a><h2>Floppy disk images</h2>
2296:
1.1 root 2297: <p>Hatari does not use floppy disks directly but disk images due to
2298: differences between the floppy disk controllers of the ST and the PC.
1.1.1.3 root 2299: Three types of disk images are currently supported: The raw "ST" type,
2300: the similar "DIM" type and
1.1.1.2 root 2301: the compressed "MSA" (Magic-Shadow-Archiver) type. </p>
1.1 root 2302: <p> The raw type (file suffix should be "*.st") is simply a sector by
2303: sector image of a real floppy disk. You can easily create such an image
1.1.1.3 root 2304: with the <span class="commandline">dd</span> program which should
2305: normally be pre-installed on every
2306: Unix-like system. Simply type something like <span class="commandline">dd
2307: if=/dev/fd0 of=myimage.st</span> to create a disk image. Of course you
2308: need access to
1.1 root 2309: /dev/fd0, and depending on your system and the type of floppy disk you
2310: might have to use another device name here (for example I use
1.1.1.3 root 2311: /dev/fd0u720 for 720kB disks). However, if the disk is copy-protected
2312: or
1.1 root 2313: doesn't use a MSDOS compatible file system, this might fail. So be very
1.1.1.10 root 2314: careful if you are not sure about the disk format. </p>
1.1.1.3 root 2315: <p> The other possibility is to image the disk on a real Atari ST.
2316: There
1.1 root 2317: are programs like the Magic Shadow Archiver for this task. Hatari
1.1.1.3 root 2318: supports this slightly compressed MSA disk images, too. Note that
2319: Hatari
2320: only supports the "old" MSA format, there are some Magic Shadow
2321: Archiver
1.1 root 2322: clones (like Jay-MSA) that create better compressed but
1.1.1.2 root 2323: Hatari-incompatible disk images. However, if you have got such a MSA
1.1.1.3 root 2324: disk and want to use it with Hatari, you can still run the
2325: corresponding
1.1.1.2 root 2326: MSA program within Hatari to extract the incompatible disk image to a
2327: normal floppy disk image. </p>
1.1 root 2328: <p> While *.ST and *.MSA are more or less the "standard" types of Atari
1.1.1.2 root 2329: disk images, you might sometimes also find STT or ADF images on the
1.1.1.3 root 2330: internet. These currently do not work with Hatari. </p>
2331: <p>Hatari can now also utilize *.DIM images just as *.ST ones without
2332: any problems.
1.1.1.2 root 2333: Note that DIM images are nearly the same as the raw ST images
1.1.1.3 root 2334: (they only have an additional 32 bytes header), so you can easily
2335: transform
1.1.1.2 root 2336: the DIM images into ST images by stripping the header from the files.
2337: For example try something like:
2338: <span class="commandline">dd if=input.dim of=output.st bs=32 skip=1</span>
2339: </p>
1.1 root 2340: <p> If you've got a disk image that has been created with the old ST
2341: emulator PaCifiST (for DOS) or with early versions of the program
2342: Makedisk, and the disk image does not work with Hatari, then the disk
1.1.1.3 root 2343: probably suffers from the "PaCifiST bootsector bug" (Hatari will
2344: display a
1.1 root 2345: warning message then). In this case, the bootsector of the disk
2346: contains some illegal data, so that the disk even does not work on a
2347: real ST any more. However, if it is a .ST and not a .MSA disk, you can
1.1.1.3 root 2348: easily fix it by using a hex-editor to change the byte at offset $D
2349: (13)
1.1 root 2350: from 0 to 1 (don't forget to backup your disk image first, since you
2351: can also easily destroy your disk image when changing a wrong byte
2352: there). If the disk contains a bootsector program, you probably have to
2353: adjust the boot sector check sum, too (it can be found at offset $1FE +
2354: $1FF). </p>
1.1.1.2 root 2355: <p>Hatari supports disk images that are compressed with (Pk-)ZIP
2356: (file suffix must be ".zip") or GZip (file suffix must be ".st.gz" or
1.1.1.3 root 2357: ".msa.gz"), so you can archive your disk images into zip archives.
1.1.1.2 root 2358: You can also directly run the zip archives you may download from the
2359: net as long as the archive contains a disk image in .ST or .MSA format.</p>
1.1.1.3 root 2360: <p><em>Note:</em> Hatari does not save disk images back to *.ZIP files
2361: so
1.1.1.2 root 2362: your highscores and savegames are lost if you load the game from such
2363: a zipped disk image.</p>
1.1.1.5 root 2364:
1.1.1.10 root 2365:
1.1.1.5 root 2366: <a name="Hard disk support"></a><h2>Hard disk support</h2>
2367:
1.1.1.8 root 2368: <p>
1.1.1.10 root 2369: Hatari supports three ways of emulating Atari hard drives: The low-level
2370: ACSI and IDE hard disk emulation and a GEMDOS based drive emulation.
2371: In most cases the GEMDOS based hard disk emulation is best as it allows
2372: exchanging files easily between the emulated and the host environment.
2373: </p>
2374: <p>
2375: Please note that changing the HD-image or the GEMDOS HD-folder will reset
1.1.1.8 root 2376: the emulated Atari since it is not possible to switch the hard disk
2377: while the emulator is running.
2378: </p>
1.1.1.12! root 2379: <p>
! 2380: On a 32-bit host system, the size of a hard disk image is limited to 2 GB.
! 2381: On 64-bit host systems, bigger images might be possible but the support for
! 2382: bigger images is not tested very well yet.
! 2383: </p>
1.1.1.6 root 2384:
2385:
2386: <a name="GEMDOS based hard disk emulation"></a><h3>GEMDOS based hard disk emulation</h3>
1.1.1.12! root 2387: <p>
! 2388: With the GEMDOS based drive emulation, you can easily "mount" a
1.1 root 2389: folder from the host file system to a drive of the emulated Atari. To
2390: use the GEMDOS based drive emulation, you should use a folder on your
1.1.1.3 root 2391: hard disk that only contains files and folders with valid TOS
1.1.1.12! root 2392: filenames i.e. file and folders names shouldn't contain invalid GEMDOS
! 2393: filename characters and their length shouldn't exceed the 8+3 file name
! 2394: length limit.
! 2395: </p>
! 2396: <p>
! 2397: If you provide <span class="commandline">--harddisk</span> option
! 2398: a directory containing only single letter subdirectories, each of
! 2399: these subdirectories will be treated as a separate partition, otherwise
! 2400: the given directory itself will be assigned to drive "C:". In the
! 2401: multiple partition case, the letters used as the subdirectory names
! 2402: will determine to which drives/partitions they're assigned.
! 2403: </p>
! 2404: <p>
! 2405: GEMDOS drive emulation is an easy way to share files between the
! 2406: host system and the emulated Atari, but there are also some known
! 2407: limitations which are due to the way the GEMDOS drive emulation is
! 2408: implemented:
! 2409: </p>
! 2410: <ul>
! 2411: <li>It is not possible to use a cartridge image at the same time
! 2412: with the GEMDOS drive emulation (Hatari has it's own cartridge code
! 2413: that is used for GEMDOS emulation).</li>
! 2414: <li>As MiNT installs its own GEMDOS handler, it doesn't work with
! 2415: the GEMDOS drive emulation. MiNT needs to be booted from a real hard
! 2416: disk image.</li>
! 2417: <li>GEMDOS drive emulation conflicts with the ACSI and IDE harddisk images.
! 2418: If you want to use GEMDOS HD emulation and ACSI/IDE disk images together,
! 2419: use a multiple partition GEMDOS emulation setup and select the partition
! 2420: subdirectories (letters) so that they don't conflict with the ACSI/IDE
! 2421: drive partitions (letters). With HD Driver you have also another option,
! 2422: see <a href="#Using HD Driver with GEMDOS partitions">Using HD Driver
! 2423: with GEMDOS partitions</a>.</li>
! 2424: <li><em>The GEMDOS drive emulation does not work (very well) with TOS
! 2425: 1.00 and 1.02</em>. Use at least TOS 1.04 if you want the GEMDOS drive
! 2426: emulation to work properly.</li>
! 2427: </ul>
! 2428: <p>
! 2429: So, if your programs complain that they could not find/read/write
! 2430: files on the GEMDOS emulated drive, you should try to copy them to a
! 2431: floppy disk image or a real hard disk image!
1.1.1.6 root 2432: </p>
1.1.1.8 root 2433:
1.1.1.10 root 2434: <a name="ACSI hard disk emulation"></a><h3>ACSI hard disk emulation</h3>
2435: <p>
2436: To use the ACSI hard disk emulation, you need a hard disk image file
1.1.1.12! root 2437: with a pre-installed HD driver in it. You can try to get an image of
! 2438: your old ST hard disk or grab one from the internet (e.g. from the
! 2439: Hatari website).
! 2440: </p>
! 2441: <p>
! 2442: To create a <em>new</em> ACSI hard disk image, you can start with an empty
! 2443: image that you have created for example with the following command:
! 2444: <span class="commandline">dd if=/dev/zero of=hd.img bs=512 count=xxx</span>
! 2445: (where 'xxx' is size in 512 byte blocks). Copy the complete AHDI 5.0
! 2446: package to a floppy disk image, then boot Hatari with this floppy disk
! 2447: image and the fresh hard disk image like this:
! 2448: <span class="commandline">--acsi hd.img ahdi.st</span>.
! 2449: Then start HDX.PRG from the floppy disk and format + partition the hard
! 2450: disk image with it.
! 2451: </p>
! 2452: <p>
! 2453: Formatting and partitioning works currently only with AHDI 5, but you
! 2454: can install the AHDI 6 driver to the hard disk after it's formatted.
! 2455: Restart the emulated system, run AHDI.PRG from the floppy disk to access
! 2456: the hard disk image from the emulated Atari and then run HINSTALL.PRG.
! 2457: After installing the hard disk driver to the fresh HD image with
! 2458: HINSTALL.PRG, you can boot directly from the hard disk image.
1.1.1.10 root 2459: </p>
2460:
2461: <a name="IDE hard disk emulation"></a><h3>IDE hard disk emulation</h3>
2462: <p>
1.1.1.12! root 2463: <p>
! 2464: As the IDE disk format (little endian) differs from the ACSI disk format
! 2465: (big endian), you need separate disk images for them. Hatari doesn't
! 2466: currently support formatting IDE disks with AHDI, but you can do it with
! 2467: <em>Cecile</em>.
! 2468: </p>
! 2469: <p>
! 2470: First create an empty image file with the size of your choice with:
1.1.1.10 root 2471: <span class="commandline">dd if=/dev/zero of=hd.img bs=1k count=xxx</span>.
2472: Then get the Cecile hard disk driver from
2473: <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 2474: and put it on a floppy disk image (e.g. to one named "cecile.st" using:
! 2475: <span class="commandline">zip2st.sh cecile.zip</span>).
1.1.1.10 root 2476: </p>
2477: <p>
2478: Run Hatari with
1.1.1.12! root 2479: <span class="commandline">hatari --machine falcon --tos tos404.rom
! 2480: --ide-master hd.img cecile.st</span>, switch to larger color resolution
! 2481: and warm up your French language skills. Then start the Cecile hard
! 2482: disk driver CECILE.PRG and run CC_TOOLS.APP to partition your hard
! 2483: disk image. Click the "Partition" button, select "Hatari IDE disk" and set
! 2484: suitable partition size with the arrows (below type field). Then click
! 2485: "Valider".
1.1.1.10 root 2486: </p>
2487: <p>
2488: If you only want to use your HD image in Falcon mode, you can install
2489: the Cecile hard disk driver to the image from the Cecile CC_TOOLS.APP:
1.1.1.12! root 2490: Click the "Installer" button and save the Cecile driver to the
1.1.1.10 root 2491: 1st partition on "Hatari IDE disk". If you want to also use your HD
2492: image in ST/STE mode, you need to get and install AHDI 6 driver on it
1.1.1.12! root 2493: instead (see <a href="ACSI hard disk emulation">ASCI hard disk
! 2494: emulation</a> section).
1.1.1.10 root 2495: </p>
2496: <p>
2497: Then you can boot from your hard disk image by simply specifying it
1.1.1.12! root 2498: with the <span class="commandline">--ide-master</span> parameter.
1.1.1.10 root 2499: </p>
2500:
2501:
1.1.1.12! root 2502: <a name="Moving files to/from hard disk images"></a><h2>Moving files
! 2503: to/from hard disk images</h2>
! 2504:
! 2505: <p>Moving files to and from Atari hard disk images can be done
! 2506: either through GEMDOS partitions (host directories mounted inside
! 2507: Hatari emulation) or accessing the images directly on the host
! 2508: (outside the emulation). Both have their own limitations.</p>
! 2509:
! 2510: <p>If it's fine for the IDE/ACSI partitions to be first, you can use
! 2511: hard disk images with AHDI or Cecile driver and a multipartition
! 2512: GEMDOS setup as described in above sections. If you want to boot from
! 2513: a GEMDOS partition i.e. such to be before hard disk image partitions,
! 2514: and still to be able to access all the IDE/ACSI partitions, you need to
! 2515: use HD Driver.</p>
! 2516:
! 2517: <a name="Using HD Driver with GEMDOS partitions"></a><h3>Using HD Driver
! 2518: with GEMDOS partitions</h3>
! 2519:
! 2520: <p>Uwe Seimet's <a href="http://www.seimet.de/atari/en/hddriver.html">HD
! 2521: Driver</a> works fine with both the Hatari GEMDOS partitions and normal
! 2522: hard disk images. However, it doesn't work with EmuTOS so you need
! 2523: real TOS (at least version v1.04).
! 2524: </p>
! 2525:
! 2526: <p>First copy the HDDRIVER.PRG binary into your GEMDOS drive emulation
! 2527: directory AUTO folder. Then start the HDDRUTIL.APP configuration utility,
! 2528: locate HDDRIVER.PRG, open the
! 2529: <a href="http://www.seimet.de/atari/en/hddriverscreenshots.html">"Devices
! 2530: and Partitions" dialog</a> and select the "Preserve Existing Partitions"
! 2531: option. Then you can just start Hatari with your hard disk image and
! 2532: this GEMDOS directory, for example like this:
! 2533: "<span class="commandline">hatari --harddisk gemdos-hd/ --ide-master
! 2534: ide-hd.image</span>".</p>
! 2535:
! 2536: <p>If you're using the <em>demo</em> version of HD Driver, you can
! 2537: write files only to the C: partition, i.e. in above case only copy
! 2538: files from the hard disk image partition to the GEMDOS partition (with
! 2539: some write slowndowns included into the demo version). If you want to
! 2540: copy files to the hard disk image with the <em>demo</em> version of
! 2541: the HD Driver, you need to set the hard disk image as drive C:.</p>
! 2542:
! 2543: <p>To accomplish this, set the GEMDOS partitions to be from D: forward,
! 2544: i.e. have a directory which contains only single letter subdirectories,
! 2545: starting from "D" like in "<span class="commandline">mkdir gemdos-hd;
! 2546: mkdir gemdos-hd/D</span>". Then give Hatari (as the last parameter)
! 2547: a boot floppy image containing the demo version of HDDRIVER.PRG in
! 2548: its AUTO folder, like this: "<span class="commandline">hatari
! 2549: --ide-master ide-hd.image --harddisk gemdos-hd/ hd-driver-floppy.st</span>".
! 2550: </p>
! 2551:
! 2552:
! 2553: <a name="Accessing HDD image partitions outside of Hatari"></a><h3>Accessing
! 2554: HDD image partitions outside of Hatari</h3>
! 2555:
1.1.1.10 root 2556: <p>
1.1.1.12! root 2557: If you want to access the harddisk image partitions also outside
! 2558: the emulation, the disk image needs to have a DOS partition table.
! 2559: The <span class="commandline">atari-hd-image</span> script included
1.1.1.10 root 2560: with Hatari can be used to create such an image.
2561: </p>
2562: <p>
2563: Inside the Hatari emulator, EmuTOS can access partition(s) on these
2564: kind of images directly without any driver software. Of the Atari HD
1.1.1.12! root 2565: drivers mentioned above, Centek's Cecile and Uwe Seimet's HD Driver
! 2566: (demo) work fine with these partitions. E.g. AHDI and CBHD don't.
1.1.1.10 root 2567: </p>
2568: <p>
1.1.1.12! root 2569: Note that plain EmuTOS supports only ACSI and the listed HD drivers
! 2570: support only IDE (emulation). Cecile needs TT or Falcon and HD Driver
! 2571: doesn't work with EmuTOS. To summarise; if ASCI emulation and
! 2572: EmuTOS are enough, use those. Otherwise, if you want to use TT or
! 2573: Falcon emulation, use Cecile (or full HD Driver version if you have
! 2574: it), otherwise use HD Driver (demo).
1.1.1.10 root 2575: </p>
2576: <p>
2577: To access the content of the partitions on Linux host, there are two
2578: possibilities:
2579:
2580: <h4>Using Mtools</h4>
2581: <p>
2582: For this you need to add an entry for the hard disk
2583: image to your <span class="commandline">~/.mtoolsrc</span> and
2584: specify which partition you want to access from the image. For
2585: an image created with the above mentioned script, the line in
2586: the configuration file should look something like this:
2587: </p>
2588: <pre>
2589: MTOOLS_NO_VFAT=1
2590: drive c: file="/home/user/hatari/hd.img" partition=1
2591: </pre>
2592: <p>
2593: Note that Mtools is instructed to use FAT compatibility mode because
2594: EmuTOS cannot deal properly with VFAT file information. If you don't
2595: want this setting for all your Mtools drives, you can set it also via
1.1.1.12! root 2596: the environment like this ("::" refers to the drive image given with
! 2597: the "-i" option):
1.1.1.10 root 2598: </p>
2599: <pre>
1.1.1.12! root 2600: MTOOLS_NO_VFAT=1 mcopy -spmv -i hd.img files/* ::
1.1.1.10 root 2601: </pre>
2602:
2603: <h4>Using a loopback device</h4>
2604: <p>
2605: This is recommended even by Mtools documentation, but it's less
2606: convenient as it requires root rights. First you need to "loop"
2607: mount the image:
2608: </p>
2609: <pre>
2610: $ su
2611: # image="hd.img"; mountdir="hd"
2612: # start=$(parted $image unit s print | awk '/ 1 /{print $2}' | tr -d s)
2613: # losetup -f $image -o $((512*$start))
2614: # loop=$(losetup -a | tail -1 | cut -d: -f1)
2615: # mkdir -p $mountdir
2616: # mount -t msdos $loop $mountdir
2617: </pre>
2618: <p>
2619: This uses <span class="commandline">parted</span> to find out the first
2620: partition offset in sectors and then tells <span class="commandline">losetup</span>
2621: to bind the first free loop device to a corresponding offset from
2622: the <span class="commandline">hd.img</span> image.
2623: <span class="commandline">mount</span> is then used to mount the file system
2624: from the loop device on top of the "hd" directory.
2625: </p>
2626: <p>
2627: After you've copied the relevant files to the "hd" directory, you need
2628: unmount the file system and remove the loop device binding before using
2629: the disk image from Hatari:
2630: </p>
2631: <pre>
2632: # umount $mountdir
2633: # losetup -d $loop
2634: </pre>
2635:
2636: <a name="The debugger"></a><h2>The debugger</h2>
2637:
2638: <p>
2639: Hatari has a built-in debugging interface which can be used for
1.1.1.12! root 2640: analyzing code that runs in the emulated system. To invoke the
! 2641: debugger, press the <span class="key">AltGr + Pause</span>
! 2642: key combination.
! 2643: </p>
1.1.1.10 root 2644:
2645: <p>
1.1.1.12! root 2646: If you start Hatari with the "-D" command line option, m68k
! 2647: exceptions will automatically invoke the debugger. You can
! 2648: toggle this also later from the debugger with the "setopt -D"
1.1.1.10 root 2649: command.
2650: </p>
2651:
2652: <p>
1.1.1.12! root 2653: The debugger uses Hatari's parent console window, so make sure you run
! 2654: Hatari from the command line when you want to use the debugger. On
! 2655: Linux you can add for example an icon to your desktop that runs: <span
! 2656: class="commandline">xterm -T "Hatari debug window" -e hatari</span>.
1.1.1.10 root 2657: </p>
2658:
1.1.1.12! root 2659:
! 2660: <a name="General debugger use"></a><h3>General debugger use</h3>
! 2661:
1.1.1.10 root 2662: <p>
1.1.1.12! root 2663: At the debugger prompt, type "help" to get a list of all
1.1.1.10 root 2664: the available commands and their shortcuts:
2665: </p>
2666: <pre>
1.1.1.12! root 2667: Generic commands:
! 2668: cd ( ) : change directory
! 2669: evaluate ( e) : evaluate an expression
! 2670: exec ( ) : execute a shell command
! 2671: help ( h) : print help
! 2672: info ( i) : show machine/OS information
! 2673: lock ( ) : lock info to show on entering debugger
! 2674: logfile ( f) : open or close log file
! 2675: parse ( p) : get debugger commands from file
! 2676: setopt ( o) : set Hatari command line and debugger options
! 2677: stateload ( ) : restore emulation state
! 2678: statesave ( ) : save emulation state
! 2679: trace ( t) : select Hatari tracing settings
! 2680: quit ( q) : quit emulator
! 2681:
! 2682: CPU commands:
! 2683: address ( a) : set CPU PC address breakpoints
! 2684: breakpoint ( b) : set/remove/list conditional CPU breakpoints
1.1.1.10 root 2685: disasm ( d) : disassemble from PC, or given address
2686: cpureg ( r) : dump register values or set register to value
2687: memdump ( m) : dump memory
2688: memwrite ( w) : write bytes to memory
2689: loadbin ( l) : load a file into memory
2690: savebin ( s) : save memory to a file
1.1.1.12! root 2691: symbols ( ) : load CPU symbols & their addresses
1.1.1.10 root 2692: cont ( c) : continue emulation / CPU single-stepping
1.1.1.12! root 2693:
! 2694: DSP commands:
! 2695: dspaddress (da) : set DSP PC address breakpoints
! 2696: dspbreak (db) : set/remove/list conditional DSP breakpoints
! 2697: dspdisasm (dd) : disassemble DSP code
! 2698: dspmemdump (dm) : dump DSP memory
! 2699: dspsymbols ( ) : load DSP symbols & their addresses
! 2700: dspreg (dr) : read/write DSP registers
! 2701: dspcont (dc) : continue emulation / DSP single-stepping
1.1.1.10 root 2702: </pre>
2703:
2704: <p>
1.1.1.12! root 2705: When entering numbers to the debugger commands in other number bases
! 2706: than the default/selected one, they need to be prefixed with a
! 2707: character indicating this. For decimals this prefix is "#" (#15),
! 2708: for hexadecimals "$" ($F), and for binary values it's "%" (%1111).
! 2709: By default the debugger expects all numbers without a prefix to be
! 2710: decimals, but you can change the default number base with the "setopt"
! 2711: command, just give it the desired default number base (bin/dec/hex).
! 2712: </p>
! 2713:
! 2714: <p>
! 2715: Instead of a number, you can also use an expression, by surrounding
! 2716: it with quotes (""). An expression can contain calculations with
! 2717: register and symbol values in addition to numbers. For example to
! 2718: give a sum of A0 and D0 register values to a command, use "a0+d0".
! 2719: </p>
! 2720:
! 2721: <p>
! 2722: <em>Note that within expressions parenthesis are used to change
! 2723: the order of precendence, they <strong>cannot</strong> be used for
! 2724: indicating indirect addressing like with conditional breakpoints
! 2725: (explained below). Even when using expressions within conditional
! 2726: breakpoints.</em>
! 2727: And when using the hexadecimal number base, remember still to prefix
! 2728: with '$' hexadesimal numbers that can be confused with register names
! 2729: (a0-7, d0-7), otherwise results from expressions and conditional
! 2730: breakpoints can be quite surprising.
! 2731: </p>
! 2732:
! 2733: <p>
! 2734: Expressions are always evaluated before being given to a command.
! 2735: Expressions don't need to be quoted for the "evaluate" or "address"
! 2736: commands as those always interpret their results as expressions.
! 2737: </p>
! 2738:
! 2739: <p>
! 2740: With command argument completion (see <a href="#Build notes">build
! 2741: notes</a>), result from last "evaluate" command can inserted by
! 2742: typing '$' and pressing TAB.
! 2743: </p>
! 2744:
! 2745:
! 2746: <a name="Inspecting emulation state"></a><h3>Inspecting emulation state</h3>
! 2747:
! 2748: <p>
! 2749: In the beginning, probably the most interesting commands are "m" and "d"
! 2750: for dumping and disassembling memory regions. You can use "dm" and "dd"
! 2751: commands to do the same for the DSP.
1.1.1.10 root 2752: </p>
2753: <pre>
2754: > help memdump
2755: 'memdump' or 'm' - dump memory
1.1.1.12! root 2756: Usage: m [start address-[end address]]
1.1.1.10 root 2757: dump memory at address or continue dump from previous address.
2758: </pre>
2759: <pre>
2760: > help disasm
2761: 'disasm' or 'd' - disassemble from PC, or given address
1.1.1.12! root 2762: Usage: d [start address-[end address]]
1.1.1.10 root 2763: If no address is given, this command disassembles from the last
1.1.1.12! root 2764: position or from current PC if no last position is available.
1.1.1.10 root 2765: </pre>
2766: <pre>
1.1.1.12! root 2767: > disasm
1.1.1.10 root 2768: 0000aa6e: 2f08 0241 0fff 207c 00fe MOVE.L A0,-(A7)
2769: 0000aa70: 0241 0fff 207c 00fe 78c0 AND.W #$0fff,D1
2770: 0000aa74: 207c 00fe 78c0 2070 1000 MOVEA.L #$00fe78c0,A0
2771: 0000aa7a: 2070 1000 4ed0 0241 0ffe MOVEA.L (A0, D1.W*1, $00) == $00fe34ae,A0
2772: 0000aa7e: 4ed0 0241 0ffe 6712 e549 JMP.L (A0)
2773: </pre>
2774:
2775: <p>
1.1.1.12! root 2776: You can use the "info" command to see state of specific sets of HW
! 2777: registers ("info videl") or Atari OS structures ("info basepage").
! 2778: </p>
! 2779:
! 2780: <p>
! 2781: By using the "lock" command, you can ask Hatari to show above kind of
! 2782: information whenever you enter the debugger ("lock disasm"). With the
! 2783: "regaddr" subcommand, it can show also disassembly or memory dump of
! 2784: an address pointed by a given register ("lock regaddr disasm a0"). Of
! 2785: the DSP registers, only Rx ones are valid for this subcommand. To
! 2786: disable showing of this extra information, use "lock default".
! 2787: </p>
! 2788:
! 2789: <a name="Debug symbols"></a><h3>Debug symbols</h3>
! 2790:
! 2791: <p>
! 2792: You can load symbol name/address information from a file to the
! 2793: debugger with the "symbols" command (and with "dspsymbols" for DSP).
! 2794: These symbolic names can be used in expressions and all breakpoints.
! 2795: They also show up in the "disasm" command output.
! 2796: </p>
! 2797:
! 2798: <p>The symbols file format is following:</p>
! 2799: <pre>
! 2800: e01034 T random
! 2801: e01076 T kbdvbase
! 2802: e0107e T supexec
! 2803: </pre>
! 2804: <p>
! 2805: Where 'T' means text (code), 'D' means data and 'B' BSS section type
! 2806: of address. The symbol hexadecimal address, type letter and name are
! 2807: separated by white space. Empty lines and lines starting with '#'
! 2808: (comments) are ignored.
! 2809: </p>
! 2810:
! 2811: <p>
! 2812: AHCC C-compiler can provide a symbol file suitable for this with its
! 2813: "-n 'nm' list" option (not enabled by default). If you're reverse
! 2814: engineering some code, you could just create your own symbols file to
! 2815: help in debugging it later.
! 2816: </p>
! 2817:
! 2818: <p>
! 2819: If you're debugging normal TOS/GEM programs instead of code loaded
! 2820: into fixed address (like EmuTOS), you can use the "info basepage"
! 2821: command to find out the text segment address to which the program code
! 2822: has been loaded into, and then load symbols so that their addresses
! 2823: are offset by the text segment address:
! 2824: </p>
! 2825: <pre>
! 2826: > info basepage
! 2827: Process basepage information:
! 2828: - TPA start : 0x01a1bc
! 2829: - TPA end +1 : 0x7da700
! 2830: - Text segment : 0x01a2bc
! 2831: - Text size : 0xe1e0
! 2832: - Data segment : 0x02849c
! 2833: - Data size : 0x1b76
! 2834: - BSS segment : 0x02a012
! 2835: - BSS size : 0x3750
! 2836: - Process DTA : 0x01a23c
! 2837: - Parent basepage: 0x00e91c
! 2838: - Environment : 0x01a1ae
! 2839: 'PATH='
! 2840: 'C:\'
! 2841: - Command argslen: 0
! 2842: > symbols calc.sym 0x01a2bc
! 2843: </pre>
! 2844:
! 2845: <a name="Breakpoints"></a><h3>Breakpoints</h3>
! 2846:
! 2847: <p>
! 2848: There are two ways to specify breakpoints for Hatari. First, there are
! 2849: the simple address breakpoints which trigger when the CPU (or DSP)
! 2850: program counter hits a given address. Use "a" (or "da" for the DSP)
! 2851: to create them, for example:
! 2852: </p>
! 2853: <pre>
! 2854: > a $e01034
! 2855: > a some_symbol
! 2856: </pre>
! 2857:
! 2858: <p>
! 2859: (Address breakpoints are just wrappers for conditional breakpoints so
! 2860: you need to use "b" command to remove or list them.)
! 2861: </p>
! 2862:
! 2863: <p>
! 2864: Then there are the conditional breakpoints which can handle much more
! 2865: complex break conditions; they can track changes to register and
! 2866: memory values with bitmasks, include multiple conditions for
! 2867: triggering a breakpoint and so on. Use "b" (or "db" for the DSP)
! 2868: to manage them. "b help" explains the syntax:
1.1.1.10 root 2869: </p>
2870:
2871: <pre>
1.1.1.12! root 2872: breakpoint = <condition> [ && <condition> ... ] [option]
! 2873: condition = <value>[.mode] [& <number>] <comparison> <value>[.mode]
1.1.1.10 root 2874:
2875: where:
1.1.1.12! root 2876: value = [(] <register/symbol/variable name | number> [)]
! 2877: number = [#|$|%]<digits>
! 2878: comparison = '<' | '>' | '=' | '!'
! 2879: addressing mode (width) = 'b' | 'w' | 'l'
! 2880: addressing mode (space) = 'p' | 'x' | 'y'
! 2881: option = : <count> | 'once' | 'trace'
1.1.1.10 root 2882: </pre>
2883:
2884: <p>
2885: If the value is in parenthesis like in '($ff820)' or '(a0)', then the
1.1.1.12! root 2886: used value will be read from the memory address pointed by it. Note
! 2887: that this value is checked at run-time whereas quoted expressions
! 2888: (mentioned above, please read!) are evaluated already when adding a
! 2889: breakpoint. For example, to break when value in adress pointed by A0
! 2890: matches the value currently in D0, one would use:
1.1.1.10 root 2891: </p>
1.1.1.12! root 2892: <pre>
! 2893: > b (a0) = "d0"
! 2894: </pre>
! 2895:
1.1.1.10 root 2896: <p>
1.1.1.12! root 2897: M68k addresses can have byte ("b"), word ("w") or long ("l", default)
! 2898: width. DSP addresses belong to different address spaces: "P", "X" or
! 2899: "Y". Note that on DSP only R0-R7 registers can be used for memory
! 2900: addressing.
1.1.1.10 root 2901: </p>
2902:
2903: <p>Examples:</p>
2904: <pre>
1.1.1.12! root 2905: b (r0).x = 1 && (r0).y = 2
! 2906: b pc = $64543 && ($ff820).w & 3 = (a0) && d0 = %1100
! 2907: </pre>
1.1.1.10 root 2908:
2909: <p>
1.1.1.12! root 2910: The debugger supports also setting conditional breakpoints on values
! 2911: of some internal Hatari variables (listed by "b help"). For example
1.1.1.10 root 2912: if you want to stop at a specific cycle within a frame (that is, PC
1.1.1.12! root 2913: relative to the current VBL/HBL in cycles), set breakpoints to
! 2914: specific "HBL" and "LineCycles" variable values. The "e" command
! 2915: can be used to calculate suitable register and variable values.
! 2916: </p>
! 2917:
! 2918: <p>
! 2919: As a convenience, if the value expressions on both sides of the
! 2920: comparison are exactly the same, right side is replaced with its
! 2921: current value. For inequality ('!') comparison, conditional breakpoint
! 2922: tracks all further changes for the given address/register expression,
! 2923: this can be used for example to find out all value changes in a given
! 2924: memory address (see examples below).
! 2925: </p>
1.1.1.10 root 2926:
2927: <p>
1.1.1.12! root 2928: There are also several options that you can use with both breakpoint
! 2929: types. ":trace" option will make breakpoint to print out the tracked
! 2930: value instead of breaking. This can be useful e.g. when tracking
! 2931: changes to some register like in:
! 2932: </p>
! 2933: <pre>
! 2934: > b ($ffff9202).w ! ($ffff9202).w :trace
! 2935: </pre>
! 2936:
! 2937: <p>
! 2938: ":once" option that removes breakpoint after hit can be useful when one
! 2939: wants to get out of a loop (when at the instruction that branches back
! 2940: to loop start) or just to get to a specific point in code:
! 2941: </p>
! 2942: <pre>
! 2943: > b pc > pc :once
! 2944: > a some_symbol :once
! 2945: </pre>
! 2946:
! 2947: <p>
! 2948: Whereas giving count (like ":2") as option will break only on every
! 2949: <count> hit.
! 2950: </p>
! 2951:
! 2952: <p>
! 2953: After analyzing and/or setting new breakpoints, you can continue the
! 2954: emulation with the "c" command. You can continue for a given number of
! 2955: CPU instructions (or DSP instructions when "dc" is used), or you can
! 2956: continue forever (until a breakpoint triggers) if you omit the
1.1.1.10 root 2957: instruction count.
2958: </p>
2959:
1.1.1.12! root 2960: <a name="Tracing"></a><h3>Tracing</h3>
! 2961:
1.1.1.10 root 2962: <p>
1.1.1.12! root 2963: If you want to continue with real-time disassembling, you can enable it
! 2964: with "trace cpu_disasm" at the debugger prompt before continuing.
! 2965: </p>
! 2966: <p>
! 2967: Disable tracing with "trace none" when you enter the debugger again.
! 2968: "trace help" (or TAB) can be used to list all the supported trace points.
! 2969: </p>
! 2970: <p>
! 2971: Because Hatari normally emulates things at the hardware level, tracing
! 2972: Atari OS functions requires setting additional Hatari options which
! 2973: tell it to intercept higher level functionality:
! 2974: <ul>
! 2975: <li>BIOS and XBIOS tracing require enabling bios intercepting</li>
! 2976: <li>GEMDOS tracing use of the GEMDOS harddisk emulation</li>
! 2977: <li>VDI tracing use of a VDI graphics mode</li>
! 2978: </ul>
! 2979: <p>
! 2980: Tracing options can be set even from a program within the emulation
! 2981: if you enable Hatari "--bios-intercept" option and call XBios 255 from
! 2982: the program with a suitable Hatari command line string.
! 2983: </p>
! 2984: <p>
! 2985: Note that the trace output file can be set only when Hatari starts,
! 2986: it cannot be changed from within the debugger (or emulation).
1.1.1.10 root 2987: </p>
2988:
1.1.1.12! root 2989: <a name="Build notes"></a><h3>Build notes</h3>
! 2990:
1.1.1.10 root 2991: <p>
2992: Lastly, the debugger is much nicer to use with the command line
1.1.1.12! root 2993: history, editing and especially with the command, command argument and
! 2994: symbol name completion support. If you're building Hatari yourself,
! 2995: please make sure that you have the GNU readline development files
! 2996: installed (on Debian / Ubuntu these come from the libreadline5-dev
! 2997: package). Otherwise this doesn't get enabled when you configure
! 2998: Hatari.
! 2999: </p>
! 3000:
! 3001: <p>
! 3002: ENABLE_TRACING define needs to be set for tracing to work.
! 3003: By default it should be enabled.
1.1.1.10 root 3004: </p>
3005:
3006:
3007: <a name="Performance"></a><h2>Performance</h2>
1.1.1.12! root 3008:
! 3009: <p>Hatari performance varies between Atari programs, depending on what
! 3010: features Hatari needs to emulate for them. Less accurate Atari
! 3011: emulators may be faster as emulation accuracy has a performance
! 3012: overhead.</p>
! 3013:
! 3014:
1.1.1.10 root 3015: <a name="Improving Hatari performance"></a><h3>Improving Hatari performance</h3>
3016:
3017: <p>
3018: Unless you've disabled compiler optimizations (like GCC's -O2 or -O3
3019: options) in the Hatari build, the extra optimization flags (like GCC's
3020: "-mtune=i686") don't seem to have very large effect on Hatari
1.1.1.12! root 3021: performance. Using GCC -O3 option instead of -O2 can give minor
! 3022: (5-10%) performance improvements for things (demos) that use very
! 3023: heavily interrupts.
1.1.1.10 root 3024: </p>
3025: <p>
3026: However, Hatari can be sped up considerably by giving up some
3027: emulation or emulator accuracy. Most of these options should
3028: be needed only on slow devices like handhelds.
3029: </p>
3030:
3031:
3032: <h4>Emulation options</h4>
3033:
3034: <p>
3035: Emulation options have the largest impact on performance.
3036: These options can be changed from the Hatari GUI System dialog and
3037: the emulation needs to be rebooted for any of these changes to take
3038: an effect!
3039: </p>
3040:
3041: <h5>DSP</h5>
3042: <p>
1.1.1.12! root 3043: Emulating the Falcon DSP is performance-wise several times more demanding
1.1.1.10 root 3044: than emulating the m68k; DSP runs at higher frequency, executes many
3045: instructions for each m68k instruction and emulation isn't as mature
3046: and optimized. Unless some program needs DSP, <em>none</em> or
3047: <em>dummy</em> DSP emulation mode could be used. Even of the programs
3048: that do use DSP, many use it only for background music and work
3049: fine without the real DSP emulation.
3050: </p>
1.1.1.12! root 3051:
1.1.1.10 root 3052: <h5>Timer-D</h5>
3053: <p>
3054: The single largest factor contributing to general Hatari emulation
3055: performance is the handling of interrupts. Enabling Timer-D patching
1.1.1.12! root 3056: option (about) doubles Hatari ST/STE emulation performance as it
! 3057: significantly reduces the number of interrupts generated by the emulated
! 3058: Atari machine. Using this has adverse effect only for very rare programs.
1.1.1.10 root 3059: </p>
1.1.1.12! root 3060:
1.1.1.10 root 3061: <h5>Compatible CPU</h5>
3062: <p>
1.1.1.12! root 3063: After the DSP and interrupts, m68k emulation takes most time.
1.1.1.10 root 3064: Disabling the "Slower but more compatible CPU" option will speed up
3065: the emulation a lot, but it won't anymore be cycle accurate. This can
3066: be fine for many games and other programs, but won't work e.g. for demos
3067: using overscan or rasters.
3068: </p>
3069:
3070: <p>
1.1.1.12! root 3071: Roughly speaking, for DSP emulation, one needs at least 2Ghz machine.
! 3072: For normal (unpatched) Timer-D frequency on some specific cases (like
1.1.1.10 root 3073: demos with overscan 512 color animations) one may need over 1GHz
1.1.1.12! root 3074: machine, but some rare ST/STE demos may require over 1GHz machine even
! 3075: with Timer-D patching. For "Compatible CPU" one needs at least 1/2Ghz
! 3076: machine.
1.1.1.10 root 3077: </p>
1.1.1.12! root 3078:
1.1.1.10 root 3079: <p>
1.1.1.12! root 3080: NOTE: Above options may cause some programs not to work correctly.
! 3081: The <a href="compatibility.html">Hatari Software Compatibility List</a>
! 3082: lists programs known to need real real Falcon DSP emulation or Timer-D
! 3083: frequency. Disabling "Compatible CPU" option is recommended only as
! 3084: a last resort.
1.1.1.10 root 3085: </p>
3086:
3087:
3088: <h4>Emulator options</h4>
3089:
3090: <p>
3091: Emulator options don't have as large effect on performance as
3092: emulation options, but they don't affect the emulated programs at all,
3093: just the quality of the emulation "output". These options can also
3094: be toggled at run-time without rebooting the emulation.
3095: </p>
3096:
3097: <h5>Sound</h5>
3098: <p>
3099: Internal Hatari sound handling and the SDL_mixer sound thread
3100: libALSA sound processing can account up to 1/3 of the Hatari CPU usage
1.1.1.12! root 3101: in normal ST/STE emulation. Disabling sound will get rid of that.
! 3102: Using low sound frequency or one matching your sound card may also help.
! 3103: Best is if you disable also background music from the programs you run
! 3104: in Hatari as this can significantly reduce the number of generated
! 3105: interrupts.
1.1.1.10 root 3106: </p>
1.1.1.12! root 3107:
1.1.1.10 root 3108: <h5>Frame skipping</h5>
3109: <p>
3110: Screen rendering can take noticeable amount of CPU time. The default
3111: Hatari "auto" frame skipping should be used unless there's a good
3112: reason not to. It will skip converting and showing some of the frames
3113: if there's not enough time for them. If your monitor refresh frequency
3114: is lower than the selected Hatari monitor frequency (e.g. LCD monitors
1.1.1.12! root 3115: usually use 60Hz whereas Atari monochrome monitor uses 71Hz), you
1.1.1.10 root 3116: should use frameskip of one. The reason is that if your SDL library
3117: uses VSync to synchronize the output to screen (like OSX one?), with
3118: zero frame skip that forces the emulation to run slower than a real
3119: Atari. If SDL doesn't use VSync, Hatari does redundant work to
3120: convert frames you can't see.
3121: </p>
1.1.1.12! root 3122:
! 3123: <h5>Zooming</h5>
1.1.1.10 root 3124: <p>
3125: If you are not using frame skip, disabling zooming can have
1.1.1.12! root 3126: noticeable improvement on performance. You can do this by specifying
! 3127: suitably low "Max zoomed" resolution (<span class="commandline">--zoom
! 3128: 1</span> command line option sets it to 320x200). If you still want to
! 3129: have a nice fullscreen mode, you should rather add the right resolution
! 3130: mode-lines (e.g. "320x200") to your xorg.conf file. If you still want
! 3131: to use zooming, disabling borders may help a bit.
1.1.1.10 root 3132: </p>
1.1.1.12! root 3133:
1.1.1.10 root 3134: <h5>Spec512 color handling</h5>
3135: <p>
3136: Handling Spec512 color modes which change the ST/e palette constantly
3137: takes some extra CPU. If you have problems with CPU usage in such
3138: screens and you care more e.g. from the sound quality than visuals, you
3139: can disable the Spec512 mode handling by zeroing the threshold for that
3140: with the <span class="commandline">--spec512 0</span> option.
3141: </p>
1.1.1.12! root 3142:
1.1.1.10 root 3143: <h5>Statusbar and drive LED</h5>
3144: <p>
3145: If your version of libSDL uses VSync to synchronize the screen
3146: output, drawing of the statusbar or the drive LED (when statusbar is
3147: disabled) may have some minor impact on performance too. Normally
3148: they shouldn't.
3149: </p>
3150:
3151: <p>
3152: Btw. Hatari currently runs best in 16 or 32 bits per pixel color depth
3153: mode, so try to avoid 24 bits per pixel display modes if possible.
3154: 16-bit mode is fastest.
3155: </p>
3156: <p>
3157: If nothing else helps, try an earlier Hatari version. More accurate
3158: emulation or emulator output in newer Hatari versions means that they
3159: can be slower despite optimizations.
3160: </p>
3161:
3162:
3163: <a name="Measuring the performance"></a><h3>Measuring the performance</h3>
3164:
3165: <p>
3166: There are a couple of ways to monitor and measure Hatari performance.
3167: </p>
3168: <p>
3169: By default Hatari has Statusbar visible and automatic frameskip
3170: enabled. When Hatari has enough time that it can sleep a little each
3171: frame, the statusbar frame skip ("FS") value keeps at zero. If Hatari
3172: is completely busy, it will increase to the maximum specified
3173: (automatic) frame skip value.
3174: </p>
3175: <p>
3176: Hatari has also a facility to measure FPS i.e. Frames Per Second.
3177: Just enable the <span class="commandline">--fast-forward</span> option
3178: on command line (or use the corresponding keyboard shortcut), and
3179: after a while, press the "Pause" key. Whenever Hatari emulation is
1.1.1.12! root 3180: paused, Hatari will output on console how many VBLs it could show per
! 3181: second along with some other numbers.
1.1.1.10 root 3182: </p>
3183: <p>
3184: It depends on what you want to measure, but usually it's best to
3185: disable sound and set high frame skip like
3186: <span class="commandline">--sound off --frameskips 60</span> so that
3187: the associated external overheads are minimized. E.g. video output
3188: can on some platforms do VSync and measurements would then show
3189: your monitor refresh frequency instead of actual Hatari performance.
3190: </p>
3191: <p>
3192: On Unix systems with <span class="commandline">times()</span> function
3193: call, only the time spent by the Hatari process itself is measured.
3194: On other systems much less accurate SDL "wall clock" timings are
3195: used. To make latter more accurate you could use also
3196: <span class="commandline">--run-vbls</span> option to specify how many
1.1.1.12! root 3197: VBLs Hatari should run before it exits. In this case it's best to
! 3198: either have the test-case run automatically from the AUTO-folder or
! 3199: given as memory snapshot to Hatari with the frame skip set equal to
! 3200: the VBL count.
1.1.1.10 root 3201: </p>
3202: <p>
3203: Note that the numbers can fluctuate quite a bit, <em>especially</em>
3204: when the SDL timings are used, so for (statistically) reliable numbers
3205: you may need to repeat the measurement several times. You should of
3206: course make also sure that the system doesn't have any other activity
3207: at the same time you're making the measurements.
3208: </p>
3209:
3210:
1.1.1.5 root 3211: <a name="Appendix"></a><h2>Appendix</h2>
3212:
3213: <a name="Copying"></a><h3>Copying</h3>
1.1.1.4 root 3214:
1.1 root 3215: <div class="backdropped">
3216: <p>This program is free software; you can redistribute it and/or modify
1.1.1.3 root 3217: it under the terms of the GNU General Public License as published by
3218: the
1.1 root 3219: Free Software Foundation; either version 2 of the License, or (at your
3220: option) any later version. </p>
3221: <p>This program is distributed in the hope that it will be useful, but <em>WITHOUT
3222: ANY WARRANTY</em>; without even the implied warranty of <em>MERCHANTABILITY</em>
1.1.1.3 root 3223: or <em>FITNESS FOR A PARTICULAR PURPOSE</em>. See the GNU General
1.1.1.4 root 3224: Public License for more details. </p>
3225: <p>
3226: You should have received a copy of the GNU General Public License
3227: along with this program; if not, write to the Free Software Foundation,
3228: Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
3229: </p>
1.1 root 3230: </div>
1.1.1.3 root 3231: <p><a href="http://www.gnu.org/">The GNU Project and the Free Software
3232: Foundation</a> | <a href="http://www.fsf.org/licenses/gpl.html">The
3233: GNU General Public License</a></p>
1.1.1.4 root 3234:
1.1.1.5 root 3235: <a name="Introduction to Emulation"></a><h3>Introduction to Emulation</h3>
3236:
1.1 root 3237: <p>Emulation via software is an art and Hatari is an example of this.</p>
1.1.1.3 root 3238: <p>Emulation is to make a computer behave like a (probably) completely
3239: different machine on the lowest possible niveau.
3240: This includes CPU and custom chip emulation allowing software written
3241: for the emulated machine to be run without notice.
3242: A good emulator will run most of the software intended for the emulated
3243: platform without trouble.
1.1 root 3244: </p>
3245: <p>
1.1.1.3 root 3246: The key to emulation is to simply do those things with a software
3247: program, the emulator, that normally chips would perform.
3248: So you have an CPU emulator that basically consists of a large loop
3249: that does exactly what the real thing would do:
1.1 root 3250: </p>
3251: <ul>
1.1.1.3 root 3252: <li>fetch an instruction from virtual memory</li>
3253: <li>interpret this instruction</li>
3254: <li>fetch operands from the emulated registers and memory</li>
3255: <li>perform the operation like addition or changing the program
3256: counter on a jump instruction</li>
3257: <li>writes results back into the intended registers or memory
3258: locations</li>
3259: <li>increment of the program counter and loop</li>
1.1 root 3260: </ul>
3261: <p>
1.1.1.3 root 3262: The typical von-Neumann CPU can be emulated very fast, stable and
3263: error-free using such a simple loop system.
1.1 root 3264: </p>
3265: <p>
1.1.1.3 root 3266: But in most cases the CPU emulation is the simplest part. Correct
3267: emulation of the various custom chips and hardware
1.1 root 3268: parts of the emulated system is much trickier.
3269: </p>
3270:
1.1.1.6 root 3271: <br>
3272:
1.1.1.3 root 3273: <hr style="width: 100%; height: 2px;">
1.1 root 3274: <table border="0" width="100%">
1.1.1.3 root 3275: <tbody>
1.1 root 3276: <tr>
1.1.1.3 root 3277: <td align="left"><a href="http://validator.w3.org/check/referer"><img
3278: src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"
3279: border="0" height="31" width="88"></a></td>
3280: <td align="right">
1.1.1.12! root 3281: June 2010
1.1.1.3 root 3282: </td>
1.1 root 3283: </tr>
1.1.1.3 root 3284: </tbody>
1.1 root 3285: </table>
3286: </body>
3287: </html>
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.