--- hatari/doc/manual.html 2019/04/09 08:56:01 1.1.1.19 +++ 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.9.0, September 2015 +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,13 +104,12 @@ 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:

@@ -172,6 +175,10 @@ Recent versions of Hatari even feature S
  • 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.
    • +

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

    @@ -199,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

    @@ -313,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

    @@ -374,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 @@ -424,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, @@ -434,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 @@ -442,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)

    @@ -473,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 @@ -496,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

    @@ -572,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 @@ -589,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)

    @@ -613,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> @@ -622,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 @@ -658,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, @@ -675,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)

    @@ -710,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 @@ -731,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, @@ -771,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>

    @@ -826,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.

    @@ -855,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.

    @@ -898,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
    @@ -917,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 @@ -989,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.

    @@ -997,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 @@ -1029,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 @@ -1038,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

    @@ -1107,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.

    @@ -1156,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 @@ -1190,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.

    @@ -1213,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.

    @@ -1305,7 +1392,7 @@ resolutions for GEM. Select a resolution activate. This mode isn't affect by the other video options mentioned above. Uncheck to get back to a normal ST behaviour.

    -

    Note that there are several gotches with extended VDI +

    Note that there are several gotchas with extended VDI resolutions: