--- hatari/doc/manual.html 2019/04/09 08:54:46 1.1.1.18 +++ hatari/doc/manual.html 2019/04/09 08:58:26 1.1.1.21 @@ -1,5 +1,5 @@ - + Hatari User's Manual Hatari User's Manual

-Version 1.8.0, July 2014 +Version 2.1.0, February 2018

Manual written by: Thomas Huth, Matthias Arndt @@ -87,7 +87,7 @@ Hatari on the WWW:

General description

-Hatari is an Atari ST, STE, TT and Falcon emulator for Linux, OSX, +Hatari is an Atari ST, STE, TT and Falcon emulator for Linux, *BSD, macOS, 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 @@ -104,14 +104,14 @@ 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 STE, Falcon and basic TT emulation.

Features

+

+Hatari can also emulate a Mega-STE, which had slightly different hardware +compared to a normal STE (like a built-in real time clock chip). +

Experimental TT hardware emulation

There is support for following additional TT features:

+

+Note that TT emulation is incomplete – additional hardware like the +second MFP and the SCC UARTs is not emulated yet. +

Falcon hardware emulation

There is support for following additional Falcon features:

@@ -180,8 +188,9 @@ Recent versions of Hatari even feature S
  • STE/Falcon palette switching and shifter
  • Mono/RGB/VGA/TV monitor types
  • DSP co-processor emulation
    • +
  • RAM up to 14MiB (ST-RAM) and up to 256 MiB (TT-RAM)
  • Experimental microphone (jack) emulation
    • -
  • Experimental Crossbar sound matrix (ADC (mic & PSG), DAC, DMA, DSP) +
  • Experimental Crossbar sound matrix (ADC (mic & PSG), DAC, DMA, DSP) interconnect emulation + support for the additional DMA sound sample rates
  • Experimental IDE master and slave emulation for hard drive support
    • @@ -197,35 +206,14 @@ to be affected by them.

    System requirements

    -

    Hatari currently has the following minimum system requirements:

    -     -

    -In the course of time Hatari has successfully been tested by various people on -the following systems: +Hatari needs a fast machine (1 GHz or more for ST/STE emulation, > 2 GHz +for Falcon emulation) which is running a POSIX compatible operating system +(preferably GNU/Linux) that supports the SDL library. +There are also some ports to other operating systems like macOS or Windows, +but they are not used by the developers, so such builds are normally not very +well tested.

    -

    Compiling and running

    @@ -311,9 +299,9 @@ it at: It is not the best solution for playing games or running other old software due to compatibility issues (see emutos.txt for more details), but it's free and compatible with Hatari.

    -

    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

    @@ -354,7 +342,7 @@ overriding the earlier given ones: command or through the (optionally enabled) Hatari control socket. -

    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.

    @@ -372,11 +360,10 @@ to take effect.

  • An Atari program that should be autostarted. In this case the program's directory will be used as the C: drive from where this program will be started. - (Note that autostarting a program might not work if you've also - specified a floppy image for drive A: on command line or in config - file which contains a desktop.inf/newdesk.inf/emutos.inf file on - it.)
    • + +(These arguments are shortcuts for "--disk-a", "--harddisk" and "--auto" +options listed below.)

    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 @@ -422,6 +409,10 @@ user configuration files <bool>

    On fast machine helps skipping (fast forwarding) Hatari output

    +

    --auto <program>

    +

    Autostarts given program, if TOS finds it. +Program needs to be given with full path it will have under +emulation, for example "C:\DIR\PROGRAM.PRG"

    Common display options

    -m, @@ -432,6 +423,9 @@ color

    <x>

    Select monitor type (x = mono/rgb/vga/tv)

    +

    --tos-res <x>

    +

    Select TOS resolution for color monitors +(x = low/med/high/ttlow/ttmed)

    -f, --fullscreen

    Start the emulator in fullscreen @@ -440,6 +434,9 @@ mode

    Start the emulator in windowed mode

    --grab

    Grab mouse (also) in windowed mode

    +

    --resizable <bool>

    +

    Allow window resizing

    +

    NOTE: this is supported only by Hatari SDL2 build

    --borders <bool>

    Show ST/STE/Falcon screen borders (for low/med resolution overscan demos)

    @@ -471,19 +468,28 @@ for borders / zooming

    <bool>

    Force internal bitdepth (x = 8/15/16/32, 0=disable)

    +

    --disable-video +<bool>

    +

    Run emulation without displaying video (audio only)

    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 @@ -494,6 +500,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

    @@ -540,18 +554,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

    Devices options

    -j, @@ -566,14 +584,16 @@ given port

    <file>

    Enable printer support and write data to <file>

    +

    --midi <bool>

    +

    Enable MIDI support (PortMidi only)

    --midi-in <filename>

    Enable MIDI support and write MIDI data -to <file>

    +to <file> (Linux only)

    --midi-out <filename>

    Enable MIDI support and read MIDI data -from <file>

    +from <file> (Linux only)

    --rs232-in <filename>

    Enable serial port support and use @@ -583,7 +603,7 @@ from <file>

    Enable serial port support and use <file> as the output device

    -

    Disk options

    +

    Floppy drive options

    --drive-a <bool>

    Enable/disable drive A (default is on)

    @@ -607,6 +627,18 @@ from <file>

    Write protect floppy image contents (on/off/auto). With "auto" option write protection is according to the disk image file attributes

    + +

    Hard drive options

    +

    -d, --harddrive +<dir>

    +

    GEMDOS HD emulation. Emulate hard disk partition(s) +with <dir> contents. If directory contains only single letter +(C-Z) subdirectories, each of these subdirectories will be treated +as a 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. If <dir> is +an empty string, then harddrive's emulation is disabled

    --protect-hd <x>

    Write protect hard drive <dir> @@ -616,18 +648,29 @@ 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>

    -

    Emulate hard disk partition(s) with -<dir> contents. If directory contains only single letter -(C-Z) subdirectories, each of these subdirectories will be treated -as a 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. If <dir> is -an empty string, then harddrive's emulation is disabled

    +

    --gemdos-time <x>

    +

    Specify what file modification timestamps should be used, +emulation internal (atari) ones, or ones from the machine (host) on which +the machine is running. While Atari emulation and host clocks are in sync +at Hatari startup, they will diverge while emulation is running, especially +if you use fast forward. Default is "atari". If you modify files accessed +by the Atari side, directly from the host side while Hatari is already +running, you may want to use "host" option

    +

    --gemdos-conv <bool>

    +

    Whether GEMDOS file names with 8-bit (non-ASCII) characters +are converted between Atari and host character sets. On Linux, host file +name character set is assumed to be UTF-8. This option is disabled by +default, in case you've transferred files from Atari machine without +proper file name conversion (e.g. by zipping them on Atari and +unzipping on PC)

    +

    --gemdos-drive <drive>

    +

    Assign (seprately specified) GEMDOS HD to given +drive letter (C-Z) instead of default C:, or use "skip" to specify +that Hatari should add GEMDOS HD after IDE and ACSI drives (assumes +Hatari and native HD driver parse same number of partitions from +HD images partition tables)

    --acsi <file>

    Emulate an ACSI hard drive with an image @@ -652,7 +695,7 @@ incompatibilities)

    -s, --memsize <x>

    Set amount of emulated RAM, x = 1 to 14 -MiB, or 0 for 512 KiB

    +MiB, or 0 for 512 KiB. Other values are considered as a size in KiB

    ROM options

    -t, @@ -669,24 +712,34 @@ 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>

    -

    Select machine type (x = st, ste, tt or -falcon)

    +

    Select machine type (x = st, megast, ste, +megaste, tt or falcon)

    --blitter <bool>

    Enable blitter emulation (ST only)

    @@ -704,9 +757,6 @@ interrupts.

    Patch TOS and initialize the so-called "memvalid" system variables to by-pass the memory test of TOS, so that the system boots faster.

    -

    --rtc -<bool>

    -

    Enable real-time clock

    Sound options

    --mic @@ -725,7 +775,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, @@ -752,6 +802,8 @@ values measured on STF and "linear" just voices.

    Debug options

    +

    -W, --wincon

    +

    Open console window (Windows only)

    -D, --debug

    Toggle whether CPU exceptions invoke @@ -763,7 +815,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>

    @@ -818,6 +870,11 @@ given level

    --run-vbls <x>

    Exit after X VBLs

    +

    --benchmark

    +

    Start in benchmark mode (use with --run-vbls). +This allows to measure the speed of the emulation in frames per second +by running at maximum speed (don't wait for VBL). Disable audio/video +output to have as little OS overhead as possible

    Type hatari --help to list all the command line options supported by a given version of Hatari.

    @@ -847,16 +904,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.

    @@ -890,16 +947,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

    - Hatari's GUI - the system dialog
    @@ -909,71 +971,59 @@ changes that you have made.

    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:

    +

    + 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 @@ -981,7 +1031,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.

    @@ -989,21 +1039,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 @@ -1021,6 +1061,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

    + +
    + Hatari's GUI - 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: +

    + + +

    + 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 @@ -1030,22 +1130,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

    @@ -1099,7 +1192,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.

    @@ -1148,9 +1241,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 @@ -1158,7 +1253,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.

    @@ -1182,7 +1277,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.

    @@ -1205,7 +1300,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.

    @@ -1278,25 +1373,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 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. +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 gotchas with extended VDI +resolutions:

    + +

    +Because TT and Falcon support natively larger resolutions, +VDI mode is most useful with ST / STE emulation.

    @@ -1389,7 +1499,7 @@ the screenshots and recorded videos.

    The Keyboard Dialog

    - Hatari's GUI - the keyboard dialog
    @@ -1397,12 +1507,12 @@ the screenshots and recorded videos. called "Symbolic" and "Scancode" are predefined.

    "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 - mapping. This only works on certain architectures like Linux where the - scancodes are similar to the ST scancodes (e.g. it does not work on Mac OS X). +

    "Scancode" uses the scancode values of your PC keys for keyboard mapping. + This only works on certain architectures like Linux where the scancodes are + similar to the ST scancodes (e.g. it does not work on macOS with SDL1.2). If it works on your system, this often gives better results than the symbolic mapping. Note that you also need a TOS version with the right language (e.g. use a French TOS if you are using a French keyboard).

    @@ -1412,10 +1522,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 macOS) 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.

    @@ -1484,17 +1610,44 @@ 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.

    -

    Keyboard shortcuts

    +

    Keyboard shortcuts for the SDL GUI

    + +

    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:

    + + + +

    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 macOS, the Cmd key ⌘ is used instead. +Below are listed the default shortcut key bindings:

    @@ -1504,85 +1657,104 @@ shortcut key bindings:

    - + - + - + - - - - - + - + - - + + - + - + - + - + - + - + - + - + + + + + + + + + + + + + + + + + + + + + + + + + - + - + - +
    ALTGR+aAltGr+a record animation
    ALTGR+gAltGr+g grab a screenshot
    ALTGR+iAltGr+i boss key: leave full screen mode, pause Hatari and iconify its window
    ALTGR+jtoggle joystick emulation via cursor keys - on/off between ports 0 and 1
    ALTGR+mAltGr+m (un-)lock the mouse into the window
    ALTGR+rAltGr+r (warm) reset the ST
    ALTGR+ccoldreset the ST (same as the original power switch)AltGr+ccold reset the ST (same as the original power switch)
    ALTGR+dAltGr+d open dialog to select/change disk A
    ALTGR+sAltGr+s enable/disable sound
    ALTGR+qAltGr+q quit the emulator
    ALTGR+xAltGr+x toggle normal speed/fast forward
    ALTGR+yAltGr+y enable/disable sound recording
    ALTGR+kAltGr+k save memory snapshot
    ALTGR+lAltGr+l load memory snapshot
    ALTGR+f or F11AltGr+jtoggle joystick emulation via cursor keys + on/off between ports 0 and 1
    AltGr+F1switch joystick type on joy port 0
    AltGr+F2switch joystick type on joy port 1
    AltGr+F3switch joystick type for joypad A
    AltGr+F4switch joystick type for joypad B
    AltGr+btoggle borders on/off
    AltGr+f or F11 toggle between fullscreen and windowed mode
    ALTGR+o or F12AltGr+o or F12 activate the options GUI
    PAUSEPause pause emulation
    AltGr+PAUSEAltGr+Pause invoke the internal Hatari debugger

    You 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.

    Emulated Atari ST keyboard

    @@ -1631,9 +1803,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.

    @@ -1645,23 +1817,26 @@ 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 +in Fast Forward mode (where normal double clicking is nearly +impossible).

    Mouse scrollwheel will act as cursor up and down keys.

    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. 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,12 +2023,22 @@ 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.

    +

    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.

    @@ -1862,15 +2047,29 @@ 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 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:

    -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.

    + +

    ACSI & IDE hard drive emulation with EmuTOS

    + +

    +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. +

    + +

    ACSI hard drive emulation

    To use the ACSI hard drive emulation, you need a hard disk image file @@ -1931,13 +2150,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. +

    +

    IDE hard drive emulation

    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 +2188,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 +2205,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.

    Using HD Driver with GEMDOS partitions

    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 +2234,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 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:.

    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 +2250,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.

    Accessing HDD image partitions outside of Hatari

    @@ -2035,14 +2267,12 @@ Inside the Hatari emulator, EmuTOS can a kind of images directly without any driver software. Of the Atari HD drivers mentioned above, Centek's Cecile and Uwe Seimet's HD Driver (demo) work fine with these partitions. E.g. AHDI and CBHD don't. +Cecile works only with TT or Falcon.

    -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 @@ -2096,8 +2326,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
@@ -2113,21 +2343,31 @@ 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 / macOS) 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
 
    
 
 
    
-To run debugger commands at Hatari startup, one can use the "--parse
-<file>" command line option.  This is useful e.g. for debugging
-TOS or some demo startup code, or if you always want to use some
-specific debugger setup (breakpoints etc).
+To run debugger commands from a file at Hatari startup, one can use
+the "--parse <file>" command line option.  This is useful e.g.
+for debugging TOS or some demo startup code, or if you always want to
+use some specific debugger setup (breakpoints etc).
+
    
+
+
    
+Note that when debugger scripts are run, current directory is set to
+the currently running script's directory i.e. all file operations are
+relative to it.  After script finishes, earlier current directory is
+restored.  To set current directory from a setup script, e.g. for
+scripts run at breakpoints, you need to give '-f' option for the
+'cd' command.
 
    
 
 
@@ -2170,15 +2410,18 @@ Generic commands:
            cd (  ) : change directory
      evaluate ( e) : evaluate an expression
          help ( h) : print help
-      history (hi) : show last CPU & DSP PC values & executed instructions
+      history (hi) : show last CPU/DSP PC values & executed instructions
          info ( i) : show machine/OS information
          lock (  ) : specify information to show on entering the debugger
       logfile ( f) : open or close log file
         parse ( p) : get debugger commands from file
+       rename (  ) : rename given file
+        reset (  ) : reset emulation
        setopt ( o) : set Hatari command line and debugger options
     stateload (  ) : restore emulation state
     statesave (  ) : save emulation state
         trace ( t) : select Hatari tracing settings
+    variables ( v) : List builtin symbols / variables
          quit ( q) : quit emulator
 
 CPU commands:
@@ -2193,7 +2436,7 @@ CPU commands:
       savebin (  ) : save memory to a file
       symbols (  ) : load CPU symbols & their addresses
          step ( s) : single-step CPU
-         next ( n) : step CPU, proceeding through subroutine calls
+         next ( n) : step CPU through subroutine calls / to given instruction type
          cont ( c) : continue emulation / CPU single-stepping
 
 DSP commands:
@@ -2205,7 +2448,7 @@ DSP commands:
    dspprofile (dp) : profile DSP code
        dspreg (dr) : read/write DSP registers
       dspstep (ds) : single-step DSP
-      dspnext (dn) : step DSP, proceeding through subroutine calls
+      dspnext (dn) : step DSP through subroutine calls / to given instruction type
       dspcont (dc) : continue emulation / DSP single-stepping
    @@ -2247,7 +2490,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 @@ -2257,7 +2500,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 @@ -2305,7 +2548,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 +2608,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 +2626,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:
 
    
@@ -2431,11 +2674,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 as you're debugging a program.
+
    • 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
@@ -2453,7 +2708,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
@@ -2639,7 +2894,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
 
    
@@ -2682,7 +2937,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.
 
    
 
 
@@ -2698,19 +2953,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!
@@ -2723,7 +2978,7 @@ indicates Blitter to be active (busy), t
 
    
 In addition to loaded symbols, the debugger supports also setting
 conditional breakpoints on values of some "virtual" variables listed
-by "b help". For example:
+by "variables" (v) command. For example:
 
    
 
      
 
    • If you want the emulation to stop on the first instruction of
@@ -2768,7 +3023,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
@@ -2867,19 +3122,29 @@ triggers) if you omit the instruction co
 
      
 If you want to continue just to the next instruction, use "s" (step)
 command to continue for exactly one instruction, or "n" (next), if you
-want to skip subroutine and exception calls.  "ds" and "dn" commands
-do the same for DSP.
+want to skip subroutine + exception calls and DBCC branching backwards
+(i.e. loops).  "ds" and "dn" commands do the same for DSP (except that
+"dn" doesn't skip loops).
 
      
 
 
      
 You can also continue with the "n" until instruction of certain
 type is encountered, by giving it the instruction type:
 
        
-
      • "branch" matches branch instructions: BCC, BRA, DBCC, JMP
        • 
-
      • "subcall" matches subroutine calls: BSR, JSR
        • 
-
      • "subreturn" matches return from subroutine: RTD, RTR, RTS
        • 
-
      • "exception" matches exceptions: BKPT, ILLG, STOP, TRAP, TRAPV
        • 
-
      • "exreturn" matches return from exception: RTE
        • 
+
      • "branch" matches branch instructions:
        
+    CPU: BCC, BRA, DBCC, JMP
        
+    DSP: DO/ENDO JCC, JCLR, JMP, JSET, REP
        • 
+
      • "subcall" matches subroutine calls:
        
+    CPU: BSR, JSR
        
+    DSP: JSCC, JSCLR, JSSET, JSR
        • 
+
      • "subreturn" matches return from subroutine:
        
+    CPU: RTD, RTR, RTS
        
+    DSP: RTS
        • 
+
      • "exception" matches exceptions:
        
+    CPU: BKPT, ILLG, STOP, TRAP, TRAPV
        • 
+
      • "exreturn" matches return from exception:
        
+    CPU: RTE
        
+    DSP: RTI
        • 
 
      • "return" matches both subroutine and exception returns
        • 
 
      
 
@@ -3002,28 +3267,32 @@ When you're back in debugger, you can in
 'profile' - profile CPU code
 Usage:  profile <subcommand> [parameter]
 
-        Subcommands:
-	        - on
+	Subcommands:
+		- on
 		- off
 		- counts [count]
 		- cycles [count]
-		- misses [count]
+		- i-misses [count]
+		- d-hits [count]
 		- symbols [count]
 		- addresses [address]
 		- callers
+		- caches
 		- stack
 		- stats
 		- save <file>
 		- loops <file> [CPU limit] [DSP limit]
 
-        'on' & 'off' enable and disable profiling.  Data is collected
+	'on' ¨ 'off' enable and disable profiling.  Data is collected
 	until debugger is entered again at which point you get profiling
 	statistics ('stats') summary.
 
 	Then you can ask for list of the PC addresses, sorted either by
-	execution 'counts', used 'cycles' or cache 'misses'. First can
-	be limited just to named addresses with 'symbols'.  Optional
-	count will limit how many items will be shown.
+	execution 'counts', used 'cycles', i-cache misses or d-cache hits.
+	First can be limited just to named addresses with 'symbols'.
+	Optional count will limit how many items will be shown.
+
+	'caches' shows histogram of CPU cache usage.
 
 	'addresses' lists the profiled addresses in order, with the
 	instructions (currently) residing at them.  By default this
@@ -3065,15 +3334,16 @@ around top addresses:
 
       > profile addresses 0xe06f04
 # disassembly with profile data:
-# <instructions percentage>% (<sum of instructions>, <sum of cycles>, <sum of i-cache misses>)
-$e06f04 :             bra.s     $e06f10                    0.00% (48, 576, 0)
-$e06f06 :             move.b    $fffffa01.w,d1            12.11% (555708, 8902068, 0)
-$e06f0a :             btst      #5,d1                     12.11% (555708, 6685268, 0)
-$e06f0e :             beq.s     $e06f1e                   12.11% (555708, 4457312, 0)
-$e06f10 :             move.l    $4ba,d1                   12.11% (555724, 11125668, 0)
-$e06f16 :             cmp.l     d1,d0                     12.11% (555724, 4461708, 0)
-$e06f18 :             bgt.s     $e06f06                   12.11% (555724, 4455040, 0)
-$e06f1a :             moveq     #1,d0                      0.00% (16, 64, 0)
+# <instructions percentage>% (<sum of instructions>, <sum of cycles>, <sum of i-cache misses>, <sum of d-cache hits>)
+
+$e06f04 :             bra.s     $e06f10                    0.00% (48, 576, 0, 0)
+$e06f06 :             move.b    $fffffa01.w,d1            12.11% (555708, 8902068, 0, 0)
+$e06f0a :             btst      #5,d1                     12.11% (555708, 6685268, 0, 0)
+$e06f0e :             beq.s     $e06f1e                   12.11% (555708, 4457312, 0, 0)
+$e06f10 :             move.l    $4ba,d1                   12.11% (555724, 11125668, 0, 0)
+$e06f16 :             cmp.l     d1,d0                     12.11% (555724, 4461708, 0, 0)
+$e06f18 :             bgt.s     $e06f06                   12.11% (555724, 4455040, 0, 0)
+$e06f1a :             moveq     #1,d0                      0.00% (16, 64, 0, 0)
 Disassembled 8 (of active 14240) CPU addresses.
 
      
 
      
@@ -3096,16 +3366,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.
        • 
 
      
 
 
@@ -3149,6 +3418,11 @@ Finalizing costs for 12 non-returned fun
 
      ("profile stack" command can be used in breakpoints with :noinit
 option to show backtraces during caller profiling.)
      
 
+
      Note: rest of this subsection is about caller information format
+which is mainly of interest for people writing profiling
+post-processing tools.  Come back here if you think there's
+some problem with callgraphs produced by those tools.
      
+
 
      Other information collected during profiling is shown with
 following command:
      
 
      @@ -3217,7 +3491,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%.
      • 
@@ -3266,7 +3540,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.
      
 
@@ -3492,7 +3766,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.
      
@@ -3505,10 +3779,10 @@ sure your optimization efforts can actua
 
 
      Generating and viewing callgraphs
      
 
-
      Callgraphs 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:
      
@@ -3594,7 +3868,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).
@@ -3663,7 +3937,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
 
      
@@ -3694,7 +3968,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.
 
      
 
 
      Stopping when register has a specific value
      
@@ -3721,7 +3995,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
@@ -3780,7 +4054,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:
 
      @@ -3832,6 +4106,19 @@ Please see also Profiling section for more info.
+
      
+
 
      Finding where a program or the OS is stuck
      
 
      Profiling tells from which addresses CPU is executing the instructions:
 
      @@ -3857,7 +4144,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:
 
      @@ -3918,10 +4205,10 @@ mode, so try to avoid 24 bits per pixel
 
      
 
 
      
-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
+On macOS with SDL 1.2, 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 macOS backend and how
+macOS itself composites non-fullscreen window contents. MacOS uses always
 32-bit mode.
 
      
 
@@ -4005,7 +4292,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.
 
      
@@ -4043,9 +4330,9 @@ Also, if your monitor refresh frequency
 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.
+output to screen, 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.
 
      
 
 
      Zooming
      
@@ -4153,11 +4440,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
@@ -4181,8 +4466,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.