-Version 1.2 +
+Version 1.5
-+
Manual written by: Thomas Huth, Matthias Arndt - & Eero Tamminen + & Eero Tamminen
-+
Hatari on the WWW: http://hatari.berlios.de/
@@ -64,8 +73,8 @@ Hatari on the WWW: General description-Hatari is an Atari ST, STE, TT and Falcon emulator for Linux, FreeBSD, BeOS and -other Systems which are supported by the SDL library. +Hatari is an Atari ST, STE, TT and Falcon emulator for Linux, OSX, +Windows and other Systems which are supported by the SDL library. The emulator is open source software and is distributed under the terms of the GNU General Public License (GPL). @@ -134,7 +170,7 @@ Unlike many other Atari ST emulators whi environment for running GEM applications, Hatari tries to emulate the hardware of a ST as close as possible so that it is able to run most of the old ST games and demos. Of course you can run normal GEM applications with Hatari, too. -Recent versions of Hatari even feature basic STE, TT and Falcon emulation. +Recent versions of Hatari even feature STE, Falcon and basic TT emulation.
There is support for following additional STE features:
There is support for following additional TT features:
There is support for following additional Falcon features:
-DSP emulation is still very experimental and unstable, but there's a dummy mode, -too, which helps to get some demos and games running. -
+See the developers' doc/todo.txt file +(included with Hatari sources) for the details on the few remaining +emulation gaps and the Hatari Atari +Software Compatibility List for which Atari programs are known +to be affected by them.
Hatari currently has the following system requirements:
+Hatari currently has the following minimum system requirements:
-Certain versions of Hatari have successfully been tested by various people on +Earlier versions of Hatari have successfully been tested by various people on the following systems:
First, you need the SDL library, you can get it at: -http://www.libsdl.org/. Most -distributions already ship a suitable version. -Make sure to install the appropriate header files as well often called -"libsdl-dev" or the like. -
-Second, you need the zLib compression library. You can get it from http://www.gzip.org/zlib/ -but the version shipped with your distribution will be sufficient in -most cases. Make sure to have the header files -for it installed as well. -
--For optional features like PNG format screenshots and Hatari window -embedding, you need to have the header files for libpng and libX11. -
--Of course, you need the GNU C compiler and (GNU) Make, too! -
-Change to the hatari/ directory, copy -Makefile-default.cnf to -Makefile.cnf and adapt the configuration file -to suite your system. Alternatively, you can use the supplied configure -script to auto-detect all parameters (type -"./configure --help" -to see the options of the script). -Don't forget to use some good CFLAGS for the compiler optimizations, e.g. -run configure in the following way: -
+Required:
+Optional:
+- CFLAGS="-O3 -fomit-frame-pointer" ./configure +The versions available in your Linux distribution will be sufficient +in most cases, but make sure you have also the header files installed +for the libraries as well! Typically they're in a corresponding -dev +package.
+ ++After you've verified that you have the required libraries and their +development files, change to the hatari/ +directory. Create a build/ directory under +it and configure the build system for your environment: +
+mkdir -p build +cd build +cmake .. +
Then compile Hatari by typing make. -If all -works fine, you'll get the executable hatari +If all works fine, you'll get the executable hatari in the src/ subdirectory.
++Note: Instead of calling CMake directly, you can also use the supplied +configure script to run CMake and to give the arguments (like install +prefix) in a format familiar from GNU Autotools using programs. Type +"./configure --help" +to see all the options supported by this script. +
Before you can start Hatari, you have to copy a TOS ROM image to the data -directory (the data directory is specified -in the configuration file Makefile.cnf) and +directory (<prefix>/share/hatari/, by +default /usr/local/share/hatari/) and rename it to tos.img, or use the --tos command line option to tell Hatari where to find a TOS ROM. @@ -305,7 +364,7 @@ of the emulated Atari. Unfortunately it is not possible to ship an original ROM image with the Hatari package since these images are still copyrighted. But you can easily create an image with a real ST and one of those various -ROM-image programs for the ST (search for "TOSDUMP" with your +ROM-image programs for the ST (search for "TOSDUMP" with your favourite internet search engine). If your old ST does not work anymore, you can also try to search the internet directly for corresponding TOS ROM image, but don't ask the Hatari team where to get one.
@@ -322,12 +381,11 @@ select a TOS image file from the GUI.Type make install as root to do a -systemwide installation. In this case it is recommended -to set the DATADIR variable in Makefile.cnf to a proper value. /usr/local/share/hatari -is a good value in that case.
-The Hatari executable should now be in your PATH and accessible from -anywhere.
+Type make install as "root" user to +do a systemwide installation.
+Assuming you didn't change the default installation prefix and that +/usr/local/bin/ is in your PATH, you should +be now able to start the Hatari executable from anywhere.
When you finally have got a TOS image, try starting Hatari with the option --help to find out more about its command line parameters.
@@ -343,13 +401,31 @@ to turn on the GUI to configure Hatari to suit your needs, press F11 to toggle windowed and fullscreen mode. -Usage:
- hatari [options] [disk image name] + hatari [options] [disk image | directory | Atari program ]+
As an argument one can give either a name of:
+Booting will be done from the disk image or directory that's given +last on the command line as an option or the argument (and which +corresponds to A: or C:).
+Hatari command line options are split into several categories:
++Hint: "info" command "aes", "gemdos" and "vdi" subcommands for can be +used to list the corresponding OS-call opcodes. For example, +to see the GEMDOS opcodes, use:
++info gemdos 1 ++ + + +
+As the file pointed by the breakpoint ":file" option (see +Breakpoint options) can contain any +debugger commands, it can also be used to do automatic "chaining" of +debugger and breakpoint actions so that after one breakpoint is hit, +another one is set. +
+ +For example if you have these input files:
++b GemdosOpcode = 0x3D :trace :file trace.ini ++
+setopt --bios-intercept --trace gemdos,xbios,fdc,io_all +b VBL = "VBL+4" :trace :file disable.ini ++
+trace none +b all ++
+And then start Hatari with the first debugger input file and a GEMDOS +harddisk directory containing "desktop.inf" file: +
++hatari --parse break.ini -d testdir ++ +
+Note: because debugger input files cannot "continue" +emulation, ":trace" option needs to be used for the breakpoint(s) +if you want emulation to continue after the breakpoint action(s). +
+ ++Hint: It's better to test each input file separate before testing the +whole chain. Besides the ":file" breakpoint option, these debugger +input files can be also read with the debugger "file" command, "lock" +command "file" option and with the Hatari "--parse" command line +option. +
+ + ++After analyzing the emulation state and/or setting new breakpoints, +you can continue the emulation with the "c" command. You can continue +for a given number of CPU instructions (or DSP instructions when "dc" +is used), or you can continue forever (until a non-tracing breakpoint +triggers) if you omit the instruction count. +
+ ++If you want to continue with real-time disassembling, you can enable +it with "trace cpu_disasm" (or "trace dsp_disasm" for DSP) at the +debugger prompt before continuing. +
++Disable tracing with "trace none" when you enter the debugger again. +"trace help" (or TAB) can be used to list all the (over 30) supported +traceable things, from HW events to OS functions. +
++Because Hatari normally emulates things at the hardware level, tracing +certain Atari OS Traps requires setting additional Hatari options +which tell it to intercept this higher level functionality: +
+If use of above isn't possible for the things you'd like to track, +you can use the OS call opcode breakpoints explained above with the +":trace" breakpoint option. +
++Tracing options can be set even from a program within the emulation +if you enable the Hatari "--bios-intercept" option and call XBios 255 +from the program with a suitable Hatari command line string. Bios +interception will also show the (Bios level) CON: output on the host +console. +
++Note that the trace output file can be set only when Hatari starts, +it cannot be changed from within the debugger (or emulation). +
+ + ++Profiling tells where the emulated code spends most of its (emulated) +time. It can be used to find out where a program is (apparently) +stuck or what are the largest performance bottlenecks for a program. +
+ ++Profiling is used by first enabling the profiler (use "dp" for DSP): +
++> profile on +Profiling enabled. ++
+And profiling will start once you continue the emulation: +
++> c +Returning to emulation... +Allocated CPU profile buffer (18 MB). ++ +
+When you get back to the debugger, the collected profiling information +is processed and a summary of in which parts of the RAM the execution +happened is shown: +
++Allocated CPU profile address buffer (4 KB). +Normal RAM (0-0x400000): +- no activity +Cartridge ROM (0xFA0000-0xFC0000): +- no activity +ROM TOS (0xE00000-0xE80000): +- active address range: + 0xe0014c-0xe23f02 +- active instruction addresses: + 707 (100.00% of all) +- executed instructions: + 629144 (100.00% of all) +- used cycles: + 9408503 (100.00% of all) +- address with most cycles: + 0xe0dcca, 402628 cycles (4.28% of all in area) +- address with most hits: + 0xe004a4, 4900 hits (0.78% of all in area) ++
+(DSP RAM will be shown only as single area in profile information.) +
+ ++After this you can request more detailed profiling information: +
++> profile +'profile' - profile CPU code +Usage: profile <on|off|counts|cycles|symbols|stats> [show count] + on & off enable and disable profiling. Data is collected + until debugger is entered again after which you can view + statistics about the data or view PC addresses that took + most cycles or functions/symbols called most often. + You can specify how many items are shown at most. ++ +
For example:
++> profile counts 8 +addr: count: +0xe004a4 0.78% 4900 +0xe004b6 0.78% 4896 +0xe0dcbc 0.55% 3448 +0xe0dcc6 0.55% 3448 +0xe0f59e 0.55% 3446 +0xe0dcce 0.55% 3445 +0xe0dcd6 0.55% 3445 +8 CPU addresses listed. ++
+If you have loaded symbol information for code addresses, with the +"profile symbols" command you get a list of how many times the code +execution passed through the defined symbol addresses. +
+ ++After the profiling information has been post-processed, it will +also be shown in the disassembly output. +
+ + ++Here's a list of some common debugging tasks and how to do them +with the Hatari debugger: +
+ ++trace gemdos,io_all ++Please see Tracing section for more information +on tracing, what's possible with in and what are its limitations. +
+a $12345 :6 ++
+b d1 = 5 ++
+b d1 ! d1 ++
+b d1 > 9 && d1 < 31 ++
+b ($ff820a).b & 2 = 2 ++
+b ($ff820a).b & 2 ! ($ff820a).b & 2 ++
+b ($ff820a).b & 2 ! ($ff820a).b & 2 :trace ++
+b VBL = 100 && HBL = 40 && FrameCycles = 5 ++
+b d0 = "d0 + 10" ++
+lock registers +c 1 +[new register values] +c 1 +[new register values] +... ++
+m "a7-64"-a7 ++
+lock file stack.ini ++Please see also Chaining breakpoints +section for more examples on what you can do with the debugger input files. +
+profile on +c +[after a while, use AltGr+Pause to get back to debugger] +profile counts ++
+Hint: for most of above commands, one just needs to prefix them with +"d" (or "dsp" if using full command names) to do similar operation on +DSP. +
+ + ++Lastly, the debugger is much nicer to use with the command line +history, editing and especially with the command, command argument and +symbol name completion support. If you're building Hatari yourself, +please make sure that you have the GNU readline development files +installed (on Debian / Ubuntu these come from the libreadline5-dev +package). Otherwise completion doesn't get enabled when you configure +Hatari. +
+ ++ENABLE_TRACING define needs to be set for tracing to work. +By default it should be enabled. +
+ + +Hatari performance varies between Atari programs, depending on what +features Hatari needs to emulate for them. Less accurate Atari +emulators may be faster as emulation accuracy has a performance +overhead.
+ +The operating system and libraries below Hatari can also sometimes +have a noticeable effect on performance.
+ + ++Hatari currently runs best in 16 or 32 bits per pixel color depth +mode, so try to avoid 24 bits per pixel display modes if possible. +16-bit mode is fastest. +
+ ++On OSX, frame skipping, zooming and drive LED options (listed below) +seem to have a large effect on performance in the windowed mode. +This is apparently due to issues in the SDL OSX backend and how OSX +itself composites non-fullscreen window contents. OSX uses always +32-bit mode. +
+ ++Unless you've disabled compiler optimizations (like GCC's -O2 or -O3 +options) in the Hatari build, the extra optimization flags (like GCC's +"-mtune=i686") don't seem to have very large effect on Hatari +performance. Using GCC -O3 option instead of -O2 can give minor +(5-10%) performance improvements for things (demos) that use very +heavily interrupts. +
+ ++However, Hatari can be sped up considerably by giving up some +emulation or emulator accuracy. Except for DSP, these options +should be needed only on very slow devices like handhelds. See below. +
+ ++If nothing else helps, try an earlier Hatari version. More accurate +emulation or emulator output in newer Hatari versions means that they +can be slower despite optimizations. +
+ + ++Emulation options have the largest impact on performance. +These options can be changed from the Hatari GUI System dialog and +the emulation needs to be rebooted for any of these changes to take +an effect! +
+ ++Emulating the Falcon DSP is performance-wise several times more demanding +than emulating the m68k; DSP runs at higher frequency, executes many +instructions for each m68k instruction and emulation isn't as mature +and optimized. Unless some program needs DSP, none or +dummy DSP emulation mode could be used. Even of the programs +that do use DSP, many use it only for background music and work +fine without the real DSP emulation. +
+ ++The single largest factor contributing to general Hatari emulation +performance is the handling of interrupts. Enabling Timer-D patching +option (about) doubles Hatari ST/STE emulation performance as it +significantly reduces the number of interrupts generated by the emulated +Atari machine. Using this has adverse effect only for very rare programs. +
+ ++After the DSP and interrupts, m68k emulation takes most time. +Disabling the "Slower but more compatible CPU" option will speed up +the emulation a lot, but it won't anymore be cycle accurate. This can +be fine for many games and other programs, but won't work e.g. for demos +using overscan or rasters. +
+ ++Roughly speaking, for DSP emulation, one needs at least 2Ghz machine. +For normal (unpatched) Timer-D frequency on some specific cases (like +demos with overscan 512 color animations) one may need over 1GHz +machine, but some rare ST/STE demos may require over 1GHz machine even +with Timer-D patching. For "Compatible CPU" one needs at least 1/2Ghz +machine. +
+ ++NOTE: Above options may cause some programs not to work correctly. +The Hatari Software Compatibility List +lists programs known to need real real Falcon DSP emulation or Timer-D +frequency. Disabling "Compatible CPU" option is recommended only as +a last resort. +
+ + ++Emulator options don't usually have as large effect on performance as +emulation options, but they don't affect the emulated programs at all, +just the quality of the emulation "output". These options can also +be toggled at run-time without rebooting the emulation. +
+ ++Internal Hatari sound handling and the SDL_mixer sound thread +libALSA sound processing can account up to 1/3 of the Hatari CPU usage +in normal ST/STE emulation. Disabling sound will get rid of that. +Using low sound frequency or one matching your sound card may also help. +Best is if you disable also background music from the programs you run +in Hatari as this can significantly reduce the number of generated +interrupts. +
+ ++Screen rendering can take noticeable amount of CPU time. The default +Hatari "auto" frame skipping should be used unless there's a good +reason not to. It will skip converting and showing some of the frames +if there's not enough time for them. +
++Also, if your monitor refresh frequency is lower than the selected +Hatari monitor frequency (e.g. LCD monitors usually use 60Hz whereas +Atari monochrome monitor uses 71Hz), you should use frameskip of one. +The reason is that if your SDL library uses VSync to synchronize the +output to screen (like OSX one?), with zero frame skip that forces the +emulation to run slower than a real Atari. If SDL doesn't use VSync, +Hatari does redundant work to convert frames you can't see. +
+ ++If you are not using frame skip, disabling zooming can have +noticeable improvement on performance. You can do this by specifying +suitably low "Max zoomed" resolution (--zoom +1 command line option sets it to 320x200). If you still want to +have a nice fullscreen mode, you should rather add the right resolution +mode-lines (e.g. "320x200") to your xorg.conf file. If you still want +to use zooming, disabling borders may help a bit. +
+ ++Handling Spec512 color modes which change the ST/e palette constantly +takes some extra CPU. If you have problems with CPU usage in such +screens and you care more e.g. from the sound quality than visuals, you +can disable the Spec512 mode handling by zeroing the threshold for that +with the --spec512 0 option. +
+ ++If your version of libSDL uses VSync to synchronize the screen output, +drawing of the statusbar or the drive LED may have some minor impact +on performance too. Normally they shouldn't. +
+ + ++There are a couple of ways to monitor and measure Hatari performance. +
++By default Hatari has Statusbar visible and automatic frameskip +enabled. When Hatari has enough time that it can sleep a little each +frame, the statusbar frame skip ("FS") value keeps at zero. If Hatari +is completely busy, it will increase to the maximum specified +(automatic) frame skip value. +
++Hatari has also a facility to measure FPS i.e. Frames Per Second. +Just enable the --fast-forward option +on command line (or use the corresponding keyboard shortcut), and +after a while, press the "Pause" key. Whenever Hatari emulation is +paused, Hatari will output on console how many VBLs it could show per +second along with some other numbers. +
++It depends on what you want to measure, but usually it's best to +disable sound and set high frame skip like +--sound off --frameskips 60 so that +the associated external overheads are minimized. E.g. video output +can on some platforms do VSync and measurements would then show +your monitor refresh frequency instead of actual Hatari performance. +
++On Unix systems with times() function +call, only the time spent by the Hatari process itself is measured. +On other systems much less accurate SDL "wall clock" timings are +used. To make latter more accurate you could use also +--run-vbls option to specify how many +VBLs Hatari should run before it exits. In this case it's best to +either have the test-case run automatically from the AUTO-folder or +given as memory snapshot to Hatari with the frame skip set equal to +the VBL count. +
++Note that the numbers can fluctuate quite a bit, especially +when the SDL timings are used, so for (statistically) reliable numbers +you may need to repeat the measurement several times. You should of +course make also sure that the system doesn't have any other activity +at the same time you're making the measurements.
@@ -2036,7 +3956,7 @@ parts of the emulated system is much tri src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" border="0" height="31" width="88">