-Version 1.8.0, July 2014 +Version 1.9.0, September 2015
Manual written by: Thomas Huth, Matthias Arndt @@ -110,8 +110,9 @@ Recent versions of Hatari even feature S
Some of the run-time changes require emulation to be reseted for them +
Some of the run-time changes require emulation to be reset for them to take effect.
@@ -540,18 +542,22 @@ depth <x> (x = 1, 2 or 4)Remove statusbar from the screen captures
--avirecord
-Start AVI recording
---avi-vcodec -<x>
-Select avi video codec (x = -bmp/png)
---avi-fps -<x>
-Force avi frame rate (x = -50/60/71/...)
---avi-file -<file>
-Use <file> to record avi
+Start AVI recording. Note: recording will +automatically stop when emulation resolution changes.
+--avi-vcodec <x>
+Select AVI video codec (x = bmp/png). +PNG compression can be much slower than using the uncompressed BMP +format, but uncompressed video content takes huge amount of space.
+--png-level <x>
+Select PNG compression level for AVI video (x = 0-9). +Both compression efficiency and speed depend on the compressed +screen content. Highest compression level (9) can be really +slow with some content. Levels 3-6 should compress nearly as well +with clearly smaller CPU overhead.
+--avi-fps <x>
+Force AVI frame rate (x = 50/60/71/...)
+--avi-file <file>
+Use <file> to record AVI
-j, @@ -752,6 +758,8 @@ values measured on STF and "linear" just voices.
-W, --wincon
+Open console window (Windows only)
-D, --debug
Toggle whether CPU exceptions invoke @@ -1158,7 +1166,7 @@ ends with a 'b'. emulation directory or creating new files under it.
- Note that for IDE hard drive emulation you also need a TOS version >= 2.05. + Note that you need TOS version >= 2.05 to boot from IDE hard drive. And ACSI hard drive emulation does not work with TOS 4.0x in Falcon mode.
@@ -1278,25 +1286,40 @@ certain games. In some other games, it g In TT mode, you can only choose between TT-high resolution ("Mono") and normal modes (select one of the other monitor types). Finally the Falcon mode supports all four types of monitors. Note that most - Falcon demos/games require a RGB or TV mode and do not work with VGA. + Falcon demos/games require a RGB or TV mode, and do not work with + VGA, although there are also few VGA-only games and demos."Show ST/STE borders" toggles the displaying of the borders around the ST / - STE screen. Some demos and games use the screen borders for displaying + STE. Some demos and games use the screen borders for displaying additional graphics. As enabling this option increases CPU computing time, don't enable it if you have a very slow computer. - This option affects only the ST and STE modes, TT and Falcon modes are - always displayed without borders. -
+ Borders are shown also in Falcon emulation, but Videl emulation doesn't + yet support palette effects. + This option doesn't affect TT screen mode or extended VDI resolutions. + +
+Extended VDI resolutions will emulate a sort of extended graphics card
+in the emulated machine, which gives you larger (2-16 color)
+resolutions for GEM. Select a resolution and color depth. Check to
+activate. This mode isn't affect by the other video options mentioned
+above. Uncheck to get back to a normal ST behaviour.
+
Note that there are several gotches with extended VDI +resolutions:
+
-Extended VDI resolutions will emulate a sort of extended graphics
-card in the emulated ST which give you larger resolutions with a higher
-colordepth for GEM. Select a resolution and color depth. Check to
-activate. It will disable all other video options mentioned above.
-Uncheck to get back to a normal ST behaviour.
-Note: Using an extended resolution will only work with GEM
-conformant applications. 99% of all games and demos will not run if you
-activate any extended resolution here.
+Because TT and Falcon support natively larger resolutions,
+VDI mode is most useful with ST / STE emulation.
There are multiple ways to interact with the SDL GUI.
+ +TAB and cursor keys change focus between UI elements. Additionally +Home key moves focus to first item, End key to last one. Initially +focus is on default UI element, but focus changes are remembered +between dialog invocations. Enter and Space invoke focused item. UI +elements with underlined characters can be invoked directly with Alt + +key with that character. Alt + arrow keys will act on arrow +buttons.
+ +Most importantly:
+While the emulator is running, you can activate or toggle various features via Hatari keyboard shortcuts. Below are listed the default @@ -1517,11 +1565,6 @@ shortcut key bindings:
and iconify its windowYou can change the key bindings from the Hatari configuration file. -The required key values can be seen in the SDL_keysym.h include file -(usually in /usr/include/SDL/).
+See keymap-sample.txt file for instructions.Middle button click emulates double click, which is very useful +in Fast Forward mode (where normal double clicking is nearly +impossible).
Mouse scrollwheel will act as cursor up and down keys.
The Atari ST joysticks are emulated ofcourse allowing you to play your favourite games with Hatari.
The default mode is to use a connected PC joystick. You can use any -joystick that is supported by your kernel. If your joystick works with -other applications, it will likely work with Hatari as well. Make sure +joystick that is supported by your kernel / SDL library. If your joystick works +with other applications, it will likely work with Hatari as well. Make sure it is calibrated and then off you go. Move the stick to point into the desired direction. Please note that Hatari will not detect analogue movement as the Atari ST only had digital joysticks. The first @@ -1848,9 +1914,19 @@ for bigger images is not tested very wel
The maximum size of partitions inside the hard disk (images) depends on the TOS version. TOS 1.00 and 1.02 support up to 256 MB, TOS 1.04 to 3.06 up to -512 MiB and TOS 4.0x supports up to 1 GB partitions. +512 MB and TOS 4.0x supports up to 1 GB partitions. +
++NOTE: you need to be careful when mounting device files. Depending on +the system setup (e.g. udev settings) partitions on memory cards etc. +can be mounted automatically. When Hatari is started and uses a device +file with partitions that are already mounted, data can be destroyed +(when several programs independently write to the same device). +Disable your desktop automount, or remember to manually unmount +devices before giving them to Hatari.
+With the GEMDOS HD emulation, you can easily "mount" a folder from the @@ -1862,7 +1938,17 @@ subdirectories, each of these subdirecto separate partition, otherwise the given directory itself will be assigned to drive "C:". In the multiple partition case, the letters used as the subdirectory names will determine to which -drives/partitions they're assigned. +drives/partitions they're assigned. For example following +directory setup: +
++partitions/ + + C/ + + D/ ++
+That is given to Hatari as "hatari -d partitions", will give you +GEMDOS HD emulated C: and D: drives.
GEMDOS HD emulation is an easy way to share files between the @@ -1884,11 +1970,12 @@ that is used for GEMDOS HD emulation).Anything that installs its own GEMDOS handler, like MiNT, doesn't work with the GEMDOS HD emulation. Such things need to be run from a real hard disk image. -
-So, if your programs complain that they could not find/read/write -files on the GEMDOS emulated drive, you should try to copy them to a -floppy disk image or a real hard disk image! +If your programs complain that they could not find/read/write +files on the GEMDOS emulated drive, you can copy and use them +from a floppy disk image or a real hard disk image instead. +
+ + ++Accessing HD image files is easiest with EmuTOS. It supports both +ASCI and IDE interfaces, regardless of emulated machine type, and +understands DOS partition tables without additional drivers. +atari-hd-image.sh script coming +with Hatari can be used to create such image files and to copy +initial data to them. +
++If you have an hard drive (image) with Atari format partition table, +that should already have hard disk driver on it and work fine. +Partitioning/formatting them is the problem. Creating such images +from scratch is described in following sections.
+To use the ACSI hard drive emulation, you need a hard disk image file @@ -1931,13 +2037,19 @@ the hard disk image from the emulated At After installing the hard disk driver to the fresh HD image with HINSTALL.PRG, you can boot directly from the hard disk image.
++HD Driver (v9) partitioning is also compatible with Hatari ACSI +emulation. CBHD and ICDPro AdSCSI drivers work on images which have +been partitioned elsewhere. +
+
As the IDE disk format (little endian) differs from the ACSI disk format (big endian), you need separate disk images for them. Hatari doesn't -currently support formatting IDE disks with AHDI, but you can do it with +currently support partitioning IDE disks with AHDI, but you can do it with Cecile.
@@ -1963,9 +2075,9 @@ If you only want to use your HD image in the Cecile hard disk driver to the image from the Cecile CC_TOOLS.APP: Click the "Installer" button and save the Cecile driver to the 1st partition on "Hatari IDE disk". If you want to also use your HD -image in ST/STE mode, you need to get and install AHDI 6 driver on it -instead (see ASCI hard drive -emulation section). +image in ST/STE mode, you need to get and install either HD Driver or +AHDI 6 driver on it instead (see ASCI +hard drive emulation section).
Then you can boot from your hard disk image by simply specifying it @@ -1980,19 +2092,23 @@ either through GEMDOS HD partitions (hos Hatari emulation) or accessing the images directly on the host (outside the emulation). Both have their own limitations.
-If it's fine for the IDE/ACSI partitions to be first, you can use -hard disk images with AHDI or Cecile driver and a multipartition -GEMDOS HD setup as described in above sections. If you want to boot from -a GEMDOS HD partition i.e. such to be before hard disk image partitions, -and still to be able to access all the IDE/ACSI partitions, you need to -use HD Driver.
+If it's fine for the IDE/ACSI partitions to be first, you can +either use ACSI/IDE partition skip option, or a multipartition GEMDOS +HD setup as described in above sections. +
+ +If you want to boot from a GEMDOS HD partition i.e. such to be +before hard disk image partitions, and still to be able to access all +the IDE/ACSI partitions, you need to use HD Driver. Note: this is the +preferred method with EmuTOS (v0.9.x), because it doesn't run/use +driver installed to the IDE/ACSI image directly although its own +partition table/type support is very limited.
Uwe Seimet's HD Driver works fine with both the Hatari GEMDOS HD partitions and normal -hard disk images. However, it doesn't work with EmuTOS so you need -real TOS (at least version v1.04). +hard disk images.
First copy the HDDRIVER.PRG binary into your GEMDOS HD emulation @@ -2005,12 +2121,14 @@ this GEMDOS HD directory, for example li "hatari --harddrive gemdos-hd/ --ide-master ide-hd.image".
-If you're using the demo version of HD Driver, you can -write files only to the C: partition, i.e. in above case only copy -files from the hard disk image partition to the GEMDOS HD partition (with -some write slowndowns included into the demo version). If you want to -copy files to the hard disk image with the demo version of -the HD Driver, you need to set the hard disk image as drive C:.
+If you're using +the demo version +of HD Driver, you can write files only to the C: partition, i.e. in +above case only copy files from the hard disk image partition to the +GEMDOS HD partition (with some write slowndowns included into the demo +version). If you want to copy files to the hard disk image with +the demo version of the HD Driver, you need to set the hard disk +image as drive C:.
To accomplish this, set the GEMDOS HD partitions to be from D: forward, i.e. have a directory which contains only single letter subdirectories, @@ -2019,7 +2137,8 @@ mkdir gemdos-hd/D". Then give Hat a boot floppy image containing the demo version of HDDRIVER.PRG in its AUTO folder, like this: "hatari --ide-master ide-hd.image --harddrive gemdos-hd/ hd-driver-floppy.st". -
+You can convert HD Driver ZIP package to floppy image with the +zip2st utility.-Note that plain EmuTOS supports only ACSI and the listed HD drivers -support only IDE (emulation). Cecile needs TT or Falcon and HD Driver -doesn't work with EmuTOS. To summarise; if ASCI emulation and -EmuTOS are enough, use those. Otherwise, if you want to use TT or -Falcon emulation, use Cecile (or full HD Driver version if you have -it), otherwise use HD Driver (demo). +To summarise; if EmuTOS is enough, use that. Otherwise, if you want to +use TT or Falcon emulation, use Cecile (or full HD Driver version if +you have it), otherwise use HD Driver (demo).
To access the content of the partitions on Linux host, there are two @@ -2113,11 +2230,12 @@ analyzing code that runs in the emulated
-The debugger uses Hatari's parent console window, so make sure you run -Hatari from the command line when you want to use the debugger. On -Linux you can add for example an icon to your desktop that does it -with something like this (replace "xterm" with your favorite terminal -program): +On Unix (Linux / OSX) debugger uses Hatari's parent console window, so +make sure you run Hatari from the command line when you want to use +the debugger. On Windows you need to use "-W" option to get console +window. You can add an icon to your desktop that does it. On Linux +it should do something like this (replace "xterm" with your favorite +terminal program):
xterm -T "Hatari debug window" -e hatari @@ -2305,7 +2423,7 @@ Both commands accept in addition to nume and symbol names, like in above example. If you don't specify an address, the commands continue showing from an address that comes after the previously shown data. "disasm" command default address -will be reseted to PC address every time you re-enter the debugger. +will be reset to PC address every time you re-enter the debugger.@@ -2365,11 +2483,17 @@ dsp_symbols").
For a program under GEMDOS HD emulation
-If you're using GEMDOS HD emulation, and your program contains symbol -table in DRI/GST format, you can load its symbol names/addresses to -the debugger with the following command, after program has been loaded -to the memory by TOS (see setting -breakpoint at program startup): +If currently running program contains symbol table in DRI/GST format, +and it's started from GEMDOS HD emulated drive, its symbol names / +addresses are automatically loaded when debugger is entered, and +removed when program terminates.
+ ++Above happens only if there are no symbols loaded when the program +starts. If there are, you can load program symbol data manually with +the following command, after program has been loaded to the memory by +TOS (see setting breakpoint at program +startup):
symbols prg @@ -2377,12 +2501,6 @@ symbols prg
-Debugger loads the symbols automatically for currently running -Atari program when entering the debugger, if no CPU symbols are yet -loaded. -
- -The options you need to add suitable symbol table to your programs, depend on which toolchain you use to build it:
@@ -2433,7 +2551,7 @@ cannot re-compile it to have them, you h Writing converters for other ASCII formats is easy, and Hatari already contains covertors for DSP LOD files, nm output for MiNT/a.out binaries and AHCC map files. -
ASCII symbols file format is following:
@@ -3505,10 +3623,10 @@ sure your optimization efforts can actuaCallgraphs require saved profile data to contain caller function -address information, i.e. symbols should have been loaded before -starting profiling (either automatically, or manually from ASCII -symbols file).
+Callgraphs require that saved profile data contains caller +function address information, i.e. symbols for the code should +be loaded before starting profiling it (see +loading symbol data).
Separate callgraphs will be created for each of the costs (0=calls, 1=instructions, 2=cycles) with the -g option:
@@ -3694,7 +3812,7 @@ After bus error invokes debugger, 'histo to see (executed memory addresses with their current) instructions leading to the error. The most interesting vector addresses are: $8 (Bus error), $C (Address error), $10 (Illegal instruction), -$14 (Division by zero). +$14 (Division by zero). See also --debug-except option.