--- hatari/doc/manual.html 2019/04/09 08:57:12 1.1.1.20
+++ hatari/doc/manual.html 2019/04/09 09:00:43 1.1.1.23
@@ -8,7 +8,7 @@
-
-
+
@@ -64,7 +64,7 @@
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
Public License (GPL).
-The Atari ST was a 16/32 bit computer system which was first released by Atari
+The Atari ST was a 16/32-bit computer system which was first released by Atari
in 1985. Using the Motorola 68000 CPU, it was a very popular computer having
quite a lot of CPU power at that time. See Appendix B for details on emulation
in general.
-Unlike many other Atari ST emulators which try to give you a good
+Unlike many other Atari emulators which try to give you a good
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
+as close as possible so that it is able to run most of the old 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
- 68000 - 68040 emulation via the UAE CPU core
- (68060 and MMU emulation only with the WinUAE CPU core)
+ (additional 68060 and MMU emulation only with the WinUAE CPU core)
- ST RAM size variable (from 512kiB up to 14MiB are possible)
- - TT RAM size variable (from 0 up to 256MiB are possible)
+ - TT RAM size variable (from 0 up to 512MiB are possible)
- optional cartridge images for the ST ROM port
- most of the ST specific hardware
- ST Shifter with ST-High, ST-Medium and ST-Low resolutions,
@@ -120,7 +119,8 @@ Recent versions of Hatari even feature S
- 512 color ST palette
- Spec512 mode support for low and medium resolutions
- many raster effects
- - scaling of low resolutions by factor two
+ - scaling of low ST resolutions by factor two (with SDL1)
+ or to any size (with SDL2)
- interleaved lines rendering of ST-medium and (scaled) ST-low
resolutions for the TV "monitor type"
- Blitter chip emulation
@@ -128,7 +128,7 @@ Recent versions of Hatari even feature S
- Printer port emulation on hardware level (print to file)
- RS232 emulation
- MIDI input/output/through emulation
- - Mega ST real time clock
+ - Mega ST(E) real time clock (for Mega-ST and Mega-STE mode)
- IKBD emulation (keyboard, mouse and joystick) with custom
keyboard mapping
- joystick emulation via cursor keys and joystick emulation via a
@@ -163,15 +163,23 @@ Recent versions of Hatari even feature S
- STE joypads
- TOS versions 1.06, 1.62, 2.05 and 2.06 (and EmuTOS) can be used in STE mode.
+
+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:
- TT low/med/high resolution support
- ST/TT palette switching and video shifter
- - RAM up to 14MiB (ST-RAM) and up to 256 MiB (TT-RAM)
- - Only TOS version 3.06 (and EmuTOS) can be used in TT mode.
+ - RAM up to 14MiB (ST-RAM) and up to 512 MiB (TT-RAM)
+ - Only TOS version 3.05 and 3.06 (and EmuTOS) can be used in TT mode.
+
+Note that TT emulation is incomplete – e.g. the second MFP is not
+emulated yet.
+
Falcon hardware emulation
There is support for following additional Falcon features:
@@ -181,14 +189,21 @@ 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)
+ RAM up to 14MiB (ST-RAM) and up to 512 MiB (TT-RAM)
Experimental microphone (jack) emulation
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
- TOS versions 4.00, 4.02, 4.04 and 4.92 (and EmuTOS) can be used in Falcon mode.
+ Experimental NCR5380 SCSI emulation for hard drive support (incomplete)
+ TOS versions 4.00, 4.02, 4.04 and 4.92 (and EmuTOS) can be used in Falcon
+ mode. There is also experimental support for TOS 2.07 (the "Sparrow"-TOS),
+ but it is not recommended to use it
+
+Both TT and Falcon emulation support NVRAM for persistent OS configuration
+and RTC (real time clock).
+
See the developers' doc/todo.txt file
(included with Hatari sources) for the details on the few remaining
@@ -199,35 +214,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.
-
- - Linux/i86 with Kernel 2.4.x and 2.6.x
- - Linux/PPC with Kernel 2.4.x and 2.6.x
- - BeOS/i86
- - Apple Mac OS X on PowerPC and i86
- - NetBSD 1.6 on i86
- - NetBSD on a Digital Alpha
- - FreeBSD 4.1 on an i486, FreeBSD 4.8 on a Pentium 4 and FreeBSD 5.1
- - OpenBSD 3.5 and 5.0
- - Solaris 8 on a SUN UltraSparc 1
- - Linux/ARM (oabi) on Sharp Zaurus SL-C760 PDA
- - Linux/ARM (eabi) on Nokia Maemo Internet Tablets and N900 phone
- - Windows XP
-
Compiling and running
@@ -254,7 +248,12 @@ decrease AVI video recording file sizes.
The GNU Readline library for Hatari debugger command line editing.
The Xlib library to support Hatari Python UI window embedding
on systems with the X window system (Linux and other unixes).
-The portaudio library for Falcon microphone recording support
+The PortMidi library required for MIDI support on macOS and Windows
+http://portmedia.sourceforge.net/.
+The portaudio library for Falcon microphone recording support.
+The udev library for NatFeats SCSI driver media change detection (Linux).
+The IPF support library
+http://www.softpres.org/download.
The versions available in your Linux distribution will be sufficient
@@ -264,7 +263,7 @@ package.
-After you've verified that you have the required libraries and their
+After you have verified that you have the required libraries and their
development files, change to the hatari/
directory. Create a build/ directory under
it and configure the build system for your environment:
@@ -301,18 +300,18 @@ of the emulated Atari.
Unfortunately it is not possible to ship an original ROM
image with the Hatari package since these images are still copyrighted.
-But you can easily create an image with a real ST and one of those various
-ROM-image programs for the ST (search for "TOSDUMP" with your
-favourite internet search engine). If your old ST does not work anymore, you
-can also try to search the internet directly for corresponding TOS ROM image,
-but don't ask the Hatari team where to get one.
+But you can easily create an image with a real Atari machine and one of
+those various ROM-image programs for them (search for "TOSDUMP" with your
+favourite internet search engine).
Another solution is EmuTOS, which is also shipped with the official
release versions of Hatari. EmuTOS is an open-source TOS clone. You can find
it at:
http://emutos.sourceforge.net/.
-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.
+It is not the best solution for Falcon emulation, playing old games
+or running other old software due to compatibility issues (see
+emutos.txt for more details),
+but it is free, compatible with Hatari, doesn't require driver to
+support harddisk images, and it boots much faster than original TOS.
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.
@@ -352,8 +351,9 @@ overriding the earlier given ones:
User specific ~/.hatari/hatari.cfg
configuration file
Command line arguments
-Option changes done at run-time in Hatari options GUI, with debugger "setopt"
- command or through the (optionally enabled) Hatari control socket.
+Option changes done at run-time in Hatari options GUI, with debugger
+ "setopt" command, or through the (optionally enabled) Hatari command
+ FIFO or control socket
Some of the run-time changes require emulation to be reset for them
@@ -374,11 +374,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
@@ -424,6 +423,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,
@@ -434,6 +437,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
@@ -442,6 +448,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)
@@ -473,6 +482,9 @@ 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
@@ -544,11 +556,30 @@ depth <x> (x = 1, 2 or 4)
--vdi-width
<w>
Use extended VDI resolution with width
-<w> (320 < w <= 1280)
+<w> (320 < w <= 2048)
--vdi-height
<h>
Use extended VDI resolution with height
-<h> (200 < h <= 960)
+<h> (200 < h <= 1280)
+
+TOS and popular GEM progams add extra restrictions for the VDI screen
+size. In total screen can take at maximum 300kB, width needs to be
+multiple of 128/planes, and height multiple of 16 pixels (or 8,
+depending on system font height). That translates to following maximum
+standard resolutions for the VDI mode:
+
+monochrome
+
+FullHD (1920×1080), WUXGA (1920x1200) and QWXGA (2048x1152)
+
+2 plane mode (4 colors)
+
+HD (1280x720), WXGA (1280x768) and XGA+ (1152x864)
+
+4 plane mode (16-colors)
+
+qHD (960x540), DVGA (960x640) and WSVGA (1024x600)
+
Screen capture options
--crop
@@ -586,24 +617,30 @@ 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
+
Enable MFP serial port support and use
<file> as the input device
--rs232-out
<filename>
-Enable serial port support and use
+
Enable MFP serial port support and use
<file> as the output device
+--scc-b-out
+<filename>
+Enable SCC channel B serial port support and use
+<file> for the output (only for Mega-STE, TT and Falcon)
-Disk options
+Floppy drive options
--drive-a
<bool>
Enable/disable drive A (default is on)
@@ -622,11 +659,27 @@ from <file>
--disk-b
<file>
Set disk image for floppy drive B
+--fastfdc
+<bool>
+Speed up FDC emulation (can cause
+incompatibilities)
--protect-floppy
<x>
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>
@@ -638,32 +691,47 @@ emulation
Specify whether new dir/filenames are forced to be
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
---acsi
-<file>
-Emulate an ACSI hard drive with an image
-<file>
+--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 have 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 (separately 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
+the partition tables in HD images)
+--acsi <id>=<file>
+Emulate an ACSI hard drive with given bus ID (0-7)
+using image <file>. If just a filename is given, it is assigned to
+bus ID 0
+--scsi <id>=<file>
+Emulate a SCSI hard drive with given bus ID (0-7)
+using image <file>. If just a filename is given, it is assigned to
+bus ID 0
--ide-master
<file>
-Emulate an IDE master hard drive with an
+
Emulate an IDE 0 (master) hard drive with an
image <file>
--ide-slave
<file>
-Emulate an IDE slave hard drive with an
+
Emulate an IDE 1 (slave) hard drive with an
image <file>
---fastfdc
-<bool>
-Speed up FDC emulation (can cause
-incompatibilities)
+--ide-swap <id>=<x>
+Set byte-swap option <x> (off/on/auto) for
+given IDE <id> (0/1). If just option is given, it is applied to
+IDE 0
Memory options
@@ -672,7 +740,11 @@ 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
+--ttram
+<x>
+Set amount of emulated TT RAM (for Falcon and TT
+mode), x = 0 to 512 MiB
ROM options
-t,
@@ -709,14 +781,16 @@ CPU mode with better prefetch accuracy a
Use 24-bit instead of 32-bit addressing mode (24-bit is enabled by default)
--fpu <x>
FPU type (x=none/68881/68882/internal)
+--fpu-softfloat <bool>
+Use full software FPU emulation (Softfloat library)
--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)
@@ -734,9 +808,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
@@ -792,12 +863,13 @@ the debugger
Specify which exceptions invoke debugger, see
"--debug-except help" for available (comma separated) exception
flags.
---bios-intercept
+--bios-intercept <bool>
-Toggle XBios command parsing. Allows Atari programs to use all Hatari
+Enable/disable XBios command parsing. Allows Atari programs to use all Hatari
functionality and change Hatari state through Hatari specific
XBios(255) calls. XBios(20) printscreen calls produce also Hatari
-screenshots.
+screenshots. XBios(11) Dbmsg call can be used to invoke the debugger.
+
--conout <device>
Enable console (xconout vector functions) output
redirection for given <device> to host terminal. Device 2 is for
@@ -831,10 +903,18 @@ used to create it automatically.
core dumps. SDL parachute is enabled by default to restore video
mode in case Hatari terminates abnormally while using non-standard
screen resolution.
---control-socket
-<file>
-Hatari reads options from given socket
-at run-time
+--control-socket <path>
+
+Hatari connects to given local socket file and reads commands from it.
+Use when the control process life-time is longer than Hatari's, or
+control process needs response from Hatari
+
+--cmd-fifo <path>
+
+Hatari creates the indicated FIFO file and reads commands from it.
+Commands can be echoed to FIFO file, and are same as with the control
+socket. Hatari outputs help for unrecognized commands and subcommands
+
--log-file
<file>
Save log output to <file>
@@ -850,6 +930,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.
@@ -857,7 +942,7 @@ the command line options supported by a
Using the emulated system
- Once you've started Hatari successfully, you can use the emulator as
+
Once you have started Hatari successfully, you can use the emulator as
an almost complete Atari ST computer system.
The GUI
@@ -956,14 +1041,17 @@ changes that you have made.
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.
+ operations) and a Real Time Clock (RTC) chip. A note for experts: Hatari
+ emulates the Mega-ST with the so-called IMP chipset, while the normal
+ ST is emulated with the Ricoh chipset. This gives a slightly different
+ behavior between the two machine types with regards to bus errors.
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.
+ work with an STE, it is 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.
@@ -980,7 +1068,7 @@ changes that you have made.
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
@@ -1047,7 +1135,7 @@ changes that you have made.
The CPU Dialog
-
+ When emulating the FPU, you can use your own PC's CPU/FPU to do the math.
+ This is the default and fastest method, but recent CPU might have some slight
+ differences in rounding when compared to a real Motorala FPU.
+ For higher precision, you can select the "Softfloat" emulation mode : this will
+ emulate all the FPU operations using only the CPU and with the same rules as the
+ Motorala's FPU. In that case, FPU emulation will be a little slower.
@@ -1203,7 +1297,7 @@ ends with a 'b'.
The Hard Disks Dialog
-
- Here you can select a hard disk image file for ACSI, IDE master or
- slave hard drive emulation, or you can select a host directory to be
- emulated as the Atari hard drive.
+ Here you can select a hard disk image file for ACSI, SCSI or IDE hard drive
+ emulation, or you can select a host directory to be emulated as the Atari
+ hard drive. Use the arrow buttons to select the ID of the drive that you
+ want to set, then click on Browse to choose
+ a file which should be used for providing the contents of the hard disk,
+ or click on Eject to disable the current ID.
+
+
+ IDE controllers are using a 16-bit interface, so depending on where the
+ contents of a real hard disk have initially been created (on an Atari
+ machine or on a PC), and depending on where the contents have been read
+ out from the disk, 16-bit values in the image might be byte-swapped.
+ Hatari can either try to detect this situation automatically (when
+ "Auto" is selected), or you can tell Hatari whether it should
+ always byte-swap the disk image contents or not.
+
+
+ GEMDOS HD emulation can be used to provide a folder on your host
+ computer file system as hard drive(s) to the emulated Atari. Select
+ Browse to choose a folder, or
+ Eject to disable the drive(s) again.
+
+ The "Atari <-> host 8-bit filename conversion" setting
+ can be used to tell Hatari whether it should try to convert the character
+ set of the file names on the host to the Atari character set, since
+ modern operating systems use different character sets than Atari TOS.
+ File name conversion option is best-effort conversion between
+ the host OS and Atari character set for the non-ASCII file names
+ exposed by the GEMDOS HD emulation.
+
+ GEMDOS HD emulation can override partition(s) from HD images.
+ With "Add GEMDOS HD after ACSI/SCSI/IDE partitions" option Hatari
+ tries to assign it to a drive after the partitions on HD images,
+ instead of C: (whether that works correctly depends on whether
+ your emulated Atari hard disk interprets the HD images partition
+ tables similarly to Hatari, and whether it starts assigning them
+ from C: onwards). As a last resort, you can use "--gemdos-drive"
+ command line option to explicitly specify which drive should be
+ used for GEMDOS HD.
+
+ Finally, you can also choose whether you want to provide the files on
+ GEMDOS HD only as write-protected to the Atari environment or not,
+ or whether you want Hatari to select this status automatically depending
+ on the file attributes of the file in the host file system.
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
+ boot device (if ACSI or IDE is enabled, it is C:, otherwise it is 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
- will prevent Atari programs from modifying the files in GEMDOS HD
- emulation directory or creating new files under it.
-
-
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.
+ ACSI hard drive emulation does not work with TOS 4.0x in Falcon mode.
+ For SCSI emulation, you either need to run with TT or Falcon emulation.
+ Please also refer to the Hard disk support
+ chapter for more details about hard disk emulation.
The Memory Dialog
-
You can select the amount of RAM for the emulated ST here. Only
+
You can select the amount of RAM for the emulated machine here. Only
amounts that were valid on a real unmodified STFM can be selected.
Note: This option is critical and you are strongly advised
-to reset the emulated ST
+to reset the emulated machine
when changing this option.
+TT RAM size allows to emulate up to 512 MiB of 32-bit RAM. This is only
+useful in Falcon or TT mode and require to disable "24 bit addressing" mode
+in the CPU options
Here you will find the options to save memory snapshots as well.
Click on Save to save a memory snapshot
to file. You can select a new filename here.
@@ -1270,12 +1406,14 @@ You can also select an optional cartridg
class="button">Eject to disconnect the custom cartridge image.
+Depending on the machine type that you want to emulate, you can either use
+EmuTOS, or you must use a TOS version that supports the machine type.
For ST mode, use TOS 1.00, 1.02, 1.04 or 2.06.
For STE mode, use TOS 1.06, 1.62, 2.05 or 2.06.
-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 cannot be booted from a boot disk (like it's done on a
+If you want to use the TT mode, you must specify a TOS 3.05 or 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 is the most common one.
+Also note that TOS 4.92 cannot be booted from a boot disk (like it is done on a
real Falcon), you have to specify it directly in the TOS ROM setup dialog here.
@@ -1451,7 +1589,7 @@ has different implementations for differ
You should set these values to a size that suits best your monitor
-resolution. It's intended to help in getting Hatari to best use your
+resolution. It is intended to help in getting Hatari to best use your
monitor space on a windowed mode and in fullscreen avoiding "fuzzy"
scaling done by your LCD monitor.
@@ -1485,9 +1623,9 @@ the screenshots and recorded videos.
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).
@@ -1500,9 +1638,9 @@ the screenshots and recorded videos.
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.
+ 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
@@ -1573,9 +1711,9 @@ details.
enter a new filename as well.
Check the second checkmark to enable RS232 support.
The RS232 device is configured according to the settings of
-the emulated RS232 of the Atari ST. This means Hatari will
+the emulated MFP RS232 of the Atari ST/STE/TT. This means Hatari will
automatically use baudrate and handshaking as configured for the
-emulated ST.
+emulated machine.
Click on Browse to select suitable
device files for serial input and output. On Linux a good choice is
/dev/ttyS0 or /dev/ttyS1.
@@ -1621,7 +1759,7 @@ the selected file. ESC cancels the dialo
While the emulator is running, you can activate or toggle various
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.
+modifier key. On Mac macOS, the Cmd key ⌘ is used instead.
Below are listed the default shortcut key bindings:
@@ -1654,7 +1792,7 @@ Below are listed the default shortcut ke
| AltGr+c |
- coldreset the ST (same as the original power switch) |
+ cold reset the ST (same as the original power switch) |
| AltGr+d |
@@ -1706,6 +1844,10 @@ Below are listed the default shortcut ke
switch joystick type for joypad B |
+ | AltGr+b |
+ toggle borders on/off |
+
+
| AltGr+f or F11 |
toggle between fullscreen and windowed mode |
@@ -1868,10 +2010,14 @@ this can cause your printer to print out
Serial communications in Hatari is designed to directly use a serial
port on your PC.
Communications parameters are set automatically upon the settings of
-the emulated ST. This means all you do is to set
-the communication parameters like baudrate from your ST communications
-software. Hatari will do the rest and handle
-the serial input and output for you.
+the emulated machine. This means all you do is to set the communication
+parameters like baudrate from the emulated communications software.
+Hatari will do the rest and handle the serial input and output for you.
+Note that the “normal” RS232 port of Hatari is the one that
+is connected to the MFP chip of the selected system. This port is only
+wired on the ST, STE and TT machines, but not on the Falcon. To use serial
+port emulation in Falcon mode, you have to use the “SCC channel B”
+emulation instead.
Floppy disk images
@@ -1947,7 +2093,7 @@ the DIM images into ST images by strippi
For example try something like:
dd if=input.dim of=output.st bs=32 skip=1
- If you've got a disk image that has been created with the old ST
+
If you have got a disk image that has been created with the old ST
emulator PaCifiST (for DOS) or with early versions of the program
Makedisk, and the disk image does not work with Hatari, then the disk
probably suffers from the "PaCifiST bootsector bug" (Hatari will
@@ -2032,15 +2178,10 @@ 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 GEMDOS HD emulation is
-implemented:
+host system and the emulated Atari, but there are also several
+limitations:
-- 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
@@ -2065,6 +2206,16 @@ with GEMDOS HD partitions.
- The GEMDOS HD emulation does not work (very well) with TOS
1.00 and 1.02. Use at least TOS 1.04 if you want the GEMDOS HD
emulation to work properly.
+- Fforce() file handle redirection works only for standard
+handles used with GEMDOS file functions, such as Fwrite() to standard
+output that is redirected to a file. File redirection is NOT supported
+e.g. for GEMDOS Ccon* console functions.
+
- Host and emulation have their own clocks, which will drift apart
+after emulation is started, especially when emulation is
+fast-forwarded or paused. Because of this, anything inside emulation
+that relies on file timestamps (e.g. build utilities) may not work as
+expected if you modify the files on the host after emulation is
+already running.
If your programs complain that they could not find/read/write
@@ -2115,7 +2266,7 @@ disk image with it.
Formatting and partitioning works currently only with AHDI 5, but you
-can install the AHDI 6 driver to the hard disk after it's formatted.
+can install the AHDI 6 driver to the hard disk after it is formatted.
Restart the emulated system, run AHDI.PRG from the floppy disk to access
the hard disk image from the emulated Atari and then run HINSTALL.PRG.
After installing the hard disk driver to the fresh HD image with
@@ -2130,7 +2281,6 @@ 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 partitioning IDE disks with AHDI, but you can do it with
@@ -2176,7 +2326,7 @@ 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
+
If it is 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.
@@ -2274,9 +2424,8 @@ MTOOLS_NO_VFAT=1 mcopy -spmv -i hd.img f
Using a loopback device
-This is recommended even by Mtools documentation, but it's less
-convenient as it requires root rights. First you need to "loop"
-mount the image:
+This is recommended even by Mtools documentation, but it is less convenient
+as it requires root rights. First you need to "loop" mount the image:
$ su
@@ -2296,7 +2445,7 @@ the hd.img
-After you've copied the relevant files to the "hd" directory, you need
+After you have copied the relevant files to the "hd" directory, you need
to unmount the file system and remove the loop device binding before
using the disk image from Hatari:
@@ -2314,7 +2463,7 @@ analyzing code that runs in the emulated
-On Unix (Linux / OSX) debugger uses Hatari's parent console window, so
+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
@@ -2326,10 +2475,19 @@ 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.
@@ -2343,14 +2501,14 @@ You can invoke the debugger manually by
With the "-D" command line option, you can toggle whether m68k
exceptions will also invoke the debugger. Which exceptions cause
-this, can be controlled with the "--debug-except" option.
+this, can be controlled with the "--debug-except" option.
Giving "-D" option at Hatari startup is not advised because TOS HW
-checks generate some exceptions at every TOS boot. It's better to
+checks generate some exceptions at every TOS boot. It is better to
toggle exception catching later from the debugger with the "setopt -D"
-command.
+command.
@@ -2372,15 +2530,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:
@@ -2395,7 +2556,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:
@@ -2407,7 +2568,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
@@ -2423,7 +2584,7 @@ pressing TAB will (for most commands) sh
If you want to give numbers in other number bases
than the default/selected one, they need to be prefixed with a
character indicating this. For decimals this prefix is "#" (#15),
-for hexadecimals "$" ($F), and for binary values it's "%" (%1111).
+for hexadecimals "$" ($F), and for binary values it is "%" (%1111).
@@ -2442,14 +2603,14 @@ conditional breakpoints can be unexpecte
Instead of a number, you can also use an arithmetic expression, by
surrounding it with quotes (""). An expression can contain
-calculations with CPU and DSP register, symbol and Hatari variable
-values in addition to numbers. For example to give a sum of A0 and
-D0 register values to a command, use "a0+d0".
+calculations with CPU and DSP registers, symbols and Hatari variables
+in addition to numbers. For example to give a sum of A0 and D0
+register values to a command, use "a0+d0".
-Within arithmetic expressions parenthesis are used both to change
-the order of precedence and to indicate indirect addressing.
+Also within arithmetic expressions, parenthesis are used to indicate
+indirect addressing, not to change the order of precedence.
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
@@ -2467,6 +2628,29 @@ and it will be "evaluated" before being
+Virtual V0-V7 "registers" can be used to store intermediate results
+for calculations. For example, to get a sum of "_counter" symbol
+address contents one could use following in suitable breakpoint:
+
+
+# store counter sum to V0 virtual register
+r v0=(_counter)
+# store count of how many values are added
+r v1="v1+1"
+
+And then later on, calculate the average:
+
+# round the counter sum (add half count to sum)
+r v2="v0 + v1/2"
+# and calculate the rounded average (rounded sum / count)
+e v2/v1
+
+(Another virtual register was used for rounding here, in case one
+wants to continue summing the _counter values with the original
+value.)
+
+
+
With command argument completion (see build
notes), result from the last "evaluate" command can be inserted
by typing '$' and pressing TAB.
@@ -2483,8 +2667,11 @@ commands to do the same for the DSP.
> help memdump
'memdump' or 'm' - dump memory
-Usage: m [start address-[end address]]
- dump memory at address or continue dump from previous address.
+Usage: m [b|w|l] [start address-[end address| count]]
+ dump memory at address or continue dump from previous address.
+ By default memory output is done as bytes, with 'w' or 'l'
+ option, it will be done as words/longs instead. Output amount
+ can be given either as a count or an address range.
> help disasm
@@ -2567,8 +2754,8 @@ dsp_symbols").
For a program under GEMDOS HD emulation
-If currently running program contains symbol table in DRI/GST format,
-and it's started from GEMDOS HD emulated drive, its symbol names /
+If currently running program contains debug symbol table,
+and it is started from GEMDOS HD emulated drive, its symbol names /
addresses are automatically loaded when debugger is entered, and
removed when program terminates.
@@ -2582,7 +2769,6 @@ startup):
symbols prg
-
The options you need to add suitable symbol table to your programs,
@@ -2592,10 +2778,11 @@ depend on which toolchain you use to bui
Devpac:
"OPT D+,X+"
AHCC:
-"-g", and "-l" option for local symbols, both for linking
+"-g" and "-l" options for linking
GCC:
-"-Wl,--traditional-format" option for linking,
- and "-g" for compilation to get local symbols
+"-g" for compilation, and no strip option for linking
+(with older Hatari versions that didn't support a.out format,
+also "-Wl,--traditional-format" option was needed for linking)
VBCC:
"-g" (can only be used at linking phase), when VBCC
configuration file uses "-bataritos" option for
@@ -2613,10 +2800,10 @@ $ gst2ascii -l -o program.tos > progr
For a program on a (disk) image
-If the program isn't run from a GEMDOS HD emulated drive, but from a
-cartridge, floppy or HD image, you need to have the corresponding
-program also as normal host file which location you can give to the
-debugger:
+If the program isn't run from a GEMDOS HD emulated drive, but from
+a cartridge, floppy or HD image, you need to have the corresponding
+program also as a normal host file which location you can give to
+the debugger:
symbols /path/to/the/program.tos
@@ -2626,9 +2813,9 @@ symbols /path/to/the/program.tos
ASCII debug symbol files
-If Hatari complains that your program doesn't have DRI/GST format
-symbol table, or its symbols are in some other format, and you
-cannot re-compile it to have them, you have two options:
+If Hatari complains that your program doesn't have debug symbol table,
+or its symbols are in some unsupported format, and you cannot re-compile
+it to include a.out or GST/DRI symbols, you have two options:
- Convert the symbols to ASCII format understood by the Hatari debugger.
@@ -2702,7 +2889,7 @@ breakpoints so you need to use "b" comma
Then there are the conditional breakpoints which can handle much more
complex break condition expressions; they can track changes to
register and memory values with bitmasks, include multiple conditions
-for triggering a breakpoint and so on. Use "b" (or "db" for the DSP)
+for triggering a breakpoint and so on. Use "b" (or "db" for the DSP)
to manage them.
@@ -2738,7 +2925,7 @@ conditions need to be true for a breakpo
Normally when a breakpoint is triggered, emulation is stopped and you
get to the debugger. Breakpoint options can be used to affect what
happens when a breakpoint is triggered. These options are given after
-the conditions and are prefixed with ':'.
+the conditions and are prefixed with ':'.
@@ -2752,7 +2939,7 @@ a $1234 :2
- once
-
-Delete the breakpoint when it's hit i.e. trigger it only once. It may
+Delete the breakpoint when it is hit, i.e. trigger it only once. It may
be useful if you just want to get a specific address. Or if you're on
an instruction that jumps back to a start of the loop and you want to
finish the loop, you could use:
@@ -2871,7 +3058,7 @@ b d0 > $20 && d0 < $40
As a convenience, if the both sides of the comparison are exactly the
-same (i.e. condition is redundant as it's always either true or
+same (i.e. condition is redundant as it is always either true or
false), the right side of the comparison is replaced with
its current value. This way you can give something like this:
@@ -2937,23 +3124,37 @@ 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
- next program; after TOS desktop is up, set a breakpoint on
- the TEXT segment address given in a program basepage:
+
- Aes/Bios/Gemdos/LineA/LineF/Vdi/XbiosOpcode variables can be used
+ to catch AES, BIOS, GEMDOS, Line-A, Line-F, VDI and XBIOS OS-calls.
+ By default they contain the 0xffff value, so to trace e.g. all AES
+ calls (instead of a specific one) one needs to use something like this:
+
+b AesOpcode ! AesOpcode && AesOpcode < 0xffff :trace
+
+
+- To stop when TOS starts next program, set a breakpoint for
+ Pexec(0,...) OS call:
+
+b GemdosOpcode = 0x4B && OsCallParam = 0x0
+
+
+- Then, to stop emulation on the first instruction of that
+ program, set a breakpoint when program counter matches
+ the TEXT (i.e. code) segment address (taken from program
+ basepage):
b pc = TEXT :once
-Note1: It's better to trigger it only once because if you'd leave it on,
-during reboot you would get a warning for every instruction until TOS sets
-a valid basepage.
+Note1: It is better to trigger it only once, because if you would leave it
+on, during (re)boot you would get a warning for every instruction
+(until TOS sets a valid basepage).
-Note2: you cannot use an address breakpoint for this because value of
-a variable given to address breakpoint is evaluated when it's set, not
-at run-time, so it cannot get the new value that the TEXT variable
-gets when you start a program.
+Note2: you cannot use an address breakpoint for this because
+variable values are evaluated at run-time only for conditional
+breakpoints.
- To view current program DATA and BSS segment contents,
use the corresponding variables:
@@ -2964,20 +3165,12 @@ m BSS
- If you want to stop at a specific cycle within a frame (that is,
PC relative to the current VBL/HBL in cycles), set breakpoints to
- specific "HBL" and "FrameCycles" variable values. If you for
- example want to break after 20 HBLs, use:
+ specific "HBL" and "FrameCycles" variable values. If you want,
+ for example, to break after 20 HBLs, use:
b HBL = "HBL+20"
-- Aes/Bios/Gemdos/LineA/LineF/Vdi/XbiosOpcode variables can be used
- to catch AES, BIOS, GEMDOS, Line-A, Line-F, VDI and XBIOS OS-calls.
- By default they contain the 0xffff value, so to trace e.g. all AES
- calls, instead of a specific one, one needs to use something like this:
-
-b AesOpcode ! AesOpcode && AesOpcode < 0xffff :trace
-
-
@@ -3001,25 +3194,30 @@ another one is set.
For example if you have these input files:
-- "break.ini":
+
- "pexec.ini":
-b GemdosOpcode = 0x3D :trace :once :file program.ini
+# continue to "program.ini" on Pexec(0, ....)
+b GemdosOpcode = 0x4B && OsCallParam = 0x0 :trace :once :file program.ini
- "program.ini":
+# continue to "trace.ini" when program execution starts
b pc = TEXT :trace :once :file trace.ini
- "trace.ini":
+# load symbols, trace gemdos & program function calls
symbols prg
trace gemdos,cpu_symbols
+# continue to "disable.ini" after 4 VBLs
b VBL = "VBL+4" :trace :once :file disable.ini
- "disable.ini":
+# stop tracing and remove breakpoints
trace none
b all
@@ -3027,20 +3225,19 @@ b all
-And then start Hatari with the first debugger input file and a GEMDOS
-HD directory containing "desktop.inf" file:
+And then start Hatari with the first debugger input file:
-hatari --parse break.ini /path/to/your/program.tos
+hatari --parse pexec.ini /path/to/your/program.tos
-- "break.ini" input file will break when TOS opens
- the "desktop.inf" file (it's the first Fopen() i.e. GEMDOS call
- 0x3D done by TOS at boot) and the breakpoint will run
- the debugger commands from the "symbols.ini" file
-
- "program.ini" will setup breakpoint to program startup
- (because TEXT variable cannot be used before TOS has booted)
+
- "pexec.ini" sets a breakpoint to parse debugger commands from
+ "program.ini" when TOS starts loading the given program
+ (it is first Pexec(0) after boot)
+
- "program.ini" sets a breakpoint to parse debugger commands from
+ "trace.ini" when program code begins executing. These two steps
+ are needed because TEXT variable isn't valid until TOS has booted
- "trace.ini" input file loads symbols for the run program, sets Hatari
to trace several things (see Tracing section
below) in the emulated system for few VBLs until breakpoint runs
@@ -3054,18 +3251,18 @@ hatari --parse break.ini /path/to/your/p
- Because debugger input files cannot "continue"
emulation, ":trace" option needs to be used for the breakpoint(s)
if you want emulation to continue after the breakpoint action(s).
-- In simpler breakpoint chain (like above), new breakpoint just
-replaces the previous one, ":once" option tells that breakpoint
-isn't needed after it's hit.
+
- In simpler breakpoint chain (like above), where new breakpoint
+just replaces the previous one, ":once" option tells debugger that
+breakpoint isn't needed after it is hit.
-Hint: It's better to test each input file separate before testing the
-whole chain. Besides the ":file" breakpoint option, these debugger
-input files can be also read with the debugger "file" command, "lock"
-command "file" option and with the Hatari "--parse" command line
-option.
+Hint: It is better to test each input file separately before testing
+the whole chain. Besides the ":file" breakpoint option, you can test
+these debugger input files also with the debugger "file" command,
+"file" option for the "lock" command, and with the Hatari "--parse"
+command line option.
Stepping through code
@@ -3081,19 +3278,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
@@ -3125,7 +3332,7 @@ Notes:
-
If GEMDOS HD emulation isn't enabled, GEMDOS call tracing needs to be
-enabled at Hatari command line, it's not possible to enable it after
+enabled at Hatari command line, it is not possible to enable it after
TOS has initialized GEMDOS.
-
@@ -3144,7 +3351,7 @@ it cannot be changed from within the deb
-If there isn't a trace option for something you'd like to track,
+If there isn't a trace option for something you would like to track,
you may be able to use tracing breakpoints, explained above.
For example, following tracks Line-A calls:
@@ -3209,35 +3416,39 @@ Cartridge ROM (0xFA0000-0xFC0000):
Investigating the profile data
-When you're back in debugger, you can inspect the collected profile data:
+When you are back in debugger, you can inspect the collected profile data:
> h profile
'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
@@ -3279,15 +3490,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.
@@ -3362,6 +3574,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:
@@ -3383,7 +3600,7 @@ following command:
For example, if you don't know all the places from which a certain
function is called, or in what context a certain interrupt handler can
-be called during the period you're profiling, profile caller
+be called during the period you are profiling, profile caller
information will tell you:
@@ -3442,7 +3659,7 @@ profiler cannot determine when exception
Saving profile data to a file
-It's useful to save the profile data to a file:
+
It is useful to save the profile data to a file:
> profile save program-profile.txt
@@ -3450,7 +3667,7 @@ profiler cannot determine when exception
With the saved profile disassembly (and optional caller information)
you can more easily investigate what your program did during
profiling, search symbols & addresses in it, and compare the
-results to profiles you've saved from earlier versions of your code.
+results to profiles you have saved from earlier versions of your code.
You may even create your own post-processing tools for
investigating the profiling data more closely, e.g. to
@@ -3495,11 +3712,11 @@ the symbols as TEXT (code) section relat
$ hatari_profile.py -r program.sym program-profile.txt
-If symbols are included to your binary in DRI/GST format, first they
-need to be extracted to the ASCII format
+
If symbols are included to your binary, first they need to be
+extracted to the ASCII format
understood by the post-processor:
-$ gst2ascii -l -o program.prg > program.sym
+$ gst2ascii -a -l -o program.prg > program.sym
If there are some extra symbols that you don't want to see
@@ -3508,7 +3725,7 @@ but e.g. loop labels, you can either rem
from the ASCII *.sym file, or filter them out with grep:
-$ gst2ascii -l -o program.prg | grep -v -e useless1 -e useless2 > program.sym
+$ gst2ascii -a -l -o program.prg | grep -v -e useless1 -e useless2 > program.sym
@@ -3580,7 +3797,7 @@ Instruction cache misses:
If you want to see also symbol addresses and what is per call
-cost, add -i option:
+cost, add -i option:
$ hatari_profile.py -st -i -r program.sym program-profile.txt
[...]
@@ -3610,7 +3827,7 @@ a cost count.)
If your profile file contains caller information, you should
add -p option to see it, as that will also help in detecting symbol
issues (see Interpreting
-the numbers):
+the numbers):
$ hatari_profile.py -st -p -r program.sym program-profile.txt
[...]
@@ -3706,7 +3923,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 branched to. Because of
-this, it's useful to compare both subroutine and between-symbols
+this, it is 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.
@@ -3771,7 +3988,7 @@ $ dot -Tsvg program-profile-1.dot > p
Ellipse shaped nodes are for other symbols (functions
called using jumps/branches, loop labels etc). Values
listed in them are between-symbols costs, i.e. normally
- they're included to inclusive (total) costs shown in
+ they are included to inclusive (total) costs shown in
subroutine call node somewhere higher in call hierarchy.
Nodes which exclusive (own) or between-symbols costs
exceed default or explicitly given threshold value,
@@ -3792,9 +4009,10 @@ $ dot -Tsvg program-profile-1.dot > p
Making large callgraphs readable
-If profile is for larger and more varied amount of code
-(e.g. program startup), the resulting callgraph can be so
-huge it's unreadable.
+
+If profile is for larger and more varied amount of code (e.g. program startup),
+the resulting callgraph can be so huge that it not really readable anymore.
+
If your code has interrupt handlers, they can get called
at any point, which can show in callgraph as "explicit" calls
@@ -3819,7 +4037,7 @@ threshold with --emph-limit (-e) option:
$ hatari_profile.py -p -g -l 0.5 -e 2.0 -r program.sym program-profile.txt
-
If you're not interested in from how many different addresses
+
If you are not interested in from how many different addresses
a given function calls another function, use --compact option. If you
still see multiple calls between two nodes with it, the reason is that
they happened through different call paths which were removed from
@@ -3834,7 +4052,7 @@ often doesn't leave much of a call hiera
consider removing all nodes except for subroutine call ones, with the
--only-subroutines option.
-If you have trouble locating nodes you're specially interested
+
If you have trouble locating nodes you are specially interested
about, you can either color them differently with the --mark option,
or exclude everything else from the callgraph except those nodes and
their immediate callers & callees, with the --only option:
@@ -3893,12 +4111,11 @@ a $12345 :6
Stopping when specific exception happens
-Hatari's -D option doesn't invoke debugger on all exceptions and
-doesn't allow invoking debugger just for specific exceptions. To
-stop at specific exception, one can check when it's called.
-At the start of memory is the CPU exception table for exception
-handler addresses, so to stop e.g. at bus error with some extra
-information, one can use following:
+If one wants a specific breakpoint to trigger on a specific
+exception, one can check when its handler address is called by the
+CPU. At the start of memory is the CPU exception table for exception
+vectors. So, to stop e.g. at bus error with some extra information,
+one can use following:
history on
b pc=($8)
@@ -3907,7 +4124,11 @@ 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). See also --debug-except option.
+$14 (Division by zero).
+NOTE: Normally, to invoke debugger for larger set of exceptions, one
+would use Hatari's "--debug-except" option to specify on which
+exceptions debugger is invoked, and "setopt -D" to enable that on
+run-time.
Stopping when register has a specific value
@@ -3924,6 +4145,14 @@ b d1 ! d1
+Stopping when part of register value changes
+To stop when e.g. D1 register lowest byte changes, set a
+breakpoint on masked lowest 8 bits:
+
+b d1 & 0xff ! d1 & 0xff
+
+
+
Stopping when register value is within some range
To stop when e.g. D1 register value is within range of 10-30,
set a breakpoint on:
@@ -3957,6 +4186,17 @@ b ($ff820a).b & 2 ! ($ff820a).b & 2 :t
+Viewing OS structure and IO register values
+To see e.g. basepage for currently running program:
+
+info basepage
+
+To see e.g. all Falcon Videl register values, use:
+
+info videl
+
+
+
Stopping at specific screen position
To stop e.g. when VBL is 100, HBL is 40 and line cycles is 5,
use the corresponding debugger variables:
@@ -4045,6 +4285,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:
@@ -4063,7 +4316,7 @@ callstack information (with some limitat
Seeing call backtraces whenever given function is called
Enable profiling, load symbols for the program and set breakpoint
-for the function you're interested about, in the following way:
+for the function you are interested about, in the following way:
profile on
symbols prg
@@ -4100,7 +4353,7 @@ history, editing and especially the comp
command, command argument and symbol names.
-If you're building Hatari yourself, please make sure that you have the
+If you are building Hatari yourself, please make sure that you have the
GNU readline development files installed (on Debian / Ubuntu these
come from the libreadline5-dev package). Otherwise the name completion
and other features don't get enabled when you configure Hatari.
@@ -4121,55 +4374,92 @@ overhead.
The operating system and libraries below Hatari can also sometimes
have a noticeable effect on performance.
+
+Hatari can be sped up considerably by giving up some emulation or
+emulator accuracy. With ST/STe emulation, these options should be
+needed only on slow devices, typically ARM and/or mobile ones (e.g.
+Rasberry Pi).
+
+
-Improving Hatari performance
+Operating system components performance
-Hatari currently runs best in 16 or 32 bits per pixel color depth
-mode, so try to avoid 24 bits per pixel display modes if possible.
-16-bit mode is fastest.
+Finding out whether there's a performance problem with the system
+components (like SDL) in your setup, requires profiling Hatari and
+rest of the system. How to do that is OS specific. On Linux that would
+involve running "perf record -a" command (as root) on the background
+for few minutes while Hatari is running, and then investigating
+the results with "perf report" command.
-On OSX, frame skipping, zooming and drive LED options (listed below)
-seem to have a large effect on performance in the windowed mode.
-This is apparently due to issues in the SDL OSX backend and how OSX
-itself composites non-fullscreen window contents. OSX uses always
-32-bit mode.
+Some other process eating CPU cycles from Hatari one can see just with
+the (Linux/Unix) "top" command.
+
+Build options impact on performance
+
-Unless you've disabled compiler optimizations (like GCC's -O2 or -O3
-options) in the Hatari build, the extra optimization flags (like GCC's
-"-mtune=i686") don't seem to have very large effect on Hatari
-performance. Using GCC -O3 option instead of -O2 can give minor
-(5-10%) performance improvements for things (demos) that use very
-heavily interrupts.
+Linux: Some HW platforms don't have properly HW accelerated
+3D driver and SDL implementation. On these platforms it's better to
+build Hatari with SDL v1.x than SDL 2.x, as latter can cause CPU
+based 3D driver to be used for scaling Hatari graphics.
-However, Hatari can be sped up considerably by giving up some
-emulation or emulator accuracy. Except for DSP, these options
-should be needed only on very slow devices like handhelds. See below.
+MacOS: With SDL v1.x, 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. These shouldn't be an issue with the SDL2 build of Hatari.
-If nothing else helps, try an earlier Hatari version. More accurate
-emulation or emulator output in newer Hatari versions means that they
-can be slower despite optimizations.
+Compiler: Unless you have disabled compiler optimizations
+(like GCC's -O2 or -O3 options) in the Hatari build, the extra
+optimization flags (like GCC's "-mtune=i686") don't seem to have very
+large effect on Hatari performance. Using GCC -O3 option instead of
+-O2 can give minor (5-10%) performance improvements for things (mainly
+demos) that use very heavily interrupts.
+
+CPU emulation: Hatari can be built with two different CPU
+core implementations. The newer WinUAE CPU core has more accurate CPU
+emulation and supports all of the higher end 680x0 CPU features. This
+accuracy causes it to be clearly slower, than the OldAUE CPU core
+implementation. If run-time options (acceptable to you) don't give
+enough performance, give the OldUAE CPU core also a try.
+
-Emulation options
+
+Older versions: If nothing else helps, try (building) much
+earlier Hatari version. More accurate emulation in newer Hatari
+versions means that they can be slower despite optimizations.
+
+
+Run-time options not affecting emulation accuracy
-Emulation options have the largest impact on performance.
-These options can be changed from the Hatari GUI System dialog and
-the emulation needs to be rebooted for any of these changes to take
-an effect! They're enabled by default.
+Hatari currently runs best in 16 or 32 bits per pixel color depth
+mode, so try to avoid 24 bits per pixel display modes if possible.
+16-bit mode is faster with SDL1. MacOS uses always 32-bit mode.
-DSP
+
+Run-time emulation options
+
+
+Emulation options have the largest impact on Hatari performance. These
+options can be changed from the Hatari GUI System and CPU dialogs and
+the emulation needs to be rebooted for any of these changes to take an
+effect! They are enabled by default.
+
+
+DSP (Falcon)
+
Emulating the Falcon DSP is performance-wise several times more demanding
than emulating the m68k; DSP runs at higher frequency, executes many
@@ -4180,47 +4470,56 @@ that do use DSP, many use it only for ba
fine without the real DSP emulation.
+CPU: cycle exact (030/TT/Falcon)
+
+
+WinUAE CPU core supports 030 cache emulation for cycle accuracy. This
+is very heavy. Unless program needs cycle accuracy to work correctly,
+you can disable it. Many Falcon demos need it, application and games
+normally don't.
+
+
Timer-D
-The single largest factor contributing to general Hatari emulation
-performance is the handling of interrupts. Enabling Timer-D patching
-option (about) doubles Hatari ST/STE emulation performance as it
-significantly reduces the number of interrupts generated by the emulated
-Atari machine. Using this has adverse effect only for very rare programs.
+With ST/STe, the single largest factor contributing to general Hatari
+emulation performance is the handling of interrupts. Enabling Timer-D
+patching option (about) doubles Hatari ST/STE emulation performance
+with OldUAE CPU core as it significantly reduces the number of
+interrupts generated by the emulated Atari machine. Using this has
+adverse effect only for very rare programs.
FDC
While accurate FDC emulation doesn't take that much CPU, it slows down
floppy image accesses (and Hatari startup) a lot. Only very
-few demos and games require accurate FDC emulation for their copy protection,
-so enabling fast floppy access is fairly safe.
+few demos and games require accurate FDC emulation for their copy
+protection, so enabling fast floppy access is fairly safe.
-Compatible CPU
+CPU: prefetch
-After the DSP and interrupts, m68k emulation takes most time.
-Disabling the "Slower but more compatible CPU" option will speed up
-the emulation a lot, but it won't anymore be cycle accurate. This can
-be fine for many games and other programs, but won't work e.g. for demos
-using overscan or rasters.
+After the DSP, cycle accuracy and interrupts, m68k emulation takes
+most time. Disabling the "Prefetch" / "Compatible" option can speed up
+the emulation noticeably, but it will be less accurate. This can be
+fine for many games and other programs, but won't work e.g. for demos
+using overscan or rasters. This is recommended only as a last resort.
-Roughly speaking, for DSP emulation, one needs at least 2Ghz machine.
-For normal (unpatched) Timer-D frequency on some specific cases (like
-demos with overscan 512 color animations) one may need over 1GHz
-machine, but some rare ST/STE demos may require over 1GHz machine even
-with Timer-D patching. For "Compatible CPU" one needs at least 1/2Ghz
-machine.
+Roughly speaking, for Falcon DSP emulation with cycle exact 030 cache
+emulation, one needs at least 3Ghz machine. For normal (unpatched)
+Timer-D frequency on some specific cases (like demos with overscan 512
+color animations) one may need over 1GHz machine for ST/STE emulation,
+but some rare demos may require over 1GHz machine even with Timer-D
+patching.
NOTE: Above options may cause some programs to work in correctly.
The Hatari Software Compatibility List
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.
+frequency or accurate FDC timings.
@@ -4234,6 +4533,7 @@ be toggled at run-time without rebooting
Sound
+
Internal Hatari sound handling and the SDL_mixer sound thread
libALSA sound processing can account up to 1/3 of the Hatari CPU usage
@@ -4244,21 +4544,34 @@ in Hatari as this can significantly redu
interrupts.
+
+If program supports both ST and STE, use STE. Emulating DMA sound, is
+more lightweight than interrupt heavy ST sound.
+
+
+
+If problem is occasional performance related audio glitches, increasing
+the sound buffer size (with "--sound-buffer-size" option) may help, but
+it increases sound latency.
+
+
Frame skipping
+
Screen rendering can take noticeable amount of CPU time. The default
Hatari "auto" frame skipping should be used unless there's a good
reason not to. It will skip converting and showing some of the frames
if there's not enough time for them.
+
Also, if your monitor refresh frequency is lower than the selected
Hatari monitor frequency (e.g. LCD monitors usually use 60Hz whereas
Atari monochrome monitor uses 71Hz), you should use frameskip of one.
The reason is that if your SDL library uses VSync to synchronize the
-output to screen (like OSX one?), with zero frame skip that forces the
-emulation to run slower than a real Atari. If SDL doesn't use VSync,
-Hatari does redundant work to convert frames you can't see.
+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
@@ -4304,14 +4617,16 @@ is completely busy, it will increase to
Hatari has also a facility to measure FPS i.e. Frames Per Second.
-Just enable the --fast-forward option
-on command line (or use the corresponding keyboard shortcut), and
-after a while, press the "Pause" key. Whenever Hatari emulation is
-paused, Hatari will output on console how many VBLs it could show per
-second along with some other numbers.
+Enable frame skipping with
+--fast-forward yes option
+(or use the corresponding keyboard shortcut) and set
+--log-level info.
+Then after a while, press the "Pause" key. Whenever Hatari emulation
+is paused, Hatari will output on console info on how many VBLs it
+could show per second, along with some other numbers.
-It depends on what you want to measure, but usually it's best to
+It depends on what you want to measure, but usually it is best to
disable sound and set high frame skip like
--sound off --frameskips 60 so that
the associated external overheads are minimized. E.g. video output
@@ -4324,7 +4639,7 @@ call, only the time spent by the Hatari
On other systems, much less accurate SDL "wall clock" timings are
used. To make latter more accurate you could use also
--run-vbls option to specify how many
-VBLs Hatari should run before it exits. In this case it's best to
+VBLs Hatari should run before it exits. In this case it is best to
either have the test-case run automatically from the AUTO-folder or
given as memory snapshot to Hatari with the frame skip set equal to
the VBL count.
@@ -4334,7 +4649,7 @@ Note that these numbers can fluctuate qu
when the SDL timings are used, so for (statistically) reliable numbers
you may need to repeat the measurement several times. You should of
course make also sure that the system doesn't have any other activity
-at the same time you're making the measurements.
+at the same time you are making the measurements.