--- hatari/doc/manual.html 2019/04/09 08:56:01 1.1.1.19
+++ hatari/doc/manual.html 2019/04/09 08:57:12 1.1.1.20
@@ -1,5 +1,5 @@
-
+
Hatari User's Manual
Hatari User's Manual
-If you do not specify a TOS image on the commandline nor can Hatari
-find a suitable TOS image in the default dir, you'll get the chance to
-select a TOS image file from the GUI.
+If you do not specify a TOS image on the commandline and Hatari
+cannot find a suitable TOS image in the default dir, you'll get the
+chance to select a TOS image file from the GUI.
Installation of the binary
@@ -477,15 +477,21 @@ for borders / zooming
ST/STE specific display options
--desktop-st
<bool>
-Whether fullscreen mode uses desktop
-resolution to avoid: messing multi-screen setups, several seconds
-delay needed by LCD monitors resolution switching and the resulting
-sound break. As Hatari ST/E display code doesn’t support
-zooming (except low-rez doubling), it doesn’t get scaled (by
-Hatari or monitor) when this is enabled. Therefore this is mainly
-useful only if you suffer from the described effects, but still
-want to grab mouse and remove other distractions from the screen
-just by toggling fullscreen mode. (disabled by default)
+
+NOTE: this has effect only for SDL1 Hatari build. In SDL2 build,
+--desktop option controls also ST/STe mode.
+Whether to use desktop resolution on fullscreen
+to avoid issues related to resolution switching (messing multi-screen
+setups, several seconds delay needed for resolution switching by some
+LCD monitors and the resulting sound break). Otherwise fullscreen will
+use a resolution that is closest to the Hatari window size.
+As Hatari ST/STe display code doesn't support
+zooming (except low-rez doubling), it doesn't get scaled (by Hatari or
+monitor) when this is enabled, and you may get large black borders
+around ST/STe screen. Therefore this is mainly useful only if you
+suffer from the described effects, but still want to grab mouse and
+remove other distractions from the screen just by toggling fullscreen
+mode. (disabled by default)
--spec512
<x>
Hatari uses this threshold to decide
@@ -496,6 +502,14 @@ Spectrum512 screen conversion functions
<x>
Zoom (double) low resolution (1=no,
2=yes)
+--video-timing
+<x>
+Wakeup State for MMU/GLUE (x=ws1/ws2/ws3/ws4/random,
+default ws3). When powering on, the STF will randomly choose one of these
+wake up states. The state will then affect the timings where border removals
+and other video tricks should be made, which can give different results on
+screen. For example, WS3 is known to be compatible with many demos, while WS1 can show
+more problems.
TT/Falcon specific display options
@@ -622,7 +636,7 @@ the file attribute modifications for the
emulation
--gemdos-case <x>
Specify whether new dir/filenames are forced to be
-in upper or lower case with the GEMDOS HD emulation. Off/upper/lower, off by default
+in upper or lower case with GEMDOS HD emulation. Off/upper/lower, off by default
-d, --harddrive
<dir>
@@ -675,19 +689,29 @@ you are doing!
(only works if GEMDOS HD emulation and extended VDI resolution are
disabled)
-CPU options
+Common CPU options
--cpulevel <x>
Specify CPU (680x0) to use (use x >=
1 with EmuTOS or TOS >= 2.06 only!)
--cpuclock
<x>
-Set the CPU clock (8, 16 or 32 Mhz)
+Set the CPU clock (8, 16 or 32 MHz)
--compatible
<bool>
Use a more compatible, but slower 68000
CPU mode with better prefetch accuracy and cycle counting
+WinUAE CPU core options
+--cpu-exact <bool>
+Use cycle exact CPU emulation (cache emulation)
+--addr24 <bool>
+Use 24-bit instead of 32-bit addressing mode (24-bit is enabled by default)
+--fpu <x>
+FPU type (x=none/68881/68882/internal)
+--mmu <bool>
+Use MMU emulation
+
Misc system options
--machine <x>
@@ -731,7 +755,7 @@ matches evenly with the STE/TT/Falcon so
<x>
SDL’s sound buffer size: 10-100,
or 0 to use default buffer size. By default Hatari uses an SDL
-buffer size of 1024 samples, which gives approximatively 20-30 ms
+buffer size of 1024 samples, which gives approximately 20-30 ms
of sound depending on the chosen sound frequency. Under some OS or
with not fully supported sound card, this default setting can cause
a bigger delay at lower frequency (nearly 0.5 sec). In that case,
@@ -771,7 +795,7 @@ flags.
--bios-intercept
Toggle XBios command parsing. Allows Atari programs to use all Hatari
-functionality and change Hatari state through Hatari specifit
+functionality and change Hatari state through Hatari specific
XBios(255) calls. XBios(20) printscreen calls produce also Hatari
screenshots.
--conout <device>
@@ -855,16 +879,16 @@ the appropriate buttons.
You can load the current settings from a configuration file by clicking
-on Load config. and you can save
+on the Load config button, and save
the current settings to a configuration file by clicking on
-Save config..
+the Save config button.
Click OK to go back and continue the emulation.
All changed options will be applied.
-Select the Reset machine option if you
+Select the "Reset machine" option if you
want the emulated machine to perform a cold reset. This is equal to
switching the power off and on again on a real Atari machine.
@@ -898,16 +922,21 @@ changes that you have made.
You can use the three buttons in the upper right corner for additional folder
navigation. Click the .. button to go up one level
- in the directory tree. Click the ~ button to return
- to your home directory. The / button can be clicked
- to go to the root directory of the file system.
+ in the directory tree. The CWD button takes you
+ to the current working directory (i.e. the folder that was current when
+ Hatari has been started). Click the ~ button to
+ return to your home directory. The / button can
+ be clicked to go to the root directory of the file system.
+
+
+ When you tick the "Show hidden files" setting, Hatari will
+ also show files that start with a dot in the file selection dialog.
-
The System Dialog
-
The machine type option is used to select the type of Atari computer to
- be emulated. The ST was the very first 16/32-bit computer from Atari.
- Most older games and demos require an ST. The STE was introduced some years
- later and had some more advanced hardware features. There are not that many
- demos or games that really require an STE but since most normal ST games/demos
- also work with an STE, it's normally safe to always work in STE mode.
-
- TT and Falcon are more advanced, but they are not as compatible to the ST as
- the STE was. Therefore many old games and demos do not work with these machine
- types anymore. There were only very few programs that were made for the TT
- exclusively, while there were some interesting games and demos specially made
- for the Falcon.
-
- Note: Falcon and especially TT emulation are still considered as
- experimental and incomplete.
- Quite a bunch of programs do not work very well yet.
-
-
- For STE emulation a STE compatible TOS image, e.q. version 1.06, 1.62 or
- 2.x, is strongly recommended. For TT emulation you need TOS 3.0x and for Falcon
- emulation you need TOS 4.0x. EmuTOS can be used on all machine types.
-
-
-
- The CPU type option can be used to select the level of the central processing
- unit. If you are not sure what to use, simply select 68000 for ST and STE
- machines and 68030 for TT and Falcon emulation, since this were the original
- configurations used in the Atari computers. In case you want to vary
- the CPU type, you have got to be aware of some constraints:
+ be emulated:
-
- Atari ST and STE have only been shipped with a 68000 CPU, so for best
- compatibility with old programs, you should choose this CPU type.
-
+ The ST was the very first 16/32-bit computer from Atari.
+ Most older games and demos require an ST. TOS 1.00, 1.02, 1.04 or 2.06
+ is required for running in ST mode.
-
- If you are going to use TOS 1.0x, you also have to select the 68000 CPU,
- since these TOS versions are not aware of the higher CPU levels yet.
- If you want to use a higher CPU level with the ST or STE machine type,
- you've got to use TOS 2.0x instead.
+ The Mega-ST was an slightly improved version which also
+ provided the so-called blitter chip (for accelerating certain graphic
+ operations) and a Real Time Clock (RTC) chip.
-
- Atari TT and Falcon computers were using the 68030 CPU, so you should select
- the 68030 CPU type for these machines.
+ The STE was introduced some years later and had some more
+ advanced hardware features, like the blitter chip, hardware scrolling and
+ DMA sample sound (but no Real Time Clock). There are not that many demos or
+ games that really require an STE but since most normal ST games/demos also
+ work with an STE, it's normally safe to always work in STE mode.
+ Also make sure to use TOS version 1.06, 1.62 or 2.0x with this machine type.
-
- TOS 3.0x and 4.0x also only work with a CPU >= 68020.
+ The Mega-STE was an improved version of the STE, with
+ 16 MHz (instead of 8 MHz) CPU frequency and a built-in Real Time Clock chip.
-
- 68010 and 68040, 68060 have never been used in official Atari computers,
- so don't use these CPU types unless you've got some good reasons.
+ The TT was the advanced workstation from Atari. It
+ featured a 32MHz 68030 CPU, a very high monochrome resolution, and a
+ lot of interfaces. However, compatibility was not as high as with the
+ other machines. For TT emulation you need TOS 3.0x.
-
- The 68060 option is only available in the "WinUAE" builds of
- Hatari, and is currently also considered as experimental, so do not use
- this option unless you know what you are doing.
-
+ The Falcon was Atari's last computer, using a 16 MHz 68030
+ CPU and some more interesting new hardware feature, like the Videl graphic
+ chip and DSP 56001 for sound. You need TOS 4.0x for running in Falcon mode.
+
+
+ Note: Falcon and especially TT emulation are still considered as
+ experimental and incomplete, so quite a bunch of programs do not work very
+ well yet.
+ Also a lot of old games and demos do not work with these machine types
+ anymore since the hardware is quite a bit different. There were only very
+ few programs that were made for the TT exclusively, while there were some
+ interesting games and demos specially made for the Falcon.
+
- The CPU clock option can be used to select the frequency that is used
- to clock the CPU. 8 Mhz is the standard for ST and STE and the most
- compatible frequency for old software.
- Use 16 MHz for Mega STE and Falcon emulation.
- The CPU in the TT was clocked with 32 MHz.
+ The video timings ("wakestate") settings influence the internal
+ timings of the ST video chip emulation. You normally do not have to change
+ these unless you know what you are doing, only some very few demos require
+ a special setting here.
+
For Falcon mode, you can choose whether you want to disable DSP emulation,
fake it or enable full emulation. Most Falcon programs only play sound or work
@@ -989,7 +1006,7 @@ changes that you have made.
power (more than 2 GHz) for full emulation. So if you have a slow host CPU,
you can try if your Falcon program also runs with DSP disabled or in
the "dummy" fake mode.
- Note that you can not change this option while the DSP based program already
+ Note that you cannot change this option while the DSP based program already
runs.
@@ -997,21 +1014,11 @@ changes that you have made.
be used to fine-tune the machine and CPU types.
- If you enable the "Real time clock emulation" switch, a RTC (like the ones
- that could be found in the Mega-ST and Mega-STE computers) will be emulated
- based on the time of the host computer.
- This option is only affects the emulation of ST and STE machines. TT and
- Falcon used a different kind of RTC (which is not optional and thus always
- enabled in Hatari).
- Note: You need at least TOS 1.02 for proper RTC emulation, TOS 1.00 does
- not support this.
-
-
- The next check box can be used to enable/disable Blitter emulation.
+ The Blitter option can be set to enable Blitter emulation in plain ST mode.
The Blitter is a custom chip that accelerates some graphical operations.
- This switch only toggles the Blitter in plain ST mode. In STE and Falcon mode,
- the Blitter is always enabled (since these machines have always been sold
- with a Blitter chip). The TT was always shipped without the Blitter chip.
+ Note that in Mega-ST, STE and Falcon mode, the Blitter is always enabled
+ (since these machines have always been sold with a Blitter chip). The TT
+ was always shipped without the Blitter chip.
The "Patch Timer-D" option changes the Timer-D initialization from
@@ -1029,6 +1036,66 @@ changes that you have made.
to be switched off to get those programs running.
+ NOTE: The emulated Atari system is very very sensitive to all of
+ these options and it is strongly recommended to reset the emulation after
+ changing them (for most things that's done automatically).
+ Most settings are also selected automatically when one uses the
+ --machine command line option.
+
+
+
+The CPU Dialog
+
+
+
+
+ The CPU type option can be used to select the level of the central processing
+ unit. If you are not sure what to use, simply select 68000 for ST and STE
+ machines and 68030 for TT and Falcon emulation, since this were the original
+ configurations used in the Atari computers. In case you want to vary
+ the CPU type, you have got to be aware of some constraints:
+
+
+ -
+ Atari ST and STE have only been shipped with a 68000 CPU, so for best
+ compatibility with old programs, you should choose this CPU type.
+
+ -
+ If you are going to use TOS 1.0x, you also have to select the 68000 CPU,
+ since these TOS versions are not aware of the higher CPU levels yet.
+ If you want to use a higher CPU level with the ST or STE machine type,
+ you've got to use TOS 2.0x instead.
+
+ -
+ Atari TT and Falcon computers were using the 68030 CPU, so you should select
+ the 68030 CPU type for these machines.
+
+ -
+ TOS 3.0x and 4.0x also only work with a CPU >= 68020.
+
+ -
+ 68010 and 68040, 68060 have never been used in official Atari computers,
+ so don't use these CPU types unless you've got some good reasons.
+
+ -
+ The 68060 option is only available in the "WinUAE" builds of
+ Hatari, and is currently also considered as experimental, so do not use
+ this option unless you know what you are doing.
+
+
+
+
+ The CPU clock option can be used to select the frequency that is used
+ to clock the CPU. 8 MHz is the standard for ST and STE and the most
+ compatible frequency for old software.
+ Use 16 MHz for Mega STE and Falcon emulation.
+ The CPU in the TT was clocked with 32 MHz.
+
+
+
The "Prefetch mode" option is used to enable the emulation of 68k
address errors and the so-called CPU prefetch buffer. This is needed for best
compatibility, but it slows down emulation a little bit so you can disable it
@@ -1038,22 +1105,15 @@ changes that you have made.
The "Cycle exact", the "MMU emulation" and
"24-bit addressing" option are only available in the
"WinUAE" builds
- of Hatari. They are considered as experimental and should be switched off
- unless you know what you are doing.
+ of Hatari. They are considered as experimental and should only be changed
+ if you know what you are doing.
The FPU settings are also only available with the "WinUAE" builds
of Hatari. They can be used to select the type of floating point unit of CPUs
- >= 68020. In the normal builds of Hatari, the FPU is always enabled for
+ >= 68020. In the non-WinUAE builds of Hatari, the FPU is always enabled for
68030 and 68040 CPUs.
-
- NOTE: The emulated Atari system is very very sensitive to all of
- these options and it is strongly recommended to reset the emulation after
- changing them (for most things that's done automatically).
- The correct CPU type and clock are automatically selected when one uses the
- --machine command line option.
-
The Floppy Disks Dialog
@@ -1107,7 +1167,7 @@ ends with a 'b'.
If you want, you can set Hatari to write-protect your disks. Atari ST
- virii can spread on disk images, so that can be a good idea. However,
+ viruses can spread on disk images, so that can be a good idea. However,
note that some programs won't work correctly (or at all) with write
protected disks, and things like saving highscores in games will fail.
@@ -1156,9 +1216,11 @@ ends with a 'b'.
emulated as the Atari hard drive.
- Check "Boot from HD" if you want Hatari to execute the AUTO folder on
- the hard disk. This option is checked by default if you specify a
- hard disk image or a directory via the command line.
+ Check "Boot from HD" to set given hard disk image / directory as TOS
+ boot device (if ACSI or IDE is enabled, it's C:, otherwise it's the
+ first specified GEMDOS HD drive). With command line options, the value
+ of this setting depends on whether you specify floppy image or harddisk
+ later on the command line (later one takes precedence).
Removing the check from the "Allow GEMDOS drive modification" option
@@ -1190,7 +1252,7 @@ to file. You can select a new filename h
snapshot from a file. Use the fileselector to select the snapshot to be
restored.
NOTE: Memory snapshots are not interchangeable between
-different versions of Hatari. E.q. if you compile a newer Hatari, you
+different versions of Hatari. e.g. if you compile a newer Hatari, you
cannot load your old memory snapshots back.
@@ -1213,7 +1275,7 @@ For STE mode, use TOS 1.06, 1.62, 2.05 o
If you want to use the TT mode, you must specify a TOS 3.06 image here.
And in Falcon mode, you have to use either TOS 4.00, 4.02, 4.04 or 4.92.
However, you should always use TOS 4.04 for Falcon mode, it's the most common one.
-Also note that TOS 4.92 can not be booted from a boot disk (like it's done on a
+Also note that TOS 4.92 cannot be booted from a boot disk (like it's done on a
real Falcon), you have to specify it directly in the TOS ROM setup dialog here.
@@ -1305,7 +1367,7 @@ resolutions for GEM. Select a resolution
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
+Note that there are several gotchas with extended VDI
resolutions:
- Only GEM conformant applications work with them, 99% of all games
@@ -1412,7 +1474,7 @@ the screenshots and recorded videos.
The Keyboard Dialog
-
"Symbolic" tries to map the symbolic values of your PC keys
to the ST keys. It should be working pretty good on all systems as long
- as your keyboard layout looks close to the standard english keyboard
+ as your keyboard layout looks close to the standard English keyboard
layout. However, you might experience some problems with special keys like
brackets etc.
"Scancode" uses the scancode values of your PC keys for keyboard
@@ -1435,10 +1497,26 @@ the screenshots and recorded videos.
at the supplied example mapfile (keymap-sample.txt) to see how to create
your own keyboard mapping.
- When the emulator runs in fast forward mode, and you want to type text,
- it can be annoying that the emulated system detects multiple key events
- due to the key repetition of the emulated system. To avoid this you can
- disable the key repetition in fast forward mode here.
+ The "Shortcuts" section can be used to configure the keyboard shortcuts
+ that can be activated while the emulation is running. Hatari supports
+ two sets of keyboard shortcuts: The first type is activated by pressing a
+ modifier key (AltGr / right Alt by default, Cmd key on Mac OS X)
+ together with the key, and the second type is directly activated by
+ pressing a single key, without additional modifier key.
+ Use the arrow buttons to select the shortcut that you want to change,
+ then press one of the Define buttons to
+ change the key for the shortcut. You'll be prompted to press the key
+ that should be used.
+ If you reconsider and don't want to change the key, you can press the
+ left mouse button instead. By pressing the right mouse button during
+ the prompt, you can also erase the current shortcut setting.
+
+
+ The last setting in this dialog can be used to disable the key repetition
+ in fast forward mode. When the emulator runs in fast forward mode, and you
+ want to type text, it can be annoying that the emulated system detects
+ multiple key events due to the key repetition of the emulated system.
+ So this can be avoided by enabling this option.
@@ -1507,7 +1585,7 @@ Click on Browse
midi-linux.txt file explains how to
select the correct MIDI device file, how to set up software sound
-synthetizing on Linux (using Alsa) if your sound card/driver doesn't
+synthesizing on Linux (using Alsa) if your sound card/driver doesn't
support MIDI, and how to set up MIDI networking e.g. between multiple
Hatari instances.
@@ -1541,8 +1619,10 @@ the selected file. ESC cancels the dialo
Keyboard shortcuts during emulation
While the emulator is running, you can activate or toggle various
-features via Hatari keyboard shortcuts. Below are listed the default
-shortcut key bindings:
+features via Hatari keyboard shortcuts. Most of them require the
+AltGr (right Alt)
+modifier key. On Mac OS X, the Cmd key ⌘ is used instead.
+Below are listed the default shortcut key bindings:
@@ -1552,93 +1632,93 @@ shortcut key bindings:
- | ALTGR+a |
+ AltGr+a |
record animation |
- | ALTGR+g |
+ AltGr+g |
grab a screenshot |
- | ALTGR+i |
+ AltGr+i |
boss key: leave full screen mode, pause Hatari
and iconify its window |
- | ALTGR+m |
+ AltGr+m |
(un-)lock the mouse into the window |
- | ALTGR+r |
+ AltGr+r |
(warm) reset the ST |
- | ALTGR+c |
+ AltGr+c |
coldreset the ST (same as the original power switch) |
- | ALTGR+d |
+ AltGr+d |
open dialog to select/change disk A |
- | ALTGR+s |
+ AltGr+s |
enable/disable sound |
- | ALTGR+q |
+ AltGr+q |
quit the emulator |
- | ALTGR+x |
+ AltGr+x |
toggle normal speed/fast forward |
- | ALTGR+y |
+ AltGr+y |
enable/disable sound recording |
- | ALTGR+k |
+ AltGr+k |
save memory snapshot |
- | ALTGR+l |
+ AltGr+l |
load memory snapshot |
- | ALTGR+j |
+ AltGr+j |
toggle joystick emulation via cursor keys
on/off between ports 0 and 1 |
- | ALTGR+F1 |
+ AltGr+F1 |
switch joystick type on joy port 0 |
- | ALTGR+F2 |
+ AltGr+F2 |
switch joystick type on joy port 1 |
- | ALTGR+F3 |
+ AltGr+F3 |
switch joystick type for joypad A |
- | ALTGR+F4 |
+ AltGr+F4 |
switch joystick type for joypad B |
- | ALTGR+f or F11 |
+ AltGr+f or F11 |
toggle between fullscreen and windowed mode |
- | ALTGR+o or F12 |
+ AltGr+o or F12 |
activate the options GUI |
- | PAUSE |
+ Pause |
pause emulation |
- | AltGr+PAUSE |
+ AltGr+Pause |
invoke the internal Hatari debugger |
@@ -1694,9 +1774,9 @@ are used for the directions and
-NOTE: Problems with simultenous keypresses most likely aren't an
+
NOTE: Problems with simultaneous keypresses most likely aren't an
issue in Hatari as many modern keyboards report/support only three
-simultenous key presses (or even just two depending on which keys
+simultaneous key presses (or even just two depending on which keys
are in question). Expensive gaming keyboards support more.
@@ -1708,12 +1788,12 @@ the ST mouse pointer.
However it is a little bit different in windowed mode as
mouse cursor positions between host and emulated Atari can get
out of sync. This can be worked around by constraining the mouse
-to the Hatari window. Pressing the ALTGR+m
+to the Hatari window. Pressing the AltGr+m
hotkey combination or starting Hatari with the
--grab command line option
grabs the mouse i.e. locks its movements to the Hatari window.
Press the shortcut key (again) to go back to normal mouse behaviour
-which allows you to move mouse outside outside the Hatari window while
+which allows you to move mouse outside the Hatari window while
Hatari is up and running. Note: pausing the emulation will also
(temporarily) release the mouse grab.
Middle button click emulates double click, which is very useful
@@ -1723,7 +1803,7 @@ impossible).
Emulated joystick
-The Atari ST joysticks are emulated ofcourse allowing you to play
+
The Atari ST joysticks are emulated of course 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 / SDL library. If your joystick works
@@ -1929,7 +2009,7 @@ devices before giving them to Hatari.
GEMDOS based hard drive emulation
-With the GEMDOS HD emulation, you can easily "mount" a folder from the
+With GEMDOS HD emulation, you can easily "mount" a folder from the
host file system to a drive of the emulated Atari.
@@ -1953,10 +2033,14 @@ GEMDOS HD emulated C: and D: drives.
GEMDOS HD emulation is an easy way to share files between the
host system and the emulated Atari, but there are also some known
-limitations which are due to the way the GEMDOS HD emulation is
+limitations which are due to the way GEMDOS HD emulation is
implemented:
+- Fforce() file handle redirection works only for standard
+handles used with GEMDOS file functions, like Fwrite() to standard
+output that is redirected to a file. File redirection is NOT supported
+e.g. for GEMDOS Ccon* console functions.
- Directory entries are returned in a (case-insensitively) sorted
order, for consistency. E.g. moving files to a different directory and
back (without changing their names) like AUTOSORT does, doesn't change
@@ -1965,10 +2049,10 @@ that order. You need to rename the files
to a valid format. If there are multiple files which converted
names are identical in TOS-format, you see only one of those.
- It is not possible to use a cartridge image at the same time
-with the GEMDOS HD emulation (Hatari has its own cartridge code
+with GEMDOS HD emulation (Hatari has its own cartridge code
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
+with GEMDOS HD emulation. Such things need to be run from a real
hard disk image.
- GEMDOS HD C: drive conflicts with the ACSI and IDE hard drives.
If you want to use GEMDOS HD directory and ACSI/IDE disk images together,
@@ -2125,7 +2209,7 @@ ide-hd.image
".
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
+GEMDOS HD partition (with some write slowdowns 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:.
@@ -2213,8 +2297,8 @@ from the loop device on top of the "hd"
After you've copied the relevant files to the "hd" directory, you need
-unmount the file system and remove the loop device binding before using
-the disk image from Hatari:
+to unmount the file system and remove the loop device binding before
+using the disk image from Hatari:
# umount $mountdir
@@ -2365,7 +2449,7 @@ D0 register values to a command, use "a0
Within arithmetic expressions parenthesis are used both to change
-the order of precendence and to indicate indirect addressing.
+the order of precedence and to indicate indirect addressing.
Unlike with conditional breakpoint expressions (explained below), you
cannot give size for the indirect addressing, a long value is always
read from the RAM address given within parenthesis. For example to
@@ -2375,7 +2459,7 @@ get a long value pointed by stack pointe
Values of arithmetic expressions are always evaluated before being
given to a command. Except for "evaluate" and "address" commands,
-they always need to be marked with quotes (""). Besides arithmetics,
+they always need to be marked with quotes (""). Besides arithmetic,
this can be used also to give symbol/register/variable values to
commands that don't otherwise interpret them. If command complains
that it didn't recognize e.g. a register name, just put it to quotes
@@ -2549,11 +2633,23 @@ cannot re-compile it to have them, you h
- Convert the symbols to ASCII format understood by the Hatari debugger.
Writing converters for other ASCII formats is easy, and Hatari already
- contains covertors for DSP LOD files, nm
+ contains converters for DSP LOD files, nm
output for MiNT/a.out binaries and AHCC map files.
- Create the ASCII symbols file by hand while you're debugging a program.
+NOTE: nm output for GCC generated
+a.out binaries includes labels also for loops,
+not just functions. While loop labels are fine for debugging, they should
+be removed before profiling. Besides causing misleading profile
+results, loop labels can seriously slow down profiling
+(call graph tracking is automatically enabled for profiling when debug
+symbols are loaded, and operations done on each matched symbol address
+cause huge overhead if that match is for something happening every few
+instructions).
+
+
+
ASCII symbols file format is following:
e01034 T random
@@ -2571,7 +2667,7 @@ starting with '#' (comments) are ignored
Debugger will automatically "relocate" the symbol addresses when it
loads them from a program binary, but with ASCII symbol files you need
to give the relocation offset(s) separately, unless the symbol names
-are for fixed adresses (like is the case e.g. with EmuTOS):
+are for fixed addresses (like is the case e.g. with EmuTOS):
symbols program.sym TEXT DATA BSS
@@ -2757,7 +2853,7 @@ b (a0) = "d0"
If you're interested only on certain bits in the value, you can use
'&' and a numeric mask on either side of comparison operator to
-mask the coresponding value, like this:
+mask the corresponding value, like this:
b ($ff820).w & 3 = (a0) && (a1) = d0 & %1100
@@ -2800,7 +2896,7 @@ b ($ffff9202).w ! ($ffff9202).w :trace
Because tracking breakpoint conditions will print the evaluated
value when it changes, they're typically used with the trace option
-to track changes e.g. to some IO register.
+to track changes e.g. to some I/O register.
@@ -2816,19 +2912,19 @@ unless tracking condition is given as th
Hatari will internally update some register values without immediately
-updating the corresponding IO address range memory addresses. For
+updating the corresponding I/O address range memory addresses. For
example the Busy bit for the internal Blitter control register is
-(internally) cleared when Blitter activity stops, but the actual IO
+(internally) cleared when Blitter activity stops, but the actual I/O
address for that control register gets updated only when something
-actually writes or reads that IO address. Many HW registers behave
+actually writes or reads that I/O address. Many HW registers behave
like this (status registers in FDC, ACIA, MFP, Blitter...).
-For breakpoints that track just a single IO register memory address, or
+For breakpoints that track just a single I/O register memory address, or
multiple ones of which none are modified by Hatari,
only by emulated code, this is not a problem, they get triggered as
expected.
-However, if you have a breakpoint that tracks multiple IO registers
+However, if you have a breakpoint that tracks multiple I/O registers
where some of them are updated by Hatari, for example to check that
other Blitter registers aren't updated while control register
indicates Blitter to be active (busy), things don't work as expected!
@@ -2886,7 +2982,7 @@ b AesOpcode ! AesOpcode && Ae
Hint: "info" command "aes", "bios", "gemdos", "vdi" and "xbios"
-subcommands for can be used to list the corresponding OS-call opcodes.
+subcommands can be used to list the corresponding OS-call opcodes.
For example, to see the GEMDOS opcodes, use:
info gemdos 1
@@ -3214,16 +3310,15 @@ Profile data accuracy from most to least
default emulation options are used is following:
- Executed CPU and DSP instruction counts are accurate.
-- DSP cycles counts (and their variance information) should be accurate.
-
-- 030 CPU instruction cache miss information (provided by WinUAE CPU core)
- is assumed to be accurate.
-- Cycles used by a given CPU instruction depend to some extent on what
- instruction(s), and data in case of 030, was processed before it.
- While Hatari has some (instruction pairing) heuristics to take
- that into account for 68000, in general instruction cycles are
- averages. For 68000, cycles (provided by OldUAE CPU core) should
- be fairly accurate, for 68030 they aren't (yet) not very accurate.
+- 68000 cycle counts have been tested to be accurate to within 1%.
+- DSP cycle counts (and the variance information) should be accurate.
+- 030 CPU instruction cache hit/miss counts (provided by WinUAE CPU core)
+ are assumed to be accurate.
+- As to 680x0 cycles... Cycles used by a given CPU instruction depend
+ on what instruction(s) is executed, where it was executed (ST or
+ TT-RAM) and what data was processed before it (was it cached).
+ E.g. 030 cycle counts can be off by tens of percents.
+- FPU instruction cycles can be off by 2x.
@@ -3335,7 +3430,7 @@ profiler cannot determine when exception
has special code to handle EmuTOS AES switcher because of this).
Typically this produces large list of functions that are finalized
at profile end, so it should be easy to detect.
-Compilicated recursive calls seem to sometimes cause inclusive
+Complicated recursive calls seem to sometimes cause inclusive
costs (ones including costs of further subroutine calls) to be
incorrect. Sometimes this can be noticed by them being even
>100%.
@@ -3384,7 +3479,7 @@ installed by Hatari, to:
When the data is post-processed, you should always provide
the post-processor symbols for the profile code! Relying just on the
-symbol in the profile data can cause costs to be asssigned to wrong
+symbol in the profile data can cause costs to be assigned to wrong
symbol, if symbol's code wasn't called through symbol's own address,
but by jumping inside its code.
@@ -3610,7 +3705,7 @@ is same as count for how many times firs
While subroutine costs should be more accurate and relevant, due to
code optimizations many of the functions are not called as subroutines
-(on m68k, using JSR/BSR), but just jumped or branced to. Because of
+(on m68k, using JSR/BSR), but just jumped or branched to. Because of
this, it's useful to compare both subroutine and between-symbols
costs. One should be able to see from the profile disassembly which
of the above cases is cause for the discrepancy in the values.
@@ -3712,7 +3807,7 @@ $ hatari_profile.py -p -g --ignore-to
In large callgraph most of the functions aren't really interesting,
because their contribution to the cost is insignificant. You can
remove large number of them with --no-leafs and --no-intermediate
-options, those options act only on on nodes which costs are below
+options, those options act only on nodes which costs are below
given threshold. Leaf nodes are ones which don't have any parents
and/or children. Intermediate ones have only single parent and
children (node calling itself is not taken into account).
@@ -3781,7 +3876,7 @@ sections.
Tracing specific things in the system
-To trace e.g. all GEMDOS calls and IO operations, use:
+To trace e.g. all GEMDOS calls and I/O operations, use:
trace gemdos,io_all
@@ -3839,7 +3934,7 @@ b d1 > 9 && d1 < 31
Stopping when memory location has a specific value
To stop when e.g. bit 1 of the Video Shifter Sync Mode byte at
-IO address $ff820a is set i.e. video frequency is 60Hz, set
+I/O address $ff820a is set i.e. video frequency is 60Hz, set
a breakpoint on:
b ($ff820a).b & 2 = 2
@@ -3898,7 +3993,7 @@ GEMDOS 0x3D Fopen("TEST.TXT", read-only)
Seeing code leading to a breakpoint
To see CPU instructions executed before debugger was entered,
-you need to enabled history tracking before it. Whenever
+you need to enable history tracking before it. Whenever
debugger is entered, you can then request given number (here 16) of
past instructions to be shown:
@@ -3975,7 +4070,7 @@ symbols prg
b pc = _my_function :quiet :noinit :file showstack.ini
I.e. whenever 'my_function' address is called, quietly trigger a
-breakpoint without reseting profiling (callstack) information and run
+breakpoint without resetting profiling (callstack) information and run
debugger command(s) from the 'showstack.ini' debugger script file,
which contains following command:
@@ -4123,7 +4218,7 @@ machine.
NOTE: Above options may cause some programs to work in correctly.
The Hatari Software Compatibility List
-lists programs known to need real real Falcon DSP emulation, Timer-D
+lists programs known to need real Falcon DSP emulation, Timer-D
frequency or accurate FDC timings. Disabling "Compatible CPU" option
is recommended only as a last resort.
@@ -4271,11 +4366,9 @@ GNU General Public License
Emulation via software is an art and Hatari is an example of this.
Emulation is to make a computer behave like a (probably) completely
-different machine on the lowest possible niveau.
+different machine on the lowest possible level.
This includes CPU and custom chip emulation allowing software written
-for the emulated machine to be run without notice.
-A good emulator will run most of the software intended for the emulated
-platform without trouble.
+for the emulated machine to be run without it noticing a difference.
The key to emulation is to simply do those things with a software
@@ -4299,8 +4392,8 @@ error-free using such a simple loop syst
But in most cases the CPU emulation is the simplest part. Correct
-emulation of the various custom chips and hardware
-parts of the emulated system is much trickier.
+emulation of the various custom chips and hardware parts of the
+emulated system, and their proper synchronization, is much trickier.