--- hatari/doc/manual.html 2019/04/09 08:57:12 1.1.1.20 +++ hatari/doc/manual.html 2019/04/09 08:58:26 1.1.1.21 @@ -64,7 +64,7 @@

Hatari User's Manual

-Version 2.0.0, November 2016 +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

    @@ -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,6 +468,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 @@ -586,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 @@ -603,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)

    @@ -627,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> @@ -638,16 +650,27 @@ 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

    +

    --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 @@ -672,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, @@ -715,8 +738,8 @@ CPU mode with better prefetch accuracy a

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

    @@ -1485,9 +1510,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 +1525,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 @@ -1621,7 +1646,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 +1679,7 @@ Below are listed the default shortcut ke - + @@ -1706,6 +1731,10 @@ Below are listed the default shortcut ke + + + + @@ -2314,7 +2343,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 +2355,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.

    @@ -2372,15 +2410,18 @@ Generic commands: cd ( ) : change directory evaluate ( e) : evaluate an expression help ( h) : print help - history (hi) : show last CPU & DSP PC values & executed instructions + history (hi) : show last CPU/DSP PC values & executed instructions info ( i) : show machine/OS information lock ( ) : specify information to show on entering the debugger logfile ( f) : open or close log file parse ( p) : get debugger commands from file + rename ( ) : rename given file + reset ( ) : reset emulation setopt ( o) : set Hatari command line and debugger options stateload ( ) : restore emulation state statesave ( ) : save emulation state trace ( t) : select Hatari tracing settings + variables ( v) : List builtin symbols / variables quit ( q) : quit emulator CPU commands: @@ -2395,7 +2436,7 @@ CPU commands: savebin ( ) : save memory to a file symbols ( ) : load CPU symbols & their addresses step ( s) : single-step CPU - next ( n) : step CPU, proceeding through subroutine calls + next ( n) : step CPU through subroutine calls / to given instruction type cont ( c) : continue emulation / CPU single-stepping DSP commands: @@ -2407,7 +2448,7 @@ DSP commands: dspprofile (dp) : profile DSP code dspreg (dr) : read/write DSP registers dspstep (ds) : single-step DSP - dspnext (dn) : step DSP, proceeding through subroutine calls + dspnext (dn) : step DSP through subroutine calls / to given instruction type dspcont (dc) : continue emulation / DSP single-stepping @@ -2937,7 +2978,7 @@ indicates Blitter to be active (busy), t

    In addition to loaded symbols, the debugger supports also setting conditional breakpoints on values of some "virtual" variables listed -by "b help". For example: +by "variables" (v) command. For example:

    AltGr+ccoldreset the ST (same as the original power switch)cold reset the ST (same as the original power switch)
    AltGr+dswitch joystick type for joypad B
    AltGr+btoggle borders on/off
    AltGr+f or F11 toggle between fullscreen and windowed mode