![[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.2 root 15: body { background-color:#FFFFFF;
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;
! 27: background-color: #eeeeee;
! 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:
35: a:link { color:#000099; background-color:#ffffff; text-decoration:none; }
1.1.1.7 root 36: a:visited { color:#cc0000; background-color:#ffffff; text-decoration:none;}
37: a:hover { color:#0000ff; background-color:#ffffff; text-decoration:none; }
38: a:active { color:#993399; background-color:#ffffff; text-decoration:none; }
1.1 root 39:
1.1.1.8 root 40: *.commandline { font-family:Fixed,Courier,monospace; font-size:90% }
1.1.1.2 root 41: *.file { color: #000088;}
1.1.1.10! root 42: *.button { color:#000000; background-color:#c0c0c0; border:outset thin grey; font-family:Fixed,Courier,monospace; padding-left:1em; padding-right:1em;}
1.1.1.8 root 43: *.key { color:#550000; font-family:Fixed,Courier,monospace; font-size:90% }
1.1 root 44: *.backdropped { background-color:#ffffee; }
1.1.1.5 root 45: *.image {margin-left: 5px; margin-right: 5px; border-width:2px; border-style:solid; border-color:#eeeeff; padding:1cm; text-align:center; }
46: *.floatimage { clear:right; float:right; margin-left:0.5cm; border-width:2px; border-style:solid; border-color:#eeeeff; padding:0.5cm; }
1.1 root 47:
48: -->
49: </style>
50: </head>
1.1.1.5 root 51:
52: <body>
53:
1.1 root 54: <h1 align="center">Hatari User's Manual</h1>
1.1.1.5 root 55:
1.1.1.2 root 56: <p align="center">
1.1.1.10! root 57: Version 1.3
1.1.1.3 root 58: </p>
59: <p align="center">
1.1.1.8 root 60: Manual written by: <strong>Thomas Huth</strong>, <strong>Matthias Arndt</strong>
1.1.1.10! root 61: & <strong>Eero Tamminen</strong>
1.1.1.2 root 62: </p>
63: <p align="center">
1.1.1.9 root 64: Hatari on the WWW: <strong><a href="http://hatari.berlios.de/"
65: target="_blank">http://hatari.berlios.de/</a></strong>
1.1.1.2 root 66: </p>
1.1 root 67:
1.1.1.5 root 68: <h2>Index</h2>
69: <ul>
70: <li><a href="#Introduction">Introduction</a>
71: <ul>
72: <li><a href="#General description">General description</a>
73: <li><a href="#Features">Features</a>
1.1.1.7 root 74: <li><a href="#STE hardware emulation">STE hardware emulation</a>
75: <li><a href="#Very experimental TT hardware emulation">Very experimental TT hardware emulation</a>
76: <li><a href="#Very experimental Falcon hardware emulation">Very experimental Falcon hardware emulation</a>
1.1.1.5 root 77: <li><a href="#System requirements">System requirements</a>
78: </ul>
79: <li><a href="#Compiling and running">Compiling and running</a>
80: <ul>
81: <li><a href="#Compiling Hatari">Compiling Hatari</a>
82: <li><a href="#Installation of a TOS ROM">Installation of a TOS ROM</a>
83: <li><a href="#Installation of the binary">Installation of the binary</a>
84: <li><a href="#Running Hatari for the first time">Running Hatari for the first time</a>
85: </ul>
86: <li><a href="#Command line options">Command line options</a>
87: <li><a href="#Using the emulated system">Using the emulated system</a>
88: <ul>
89: <li><a href="#The GUI">The GUI</a>
90: <ul>
91: <li><a href="#The Main Menu">The Main Menu</a>
1.1.1.10! root 92: <li><a href="#The File Selector Dialog">The File Selector Dialog</a>
1.1.1.5 root 93: <li><a href="#The System Dialog">The System Dialog</a>
1.1.1.10! root 94: <li><a href="#The Floppy Disks Dialog">The Floppy Disks Dialog</a>
! 95: <li><a href="#The Hard Disks Dialog">The Hard Disks Dialog</a>
1.1.1.5 root 96: <li><a href="#The Memory Dialog">The Memory Dialog</a>
97: <li><a href="#The ROM Dialog">The ROM Dialog</a>
98: <li><a href="#The Joystick Dialog">The Joystick Dialog</a>
99: <li><a href="#The Screen Dialog">The Screen Dialog</a>
100: <li><a href="#The Keyboard Dialog">The Keyboard Dialog</a>
101: <li><a href="#The Sound Dialog">The Sound Dialog</a>
102: <li><a href="#The Devices Dialog">The Devices Dialog</a>
103: </ul>
104: <li><a href="#Keyboard shortcuts">Keyboard shortcuts</a>
105: <li><a href="#Emulated Atari ST keyboard">Emulated Atari ST keyboard</a>
106: <li><a href="#Emulated mouse">Emulated mouse</a>
107: <li><a href="#Emulated joystick">Emulated joystick</a>
108: <li><a href="#Emulated video">Emulated video</a>
109: <li><a href="#Emulated printer">Emulated printer</a>
110: <li><a href="#Emulated RS232">Emulated RS232</a>
111: </ul>
112: <li><a href="#Floppy disk images">Floppy disk images</a>
113: <li><a href="#Hard disk support">Hard disk support</a>
1.1.1.6 root 114: <ul>
115: <li><a href="#GEMDOS based hard disk emulation">GEMDOS based hard disk emulation</a></li>
1.1.1.10! root 116: <li><a href="#ACSI hard disk emulation">ACSI hard disk emulation</a></li>
! 117: <li><a href="#IDE hard disk emulation">IDE hard disk emulation</a></li>
! 118: <li><a href="#Accessing disk image partitions outside of Hatari">Accessing disk image partitions outside of Hatari</a></li>
! 119: </ul>
! 120: <li><a href="#The debugger">The debugger</a>
! 121: <li><a href="#Performance">Performance</a>
! 122: <ul>
! 123: <li><a href="#Improving Hatari performance">Improving Hatari performance</a>
! 124: <li><a href="#Measuring the performance">Measuring the performance</a>
1.1.1.6 root 125: </ul>
1.1.1.5 root 126: <li><a href="#Appendix">Appendix</a>
127: <ul>
128: <li><a href="#Copying">Copying</a>
129: <li><a href="#Introduction to Emulation">Introduction to Emulation</a>
130: </ul>
131: </ul>
132:
133:
134: <a name="Introduction"></a><h2>Introduction</h2>
1.1 root 135:
1.1.1.5 root 136: <a name="General description"></a><h3>General description</h3>
1.1 root 137: <p>
1.1.1.7 root 138: Hatari is an Atari ST, STE, TT and Falcon emulator for Linux, FreeBSD, BeOS and
139: other Systems which are supported by the SDL library.
1.1.1.4 root 140: The emulator is open source software and is distributed under the terms of the
1.1.1.7 root 141: <a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU General
142: Public License (GPL)</a>.
1.1.1.4 root 143: </p>
144: <p>
1.1.1.3 root 145: The Atari ST was a 16/32 bit computer system which was first released by Atari
1.1.1.4 root 146: in 1985. Using the Motorola 68000 CPU, it was a very popular computer having
147: quite a lot of CPU power at that time. See Appendix B for details on emulation
148: in general.
1.1.1.3 root 149: </p>
150: <p>
1.1.1.4 root 151: Unlike many other Atari ST emulators which try to give you a good
152: environment for running GEM applications, Hatari tries to emulate the hardware
153: of a ST as close as possible so that it is able to run most of the old ST games
154: and demos. Of course you can run normal GEM applications with Hatari, too.
1.1.1.7 root 155: Recent versions of Hatari even feature basic STE, TT and Falcon emulation.
1.1 root 156: </p>
157:
1.1.1.5 root 158: <a name="Features"></a><h3>Features</h3>
1.1 root 159: <ul>
1.1.1.7 root 160: <li>68000 - 68040 emulation via the UAE CPU core (no PMMU support though)</li>
161: <li>ST RAM size variable (from 512kiB up to 14MiB are possible)</li>
1.1.1.3 root 162: <li>optional cartridge images for the ST ROM port</li>
1.1.1.2 root 163: <li>most of the ST specific hardware</li>
1.1 root 164: <li>ST Shifter with ST-High, ST-Medium and ST-Low resolutions,
1.1.1.7 root 165: overscan effects for all borders in color resolutions</li>
1.1.1.6 root 166: <li>512 color ST palette</li>
1.1.1.7 root 167: <li>many raster effects </li>
1.1.1.8 root 168: <li>scaling of low resolutions by factor two</li>
1.1.1.7 root 169: <li>interleaved lines rendering of ST-medium and (scaled) ST-low
170: resolutions for the TV "monitor type"</li>
1.1.1.8 root 171: <li>Blitter chip emulation</li>
1.1.1.2 root 172: <li>PSG YM2149 emulation (soundchip) including STFM samples</li>
1.1.1.8 root 173: <li>Printer port emulation on hardware level (print to file)</li>
1.1.1.10! root 174: <li>RS232 emulation</li>
! 175: <li>MIDI input/output/through emulation</li>
1.1 root 176: <li>Mega ST real time clock</li>
1.1.1.3 root 177: <li>IKBD emulation (keyboard, mouse and joystick) with custom
1.1.1.7 root 178: keyboard mapping</li>
1.1 root 179: <li>joystick emulation via cursor keys and joystick emulation via a
1.1.1.7 root 180: connected PC joystick</li>
1.1.1.3 root 181: <li>FDC emulation using floppy disk images in standard formats (*.ST,
1.1.1.7 root 182: *.MSA and *.DIM)</li>
1.1.1.5 root 183: <li>support for packed disk images (PkZip and Gzip)</li>
1.1.1.7 root 184: <li>optional write-protection for disk images</li>
1.1.1.2 root 185: <li>partial ACSI emulation for harddisk support</li>
1.1.1.10! root 186: <li>GEMDOS interface driver to mount directories as harddrives</li>
1.1.1.7 root 187: <li>support for memory snapshots (save whole system state)</li>
1.1.1.2 root 188: <li>driver for extended VDI resolutions</li>
189: <li>recording of sound as .WAV and .YM files</li>
1.1.1.8 root 190: <li>screenshots in PNG or BMP format</li>
1.1.1.2 root 191: <li>animation capturing</li>
1.1.1.8 root 192: <li>TOS versions 1.00, 1.02, 1.04 and 2.06 (and EmuTOS) can be used in ST mode.</li>
1.1 root 193: </ul>
1.1.1.5 root 194:
1.1.1.7 root 195: <a name="STE hardware emulation"></a>
196: <h4>STE hardware emulation</h4>
1.1.1.6 root 197: STE emulation is still a little bit experimental, but basically
1.1.1.7 root 198: there is support for most of the enhanced/additional STE features:
1.1.1.5 root 199: <ul>
200: <li>horizontal and vertical hardware fine scrolling</li>
201: <li>split screen techniques / in-screen video address manipulations</li>
1.1.1.8 root 202: <li>(STE specific) left border opening</li>
1.1.1.5 root 203: <li>4096 colors STE palette</li>
1.1.1.8 root 204: <li>Stereo DMA sample sound ("microwire" audio balance support missing)</li>
1.1.1.7 root 205: <li>STE joypads</li>
1.1.1.8 root 206: <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 207: </ul>
208:
1.1.1.7 root 209: <a name="Very experimental TT hardware emulation"></a>
210: <h4>Very experimental TT hardware emulation</h4>
211: There is support for following additional TT features:
212: <ul>
213: <li>TT low/med/high resolution support</li>
214: <li>ST/TT palette switching and video shifter</li>
215: <li>RAM upto 14MiB (ST-RAM only, there is no support for TT-RAM yet)</li>
1.1.1.8 root 216: <li>Only TOS version 3.06 (and EmuTOS) can be used in TT mode.</li>
1.1.1.7 root 217: </ul>
218:
219: <a name="Very experimental Falcon hardware emulation"></a>
220: <h4>Very experimental Falcon hardware emulation</h4>
221: There is support for following additional Falcon features:
222: <ul>
223: <li>Videl emulation for all Falcon screen modes</li>
224: <li>STE/Falcon palette switching and shifter</li>
225: <li>Mono/RGB/VGA/TV monitor types</li>
1.1.1.10! root 226: <li>Experimental IDE emulation for harddisk support</li>
1.1.1.7 root 227: <li>Some few parts of the Falcon sound system are emulated
228: (e.g. the additional sample rates of the DMA sound)</li>
1.1.1.8 root 229: <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 230: </ul>
231:
1.1.1.8 root 232: <p>
1.1.1.10! root 233: DSP emulation is still very experimental, but many games and demos
! 234: already work with it. If it takes too much CPU, there's a dummy mode
1.1.1.8 root 235: too, which helps to get some demos and games running.
1.1 root 236: </p>
1.1.1.5 root 237:
238:
239: <a name="System requirements"></a><h3>System requirements</h3>
240:
1.1 root 241: <p> Hatari currently has the following system requirements: </p>
242: <ul>
1.1.1.7 root 243: <li>a fast PC (>500MHz, for Falcon and TT emulation even faster) </li>
1.1.1.3 root 244: <li>some sort of Unix (preferable <a href="http://www.linux.org/">GNU/Linux</a>)
245: </li>
1.1 root 246: <li>the SDL library (<a href="http://www.libsdl.org/">http://www.libsdl.org/</a>)</li>
1.1.1.3 root 247: <li>the zLib (<a href="http://www.gzip.org/zlib/">http://www.gzip.org/zlib/</a>)
1.1.1.5 root 248: for support of ZIP-packed disk images (*.zip and *.gz)</li>
1.1 root 249: </ul>
1.1.1.5 root 250:
251: <p>
252: Certain versions of Hatari have successfully been tested by various people on
253: the following systems:
254: </p>
1.1 root 255: <ul>
1.1.1.8 root 256: <li>Linux/i86 with Kernel 2.4.x and 2.6.x</li>
257: <li>Linux/PPC with Kernel 2.4.x and 2.6.x</li>
1.1.1.2 root 258: <li>BeOS/i86 </li>
1.1 root 259: <li>Apple PowerMac with Mac OS X </li>
260: <li>NetBSD 1.6 </li>
1.1.1.4 root 261: <li>NetBSD on a Digital Alpha</li>
1.1.1.8 root 262: <li>FreeBSD 4.1 on an i486, FreeBSD 4.8 on a Pentium 4 and FreeBSD 5.1</li>
1.1.1.2 root 263: <li>OpenBSD 3.5 </li>
1.1.1.4 root 264: <li>Solaris 8 on a SUN UltraSparc 1</li>
1.1.1.8 root 265: <li>Linux/ARM (oabi) on Sharp Zaurus SL-C760 PDA</li>
266: <li>Linux/ARM (eabi) on Nokia 770, N800 and N810 Internet Tablets</li>
1.1 root 267: </ul>
1.1.1.5 root 268:
269: <a name="Compiling and running"></a><h2>Compiling and running</h2>
270:
271: <a name="Compiling Hatari"></a><h3>Compiling Hatari</h3>
272:
1.1 root 273: <p> First, you need the SDL library, you can get it at:
1.1.1.3 root 274: <a href="http://www.libsdl.org/">http://www.libsdl.org/</a>. Most
275: distributions already ship a suitable version.
276: Make sure to install the appropriate header files as well often called
277: "libsdl-dev" or the like.
278: </p>
279: <p> Second, you need the zLib compression library. You can get it from <a
280: href="http://www.gzip.org/zlib/">http://www.gzip.org/zlib/</a>
281: but the version shipped with your distribution will be sufficient in
282: most cases. Make sure to have the header files
1.1 root 283: for it installed as well.
284: </p>
285: <p>
1.1.1.8 root 286: For optional features like PNG format screenshots and Hatari window
287: embedding, you need to have the header files for libpng and libX11.
288: </p>
289: <p>
1.1 root 290: Of course, you need the GNU C compiler and (GNU) Make, too!
291: </p>
1.1.1.8 root 292: <p> Change to the <span class="file">hatari/</span> directory, copy
293: <span class="file">Makefile-default.cnf</span> to
294: <span class="file">Makefile.cnf</span> and adapt the configuration file
295: to suite your system. Alternatively, you can use the supplied configure
296: script to auto-detect all parameters (type
297: "<span class="commandline">./configure --help</span>"
1.1.1.3 root 298: to see the options of the script).
299: Don't forget to use some good CFLAGS for the compiler optimizations, e.g.
300: run <span class="commandline">configure</span> in the following way:
301: </p>
1.1.1.10! root 302: <pre>
! 303: CFLAGS="-O3 -fomit-frame-pointer" ./configure
! 304: </pre>
1.1.1.3 root 305: <p>
306: Then compile Hatari by typing <span class="commandline">make</span>.
307: If all
308: works fine, you'll get the executable <span class="commandline">hatari</span>
309: in the src/ subdirectory.
1.1.1.2 root 310: </p>
1.1.1.5 root 311:
312: <a name="Installation of a TOS ROM"></a><h3>Installation of a TOS ROM</h3>
313:
1.1.1.6 root 314: <p>
315: Before you can start Hatari, you have to copy a TOS ROM image to the data
316: directory (the data directory is specified
1.1.1.3 root 317: in the configuration file <span class="file">Makefile.cnf</span>) and
318: rename it to <span class="commandline">tos.img</span>, or use the
319: <span class="commandline">--tos</span> command line option to tell
320: Hatari where to find a TOS ROM.
1.1 root 321: Hatari needs a TOS ROM image because this contains the operating system
1.1.1.6 root 322: of the emulated Atari.
323: </p>
324: <p>
325: Unfortunately it is not possible to ship an original ROM
1.1.1.5 root 326: image with the Hatari package since these images are still copyrighted.
327: But you can easily create an image with a real ST and one of those various
328: ROM-image programs for the ST (search for "TOSDUMP" with your
329: favourite internet search engine). If your old ST does not work anymore, you
330: can also try to search the internet directly for corresponding TOS ROM image,
331: but don't ask the Hatari team where to get one. </p>
332: <p> Another solution is EmuTOS, which is also shipped with the official
333: release versions of Hatari. EmuTOS is an open-source TOS clone. You can find
334: it at:
335: <a href="http://emutos.sourceforge.net/">http://emutos.sourceforge.net/</a>.
336: It is not the best solution for playing games or running other old software
1.1.1.8 root 337: due to compatibility issues (see <span class="file">emutos.txt</span> for
338: more details), but it's free and compatible with Hatari.</p>
1.1 root 339: <p>If you do not specify a TOS image on the commandline nor can Hatari
340: find a suitable TOS image in the default dir, you'll get the chance to
341: select a TOS image file from the GUI. </p>
1.1.1.5 root 342:
343: <a name="Installation of the binary"></a><h3>Installation of the binary</h3>
344:
1.1.1.3 root 345: <p> Type <span class="commandline">make install</span> as root to do a
346: systemwide installation. In this case it is recommended
347: to set the DATADIR variable in Makefile.cnf to a proper value. <tt>/usr/local/share/hatari</tt>
348: is a good value in that case.</p>
349: <p>The Hatari executable should now be in your PATH and accessible from
350: anywhere.</p>
1.1 root 351: <p> When you finally have got a TOS image, try starting Hatari with the
1.1.1.3 root 352: option <span class="commandline">--help</span> to find out more about
353: its command line parameters. </p>
1.1.1.5 root 354:
355: <a name="Running Hatari for the first time"></a><h3>Running Hatari for the first time</h3>
356:
1.1.1.3 root 357: <p> Now type <span class="commandline">hatari</span> to run the
358: emulator for the first time. If all goes
359: well, you should now be presented with a window showing you the
360: familiar
361: little green desktop of the Atari ST. Press <span class="key">F12</span>
362: to turn on the GUI to
363: configure Hatari to suit your needs, press <span class="key">F11</span>
364: to toggle windowed and fullscreen mode. </p>
1.1.1.5 root 365:
366: <a name="Command line options"></a><h2>Command line options</h2>
367:
1.1.1.7 root 368: <p>Usage:</p>
369: <pre>
370: hatari [options] [disk image name]
371: </pre>
372:
1.1.1.8 root 373: <p>Hatari command line options are split into several categories:</p>
1.1.1.7 root 374:
1.1.1.8 root 375: <!--
376: Generated from hatari.1 options section by changing subheaders to h3
377: and removing extra paragraphs:
378: groff -man -Thtml hatari.1 | awk '
379: /OPTIONS<\/h/ { out = 1; next }
380: /INDENTATION/ { next }
381: /COMMANDS/ { out = 0; next }
382: { if(out) print }' | sed -e 's/h2/h3/g' -e 's/<\/*p>//g'
383: -->
384:
385: <a name="General options"></a>
386: <h3>General options</h3>
387: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 388: cellspacing="0" cellpadding="0">
1.1.1.8 root 389: <tr valign="top" align="left">
390: <td width="10%"></td>
391: <td width="89%">
392: <b>−h, −−help</b></td>
393: </table>
394: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 395: cellspacing="0" cellpadding="0">
1.1.1.8 root 396: <tr valign="top" align="left">
397: <td width="21%"></td>
398: <td width="77%">
399: Print command line options and terminate
400: </td>
401: </table>
402: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 403: cellspacing="0" cellpadding="0">
1.1.1.8 root 404: <tr valign="top" align="left">
405: <td width="10%"></td>
406: <td width="89%">
407: <b>−v, −−version</b></td>
408: </table>
409: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 410: cellspacing="0" cellpadding="0">
1.1.1.8 root 411: <tr valign="top" align="left">
412: <td width="21%"></td>
413: <td width="77%">
414: Print version information and terminate
415: </td>
416: </table>
417: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 418: cellspacing="0" cellpadding="0">
1.1.1.8 root 419: <tr valign="top" align="left">
420: <td width="10%"></td>
421: <td width="89%">
422: <b>−−confirm-quit <bool></b></td>
423: </table>
424: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 425: cellspacing="0" cellpadding="0">
1.1.1.8 root 426: <tr valign="top" align="left">
427: <td width="21%"></td>
428: <td width="77%">
429: Whether Hatari confirms quitting
430: </td>
431: </table>
432: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 433: cellspacing="0" cellpadding="0">
1.1.1.8 root 434: <tr valign="top" align="left">
435: <td width="10%"></td>
436: <td width="89%">
437: <b>−c, −−configfile
438: <filename></b></td>
439: </table>
440: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 441: cellspacing="0" cellpadding="0">
1.1.1.8 root 442: <tr valign="top" align="left">
443: <td width="21%"></td>
444: <td width="77%">
445: use the given file as configuration file instead of
446: ~/.hatari/hatari.cfg
447: </td>
448: </table>
449: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 450: cellspacing="0" cellpadding="0">
1.1.1.8 root 451: <tr valign="top" align="left">
452: <td width="10%"></td>
453: <td width="89%">
454: <b>−−fast-forward <bool></b></td>
455: </table>
456: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 457: cellspacing="0" cellpadding="0">
1.1.1.8 root 458: <tr valign="top" align="left">
459: <td width="21%"></td>
460: <td width="77%">
461: On fast machine helps skipping (fast forwarding) Hatari
462: output
463: </td>
464: </table>
465: <a name="Display options"></a>
466: <h3>Display options</h3>
467: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 468: cellspacing="0" cellpadding="0">
1.1.1.8 root 469: <tr valign="top" align="left">
470: <td width="10%"></td>
471: <td width="89%">
472: <b>−m, −−mono</b></td>
473: </table>
474: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 475: cellspacing="0" cellpadding="0">
1.1.1.8 root 476: <tr valign="top" align="left">
477: <td width="21%"></td>
478: <td width="77%">
479: Start in monochrome mode instead of color
480: </td>
481: </table>
482: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 483: cellspacing="0" cellpadding="0">
1.1.1.8 root 484: <tr valign="top" align="left">
485: <td width="10%"></td>
486: <td width="89%">
487: <b>−−monitor <x></b></td>
488: </table>
489: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 490: cellspacing="0" cellpadding="0">
1.1.1.8 root 491: <tr valign="top" align="left">
492: <td width="21%"></td>
493: <td width="77%">
494: Select monitor type (x = mono/rgb/vga/tv)
495: </td>
496: </table>
497: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 498: cellspacing="0" cellpadding="0">
1.1.1.8 root 499: <tr valign="top" align="left">
500: <td width="10%"></td>
501: <td width="89%">
502: <b>−f, −−fullscreen</b></td>
1.1 root 503: </table>
1.1.1.8 root 504: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 505: cellspacing="0" cellpadding="0">
1.1.1.8 root 506: <tr valign="top" align="left">
507: <td width="21%"></td>
508: <td width="77%">
509: Start the emulator in fullscreen mode
510: </td>
511: </table>
512: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 513: cellspacing="0" cellpadding="0">
1.1.1.8 root 514: <tr valign="top" align="left">
515: <td width="10%"></td>
516: <td width="89%">
517: <b>−w, −−window</b></td>
518: </table>
519: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 520: cellspacing="0" cellpadding="0">
1.1.1.8 root 521: <tr valign="top" align="left">
522: <td width="21%"></td>
523: <td width="77%">
524: Start the emulator in window mode
525: </td>
526: </table>
527: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 528: cellspacing="0" cellpadding="0">
1.1.1.8 root 529: <tr valign="top" align="left">
530: <td width="10%"></td>
531: <td width="89%">
1.1.1.10! root 532: <b>−−grab</b></td>
! 533: </table>
! 534: <table width="100%" border=0 rules="none" frame="void"
! 535: cellspacing="0" cellpadding="0">
! 536: <tr valign="top" align="left">
! 537: <td width="21%"></td>
! 538: <td width="77%">
! 539: Grab mouse (also) in window mode
! 540: </td>
! 541: </table>
! 542: <table width="100%" border=0 rules="none" frame="void"
! 543: cellspacing="0" cellpadding="0">
! 544: <tr valign="top" align="left">
! 545: <td width="10%"></td>
! 546: <td width="89%">
1.1.1.8 root 547: <b>−z, −−zoom <x></b></td>
548: </table>
549: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 550: cellspacing="0" cellpadding="0">
1.1.1.8 root 551: <tr valign="top" align="left">
552: <td width="21%"></td>
553: <td width="77%">
554: Zoom low resolution (1=no, 2=yes)
555: </td>
556: </table>
557: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 558: cellspacing="0" cellpadding="0">
1.1.1.8 root 559: <tr valign="top" align="left">
560: <td width="10%"></td>
561: <td width="89%">
562: <b>−−frameskips <x></b></td>
563: </table>
564: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 565: cellspacing="0" cellpadding="0">
1.1.1.8 root 566: <tr valign="top" align="left">
567: <td width="21%"></td>
568: <td width="77%">
569: Skip <x> frames after each displayed frame to
570: accelerate emulation (0=disabled, >4 uses automatic
571: frameskip with given value as maximum)
572: </td>
573: </table>
574: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 575: cellspacing="0" cellpadding="0">
1.1.1.8 root 576: <tr valign="top" align="left">
577: <td width="10%"></td>
578: <td width="89%">
579: <b>−−borders <bool></b></td>
580: </table>
581: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 582: cellspacing="0" cellpadding="0">
1.1.1.8 root 583: <tr valign="top" align="left">
584: <td width="21%"></td>
585: <td width="77%">
586: Show screen borders (for overscan demos, ST(e) color mode
587: specific etc)
588: </td>
589: </table>
590: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 591: cellspacing="0" cellpadding="0">
1.1.1.8 root 592: <tr valign="top" align="left">
593: <td width="10%"></td>
594: <td width="89%">
595: <b>−−statusbar <bool></b></td>
596: </table>
597: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 598: cellspacing="0" cellpadding="0">
1.1.1.8 root 599: <tr valign="top" align="left">
600: <td width="21%"></td>
601: <td width="77%">
602: Show statusbar (with floppy leds etc etc)
603: </td>
604: </table>
605: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 606: cellspacing="0" cellpadding="0">
1.1.1.8 root 607: <tr valign="top" align="left">
608: <td width="10%"></td>
609: <td width="89%">
610: <b>−−drive-led <bool></b></td>
611: </table>
612: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 613: cellspacing="0" cellpadding="0">
1.1.1.8 root 614: <tr valign="top" align="left">
615: <td width="21%"></td>
616: <td width="77%">
617: Show overlay drive led when statusbar isn’t
618: shown
619: </td>
620: </table>
621: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 622: cellspacing="0" cellpadding="0">
1.1.1.8 root 623: <tr valign="top" align="left">
624: <td width="10%"></td>
625: <td width="89%">
626: <b>−−spec512 <x></b></td>
627: </table>
628: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 629: cellspacing="0" cellpadding="0">
1.1.1.8 root 630: <tr valign="top" align="left">
631: <td width="21%"></td>
632: <td width="77%">
633: Hatari uses this threshold to decide when to render a
634: screen with the slower but more accurate Spectrum512 screen
635: conversion functions (0 <= x <= 512, 0=disable)
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%">
643: <b>−−bpp <bool></b></td>
644: </table>
645: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 646: cellspacing="0" cellpadding="0">
1.1.1.8 root 647: <tr valign="top" align="left">
648: <td width="21%"></td>
649: <td width="77%">
650: Force internal bitdepth (x = 8/15/16/32, 0=disable)
651: </td>
652: </table>
653: <a name="VDI options"></a>
654: <h3>VDI options</h3>
655: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 656: cellspacing="0" cellpadding="0">
1.1.1.8 root 657: <tr valign="top" align="left">
658: <td width="10%"></td>
659: <td width="89%">
660: <b>−−vdi <bool></b></td>
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: Whether to use VDI screen mode
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%">
675: <b>−−vdi−planes <x></b></td>
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: Use extended VDI resolution with bit depth <x> (x =
683: 1, 2 or 4)
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%">
691: <b>−−vdi−width <w></b></td>
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: Use extended VDI resolution with width <w> (384
699: <= w <= 1024)
700: </td>
701: </table>
702: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 703: cellspacing="0" cellpadding="0">
1.1.1.8 root 704: <tr valign="top" align="left">
705: <td width="10%"></td>
706: <td width="89%">
707: <b>−−vdi−height <h></b></td>
708: </table>
709: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 710: cellspacing="0" cellpadding="0">
1.1.1.8 root 711: <tr valign="top" align="left">
712: <td width="21%"></td>
713: <td width="77%">
714: Use extended VDI resolution with height <h> (200
715: < h <= 768)
716: </td>
717: </table>
718: <a name="Devices options"></a>
719: <h3>Devices 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%">
725: <b>−j, −−joystick
726: <port></b></td>
727: </table>
728: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 729: cellspacing="0" cellpadding="0">
1.1.1.8 root 730: <tr valign="top" align="left">
731: <td width="21%"></td>
732: <td width="77%">
733: Emulate joystick with cursor keys in given port (0-5)
734: </td>
735: </table>
736: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 737: cellspacing="0" cellpadding="0">
1.1.1.8 root 738: <tr valign="top" align="left">
739: <td width="10%"></td>
740: <td width="89%">
741: <b>−−joy<port>
742: <type></b></td>
743: </table>
744: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 745: cellspacing="0" cellpadding="0">
1.1.1.8 root 746: <tr valign="top" align="left">
747: <td width="21%"></td>
748: <td width="77%">
749: Set joystick type (none/keys/real) for given port
750: </td>
751: </table>
752: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 753: cellspacing="0" cellpadding="0">
1.1.1.8 root 754: <tr valign="top" align="left">
755: <td width="10%"></td>
756: <td width="89%">
757: <b>−−printer <file></b></td>
758: </table>
759: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 760: cellspacing="0" cellpadding="0">
1.1.1.8 root 761: <tr valign="top" align="left">
762: <td width="21%"></td>
763: <td width="77%">
764: Enable printer support and write data to <file>
765: </td>
766: </table>
767: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 768: cellspacing="0" cellpadding="0">
1.1.1.8 root 769: <tr valign="top" align="left">
770: <td width="10%"></td>
771: <td width="89%">
1.1.1.9 root 772: <b>−−midi−in <filename></b></td>
1.1.1.8 root 773: </table>
774: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 775: cellspacing="0" cellpadding="0">
1.1.1.8 root 776: <tr valign="top" align="left">
777: <td width="21%"></td>
778: <td width="77%">
1.1.1.9 root 779: Enable MIDI support and write MIDI data to <file>
1.1.1.8 root 780: </td>
781: </table>
782: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 783: cellspacing="0" cellpadding="0">
1.1.1.8 root 784: <tr valign="top" align="left">
785: <td width="10%"></td>
786: <td width="89%">
1.1.1.9 root 787: <b>−−midi−out <filename></b></td>
1.1.1.8 root 788: </table>
789: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 790: cellspacing="0" cellpadding="0">
1.1.1.8 root 791: <tr valign="top" align="left">
792: <td width="21%"></td>
793: <td width="77%">
1.1.1.9 root 794: Enable MIDI support and read MIDI data from <file>
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>−−rs232−in <filename></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: Enable serial port support and use <file> as the input device
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>−−rs232−out <filename></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: Enable serial port support and use <file> as the output device
1.1.1.8 root 825: </td>
826: </table>
827: <a name="Disk options"></a>
828: <h3>Disk options</h3>
829: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 830: cellspacing="0" cellpadding="0">
1.1.1.8 root 831: <tr valign="top" align="left">
832: <td width="10%"></td>
833: <td width="89%">
834: <b>−−disk-a <file></b></td>
835: </table>
836: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 837: cellspacing="0" cellpadding="0">
1.1.1.8 root 838: <tr valign="top" align="left">
839: <td width="21%"></td>
840: <td width="77%">
841: Set disk image for floppy drive A
842: </td>
843: </table>
844: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 845: cellspacing="0" cellpadding="0">
1.1.1.8 root 846: <tr valign="top" align="left">
847: <td width="10%"></td>
848: <td width="89%">
849: <b>−−disk-b <file></b></td>
850: </table>
851: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 852: cellspacing="0" cellpadding="0">
1.1.1.8 root 853: <tr valign="top" align="left">
854: <td width="21%"></td>
855: <td width="77%">
856: Set disk image for floppy drive B
857: </td>
858: </table>
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%">
864: <b>−d, −−harddrive
865: <dir></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 an ST harddrive (<dir> = root
873: directory)
874: </td>
875: </table>
876: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 877: cellspacing="0" cellpadding="0">
1.1.1.8 root 878: <tr valign="top" align="left">
879: <td width="10%"></td>
880: <td width="89%">
881: <b>−−acsi <file></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: Emulate an ACSI hard disk with an image <file>
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%">
896: <b>−−ide <file></b></td>
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%">
1.1.1.9 root 903: Emulate an IDE hard disk with an image <file>
1.1.1.8 root 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%">
911: <b>−−slowfdc <bool></b></td>
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%">
918: slow down FDC emulation (deprecated)
919: </td>
920: </table>
921: <a name="Memory options"></a>
922: <h3>Memory options</h3>
923: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 924: cellspacing="0" cellpadding="0">
1.1.1.8 root 925: <tr valign="top" align="left">
926: <td width="10%"></td>
927: <td width="89%">
928: <b>−s, −−memsize <x></b></td>
929: </table>
930: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 931: cellspacing="0" cellpadding="0">
1.1.1.8 root 932: <tr valign="top" align="left">
933: <td width="21%"></td>
934: <td width="77%">
935: Set amount of emulated RAM, x = 1 to 14 MiB, or 0 for 512
936: KiB
937: </td>
938: </table>
939: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 940: cellspacing="0" cellpadding="0">
1.1.1.8 root 941: <tr valign="top" align="left">
942: <td width="10%"></td>
943: <td width="89%">
944: <b>−t, −−tos
945: <imagefile></b></td>
946: </table>
947: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 948: cellspacing="0" cellpadding="0">
1.1.1.8 root 949: <tr valign="top" align="left">
950: <td width="21%"></td>
951: <td width="77%">
952: Specify TOS ROM image to use
953: </td>
954: </table>
955: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 956: cellspacing="0" cellpadding="0">
1.1.1.8 root 957: <tr valign="top" align="left">
958: <td width="10%"></td>
959: <td width="89%">
960: <b>−−cartridge <imagefile></b></td>
961: </table>
962: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 963: cellspacing="0" cellpadding="0">
1.1.1.8 root 964: <tr valign="top" align="left">
965: <td width="21%"></td>
966: <td width="77%">
967: Use ROM cartridge image <file> (only works if
968: GEMDOS HD emulation and extended VDI resolution are
969: disabled)
970: </td>
971: </table>
972: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 973: cellspacing="0" cellpadding="0">
1.1.1.8 root 974: <tr valign="top" align="left">
975: <td width="10%"></td>
976: <td width="89%">
977: <b>−−memstate <file></b></td>
978: </table>
979: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 980: cellspacing="0" cellpadding="0">
1.1.1.8 root 981: <tr valign="top" align="left">
982: <td width="21%"></td>
983: <td width="77%">
984: Load memory snap-shot <file>
985: </td>
986: </table>
987: <a name="CPU options"></a>
988: <h3>CPU options</h3>
989: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 990: cellspacing="0" cellpadding="0">
1.1.1.8 root 991: <tr valign="top" align="left">
992: <td width="10%"></td>
993: <td width="89%">
994: <b>−−cpulevel <x></b></td>
995: </table>
996: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 997: cellspacing="0" cellpadding="0">
1.1.1.8 root 998: <tr valign="top" align="left">
999: <td width="21%"></td>
1000: <td width="77%">
1001: Specify CPU (680x0) to use (use x >= 1 with EmuTOS or
1002: TOS >= 2.06 only!)
1003: </td>
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="10%"></td>
1009: <td width="89%">
1010: <b>−−cpuclock <x></b></td>
1011: </table>
1012: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1013: cellspacing="0" cellpadding="0">
1.1.1.8 root 1014: <tr valign="top" align="left">
1015: <td width="21%"></td>
1016: <td width="77%">
1017: Set the CPU clock (8, 16 or 32 Mhz)
1018: </td>
1019: </table>
1020: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1021: cellspacing="0" cellpadding="0">
1.1.1.8 root 1022: <tr valign="top" align="left">
1023: <td width="10%"></td>
1024: <td width="89%">
1025: <b>−−compatible <bool></b></td>
1026: </table>
1027: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1028: cellspacing="0" cellpadding="0">
1.1.1.8 root 1029: <tr valign="top" align="left">
1030: <td width="21%"></td>
1031: <td width="77%">
1032: Use a more compatible but slower 68000 CPU mode
1033: </td>
1034: </table>
1035: <a name="Misc system options"></a>
1036: <h3>Misc system options</h3>
1037: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1038: cellspacing="0" cellpadding="0">
1.1.1.8 root 1039: <tr valign="top" align="left">
1040: <td width="10%"></td>
1041: <td width="89%">
1042: <b>−−machine <x></b></td>
1043: </table>
1044: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1045: cellspacing="0" cellpadding="0">
1.1.1.8 root 1046: <tr valign="top" align="left">
1047: <td width="21%"></td>
1048: <td width="77%">
1049: select machine type (x = st, ste, tt or falcon)
1050: </td>
1051: </table>
1052: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1053: cellspacing="0" cellpadding="0">
1.1.1.8 root 1054: <tr valign="top" align="left">
1055: <td width="10%"></td>
1056: <td width="89%">
1057: <b>−−blitter <bool></b></td>
1058: </table>
1059: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1060: cellspacing="0" cellpadding="0">
1.1.1.8 root 1061: <tr valign="top" align="left">
1062: <td width="21%"></td>
1063: <td width="77%">
1064: Enable blitter emulation (ST only)
1065: </td>
1066: </table>
1067: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1068: cellspacing="0" cellpadding="0">
1.1.1.8 root 1069: <tr valign="top" align="left">
1070: <td width="10%"></td>
1071: <td width="89%">
1.1.1.10! root 1072: <b>−−timer−d <bool></b></td>
! 1073: </table>
! 1074: <table width="100%" border=0 rules="none" frame="void"
! 1075: cellspacing="0" cellpadding="0">
! 1076: <tr valign="top" align="left">
! 1077: <td width="21%"></td>
! 1078: <td width="77%">
! 1079: Patch redundantly high Timer-D frequency set by TOS. This about doubles
! 1080: Hatari speed as the original Timer-D frequency causes most of the
! 1081: interrupts.
! 1082: </td>
! 1083: </table>
! 1084: <table width="100%" border=0 rules="none" frame="void"
! 1085: cellspacing="0" cellpadding="0">
! 1086: <tr valign="top" align="left">
! 1087: <td width="10%"></td>
! 1088: <td width="89%">
1.1.1.8 root 1089: <b>−−dsp <x></b></td>
1090: </table>
1091: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1092: cellspacing="0" cellpadding="0">
1.1.1.8 root 1093: <tr valign="top" align="left">
1094: <td width="21%"></td>
1095: <td width="77%">
1096: Falcon DSP emulation (x = none, dummy or emu, Falcon
1097: only)
1098: </td>
1099: </table>
1100: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1101: cellspacing="0" cellpadding="0">
1.1.1.8 root 1102: <tr valign="top" align="left">
1103: <td width="10%"></td>
1104: <td width="89%">
1105: <b>−−sound <x></b></td>
1106: </table>
1107: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1108: cellspacing="0" cellpadding="0">
1.1.1.8 root 1109: <tr valign="top" align="left">
1110: <td width="21%"></td>
1111: <td width="77%">
1.1.1.10! root 1112: Sound frequency: 6000-50066. "off" disables the sound and speeds up
! 1113: the emulation. To prevent extra sound artifacts, the frequency should be
! 1114: selected so that it either matches evenly with the STE/TT/Falcon sound
! 1115: DMA (6258, 12517, 250033, 50066 Hz) or your sound card frequencies
! 1116: (11025, 22050, 44100 or 6000...48000 Hz). Check what your sound card
! 1117: supports.
1.1.1.8 root 1118: </td>
1119: </table>
1120: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1121: cellspacing="0" cellpadding="0">
1.1.1.8 root 1122: <tr valign="top" align="left">
1123: <td width="10%"></td>
1124: <td width="89%">
1125: <b>−k, −−keymap
1126: <file></b></td>
1127: </table>
1128: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1129: cellspacing="0" cellpadding="0">
1.1.1.8 root 1130: <tr valign="top" align="left">
1131: <td width="21%"></td>
1132: <td width="77%">
1133: load keyboard mapping from <file>
1134: </td>
1135: </table>
1136: <a name="Debug options"></a>
1137: <h3>Debug options</h3>
1138: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1139: cellspacing="0" cellpadding="0">
1.1.1.8 root 1140: <tr valign="top" align="left">
1141: <td width="10%"></td>
1142: <td width="89%">
1.1.1.10! root 1143: <b>−D, −−debug</b></td>
1.1.1.8 root 1144: </table>
1145: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1146: cellspacing="0" cellpadding="0">
1.1.1.8 root 1147: <tr valign="top" align="left">
1148: <td width="21%"></td>
1149: <td width="77%">
1.1.1.10! root 1150: Toggle whether CPU exceptions invoke the debugger
1.1.1.8 root 1151: </td>
1152: </table>
1153: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1154: cellspacing="0" cellpadding="0">
1.1.1.8 root 1155: <tr valign="top" align="left">
1156: <td width="10%"></td>
1157: <td width="89%">
1158: <b>−−bios-intercept</b></td>
1159: </table>
1160: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1161: cellspacing="0" cellpadding="0">
1.1.1.8 root 1162: <tr valign="top" align="left">
1163: <td width="21%"></td>
1164: <td width="77%">
1165: Enable Bios/XBios interception
1166: </td>
1167: </table>
1168: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1169: cellspacing="0" cellpadding="0">
1.1.1.8 root 1170: <tr valign="top" align="left">
1171: <td width="10%"></td>
1172: <td width="89%">
1173: <b>−−trace <trace1,...></b></td>
1174: </table>
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="21%"></td>
1179: <td width="77%">
1180: Activate debug traces, see <b>--trace help</b> for available tracing options
1181: </td>
1182: </table>
1183: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1184: cellspacing="0" cellpadding="0">
1.1.1.8 root 1185: <tr valign="top" align="left">
1186: <td width="10%"></td>
1187: <td width="89%">
1188: <b>−−control-socket <file></b></td>
1189: </table>
1190: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1191: cellspacing="0" cellpadding="0">
1.1.1.8 root 1192: <tr valign="top" align="left">
1193: <td width="21%"></td>
1194: <td width="77%">
1195: Hatari reads options from given socket at run-time
1196: </td>
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="10%"></td>
1202: <td width="89%">
1203: <b>−−log-file <file></b></td>
1204: </table>
1205: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1206: cellspacing="0" cellpadding="0">
1.1.1.8 root 1207: <tr valign="top" align="left">
1208: <td width="21%"></td>
1209: <td width="77%">
1210: Save log output to <file> (default=stderr)
1211: </td>
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="10%"></td>
1217: <td width="89%">
1218: <b>−−log-level <x></b></td>
1219: </table>
1220: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1221: cellspacing="0" cellpadding="0">
1.1.1.8 root 1222: <tr valign="top" align="left">
1223: <td width="21%"></td>
1224: <td width="77%">
1225: Log output level (x=debug/todo/info/warn/error/fatal)
1226: </td>
1227: </table>
1228: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1229: cellspacing="0" cellpadding="0">
1.1.1.8 root 1230: <tr valign="top" align="left">
1231: <td width="10%"></td>
1232: <td width="89%">
1233: <b>−−alert-level <x></b></td>
1234: </table>
1235: <table width="100%" border=0 rules="none" frame="void"
1.1.1.9 root 1236: cellspacing="0" cellpadding="0">
1.1.1.8 root 1237: <tr valign="top" align="left">
1238: <td width="21%"></td>
1239: <td width="77%">
1240: Show dialog for log messages above given level
1241: </td>
1242: </table>
1.1.1.10! root 1243: <table width="100%" border=0 rules="none" frame="void"
! 1244: cellspacing="0" cellpadding="0">
! 1245: <tr valign="top" align="left">
! 1246: <td width="10%"></td>
! 1247: <td width="89%">
! 1248: <b>−−run-vbls <x></b></td>
! 1249: </table>
! 1250: <table width="100%" border=0 rules="none" frame="void"
! 1251: cellspacing="0" cellpadding="0">
! 1252: <tr valign="top" align="left">
! 1253: <td width="21%"></td>
! 1254: <td width="77%">
! 1255: Exit after X VBLs
! 1256: </td>
! 1257: </table>
1.1.1.8 root 1258:
1.1.1.5 root 1259:
1.1.1.7 root 1260: <p>Type <span class="commandline">hatari --help</span> to list all
1261: the command line options supported by a given version of Hatari.</p>
1262:
1.1.1.5 root 1263: <a name="Using the emulated system"></a><h2>Using the emulated system</h2>
1264:
1.1 root 1265: <p> Once you've started Hatari succesfully, you can use the emulator as
1.1.1.10! root 1266: an almost complete Atari ST computer system. </p>
1.1.1.5 root 1267:
1268: <a name="The GUI"></a><h3>The GUI</h3>
1269:
1.1.1.3 root 1270: <p>Press <span class="key">F12</span> to enter the GUI. Navigate it
1271: with the mouse.
1.1 root 1272: The GUI is rather self explanatory.</p>
1.1.1.5 root 1273:
1.1.1.8 root 1274: <a name="The Main Menu"></a><h4 class="gui">The Main Menu</h4>
1.1.1.5 root 1275:
1276: <div class="floatimage">
1.1.1.10! root 1277: <img src="images/main.png" width="500" height="304" alt="Hatari's GUI - the main menu">
1.1.1.5 root 1278: </div>
1279:
1280: <p>From the main menu, you can reach the other setup dialogs by clicking on
1281: the appropriate buttons.</p>
1282:
1283: <p>You can load the current settings from a configuration file by clicking
1.1.1.10! root 1284: on the <span class="button">Load config</span> button and you can save the
! 1285: current settings to a configuration file with the
! 1286: <span class="button">Save config</span> button.</p>
1.1.1.5 root 1287:
1.1.1.10! root 1288: <p>Click <span class="button">OK</span> to go back to the emulated
1.1.1.5 root 1289: ST. All changed options will be applied.</p>
1.1.1.10! root 1290: <p>Check the <span class="button">Reset machine</span> button if you want
! 1291: the emulated machine to perform a cold reset. This is equal to
1.1.1.5 root 1292: switching the power off and on again on a real ST.
1.1.1.3 root 1293: </p>
1294: <p>Click <span class="button">Quit</span> to terminate Hatari and
1295: return to the host OS.</p>
1296: <p>Click <span class="button">Cancel</span> to abandon any changes
1.1.1.5 root 1297: that you have made.</p>
1298:
1.1.1.10! root 1299:
! 1300: <a name="The File Selector Dialog"></a><h4 class="gui">The File Selector Dialog</h4>
! 1301:
! 1302: <div class="floatimage">
! 1303: <img src="images/fileselector.png" width="640" height="399" alt="Hatari's GUI - the fileselector">
! 1304: </div>
! 1305:
! 1306: <p>
! 1307: The file selector dialog appears whenever you are prompted to choose a file
! 1308: or folder.
! 1309: </p>
! 1310: <p>
! 1311: To enter a folder or choose a file, simply click on the entry in the main box
! 1312: of the dialog. You can use the arrows at the right, the cursor up and down
! 1313: keys and the page up and down keys to navigate through the list.
! 1314: </p>
! 1315: <p>
! 1316: You can use the three buttons in the upper right corner for additional folder
! 1317: navigation. Use the <span class="button">..</span> button to go up one level
! 1318: in the directory tree. Use the <span class="button">~</span> button to return
! 1319: to your home directory. The <span class="button">/</span> button can be used
! 1320: to go to the root directory of the file system.
! 1321: </p>
! 1322:
! 1323:
1.1.1.8 root 1324: <a name="The System Dialog"></a><h4 class="gui">The System Dialog</h4>
1.1.1.5 root 1325:
1326: <div class="floatimage">
1.1.1.10! root 1327: <img src="images/system.png" width="360" height="384" alt="Hatari's GUI - the system dialog">
1.1.1.5 root 1328: </div>
1329:
1.1.1.7 root 1330: <p>
1331: First you can select the CPU type here. Here are some important hints for
1332: choosing the correct CPU type:
1333: </p>
1334: <ul>
1335: <li>
1336: Atari ST and STE have only been shipped with a 68000 CPU, so for best
1337: compatibility with old programs, choose this CPU type.
1338: </li>
1339: <li>
1340: Atari TT and Falcon computers were using the 68030 CPU, so you should switch
1341: either to 68020 or 68020+FPU when you want to use TT or Falcon mode.
1342: (The 68020 and 68030 were pretty much the same apart from some minor details).
1343: </li>
1344: <li>
1345: TOS 1.0x only works with 68000, while TOS 3.0x and 4.0x work only with a CPU
1346: >= 68020.
1347: </li>
1348: <li>
1349: 68010 and 68040 have never been used in official Atari computers, so don't
1350: use these CPU types unless you've got some good reasons.
1351: </li>
1352: </ul>
1353:
1354: <p>
1355: Beside the CPU type, you can also choose the machine type to emulate.
1356: The ST was the very first 16/32-bit computer from Atari. Most older games
1357: and demos require an ST. The STE was introduced some years later and had
1358: some more advanced hardware features. There are not that many demos or
1359: games that really require an STE but since most normal ST games/demos also
1360: work with an STE, it's normally safe to always work in STE mode.
1361: <br>
1362: TT and Falcon are more advanced, but they are not as compatible to the ST as
1.1.1.8 root 1363: the STE was. Therefore many old games and demos do not work with these machine
1364: types anymore. There were only very few programs that were made for the TT
1.1.1.7 root 1365: exclusively, while there were some interesting games and demos specially made
1366: for the Falcon.
1367: <em>Note:</em> TT and Falcon emulation are very incomplete. They may not work
1368: very well.
1369: </p>
1370: <p>
1371: For STE emulation a STE compatible TOS image, e.q. version 1.06, 1.62 or
1372: 2.x, is strongly recommended. For TT emulation you need TOS 3.0x and for Falcon
1373: emulation you need TOS 4.0x. EmuTOS can be used on all machine types.
1374: </p>
1375: <p>
1376: Select the CPU clock you want to use. 8Mhz is ST standard and the most
1377: compatible. Use 16MHz for Mega STE and Falcon emulation.
1378: The CPU in the TT was clocked with 32 MHz.
1379: </p>
1.1.1.5 root 1380: <p>With the "Slower but more compatible CPU" option, you can enable
1381: the emulation of 68k address errors and the CPU prefetch buffer. This is needed
1382: for best compatibility, but it slows down emulation a little bit so you can
1383: disable it if you don't need it.</p>
1.1.1.10! root 1384: <p>
! 1385: For Falcon mode, you can choose whether you want to enable DSP emulation,
! 1386: fake it or completely disable it. Most Falcon programs only play sound or work
! 1387: correctly when you enable the DSP emulation, but it needs a lot of host CPU
! 1388: power (more than 2 GHz). So if you have a slow host CPU, you can try if your
! 1389: Falcon program also runs with DSP disabled or in "dummy" mode.
! 1390: Note that you can not change this option while the DSP based program already
! 1391: runs.
! 1392: </p>
1.1.1.5 root 1393: <p>You can also enable/disable Blitter emulation here. The Blitter is a custom
1394: chip that accelerates some graphical operations. This switch only toggles the
1395: Blitter in plain ST mode. In STE mode, the Blitter is always enabled (since all
1396: STEs have been sold with a Blitter chip).</p>
1397: <p>If you enable the "Real time clock emulation" switch, a RTC will
1398: be emulated based on the time of the host computer. Note that you need at least
1399: TOS 1.02 for proper RTC emulation, TOS 1.00 does not support this.</p>
1400: <p>The Timer-D patch changes the Timer-D initialization from TOS. TOS uses
1401: the MFP timer D as a baudrate generator for RS232. However, the TOS default
1402: value slows down the emulation. The patch gives you a better performance.
1.1.1.7 root 1403: It is normally safe to enable the patch, but if you encounter a program that
1.1.1.5 root 1404: does not work, you can try to disable the patch to see if it works then.</p>
1.1.1.3 root 1405: <p><em>NOTE:</em> These parameters are very sensitive to the emulated
1406: ST and it is strongly recommended to
1.1 root 1407: reset the emulated ST after changing these options.</p>
1.1.1.5 root 1408:
1409:
1.1.1.10! root 1410: <a name="The Floppy Disks Dialog"></a><h4 class="gui">The Floppy Disks Dialog</h4>
1.1.1.5 root 1411:
1.1.1.10! root 1412: <div class="floatimage">
! 1413: <img src="images/floppydisks.png" width="640" height="320" alt="Hatari's GUI - the floppy disks dialog">
1.1.1.5 root 1414: </div>
1415:
1.1.1.10! root 1416: <p>
! 1417: This dialog can be used to choose which floppy disks should be emulated
! 1418: in the disk drives. You can use most standard Atari ST disk image files.
! 1419: You may select and browse also zipped disk images. See the chapter
! 1420: <a href="#Floppy disk images">"Floppy disk images"</a> for details.
! 1421: </p>
! 1422: <p>
! 1423: Click on the button <span class="button">Browse</span> next to the
! 1424: A: and B: option to go to the fileselector to choose a disk image for the
! 1425: corresponding drive.
! 1426: </p>
1.1.1.3 root 1427: <p>Click on <span class="button">Eject</span> to eject a disk image
1428: from the emulated drive. The emulated ST will act as if had no floppy
1429: disk in its drive.</p>
1430: <p>You can specify a default directory where Hatari will start to
1431: browse the filesystem.</p>
1.1.1.2 root 1432: <p>
1.1.1.6 root 1433: Check the "Auto insert B" option if you want Hatari to be smart and
1434: insert the second disk of a two disk game automatically.
1435: Some games then use the second drive automatically.
1436: In the case that a game is not able to find the disk in the second drive,
1437: you have to insert the second disk in drive A: manually when prompted.
1438: <br>
1439: <em>NOTE:</em> This option only works properly if the file name of the
1440: first disks ends with an 'a' before the extension and the second disk name
1441: ends with a 'b'.
1.1.1.2 root 1442: </p>
1.1.1.10! root 1443: <p>
! 1444: Select if you want to use slow FDC (Floppy Disk Controller) emulation.
! 1445: "Slow floppy access" is normally not required, except for some few
! 1446: slideshows / intros which run too fast without this option.
! 1447: </p>
! 1448: <p>
! 1449: You can choose if you want Hatari to write-protect your disks. Atari ST virii
! 1450: can spread on disk images too so it might be a good idea to enable the write
! 1451: protection option. However you can't save highscores or games to your disk
! 1452: images in that case.
! 1453: </p>
! 1454:
! 1455: <div class="floatimage">
! 1456: <img src="images/newfloppy.png" width="280" height="192" alt="Hatari's GUI - the new floppy dialog">
! 1457: </div>
! 1458:
! 1459: <p>
! 1460: If you need to create a new blank disk image, click on
! 1461: <span class="button">Create blank image</span>.
! 1462: Parameters for the new image can be set in the following dialog.
! 1463: Click on <span class="button">Create</span> to save the new image or on
! 1464: <span class="button">Back</span> to return to the disk dialog.
! 1465: </p>
! 1466: <p>
! 1467: After clicking <span class="button">Create</span>, a fileselector
! 1468: appears. You can browse the filesystem now. Select the target directory,
! 1469: click beside "File:" and type in a name for the new disk image.
! 1470: The name should terminate with .st or .msa.
! 1471: </p>
! 1472: <p>
! 1473: Hatari can currently create plain .ST and .MSA disk images exclusively.
! 1474: </p>
! 1475:
! 1476:
! 1477: <a name="The Hard Disks Dialog"></a><h4 class="gui">The Hard Disks Dialog</h4>
! 1478:
! 1479: <div class="floatimage">
! 1480: <img src="images/harddisks.png" width="640" height="256" alt="Hatari's GUI - the hard disks dialog">
! 1481: </div>
! 1482:
! 1483: <p>
! 1484: This dialog can be used to change the harddisk settings.
! 1485: </p>
! 1486: <p>
! 1487: You can select a harddrive image for ACSI or IDE hard drive emulation via
! 1488: image file here or you may select a directory of your local filesystem to be
! 1489: emulated as the harddrive of the emulated system.
! 1490: </p>
! 1491: <p>
! 1492: Check "Boot from HD" if you want Hatari to execute the AUTO folder
! 1493: on the harddrive.
! 1494: This option is checked by default if you specify a harddrive image or a
! 1495: directory via the command line.
! 1496: </p>
! 1497: <p>
! 1498: Note that for IDE hard disk emulation you also need a TOS version >= 2.05.
! 1499: And ACSI hard disk emulation does not work with TOS 4.0x in Falcon mode.
! 1500: </p>
! 1501:
1.1.1.5 root 1502:
1.1.1.8 root 1503: <a name="The Memory Dialog"></a><h4 class="gui">The Memory Dialog</h4>
1.1.1.5 root 1504:
1.1.1.8 root 1505: <div class="floatimage">
1506: <img src="images/memory.png" width="398" height="349" alt="Hatari's GUI - the memory dialog">
1.1.1.5 root 1507: </div>
1508:
1.1.1.3 root 1509: <p>You can select the amount of RAM for the emulated ST here. Only
1510: amounts that were valid on a real unmodified STFM can be selected.</p>
1511: <p><em>Note:</em> This option is critical and you are strongly advised
1512: to reset the emulated ST
1.1 root 1513: when changing this option.</p>
1.1.1.2 root 1514: <p>Here you will find the options to save memory snapshots as well.</p>
1.1.1.3 root 1515: <p>Click on <span class="button">Save</span> to save a memory snapshot
1516: to file. You can select a new filename here.</p>
1517: <p>Click on <span class="button">Restore</span> to restore a memory
1518: snapshot from a file. Use the fileselector to select the snapshot to be
1519: restored.</p>
1520: <p><em>NOTE:</em> Memory snapshots are not interchangeable between
1521: different versions of Hatari. E.q. if you compile a newer Hatari, you
1522: cannot load your old memory snapshots back.</p>
1523:
1.1.1.5 root 1524:
1.1.1.8 root 1525: <a name="The ROM Dialog"></a><h4 class="gui">The ROM Dialog</h4>
1526:
1527: <div class="floatimage">
1528: <img src="images/tos.png" width="519" height="367" alt="Hatari's GUI - the ROM dialog">
1.1.1.5 root 1529: </div>
1530:
1.1.1.3 root 1531: <p>Here you can select the TOS image to use. Click on <span
1.1.1.5 root 1532: class="button">Browse</span> to select it via the fileselector.
1.1.1.3 root 1533: You can also select an optional cartridge image to use. Click on <span
1.1.1.4 root 1534: class="button">Browse</span> to select one via the fileselector. Click on <span
1.1.1.5 root 1535: class="button">Eject</span> to disconnect the custom cartridge image.
1536: </p>
1.1.1.7 root 1537: <p>
1538: For ST mode, use TOS 1.00, 1.02, 1.04 or 2.06.
1539: For STE mode, use TOS 1.06, 1.62, 2.05 or 2.06.
1540: If you want to use the TT mode, you must specify a TOS 3.06 image here.
1541: And in Falcon mode, you have to use either TOS 4.00, 4.02, 4.04 or 4.92.
1542: However, you should always use TOS 4.04 for Falcon mode, it's the most common one.
1543: Also note that TOS 4.92 can not be booted from a boot disk (like it's done on a
1544: real Falcon), you have to specify it directly in the TOS ROM setup dialog here.
1545: </p>
1546: <p>
1547: Keep in mind that any custom cartridge image will not work together with
1.1.1.5 root 1548: GEMDOS hard disk emulation or the VDI extended resolution emulation
1.1.1.3 root 1549: since some additional driver code will be used in the cartridge memory
1.1.1.7 root 1550: space for these emulations.
1551: </p>
1552: <p>
1553: <em>Note:</em> These options are critical and you are strongly
1.1.1.3 root 1554: advised to reset the emulated ST
1.1.1.7 root 1555: when changing one of these option.
1556: </p>
1.1.1.5 root 1557:
1.1.1.8 root 1558:
1559: <a name="The Joystick Dialog"></a><h4 class="gui">The Joystick Dialog</h4>
1.1.1.5 root 1560:
1561: <div class="floatimage">
1562: <img src="images/joystick.png" width="320" height="288" alt="Hatari's GUI - the joystick dialog">
1563: </div>
1564:
1565: <p>In this dialog, you can configure the emulated joysticks.
1566: With the upper two arrows, you can choose the joystick which you want to
1567: configure.</p>
1.1.1.3 root 1568: <p>Joystick 1 is the normal ST joystick port and 99.9% of all ST games
1.1.1.5 root 1569: use this port.
1570: Joystick 0 emulates a joystick plugged into the ST mouse port
1571: and is often used in games for two players.</p>
1572: <p>With STE joypad A and B, you can enable the emulation of Jaguar joypads
1573: which are plugged in the enhanced joystick ports of the Atari STE.
1574: Only very few STE games support these joypads, so you often won't need this.</p>
1575: <p>Finally, Hatari also emulates joysticks which were plugged on the parallel
1576: port with a special adapter on a real ST. These were used in some few
1577: multi-player games like "Gauntlet 2".</p>
1578: <p>For each ST joystick, choose whether you want to disable it,
1579: use the keyboard for emulation or use a real PC joystick.</p>
1580: <p>For keyboard emulation, you can select the keys by pressing the
1.1.1.10! root 1581: <span class="button">Define keys</span> button. You will be prompted to press
1.1.1.5 root 1582: the keys for up, down, left, right and fire.</p>
1583: <p>If you want to use a real PC joystick for the emulation, you should connect
1584: it to your PC before you start Hatari. Then you can choose the joystick with
1585: the two lower arrows.</p>
1586: <p>Check the "Enable autofire" option if you are too lazy to pound
1587: on the fire button in shoot'em-up games. However, this option only works with
1588: certain games. In some other games, it gets worse if you enable this option.</p>
1589: <p>See also the chapter "Emulated Joystick" for details.</p>
1590:
1.1.1.8 root 1591:
1592: <a name="The Screen Dialog"></a><h4 class="gui">The Screen Dialog</h4>
1.1.1.5 root 1593:
1.1.1.7 root 1594: <div class="floatimage">
1.1.1.8 root 1595: <img src="images/screen.png" width="498" height="399" alt="Hatari's GUI - the screen dialog">
1.1.1.5 root 1596: </div>
1.1 root 1597:
1.1.1.7 root 1598: <p>
1599: Here you control the video output of the emulated Atari.
1600: </p>
1601: <p>
1602: Check "Fullscreen" to run Hatari fullscreen, default is windowed.
1603: </p>
1604: <p>
1605: "Use Borders" toggles the displaying of the borders around the ST
1606: screen. Some few demos/games use the borders for displaying additional
1607: graphics. However, when you enable this option, it increases CPU computing
1608: time, so you should not enable it if you have a slow computer.
1609: Please note that this option also only affects the ST and STE mode, TT and
1610: Falcon modes are always displayed without borders.
1611: </p>
1612: <p>
1613: "Zoom ST-Low res." controls whether Hatari doubles the low
1614: resolutions. For example Hatari then zooms the ST low resolution 320x200 to
1615: 640x400 and it doubles 384x267 (ST low with borders) to 768x534.
1616: Note that zooming also takes a lot of CPU computing time and should not be
1617: enabled on slow computers.
1618: </p>
1619: <p>
1.1.1.8 root 1620: "Statusbar" toggles the statusbar at the bottom of the screen.
1621: The statusbar shows the floppy drive LEDs, the current frameskip value,
1622: the machine type including TOS version and memory size, and whether
1623: recording is currently active.
1.1.1.7 root 1624: </p>
1625: <p>
1626: The "Frame Skip" option can be set to speed up the emulator
1.1.1.8 root 1627: if it is running too slow on your system. Disable frame-skip if you have
1628: a fast computer. When selecting 1, 2 or 4, drawing of corresponding number
1629: of frames will be skipped after each frame actually shown by Hatari.
1630: Select "Auto" to let the emulator to decide whether, and
1631: how many frames will be skipped.<br>
1632: <em>Note:</em> The frameskip option also affects the frame rate of the
1633: screen animation recording!
1.1.1.7 root 1634: </p>
1635: <p>
1636: You can select which sort of monitor to use. This option depends on the
1637: machine type which you have selected in the "System options"
1638: dialog. In ST and STE mode, you can choose between monochrome mode (select
1639: "Mono") and color mode (select one of the other monitor types).
1640: Note that when you select "TV" and use zoomed low resolution or
1641: switch to ST medium resolution, you will get a TV-like screen rendering
1642: which is a little bit faster but darker compared to the normal "RGB"
1643: monitor mode. Switching between mono and a color monitor acts like a monitor
1644: switch on a real ST - so beware, this will reboot your emulated system!<br>
1645: In TT mode, you can only choose between TT-high resolution ("Mono")
1646: and normal modes (select one of the other monitor types).
1647: Finally the Falcon mode supports all four types of monitors. Note that most
1648: Falcon demos/games require a RGB or TV mode and do not work with VGA.
1649: </p>
1650: <p>
1.1.1.3 root 1651: Extended GEM resolutions will emulate some sort of extended graphics
1652: card in the emulated ST giving you larger resolutions and a higher
1653: colordepth in GEM. Select a resolution and color depth. Check to
1654: activate. It will disable all other video options mentioned above.
1655: Uncheck to get back to a normal ST behaviour.<br>
1656: <em>Note:</em> Using an extended resolution will only work with GEM
1657: conformant applications. 99% of all games and demos will not run if you
1.1.1.7 root 1658: activate any extended resolution here.
1659: </p>
1.1.1.10! root 1660: <p>Click <span class="button">Capture Screen</span> to create a
1.1.1.8 root 1661: screenshot in PNG (or BMP) format to the current working directory or click
1.1.1.10! root 1662: <span class="button">Record Animation</span> to record a sequence of single
1.1.1.3 root 1663: screenshots. You can opt to only record new movie frames when the
1664: screen content really changed.
1.1 root 1665: </p>
1.1.1.5 root 1666:
1.1.1.8 root 1667:
1668: <a name="The Keyboard Dialog"></a><h4 class="gui">The Keyboard Dialog</h4>
1.1.1.5 root 1669:
1670: <div class="floatimage">
1.1.1.8 root 1671: <img src="images/keyboard.png" width="459" height="223" alt="Hatari's GUI - the keyboard dialog">
1.1.1.5 root 1672: </div>
1673:
1674: <p>Here you can select the keyboard mapping to use. Two different mappings
1675: called "Symbolic" and "Scancode" are predefined.</p>
1676: <p>"Symbolic" tries to map the symbolic values of your PC keys
1677: to the ST keys. It should be working pretty good on all systems as long
1678: as your keyboard layout looks close to the standard english keyboard
1679: layout. However, you might experience some problems with special keys like
1680: brackets etc.</p>
1681: <p>"Scancode" uses the scancode values of your PC keys for keyboard
1682: mapping. This only works on certain architectures like Linux where the
1683: scancodes are similar to the ST scancodes (e.g. it does not work on Mac OS X).
1684: If it works on your system, this often gives better results than the symbolic
1685: mapping. Note that you also need a TOS version with the right language
1686: (e.g. use a French TOS if you are using a French keyboard).</p>
1687: <p>You can also load a custom keyboard mapping file here if you wish. Please
1.1.1.6 root 1688: note that the custom keyboard mapping will use the "symbolic"
1689: mapping for all keys that are not defined by your map file. Have a look
1690: at the supplied example mapfile (keymap-sample.txt) to see how to create
1691: your own keyboard mapping.</p>
1.1.1.8 root 1692: <p>
1693: When the emulator runs in fast forward mode, and you want to type text,
1694: it can be annoying that the emulated system detects multiple key events
1695: due to the key repetition of the emulated system. To avoid this you can
1696: disable the key repetition in fast forward mode here.
1697: </p>
1.1.1.5 root 1698:
1699:
1.1.1.8 root 1700: <a name="The Sound Dialog"></a><h4 class="gui">The Sound Dialog</h4>
1701:
1702: <div class="floatimage">
1.1.1.10! root 1703: <img src="images/sound.png" width="380" height="384" alt="Hatari's GUI - the sound dialog">
1.1.1.5 root 1704: </div>
1705:
1.1.1.2 root 1706: <p>Here you can control the sound subsystem.</p>
1.1.1.3 root 1707: <p>Check if you want emulated sound at all. Emulation is faster if
1708: sound emulation is turned off.</p>
1.1.1.10! root 1709: <p>
! 1710: Nine frequencies from low to high quality are available. Experiment a
! 1711: little bit to find out which fits best for your setup.
! 1712: For most modern computers, 44100 Hz or 48000 Hz should be fine.
! 1713: For older or slower host systems, you should use a lower frequency.
! 1714: 12517, 250033 and 50066 Hz are frequencies supported by
! 1715: the STE/TT/Falcon sound DMA.
! 1716: </p>
! 1717: <p>
! 1718: You can select to record a piece of sound here.
! 1719: Use the <span class="button">Browse</span> button to choose a file.
! 1720: The file name extension that you use (.WAV or .YM) determines in which format
! 1721: the sound is recorded in. The <span class="button">Record sound</span> button
! 1722: is a toggle so you will need to return to the GUI to switch sound recording off
! 1723: again (or to use the keyboard shortcut for that).
! 1724: </p>
1.1.1.5 root 1725:
1726:
1.1.1.8 root 1727: <a name="The Devices Dialog"></a><h4 class="gui">The Devices Dialog</h4>
1.1.1.5 root 1728:
1.1.1.8 root 1729: <div class="floatimage">
1.1.1.10! root 1730: <img src="images/devices.png" width="520" height="383" alt="Hatari's GUI - the device dialog">
1.1.1.5 root 1731: </div>
1732:
1.1.1.10! root 1733: <p>Check the first checkmark to enable experimental printer support.
! 1734: See the <a href="#Emulated printer">Emulated printer</a> section for
! 1735: details.</p>
1.1.1.8 root 1736:
1.1.1.3 root 1737: <p>As Hatari currently only supports printing to file, click on <span
1.1.1.10! root 1738: class="button">Browse</span> to select the file to print to. You can
1.1.1.3 root 1739: enter a new filename as well.</p>
1.1.1.10! root 1740: <p>Check the second checkmark to enable experimental RS232 support.
! 1741: The RS232 device is configured according to the settings of
1.1.1.3 root 1742: the emulated RS232 of the Atari ST. This means Hatari will
1743: automatically use baudrate and handshaking as configured for the
1744: emulated ST.</p>
1.1.1.10! root 1745: <p>Click on <span class="button">Browse</span> to select suitable
! 1746: device files for serial input and output. On Linux a good choice is
! 1747: /dev/ttyS0 or /dev/ttyS1.
! 1748: </p>
! 1749: <p>Check the third checkmark to enable experimental MIDI support.
! 1750: Click on <span class="button">Browse</span> to select a suitable
! 1751: MIDI device files for MIDI input and output.</p>
! 1752: <p><span class="file">midi-linux.txt</span> file explains how to
! 1753: select the correct MIDI device file, how to set up softare sound
! 1754: synthetizing on Linux (using Alsa), if your sound card/driver doesn't
! 1755: support MIDI, and how to set up MIDI networking between multiple
! 1756: Hatari instances.
1.1.1.2 root 1757: </p>
1.1.1.5 root 1758:
1.1.1.8 root 1759:
1760: <a name="Keyboard shortcuts"></a><h3 style="clear:both;">Keyboard shortcuts</h3>
1.1.1.5 root 1761:
1.1 root 1762: <p> While the emulator is running, you can activate or toggle various
1.1.1.6 root 1763: features via Hatari keyboard shortcuts. Below are listed the default
1764: shortcut key bindings:</p>
1.1.1.3 root 1765: <table border="1" cellpadding="3">
1.1 root 1766: <tbody>
1767: <tr class="backdropped">
1768: <td align="center">Shortcut</td>
1769: <td align="center">Purpose</td>
1770: </tr>
1771: <tr>
1.1.1.2 root 1772: <td align="center"><span class="key">ALTGR+a</span></td>
1773: <td align="center">record animation</td>
1774: </tr>
1775: <tr>
1.1 root 1776: <td align="center"><span class="key">ALTGR+g</span></td>
1.1.1.8 root 1777: <td align="center">grab a screenshot</td>
1.1 root 1778: </tr>
1779: <tr>
1.1.1.2 root 1780: <td align="center"><span class="key">ALTGR+i</span></td>
1.1.1.8 root 1781: <td align="center">boss key: leave full screen mode, pause Hatari
1782: and iconify its window</td>
1.1.1.2 root 1783: </tr>
1784: <tr>
1.1 root 1785: <td align="center"><span class="key">ALTGR+j</span></td>
1.1.1.8 root 1786: <td align="center">toggle joystick emulation via cursor keys
1787: on/off between ports 0 and 1</td>
1.1 root 1788: </tr>
1789: <tr>
1790: <td align="center"><span class="key">ALTGR+m</span></td>
1.1.1.8 root 1791: <td align="center">(un-)lock the mouse into the window</td>
1.1 root 1792: </tr>
1793: <tr>
1794: <td align="center"><span class="key">ALTGR+r</span></td>
1.1.1.2 root 1795: <td align="center">(warm) reset the ST</td>
1.1 root 1796: </tr>
1797: <tr>
1798: <td align="center"><span class="key">ALTGR+c</span></td>
1.1.1.3 root 1799: <td align="center">coldreset the ST (same as the original power
1800: switch)</td>
1.1 root 1801: </tr>
1802: <tr>
1.1.1.8 root 1803: <td align="center"><span class="key">ALTGR+d</span></td>
1804: <td align="center">open dialog to select/change disk A</td>
1805: </tr>
1806: <tr>
1.1.1.2 root 1807: <td align="center"><span class="key">ALTGR+s</span></td>
1808: <td align="center">enable/disable sound</td>
1809: </tr>
1810: <tr>
1.1 root 1811: <td align="center"><span class="key">ALTGR+q</span></td>
1812: <td align="center">quit the emulator</td>
1813: </tr>
1814: <tr>
1.1.1.2 root 1815: <td align="center"><span class="key">ALTGR+x</span></td>
1.1.1.10! root 1816: <td align="center">toggle normal speed/fast forward</td>
1.1.1.2 root 1817: </tr>
1818: <tr>
1819: <td align="center"><span class="key">ALTGR+y</span></td>
1820: <td align="center">enable/disable sound recording</td>
1821: </tr>
1822: <tr>
1.1.1.7 root 1823: <td align="center"><span class="key">ALTGR+k</span></td>
1824: <td align="center">save memory snapshot</td>
1825: </tr>
1826: <tr>
1827: <td align="center"><span class="key">ALTGR+l</span></td>
1828: <td align="center">load memory snapshot</td>
1829: </tr>
1830: <tr>
1.1.1.5 root 1831: <td align="center"><span class="key">ALTGR+f or F11</span></td>
1.1.1.8 root 1832: <td align="center">toggle between fullscreen and windowed mode</td>
1.1 root 1833: </tr>
1834: <tr>
1.1.1.5 root 1835: <td align="center"><span class="key">ALTGR+o or F12</span></td>
1.1.1.8 root 1836: <td align="center">activate the options GUI</td>
1.1 root 1837: </tr>
1838: <tr>
1839: <td align="center"><span class="key">PAUSE</span></td>
1.1.1.10! root 1840: <td align="center">pause emulation</td>
! 1841: </tr>
! 1842: <tr>
! 1843: <td align="center"><span class="key">AltGr+PAUSE</span></td>
! 1844: <td align="center">invoke the internal Hatari debugger</td>
1.1 root 1845: </tr>
1846: </tbody>
1847: </table>
1.1.1.5 root 1848:
1.1.1.6 root 1849: <p>You can change the key bindings from the Hatari configuration file.
1.1.1.10! root 1850: The required key values can be seen in the SDL_keysym.h include file
1.1.1.8 root 1851: (usually in /usr/include/SDL/).</p>
1.1.1.6 root 1852:
1853:
1.1.1.5 root 1854: <a name="Emulated Atari ST keyboard"></a><h3>Emulated Atari ST keyboard</h3>
1855:
1.1 root 1856: <p> All other keys on the keyboard act as the normal Atari ST keys so
1857: pressing SPACE on your PC will result in an emulated press of the SPACE
1858: key on the ST. The following keys have special meanings: </p>
1.1.1.3 root 1859: <table border="1" cellpadding="3">
1.1 root 1860: <tbody>
1861: <tr class="backdropped">
1862: <td align="center">Key</td>
1863: <td align="center">Meaning</td>
1864: </tr>
1865: <tr>
1866: <td align="center"><span class="key">Alt</span></td>
1867: <td align="center">will act as the ST's ALTERNATE key</td>
1868: </tr>
1869: <tr>
1870: <td align="center"><span class="key">left CTRL</span></td>
1871: <td align="center">will act as the ST's CONTROL key</td>
1872: </tr>
1873: <tr>
1.1.1.2 root 1874: <td align="center"><span class="key">Print Screen</span></td>
1.1 root 1875: <td align="center">will emulate the ST's HELP key</td>
1876: </tr>
1877: <tr>
1.1.1.2 root 1878: <td align="center"><span class="key">Scroll Lock</span></td>
1.1 root 1879: <td align="center">will emulate the ST's UNDO key</td>
1880: </tr>
1.1.1.2 root 1881: <tr>
1882: <td align="center"><span class="key">Page Up</span></td>
1883: <td align="center">will emulate the ST's ( key in the keypad</td>
1884: </tr>
1885: <tr>
1886: <td align="center"><span class="key">Page Down</span></td>
1887: <td align="center">will emulate the ST's ) in the keypad</td>
1888: </tr>
1.1 root 1889: </tbody>
1890: </table>
1.1.1.5 root 1891:
1.1.1.8 root 1892: <p>If joystick emulation via keyboard is enabled, by default cursor keys
1893: are used for the directions and <span class="key">right CTRL</span> key
1894: as the fire button. Otherwise they act as corresponding keys of the emulated
1895: Atari ST.</p>
1896:
1.1.1.5 root 1897:
1898: <a name="Emulated mouse"></a><h3>Emulated mouse</h3>
1899:
1.1 root 1900: <p>For obvious reasons your PC mouse will act as the emulated Atari ST
1901: mouse. In fullscreen mode it will act as expected, directly controlling
1902: the ST mouse pointer. </p>
1903: <p>However it is a little bit different in windowed mode. To make the
1904: mouse work there as expected you need to grab it first or lock it into
1.1.1.3 root 1905: the Hatari window. Do this by pressing the <span class="key">ALTGR+m</span>
1.1.1.10! root 1906: hotkey combination or starting Hatari with the
! 1907: <span class="commandline">--grab</span> command line option.
! 1908: Press the shortcut key (again) to go back to normal mouse behaviour
! 1909: which allows you to move mouse outside outside the Hatari window while
! 1910: Hatari is up and running. Note: pausing the emulation will also
! 1911: (temporarily) release the mouse grab.</p>
1.1.1.6 root 1912: <p>Mouse scrollwheel will act as cursor up and down keys. </p>
1.1.1.5 root 1913:
1914: <a name="Emulated joystick"></a><h3>Emulated joystick</h3>
1915:
1.1 root 1916: <p>The Atari ST joysticks are emulated ofcourse allowing you to play
1917: your favourite games with Hatari. </p>
1918: <p>The default mode is to use a connected PC joystick. You can use any
1919: joystick that is supported by your kernel. If your joystick works with
1920: other applications, it will likely work with Hatari as well. Make sure
1921: it is calibrated and then off you go. Move the stick to point into the
1922: desired direction. Please note that Hatari will not detect analogue
1923: movement as the Atari ST only had digital joysticks. The first
1.1.1.3 root 1924: firebutton will act as the normal firebutton on the Atari ST while the
1925: second
1926: firebutton will emulate a keypress of the <span class="key">SPACE</span>
1927: key on the ST as many ST
1.1.1.8 root 1928: games utilize the SPACE bar for secondary game functions. (Xenon for
1.1.1.3 root 1929: example)</p>
1.1 root 1930: <p>If you do not have a PC joystick or joypad, then you do not need to
1931: desperate. You can emulate one of the two Atari ST joysticks via the
1932: cursor keys. Just activate it in the GUI. Then the cursor keys will act
1933: as the joystick directions, the right CTRL key will act as the
1934: firebutton. You can still use the cursor keys as the ST's
1.1.1.3 root 1935: cursorkeys in this mode as long as you press <span class="key">SHIFT</span>
1.1.1.8 root 1936: along with the cursorkeys. You can also configure these keys from the
1937: joystick options.</p>
1.1.1.5 root 1938:
1939: <a name="Emulated video"></a><h3>Emulated video</h3>
1940:
1.1.1.8 root 1941: <p>Hatari emulates all screen modes of the original machine.</p>
1942: <p>
1943: ST/STE shifter overscan effects are emulated, but due to the fact
1944: that these effects are achieved by using quirks and glitches in the
1945: original chips to do things beyond their specification, emulation is
1946: a bit tricky for these effects. As a result, some demos using these
1947: techniques might not be displayed correctly in Hatari, known ones are
1948: listed in the <span class="file">compatibility.html</span> file.
1.1.1.3 root 1949: </p>
1950: <p>Beside that you can setup extended VDI modes. These only work with
1951: GEM-compliant applications and they are equal to fitting a videocard
1952: into your Mega ST.</p>
1953: <p>Make sure to disable extended VDI modes for playing games as 99% of
1954: all ST games will not be able to make use of higher resolutions.</p>
1.1.1.5 root 1955:
1956: <a name="Emulated printer"></a><h3>Emulated printer</h3>
1957:
1.1.1.3 root 1958: <p>Due to the fact that printer handling is very different between Unix
1959: style machines and the Atari ST, emulation
1.1.1.2 root 1960: of the printer is achieved by writing all printer output to a file.</p>
1.1.1.3 root 1961: <p>The file will contain a sequence of data, the same that would appear
1962: on the data pins of the Atari ST printer port.
1963: That would include control characters and commands for graphic
1964: printing. Clicking "Print desktop" on the GEM desktop would result
1.1.1.2 root 1965: in a messy data dump in the printer output.</p>
1.1.1.3 root 1966: <p>Printer emulation works best for plain text files or programs that
1967: do not format the output for a specific printer.
1968: The file contents can be used with your favourite text editor for
1969: further processing and printing to a real printer.</p>
1970: <p>To get real direct printing out of Hatari on a PostScript printer,
1971: you may set up a GDOS printer with a PostScript driver on the emulated
1972: Atari and set your printer device file as Hatari's printer output.<br>
1973: <em>NOTE:</em> This has not been tested yet and the Hatari team cannot
1974: guarantee that it will work.</p>
1.1.1.5 root 1975:
1976: <a name="Emulated RS232"></a><h3>Emulated RS232</h3>
1977:
1.1.1.3 root 1978: <p>Serial communications in Hatari is designed to directly use a serial
1979: port on your PC.</p>
1980: <p>Communications parameters are set automatically upon the settings of
1981: the emulated ST. This means all you do is to set
1982: the communication parameters like baudrate from your ST communications
1983: software. Hatari will do the rest and handle
1.1.1.2 root 1984: the serial input and output for you.</p>
1.1.1.5 root 1985:
1986: <a name="Floppy disk images"></a><h2>Floppy disk images</h2>
1987:
1.1 root 1988: <p>Hatari does not use floppy disks directly but disk images due to
1989: differences between the floppy disk controllers of the ST and the PC.
1.1.1.3 root 1990: Three types of disk images are currently supported: The raw "ST" type,
1991: the similar "DIM" type and
1.1.1.2 root 1992: the compressed "MSA" (Magic-Shadow-Archiver) type. </p>
1.1 root 1993: <p> The raw type (file suffix should be "*.st") is simply a sector by
1994: sector image of a real floppy disk. You can easily create such an image
1.1.1.3 root 1995: with the <span class="commandline">dd</span> program which should
1996: normally be pre-installed on every
1997: Unix-like system. Simply type something like <span class="commandline">dd
1998: if=/dev/fd0 of=myimage.st</span> to create a disk image. Of course you
1999: need access to
1.1 root 2000: /dev/fd0, and depending on your system and the type of floppy disk you
2001: might have to use another device name here (for example I use
1.1.1.3 root 2002: /dev/fd0u720 for 720kB disks). However, if the disk is copy-protected
2003: or
1.1 root 2004: doesn't use a MSDOS compatible file system, this might fail. So be very
1.1.1.10! root 2005: careful if you are not sure about the disk format. </p>
1.1.1.3 root 2006: <p> The other possibility is to image the disk on a real Atari ST.
2007: There
1.1 root 2008: are programs like the Magic Shadow Archiver for this task. Hatari
1.1.1.3 root 2009: supports this slightly compressed MSA disk images, too. Note that
2010: Hatari
2011: only supports the "old" MSA format, there are some Magic Shadow
2012: Archiver
1.1 root 2013: clones (like Jay-MSA) that create better compressed but
1.1.1.2 root 2014: Hatari-incompatible disk images. However, if you have got such a MSA
1.1.1.3 root 2015: disk and want to use it with Hatari, you can still run the
2016: corresponding
1.1.1.2 root 2017: MSA program within Hatari to extract the incompatible disk image to a
2018: normal floppy disk image. </p>
1.1 root 2019: <p> While *.ST and *.MSA are more or less the "standard" types of Atari
1.1.1.2 root 2020: disk images, you might sometimes also find STT or ADF images on the
1.1.1.3 root 2021: internet. These currently do not work with Hatari. </p>
2022: <p>Hatari can now also utilize *.DIM images just as *.ST ones without
2023: any problems.
1.1.1.2 root 2024: Note that DIM images are nearly the same as the raw ST images
1.1.1.3 root 2025: (they only have an additional 32 bytes header), so you can easily
2026: transform
1.1.1.2 root 2027: the DIM images into ST images by stripping the header from the files.
2028: For example try something like:
2029: <span class="commandline">dd if=input.dim of=output.st bs=32 skip=1</span>
2030: </p>
1.1 root 2031: <p> If you've got a disk image that has been created with the old ST
2032: emulator PaCifiST (for DOS) or with early versions of the program
2033: Makedisk, and the disk image does not work with Hatari, then the disk
1.1.1.3 root 2034: probably suffers from the "PaCifiST bootsector bug" (Hatari will
2035: display a
1.1 root 2036: warning message then). In this case, the bootsector of the disk
2037: contains some illegal data, so that the disk even does not work on a
2038: real ST any more. However, if it is a .ST and not a .MSA disk, you can
1.1.1.3 root 2039: easily fix it by using a hex-editor to change the byte at offset $D
2040: (13)
1.1 root 2041: from 0 to 1 (don't forget to backup your disk image first, since you
2042: can also easily destroy your disk image when changing a wrong byte
2043: there). If the disk contains a bootsector program, you probably have to
2044: adjust the boot sector check sum, too (it can be found at offset $1FE +
2045: $1FF). </p>
1.1.1.2 root 2046: <p>Hatari supports disk images that are compressed with (Pk-)ZIP
2047: (file suffix must be ".zip") or GZip (file suffix must be ".st.gz" or
1.1.1.3 root 2048: ".msa.gz"), so you can archive your disk images into zip archives.
1.1.1.2 root 2049: You can also directly run the zip archives you may download from the
2050: net as long as the archive contains a disk image in .ST or .MSA format.</p>
1.1.1.3 root 2051: <p><em>Note:</em> Hatari does not save disk images back to *.ZIP files
2052: so
1.1.1.2 root 2053: your highscores and savegames are lost if you load the game from such
2054: a zipped disk image.</p>
1.1.1.5 root 2055:
1.1.1.10! root 2056:
1.1.1.5 root 2057: <a name="Hard disk support"></a><h2>Hard disk support</h2>
2058:
1.1.1.8 root 2059: <p>
1.1.1.10! root 2060: Hatari supports three ways of emulating Atari hard drives: The low-level
! 2061: ACSI and IDE hard disk emulation and a GEMDOS based drive emulation.
! 2062: In most cases the GEMDOS based hard disk emulation is best as it allows
! 2063: exchanging files easily between the emulated and the host environment.
! 2064: </p>
! 2065: <p>
! 2066: Please note that changing the HD-image or the GEMDOS HD-folder will reset
1.1.1.8 root 2067: the emulated Atari since it is not possible to switch the hard disk
2068: while the emulator is running.
2069: </p>
1.1.1.6 root 2070:
2071:
2072: <a name="GEMDOS based hard disk emulation"></a><h3>GEMDOS based hard disk emulation</h3>
1.1 root 2073: <p>With the GEMDOS based drive emulation, you can easily "mount" a
2074: folder from the host file system to a drive of the emulated Atari. To
2075: use the GEMDOS based drive emulation, you should use a folder on your
1.1.1.3 root 2076: hard disk that only contains files and folders with valid TOS
2077: filenames.
1.1 root 2078: That means that all files/folders should be written in capital letters
2079: and their length mustn't exceed the 8+3 file name length limit. If you
2080: don't want to rename all files to get capital letters, it is also
2081: possible to store that folder on a FAT filesystem since those
2082: filesystems are case-insensitive. </p>
2083: <p>GEMDOS drive emulation is an easy way to share files between the
1.1.1.8 root 2084: host system and the emulated Atari, but it is known to be incomplete and
1.1 root 2085: a little bit unstable, especially if you use it together with the ACSI
2086: hard disk emulation. So if your programs complain that they could not
2087: find/read/write files on the GEMDOS HD drive, you should try to copy
1.1.1.3 root 2088: them to a floppy disk image or a real hard disk image!</p>
1.1.1.6 root 2089: <p>
1.1.1.8 root 2090: There are also some known limitations which are due to the way the GEMDOS
2091: drive emulation is implemented: First, it is not possible to use a cartridge
2092: image together with GEMDOS drive emulation at the same time.
2093: Second, <em>the GEMDOS HD emulation does not work very well with TOS
2094: 1.00 and 1.02</em>. So you should use at least TOS 1.04 if you want
2095: to use the GEMDOS HD emulation.
1.1.1.6 root 2096: </p>
1.1.1.4 root 2097:
1.1.1.8 root 2098:
1.1.1.10! root 2099: <a name="ACSI hard disk emulation"></a><h3>ACSI hard disk emulation</h3>
! 2100: <p>
! 2101: To use the ACSI hard disk emulation, you need a hard disk image file
! 2102: with a pre-installed HD driver in it. So either try to image your old
! 2103: ST hard disk or grab one from the internet (e.g. from the Hatari website).
! 2104: Please note that AHDI 5.0 is currently the <em>only</em> hard disk driver
! 2105: that is officially supported. Other hard disk drivers might not work.
! 2106: </p>
! 2107: <p>
! 2108: To create a new ACSI hard disk image, you can start with an empty image that
! 2109: you have for example created with the following command:
! 2110: <span class="commandline">dd if=/dev/zero of=hd.img bs=512 count=xxx</span>.
! 2111: Then copy the complete AHDI 5.0 package to a floppy disk image, and enable
! 2112: this floppy disk image and the fresh hard disk image in the emulator.
! 2113: Start HDX.PRG from the floppy disk and format and partition the hard disk
! 2114: with this tool. When you're finished, you have to restart the emulated system,
! 2115: run AHDI.PRG from the floppy disk and HINSTALL.PRG afterwards.
! 2116: With HINSTALL.PRG you can install the hard disk driver to the fresh HD image,
! 2117: so you can directly boot from the hard disk image in the future.
! 2118: </p>
! 2119:
! 2120: <a name="IDE hard disk emulation"></a><h3>IDE hard disk emulation</h3>
! 2121: <p>
! 2122: Create an empty image file with the size of your choice with:
! 2123: <span class="commandline">dd if=/dev/zero of=hd.img bs=1k count=xxx</span>.
! 2124: Then get the Cecile hard disk driver from
! 2125: <a href="http://centek.free.fr/atari/softs/s_cecile.htm">http://centek.free.fr/atari/softs/s_cecile.htm</a>
! 2126: and put it on a floppy disk image (named "cecile.st") e.g. with:
! 2127: <span class="commandline">zip2st.sh cecile.zip</span>.
! 2128: </p>
! 2129: <p>
! 2130: Run Hatari with
! 2131: <span class="commandline">hatari --machine falcon --tos tos404.rom --ide hd.img cecile.st</span>,
! 2132: warm up your French language skills, start the Cecile hard disk driver
! 2133: CECILE.PRG, then use the tool CC_TOOLS.APP to partition your hard disk
! 2134: image: click to "Partition", select "Hatari IDE disk" and set suitable
! 2135: partition size. Then click "Valider".
! 2136: </p>
! 2137: <p>
! 2138: If you only want to use your HD image in Falcon mode, you can install
! 2139: the Cecile hard disk driver to the image from the Cecile CC_TOOLS.APP:
! 2140: select "Installer" from main menu and save the Cecile driver to the
! 2141: 1st partition on "Hatari IDE disk". If you want to also use your HD
! 2142: image in ST/STE mode, you need to get and install AHDI 6 driver on it
! 2143: instead (see "ASCI hard disk emulation" section for AHDI usage
! 2144: instructions).
! 2145: </p>
! 2146: <p>
! 2147: Then you can boot from your hard disk image by simply specifying it
! 2148: with the <span class="commandline">--ide</span> parameter.
! 2149: </p>
! 2150:
! 2151:
! 2152: <a name="Accessing disk image partitions outside of Hatari"></a><h3>Accessing disk image partitions outside of Hatari</h3>
! 2153: <p>
! 2154: If you want to access the partitions also outside the emulation,
! 2155: the disk image needs to have a DOS partition table. The
! 2156: <span class="commandline">atari-hd-image</span> script included
! 2157: with Hatari can be used to create such an image.
! 2158: </p>
! 2159: <p>
! 2160: Inside the Hatari emulator, EmuTOS can access partition(s) on these
! 2161: kind of images directly without any driver software. Of the Atari HD
! 2162: drivers, Centek's Cecile (mentioned above) and Uwe Seimet's
! 2163: <a href="http://www.seimet.de/atari/en/hddriver.html">HD Driver
! 2164: (demo)</a> work fine with them. E.g. AHDI and CBHD don't.
! 2165: </p>
! 2166: <p>
! 2167: Note also that plain EmuTOS supports only ACSI and the drivers support
! 2168: only IDE (emulation). Cecile needs TT or Falcon and HD driver doesn't
! 2169: work with EmuTOS or TOS4. To summarise; if ASCI emulation and EmuTOS
! 2170: are enough, use those. Otherwise, if you want to use TT or Falcon
! 2171: emulation, use Cecile (or full HD Driver version if you have it),
! 2172: otherwise use HD driver (demo).
! 2173: </p>
! 2174: <p>
! 2175: To access the content of the partitions on Linux host, there are two
! 2176: possibilities:
! 2177:
! 2178: <h4>Using Mtools</h4>
! 2179: <p>
! 2180: For this you need to add an entry for the hard disk
! 2181: image to your <span class="commandline">~/.mtoolsrc</span> and
! 2182: specify which partition you want to access from the image. For
! 2183: an image created with the above mentioned script, the line in
! 2184: the configuration file should look something like this:
! 2185: </p>
! 2186: <pre>
! 2187: MTOOLS_NO_VFAT=1
! 2188: drive c: file="/home/user/hatari/hd.img" partition=1
! 2189: </pre>
! 2190: <p>
! 2191: Note that Mtools is instructed to use FAT compatibility mode because
! 2192: EmuTOS cannot deal properly with VFAT file information. If you don't
! 2193: want this setting for all your Mtools drives, you can set it also via
! 2194: the environment like this:
! 2195: </p>
! 2196: <pre>
! 2197: MTOOLS_NO_VFAT=1 mcopy foobar.txt c:
! 2198: </pre>
! 2199:
! 2200: <h4>Using a loopback device</h4>
! 2201: <p>
! 2202: This is recommended even by Mtools documentation, but it's less
! 2203: convenient as it requires root rights. First you need to "loop"
! 2204: mount the image:
! 2205: </p>
! 2206: <pre>
! 2207: $ su
! 2208: # image="hd.img"; mountdir="hd"
! 2209: # start=$(parted $image unit s print | awk '/ 1 /{print $2}' | tr -d s)
! 2210: # losetup -f $image -o $((512*$start))
! 2211: # loop=$(losetup -a | tail -1 | cut -d: -f1)
! 2212: # mkdir -p $mountdir
! 2213: # mount -t msdos $loop $mountdir
! 2214: </pre>
! 2215: <p>
! 2216: This uses <span class="commandline">parted</span> to find out the first
! 2217: partition offset in sectors and then tells <span class="commandline">losetup</span>
! 2218: to bind the first free loop device to a corresponding offset from
! 2219: the <span class="commandline">hd.img</span> image.
! 2220: <span class="commandline">mount</span> is then used to mount the file system
! 2221: from the loop device on top of the "hd" directory.
! 2222: </p>
! 2223: <p>
! 2224: After you've copied the relevant files to the "hd" directory, you need
! 2225: unmount the file system and remove the loop device binding before using
! 2226: the disk image from Hatari:
! 2227: </p>
! 2228: <pre>
! 2229: # umount $mountdir
! 2230: # losetup -d $loop
! 2231: </pre>
! 2232:
! 2233: <a name="The debugger"></a><h2>The debugger</h2>
! 2234:
! 2235: <p>
! 2236: Hatari has a built-in debugging interface which can be used for
! 2237: analyzing the program that runs in the emulated system. The debugger
! 2238: uses Hatari's parent console window, so make sure you run Hatari from
! 2239: the command line when you want to use the debugger. To invoke
! 2240: the debugger, press the <span class="key">AltGr + Pause</span> key
! 2241: combination.
! 2242: <p>
! 2243:
! 2244: <p>
! 2245: If you start Hatari with the "-D" command line option, m68k
! 2246: exceptions will automatically invoke the debugger. You can toggle
! 2247: this also later from the debugger with the "setopt -D"
! 2248: command.
! 2249: </p>
! 2250:
! 2251: <p>
! 2252: When entering values to the debugger in other number bases than the
! 2253: default/selected one, they need to be prefixed with a character
! 2254: indicating this. For decimals it's "#" (#15), for
! 2255: hexadecimals "$" ($F), and for binary values it's
! 2256: "%" (%1111). By default the debugger expects all values
! 2257: without a prefix to be decimals, but you can change the default number
! 2258: base with the "value" command.
! 2259: </p>
! 2260:
! 2261: <p>
! 2262: At the debugger prompt, type "help" to get a list of all
! 2263: the available commands and their shortcuts:
! 2264: </p>
! 2265: <pre>
! 2266: Available commands:
! 2267: dspaddress (da) : toggle or list (traditional) DSP address breakpoints
! 2268: dspbreak (db) : set/remove/list DSP register/RAM condition breakpoints
! 2269: dspdisasm (dd) : disassemble DSP code
! 2270: dspmemdump (dm) : dump DSP memory
! 2271: dspreg (dr) : read/write DSP registers
! 2272: dspcont (dc) : continue emulation / DSP single-stepping
! 2273: address ( a) : toggle or list (traditional) CPU address breakpoints
! 2274: breakpoint ( b) : set/remove/list register/RAM condition breakpoints
! 2275: disasm ( d) : disassemble from PC, or given address
! 2276: cpureg ( r) : dump register values or set register to value
! 2277: memdump ( m) : dump memory
! 2278: memwrite ( w) : write bytes to memory
! 2279: logfile ( f) : open or close log file
! 2280: loadbin ( l) : load a file into memory
! 2281: savebin ( s) : save memory to a file
! 2282: setopt ( o) : set Hatari command line options
! 2283: value ( v) : set number base / show value in other number bases
! 2284: cont ( c) : continue emulation / CPU single-stepping
! 2285: quit ( q) : quit emulator
! 2286: help ( h) : print help
! 2287: </pre>
! 2288:
! 2289: <p>
! 2290: In the beginning, probably the most interesting commands are
! 2291: "m" and "d" for dumping and disassembling memory
! 2292: regions.
! 2293: </p>
! 2294: <pre>
! 2295: > help memdump
! 2296: 'memdump' or 'm' - dump memory
! 2297: Usage: m [address]
! 2298: dump memory at address or continue dump from previous address.
! 2299: </pre>
! 2300: <pre>
! 2301: > help disasm
! 2302: 'disasm' or 'd' - disassemble from PC, or given address
! 2303: Usage: d [address]
! 2304: If no address is given, this command disassembles from the last
! 2305: position or from current PC if no last postition is available.
! 2306: </pre>
! 2307: <pre>
! 2308: > d
! 2309: 0000aa6e: 2f08 0241 0fff 207c 00fe MOVE.L A0,-(A7)
! 2310: 0000aa70: 0241 0fff 207c 00fe 78c0 AND.W #$0fff,D1
! 2311: 0000aa74: 207c 00fe 78c0 2070 1000 MOVEA.L #$00fe78c0,A0
! 2312: 0000aa7a: 2070 1000 4ed0 0241 0ffe MOVEA.L (A0, D1.W*1, $00) == $00fe34ae,A0
! 2313: 0000aa7e: 4ed0 0241 0ffe 6712 e549 JMP.L (A0)
! 2314: </pre>
! 2315:
! 2316: <p>
! 2317: Hatari has two kinds of breakpoints. First, there are the fast and
! 2318: simple address breakpoints which trigger when the CPU (or DSP) program counter
! 2319: hits a given address. Use "a" (or "da" for the DSP) to
! 2320: manage them. Then there are the conditional breakpoints which are a little bit
! 2321: slower but can handle more complex break conditions. Use "b" (or
! 2322: "db" for the DSP) to manage them. "b help" explains
! 2323: the syntax:
! 2324: </p>
! 2325:
! 2326: <pre>
! 2327: breakpoint = <expression> [ && <expression> [ && <expression> ] ... ]
! 2328: expression = <value>[.mode] [& <number>] <condition> <value>[.mode]
! 2329:
! 2330: where:
! 2331: value = [(] <register-name | hatari-variable | number> [)]
! 2332: number = [#|$|%]<digits>
! 2333: condition = '<' | '>' | '=' | '!'
! 2334: addressing mode (width) = 'b' | 'w' | 'l'
! 2335: addressing mode (space) = 'p' | 'x' | 'y'
! 2336: </pre>
! 2337:
! 2338: <p>
! 2339: If the value is in parenthesis like in '($ff820)' or '(a0)', then the
! 2340: used value will be read from the memory address pointed by it.
! 2341: </p>
! 2342: <p>
! 2343: M68k addresses can have byte ("b"), word ("w") or
! 2344: long ("l", default) width. DSP addresses belong to different
! 2345: address spaces: "P", "X" or "Y". Note
! 2346: that on DSP only R0-R7 registers can be used for memory addressing.
! 2347: </p>
! 2348:
! 2349: <p>Examples:</p>
! 2350: <pre>
! 2351: pc = $64543 && ($ff820).w & 3 = (a0) && d0 = %1100
! 2352: (r0).x = 1 && (r0).y = 2
! 2353: </pre>
! 2354:
! 2355: <p>
! 2356: The debugger supports also setting breakpoints on values of some
! 2357: internal Hatari variables (listed by "b help"). For example
! 2358: if you want to stop at a specific cycle within a frame (that is, PC
! 2359: relative to the current VBL/HBL in cycles), set breakpoints to specific
! 2360: "HBL" and "LineCycles" variable values.
! 2361:
! 2362: <p>
! 2363: After analyzing and/or setting new breakpoints, you can continue the emulation
! 2364: with the "c" command. You can continue for a given number of
! 2365: CPU instructions (or DSP instructions when "dc" is used), or
! 2366: you can continue forever (until a breakpoint triggers) if you omit the
! 2367: instruction count.
! 2368: </p>
! 2369:
! 2370: <p>
! 2371: By the way, if you want to continue with real-time disassembling, you
! 2372: can enable it by typing "setopt --trace cpu_disasm" at the
! 2373: debugger prompt. Disable it with "setopt --trace none" when
! 2374: you enter the debugger again. "--trace help" can be used to
! 2375: list all the supported trace points. (Similar things can be done even
! 2376: from a program within the emulation if you enable Hatari
! 2377: "--bios-intercept" option and call XBios 255 from
! 2378: the program with a suitable command line string.)
! 2379: </p>
! 2380:
! 2381: <p>
! 2382: Lastly, the debugger is much nicer to use with the command line
! 2383: editing support. If you're building Hatari yourself, please make sure
! 2384: that you have the GNU readline development files installed (on Debian
! 2385: / Ubuntu these come from the libreadline5-dev package). Otherwise
! 2386: this doesn't get enabled when you configure Hatari.
! 2387: </p>
! 2388:
! 2389:
! 2390: <a name="Performance"></a><h2>Performance</h2>
! 2391: <a name="Improving Hatari performance"></a><h3>Improving Hatari performance</h3>
! 2392:
! 2393: <p>
! 2394: Unless you've disabled compiler optimizations (like GCC's -O2 or -O3
! 2395: options) in the Hatari build, the extra optimization flags (like GCC's
! 2396: "-mtune=i686") don't seem to have very large effect on Hatari
! 2397: performance.
! 2398: </p>
! 2399: <p>
! 2400: However, Hatari can be sped up considerably by giving up some
! 2401: emulation or emulator accuracy. Most of these options should
! 2402: be needed only on slow devices like handhelds.
! 2403: </p>
! 2404:
! 2405:
! 2406: <h4>Emulation options</h4>
! 2407:
! 2408: <p>
! 2409: Emulation options have the largest impact on performance.
! 2410: These options can be changed from the Hatari GUI System dialog and
! 2411: the emulation needs to be rebooted for any of these changes to take
! 2412: an effect!
! 2413: </p>
! 2414:
! 2415: <h5>DSP</h5>
! 2416: <p>
! 2417: Emulating the DSP is performance-wise several times more demanding
! 2418: than emulating the m68k; DSP runs at higher frequency, executes many
! 2419: instructions for each m68k instruction and emulation isn't as mature
! 2420: and optimized. Unless some program needs DSP, <em>none</em> or
! 2421: <em>dummy</em> DSP emulation mode could be used. Even of the programs
! 2422: that do use DSP, many use it only for background music and work
! 2423: fine without the real DSP emulation.
! 2424: </p>
! 2425: <h5>Timer-D</h5>
! 2426: <p>
! 2427: The single largest factor contributing to general Hatari emulation
! 2428: performance is the handling of interrupts. Enabling Timer-D patching
! 2429: option (about) doubles Hatari performance as it significantly reduces
! 2430: the number of interrupts generated by the emulated Atari machine.
! 2431: Using this has adverse effect only for very rare programs.
! 2432: </p>
! 2433: <h5>Compatible CPU</h5>
! 2434: <p>
! 2435: After the DSP and Timer-D interrupts, m68k emulation takes most time.
! 2436: Disabling the "Slower but more compatible CPU" option will speed up
! 2437: the emulation a lot, but it won't anymore be cycle accurate. This can
! 2438: be fine for many games and other programs, but won't work e.g. for demos
! 2439: using overscan or rasters.
! 2440: </p>
! 2441:
! 2442: <p>
! 2443: Roughly speaking, for DSP emulation, one needs at least 2Ghz machine;
! 2444: for normal (unpatched) Timer-D frequency on some specific cases (like
! 2445: demos with overscan 512 color animations) one may need over 1GHz
! 2446: machine. For Compatible CPU one needs at least 1/2Ghz machine.
! 2447: </p>
! 2448: <p>
! 2449: Above options may cause some programs not to work correctly.
! 2450: The <a href="compatibility.html">Hatari Software Compatibility List</a> lists
! 2451: programs known to need real DSP emulation or Timer-D frequency.
! 2452: </p>
! 2453:
! 2454:
! 2455: <h4>Emulator options</h4>
! 2456:
! 2457: <p>
! 2458: Emulator options don't have as large effect on performance as
! 2459: emulation options, but they don't affect the emulated programs at all,
! 2460: just the quality of the emulation "output". These options can also
! 2461: be toggled at run-time without rebooting the emulation.
! 2462: </p>
! 2463:
! 2464: <h5>Sound</h5>
! 2465: <p>
! 2466: Internal Hatari sound handling and the SDL_mixer sound thread
! 2467: libALSA sound processing can account up to 1/3 of the Hatari CPU usage
! 2468: (depending on other options you're using). Disabling sound will get
! 2469: rid of that. Using low sound frequency or one matching your sound
! 2470: card may also help. Best is if you disable also background music
! 2471: from the programs you run in Hatari as this can significantly reduce
! 2472: the number of generated interrupts.
! 2473: </p>
! 2474: <h5>Frame skipping</h5>
! 2475: <p>
! 2476: Screen rendering can take noticeable amount of CPU time. The default
! 2477: Hatari "auto" frame skipping should be used unless there's a good
! 2478: reason not to. It will skip converting and showing some of the frames
! 2479: if there's not enough time for them. If your monitor refresh frequency
! 2480: is lower than the selected Hatari monitor frequency (e.g. LCD monitors
! 2481: usually use 60Hz whereas Atari monochrome monitor uses 72Hz), you
! 2482: should use frameskip of one. The reason is that if your SDL library
! 2483: uses VSync to synchronize the output to screen (like OSX one?), with
! 2484: zero frame skip that forces the emulation to run slower than a real
! 2485: Atari. If SDL doesn't use VSync, Hatari does redundant work to
! 2486: convert frames you can't see.
! 2487: </p>
! 2488: <h5>Low-rez zooming</h5>
! 2489: <p>
! 2490: If you are not using frame skip, disabling zooming can have
! 2491: noticeable improvement on performance. If you still want to have a
! 2492: nice fullscreen mode, you should rather add the right resolution
! 2493: mode-lines (e.g. "320x200") to your xorg.conf file. If you still
! 2494: want to use zooming, disabling borders may help a bit.
! 2495: </p>
! 2496: <h5>Spec512 color handling</h5>
! 2497: <p>
! 2498: Handling Spec512 color modes which change the ST/e palette constantly
! 2499: takes some extra CPU. If you have problems with CPU usage in such
! 2500: screens and you care more e.g. from the sound quality than visuals, you
! 2501: can disable the Spec512 mode handling by zeroing the threshold for that
! 2502: with the <span class="commandline">--spec512 0</span> option.
! 2503: </p>
! 2504: <h5>Statusbar and drive LED</h5>
! 2505: <p>
! 2506: If your version of libSDL uses VSync to synchronize the screen
! 2507: output, drawing of the statusbar or the drive LED (when statusbar is
! 2508: disabled) may have some minor impact on performance too. Normally
! 2509: they shouldn't.
! 2510: </p>
! 2511:
! 2512: <p>
! 2513: Btw. Hatari currently runs best in 16 or 32 bits per pixel color depth
! 2514: mode, so try to avoid 24 bits per pixel display modes if possible.
! 2515: 16-bit mode is fastest.
! 2516: </p>
! 2517: <p>
! 2518: If nothing else helps, try an earlier Hatari version. More accurate
! 2519: emulation or emulator output in newer Hatari versions means that they
! 2520: can be slower despite optimizations.
! 2521: </p>
! 2522:
! 2523:
! 2524: <a name="Measuring the performance"></a><h3>Measuring the performance</h3>
! 2525:
! 2526: <p>
! 2527: There are a couple of ways to monitor and measure Hatari performance.
! 2528: </p>
! 2529: <p>
! 2530: By default Hatari has Statusbar visible and automatic frameskip
! 2531: enabled. When Hatari has enough time that it can sleep a little each
! 2532: frame, the statusbar frame skip ("FS") value keeps at zero. If Hatari
! 2533: is completely busy, it will increase to the maximum specified
! 2534: (automatic) frame skip value.
! 2535: </p>
! 2536: <p>
! 2537: Hatari has also a facility to measure FPS i.e. Frames Per Second.
! 2538: Just enable the <span class="commandline">--fast-forward</span> option
! 2539: on command line (or use the corresponding keyboard shortcut), and
! 2540: after a while, press the "Pause" key. Whenever Hatari emulation is
! 2541: paused, Hatari will show how many VBLs it could show per second along
! 2542: with some other numbers.
! 2543: </p>
! 2544: <p>
! 2545: It depends on what you want to measure, but usually it's best to
! 2546: disable sound and set high frame skip like
! 2547: <span class="commandline">--sound off --frameskips 60</span> so that
! 2548: the associated external overheads are minimized. E.g. video output
! 2549: can on some platforms do VSync and measurements would then show
! 2550: your monitor refresh frequency instead of actual Hatari performance.
! 2551: </p>
! 2552: <p>
! 2553: On Unix systems with <span class="commandline">times()</span> function
! 2554: call, only the time spent by the Hatari process itself is measured.
! 2555: On other systems much less accurate SDL "wall clock" timings are
! 2556: used. To make latter more accurate you could use also
! 2557: <span class="commandline">--run-vbls</span> option to specify how many
! 2558: VBLs Hatari should run in fast forward mode before it exits. In this
! 2559: case it's best to either have the test-case run automatically from the
! 2560: AUTO-folder or given as memory snapshot to Hatari with the frame skip
! 2561: set equal to the VBL count.
! 2562: </p>
! 2563: <p>
! 2564: Note that the numbers can fluctuate quite a bit, <em>especially</em>
! 2565: when the SDL timings are used, so for (statistically) reliable numbers
! 2566: you may need to repeat the measurement several times. You should of
! 2567: course make also sure that the system doesn't have any other activity
! 2568: at the same time you're making the measurements.
! 2569: </p>
! 2570:
! 2571:
1.1.1.5 root 2572: <a name="Appendix"></a><h2>Appendix</h2>
2573:
2574: <a name="Copying"></a><h3>Copying</h3>
1.1.1.4 root 2575:
1.1 root 2576: <div class="backdropped">
2577: <p>This program is free software; you can redistribute it and/or modify
1.1.1.3 root 2578: it under the terms of the GNU General Public License as published by
2579: the
1.1 root 2580: Free Software Foundation; either version 2 of the License, or (at your
2581: option) any later version. </p>
2582: <p>This program is distributed in the hope that it will be useful, but <em>WITHOUT
2583: ANY WARRANTY</em>; without even the implied warranty of <em>MERCHANTABILITY</em>
1.1.1.3 root 2584: or <em>FITNESS FOR A PARTICULAR PURPOSE</em>. See the GNU General
1.1.1.4 root 2585: Public License for more details. </p>
2586: <p>
2587: You should have received a copy of the GNU General Public License
2588: along with this program; if not, write to the Free Software Foundation,
2589: Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
2590: </p>
1.1 root 2591: </div>
1.1.1.3 root 2592: <p><a href="http://www.gnu.org/">The GNU Project and the Free Software
2593: Foundation</a> | <a href="http://www.fsf.org/licenses/gpl.html">The
2594: GNU General Public License</a></p>
1.1.1.4 root 2595:
1.1.1.5 root 2596: <a name="Introduction to Emulation"></a><h3>Introduction to Emulation</h3>
2597:
1.1 root 2598: <p>Emulation via software is an art and Hatari is an example of this.</p>
1.1.1.3 root 2599: <p>Emulation is to make a computer behave like a (probably) completely
2600: different machine on the lowest possible niveau.
2601: This includes CPU and custom chip emulation allowing software written
2602: for the emulated machine to be run without notice.
2603: A good emulator will run most of the software intended for the emulated
2604: platform without trouble.
1.1 root 2605: </p>
2606: <p>
1.1.1.3 root 2607: The key to emulation is to simply do those things with a software
2608: program, the emulator, that normally chips would perform.
2609: So you have an CPU emulator that basically consists of a large loop
2610: that does exactly what the real thing would do:
1.1 root 2611: </p>
2612: <ul>
1.1.1.3 root 2613: <li>fetch an instruction from virtual memory</li>
2614: <li>interpret this instruction</li>
2615: <li>fetch operands from the emulated registers and memory</li>
2616: <li>perform the operation like addition or changing the program
2617: counter on a jump instruction</li>
2618: <li>writes results back into the intended registers or memory
2619: locations</li>
2620: <li>increment of the program counter and loop</li>
1.1 root 2621: </ul>
2622: <p>
1.1.1.3 root 2623: The typical von-Neumann CPU can be emulated very fast, stable and
2624: error-free using such a simple loop system.
1.1 root 2625: </p>
2626: <p>
1.1.1.3 root 2627: But in most cases the CPU emulation is the simplest part. Correct
2628: emulation of the various custom chips and hardware
1.1 root 2629: parts of the emulated system is much trickier.
2630: </p>
2631:
1.1.1.6 root 2632: <br>
2633:
1.1.1.3 root 2634: <hr style="width: 100%; height: 2px;">
1.1 root 2635: <table border="0" width="100%">
1.1.1.3 root 2636: <tbody>
1.1 root 2637: <tr>
1.1.1.3 root 2638: <td align="left"><a href="http://validator.w3.org/check/referer"><img
2639: src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"
2640: border="0" height="31" width="88"></a></td>
2641: <td align="right">
1.1.1.10! root 2642: August 2009
1.1.1.3 root 2643: </td>
1.1 root 2644: </tr>
1.1.1.3 root 2645: </tbody>
1.1 root 2646: </table>
2647: </body>
2648: </html>
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.