-Version 1.4 +Version 1.5
Manual written by: Thomas Huth, Matthias Arndt
@@ -84,7 +84,7 @@ Hatari on the WWW: Installation of the binary
-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).
@@ -166,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:
General description
Features
@@ -178,6 +182,7 @@ Recent versions of Hatari even feature b
STE hardware emulation
-There is support for following additional STE features:
+
Experimental TT hardware emulation
-There is support for following additional TT features:
+
Falcon hardware emulation
-There is support for following additional Falcon features:
+
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. -For Falcon microphone recording support portaudio library is needed. -
--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:
++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:
-CFLAGS="-O3 -fomit-frame-pointer" ./configure +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. @@ -363,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.
@@ -384,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:
+-":once" option that removes breakpoint after hit can be useful when one -wants to get out of a loop (when at the instruction that branches back -to loop start) or just to get to a specific point in code: +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 ++
-> b pc > pc :once -> a some_symbol :once +trace none +b all+
-Whereas giving count (like ":2") as option will break only on every -<count> hit. +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).
-After analyzing 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 breakpoint triggers) if you omit the -instruction count. +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.
+-If you want to continue with real-time disassembling, you can enable it -with "trace cpu_disasm" at the debugger prompt before continuing. +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 supported trace points. +"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 -Atari OS functions requires setting additional Hatari options which -tell it to intercept higher level functionality: +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 Hatari "--bios-intercept" option and call XBios 255 from -the program with a suitable Hatari command line string. +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. +
+ +@@ -2994,7 +3658,7 @@ history, editing and especially with the 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 this doesn't get enabled when you configure +package). Otherwise completion doesn't get enabled when you configure Hatari.
@@ -3011,10 +3675,27 @@ features Hatari needs to emulate for the 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 @@ -3022,14 +3703,21 @@ performance. Using GCC -O3 option inste (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. Most of these options should -be needed only on slow devices like handhelds. +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. @@ -3085,10 +3773,10 @@ a last resort.
--Emulator options don't have as large effect on performance as +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. @@ -3110,14 +3798,16 @@ 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. 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 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 your version of libSDL uses VSync to synchronize the screen -output, drawing of the statusbar or the drive LED (when statusbar is -disabled) may have some minor impact on performance too. Normally -they shouldn't. -
- --Btw. 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. -
--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. +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.
@@ -3278,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">