Usage and Options

### Usage

WHDLoad can be started from the command line (CLI/Shell) or from the Workbench. Options can specified in a global configuration file and via arguments or Tooltypes. The Slave option is usually required. Other options maybe necessary too, depending on your hardware and the program to execute within WHDLoad. When started from the command line WHDLoad exits with the follwing return codes:

- 0 - successful execution
- 10 - error, Slave couldn't be executed because previous problems, error message is shown
- 20 - fatal error, not enough free memory
- > 100 - the Slave has been executed, it has returned with 100 + TDREASON

### Options and global configuration

There are local and global options. Local options are specified as arguments via the command line or as ToolTypes when started from the Workbench.
The global configuration file is "`S:WHDLoad.prefs`". It is a usual ASCII file and contains one option per line. Empty lines and comments are ignored. A comment is line based, starts with the character "`;`" and goes up to the end of line.
An example configuration file is contained in the WHDLoad package ("`S/WHDLoad.prefs`").

### List of available options

there are three types of options:

numerical: | the value of the option is an integer, on the command line you must use decimal notation, as ToolType you can also use hexadecimal notation indicated by a leading "`$`"
string: | the value of the option is a string
switcher: | option will be enabled if specified (boolean)

The column Local shows if the option can be used on the commandline and as tooltype in the icon. The column Global shows if the option can be used in the global configuration file.

Many options are not available in WHDLoadCD32. The column CD³² shows if the option is present in this special WHDLoad version.

Name of option | Type | Local | Global | CD³² | Default value
--- | --- | --- | --- | --- | ---
BranchCache | switch | x | - | -
ButtonWait | switch | x | x | x
Cache | switch | x | - | x
Chk | switch | x | - | -
ChkBltHog | switch | x | - | -
ChkBltSize | switch | x | - | -
ChkBltWait | switch | x | - | -
ChkColBst | switch | x | - | -
ChkCopCon | switch | x | - | -
ChkInts | switch | x | - | -
ChipNoCache | switch | x | x | -
Config | string | x | - | x | ""
ConfigDelay | numerical | x | x | x | 400
CoreDump | switch | x | - | -
CoreDumpPath | string | - | x | - | PROGDIR:
Custom | string | x | - | x | ""
Custom1 | numerical | x | - | x | 0
Custom2 | numerical | x | - | x | 0
Custom3 | numerical | x | - | x | 0
Custom4 | numerical | x | - | x | 0
Custom5 | numerical | x | - | x | 0
D | switch | x | - | -
Data | string | x | - | x | -
DebugKey | numerical | x | x | - | $78 (CAA)
DCache | switch | x | - | -
ExecuteCleanup | string | x | x | - | -
ExecuteStartup | string | x | x | - | -
Expert | switch | - | x | -
ExpChip | switch | x | - | -
ExpLocal | switch | x | - | -
Exp24Bit | switch | x | - | -
FileLog | switch | x | - | -
FreezeKey | numerical | x | x | - | $78 (CAA)
FullChip | switch | x | - | -
MMU | switch | x | x | -
NoAutoVec | switch | x | x | x
NoCache | switch | x | - | x
NoFileCache | switch | x | - | x
NoFilter | switch | x | x | x
NoFlushMem | switch | x | x | -
NoMemReverse | switch | - | x | -
NoMMU | switch | x | x | -
NoResInt | switch | x | - | x
NoReq | switch | x | x | x
NoTrapHandler | switch | x | - | x
NoVBRMove | switch | x | - | x
NoWriteCache | switch | x | x | -
NTSC | switch | x | x | x
PAL | switch | x | x | x
Preload | switch | x | - | x
PreloadSize | numerical | x | - | -
QuitKey | numerical | x | x | x | $59 (F10)
ReadDelay | numerical | - | x | x | 0
RestartKey | numerical | x | x | x | $78 (CAA)
SaveDir | string | x | - | - | -
SavePath | string | x | x | - | -
ShowRegs | string | - | x | - | SYS:Utilities/MultiView
Slave | string | x | - | x | WHDLoad.Slave
Snoop | switch | x | - | -
SnoopAGA | switch | x | - | -
SnoopECS | switch | x | - | -
SnoopOCS | switch | x | - | -
SplashDelay | numerical | x | x | x | 200
StoreBuffer | switch | x | - | -
SuperScalar | switch | x | - | -
TimeOut | numerical | x | - | x | 0
WriteDelay | numerical | x | x | - | 150

#### Example

Workbench: |
CLI or Shell: | `1> WHDLoad SuperGame.Slave Preload NTSC QuitKey=69 Custom1=1`

### Description of each Option

#### ButtonWait/S

This option does not affect WHDLoad itself, but can be tested by the Slave.
The meaning of this option is that if set, the users wants the installed program to wait for pressing a button when it shows pictures and/or plays music and normally it does this only for a very limited time (due to HD/RAM loading compared to slow disk loading).

#### BranchCache/S

This option enables the branch cache of the 68060. On other CPU-types it has no effect.
The option has no effect if NoCache/S is also set.

#### Cache/S

This option enables the instruction cache and disables the data cache for the installed program. If the MMU is used by WHDLoad it marks the Chip-Memory as Cacheable Writethrough (impercise).
The option has no effect if NoCache/S is also set.

#### Chk/S

This option is a shortcut and enables the options ChkBltSize/S, ChkBltWait/S and ChkColBst/S.

#### ChkBltHog/S

This option checks that all the time the `blthog` (`bltpri`) bit in the custom.dmacon register is not set. That feature works only in conjuction with one of the SnoopOCS/SnoopECS/SnoopAGA options.

#### ChkBltSize/S

This option checks that the installed program correctly uses the blitter, so that only valid memory areas will be used for the blitter operations. That feature works only in conjunction with one of the SnoopOCS/SnoopECS/SnoopAGA options.

#### ChkBltWait/S

This option checks that the installed program correctly waits for the blitter finish before starting a new blitter job. That feature works only in conjunction with one of the SnoopOCS/SnoopECS/SnoopAGA options.

#### ChkColBst/S

This option checks that all the time the `color` bit in the `custom.bplcon0` register is set. That feature works only in conjunction with one of the SnoopOCS/SnoopECS/SnoopAGA options.

#### ChkCopCon/S

This option checks that the installed program does not enable the copper access to DMA registers via setting `custom.copcon`. That feature works only in conjunction with one of the SnoopOCS/SnoopECS/SnoopAGA options.

#### ChkInts/S

This option checks on each interrupt occuring if there is a matching pair in `intreq` and `intena` set for this interrupt. If not the installed will be terminated with an appropriate error request. This feature allows the easy detection of interrupt acknowledge problems on faster machines (68040/060) or bad hardware which causes unwanted interrupts. Due the fact that the condition may also raise if the interrupts are disabled by setting `intena` at the same time an interrupt occurs this has been implemented as a switchable option.

#### ChipNoCache/S

This option disables the cachebility of the Chip-Memory (BaseMem). It should be used on hardware which does not allow the cachebility of Chip-Memory (e.g. BlizzardPPC boards) to avoid slowdowns in the execution speed of the installed program. See also CPU Cache Handling.

#### Config/K

Using this option configuration items can be specified which will be displayed in the WHDLoad startup splash window. This option will overwrite the ws_config specified in the Slave. For syntax to be used check ws_config in the autodocs.
If there is neither ws_config in the Slave nor Config/K set and the Slave checks Custom1-5/K/N/ButtonWait/S items via the resload_Control function, WHDLoad will add a Config/K option to the icon if started from the Workbench. The type of the items will be derived from the actual value of the Custom1-5/K/N options (0-1 boolean, 2-63 list, >63 binary).

#### ConfigDelay/K/N

This option specifies the time in 1/50 seconds that WHDLoad shows the information window at startup if there are any buttons (see Config/K and Expert/S) on it. If ConfigDelay/K/N is lower than ReadDelay/K/N or SplashDelay/K/N it is ignored. The window is displayed at least as long as Preload/S is processing. If a configuration button is pressed the timer for ConfigDelay restarts.
If the option is set to -1 a Start button is added to the window and it remains open until this button has been pressed. The splash window can also be closed by pressing Space, Return or Enter. If Esc is pressed WHDLoad will stop Preload/S and immediately quit.

#### CoreDump/S

If selected, on every exit from an installed program, WHDLoad creates a memory and register dump. This may be useful to rip a music-module from the memory dump or for debugging.

#### CoreDumpPath

The destination directory for all dump files created by WHDLoad.

#### Custom/K, Custom1/K/N, Custom2/K/N, Custom3/K/N, Custom4/K/N, Custom5/K/N

These options are not used by WHDLoad itself, but can be tested by the Slave to control various Slave specific things. Custom/K can contain a string and Custom1-5/K can only hold an integer. Check the documentation of the specific install if it supports Custom options.

#### D/S

This option his useful for debugging. If the option is enabled and a supported software freezer (HRT/TK) is found in memory, WHDLoad simulates an NMI before executing the first cpu instruction contained in the Slave.

#### Data/K

Using this option a directory can be specified which will be the base directory for file operations of the installed program. Also multiple directories can be specified seperated by a comma (therefore a directory name specified cannot contain a comma!). If multiple data directories are used on loading all specified directories are tried in order to load a file. Writing will always occure on the first data directory. This options overwrites the value ws_CurrentDir contained in the Slave.

#### DCache/S

This option enables the instruction and the data cache for the installed program. If the MMU is used by WHDLoad it marks the Chip-Memory as Cacheable Writethrough (impercise).
The option has no effect if NoCache/S is also set.

#### DebugKey/K/N

Sets the rawkey code to quit the program and write coredump files. This works only if the expert mode is active and the VBR is moved by WHDLoad (NoVBRMove/S is not set and the cpu is at least a 68010) or the Slave itself supports it.

#### ExecuteCleanup

With this option a command can be specified which will executed by WHDLoad on exit.

#### ExecuteStartup

With this option a command can be specified which will executed by WHDLoad on startup. Can be used to disable hardware which makes problems in conjunction with WHDLoad, or to stop the TCP/IP stack or similar stuff.

#### Expert/S

This option enables the expert mode of WHDLoad. It affects the DebugKey/S feature and warnings during the switch between installed program and OS (color cycle copper screens). If expert mode is not active DebugKey/S is not available. In expert mode another button in some error requesters of WHDLoad appears. This button named Show Regs allows to display register and status informations similar as written to the register dump. Additionally some buttons are added to the splash window to switch a selection of debugging related options. Changed options are saved to the icon if started from the workbench.

#### ExpChip/S, ExpLocal/S, Exp24Bit/S

If the installed program uses expansion memory (ws_ExpMem) these options can be used to force WHDLoad to allocate this memory respective in Chip Memory, Local Memory or 24BitDma Memory. This may result in a performance degration because the specified memory may be slower accessed by the CPU compared to the default Fast memory. You can use third party tools (e.g. SysInfo, GvpInfo,...) to check your memory configuration and see which memory has which properties.
In general these options are intended to fix compatibility problems of installed programs on fast machines by making them slower in execution due using slower memory.

#### FileLog/S

This option is only for debugging purposes. See Dumps and Logfiles for more info.

#### FreezeKey/K/N

If you are using one of the supported software freezers (HRTmon or Thrillkill) you can use this option to setup a rawkey code on which pressed WHDLoad will enter the freezer. For this to work, the VBR must be moved by WHDLoad (NoVBRMove/S must not be set and the cpu must be at least a 68010) and the freezer must be active. Check also the chapter System Monitors / Freezer for futher infos.

#### FullChip/S

Specifying this option causes WHDLoad to save and restore not only the chip memory area which is set as ws_BaseMemSize in the Slave but instead the whole chip memory (execbase.MaxLocMem). If WHDLoad uses a present MMU to protect memory this covers only illegal accesses caused by the CPU. Not covered are direct memory accesses by coprocessors like Blitter/Disk-DMA. These DMA actions are able to corrupt the chip memory undetected by WHDLoads memory protection. With this option selected such faults cannot harm the host operating system because the chip memory is saved and restored completely.
Before the installed program will be started the additional saved chip memory (the part between BaseMemSize and MaxLocMem) will be filled with a special pattern. After the installed program has been returned, WHDLoad checks the additional memory if it has been altered. If there is a change WHDLoad will show an appropriate error requester. Only in this case the additional memory will be written to the memory dump file (not the complete dump file), which allows further investigations.
This option may be useful for development/debugging to avoid corrupting the host AmigaOS and also to aid temporarly broken installs which have not completely fixed all bugs of the installed program.

#### MMU/S

This must be used on 68030 machines to get the MMU related features working (memory protection, improved cache managment, Snooping, resload_Protect#? functions). On 68040/060 this option has no effect because the MMU will be used by default. It is recommended to set this option in the global configuration file on all systems containing a 68030 with working MMU (i.e. not a 68ec030) because it increases stability and security a lot. If the option NoMMU/S is also set this option has no effect.

#### NoAutoVec/S

If selected WHDLoad will not quit if an unexpected autovector interrupt or NMI occurs (vectors #25-31 / $64-$7c). This should be used on systems/hardware which will create at random such interrupts to prevent WHDLoad from exiting (or better remove the broken hardware!).

#### NoCache/S

If selected all caches will be disabled.
This option overrides BranchCache/S, Cache/S, DCache/S, StoreBuffer/S and SuperScalar/S.

#### NoFileCache/S

Disables the file cache of WHDLoad and forces a switch to the OS for each disk operation of the installed program.
This option disables Preload/S.

#### NoFilter/S

Disables the audio filter. Note that this option only affects the initialisation at startup, if the installed program itself changes the state of the audio filter this option will be without effect.

#### NoFlushMem/S

Normally WHDLoad flushes the memory at startup to get as much free memory as possible for the Preload/S operation. That will remove all unused ressources like libraries, fonts etc. from memory. Using this option WHDLoad will not flush the memory. It may be used on systems with much free memory to avoid reloading resident ressources and thus improve system performance.

#### NoMemReverse/S

If that option is activated WHDLoad will not allocate memory using the MEM_REVERSE flag. There has been reports that using this flag causes problems on some configuration (configs using memory in the PCMCIA slot of the A600/A1200 as fast memory, configs with a M-Tec 1230/8 MB OS3.0). The reason for the problems is not known. This option may also help if some of the higher RAM is broken, because WHDLoad will then use memory at lower addresses first. If you get strange errors this option may be worth a try.
This option has been introduced in WHDLoad v16.8.

#### NoMMU/S

If this option is set WHDLoad will not use the MMU. This is a critical and dangerous option recommended only for testing or debugging and not for normal use. See chapter MMU for more info. The option overides MMU/S.

#### NoReq/S

This option can only be used when WHDLoad has been started from the command line (CLI/Shell). Started from the Workbench it has no effect. The option forces WHDLoad to not show any requesters in a new, seperate window but output messages to the command window WHDLoad has been started from.

#### NoResInt/S

This option disables interrupts during the execution of resload functions. Normally interrupts are allowed while resload functions are executed. Interrupts may play sound, do screen updates or do other important work. Disabling them can cause sound/screen distortion or overall malfunction. But improper working interrupts may destroying internal WHDLoad data areas, which will usually lead to crashes of WHDLoad and probably the whole operating system. This option can be used to check for such problems. If a install behaviors strange or crashes WHDLoad without this option, but works fine with this option the reason is very probably an interrupt problem. In such cases the install needs to be fixed.
Starting WHDLoad version 17.0 when entering a resload function the blitter will be checked if being active. If so WHDLoad will terminate telling you.

#### NoTrapHandler/S

If this option is enabled WHDLoad will use the original vector table from the OS which is active on starting WHDLoad. On startup WHDLoad will copy the system vector table instead of creating its own. This will only be useful for debugging purposes and should not be used for normal operation. Warning: if an exception handler called through the original vector table tries to call any OS function or tries to use OS data structures the machine will crash (e.g. exec.Alert).

#### NoVBRMove/S

By default WHDLoad moves the vector table using the VBR (Vector base Register) to a different memory location from $0. This has the advantage that the installed program cannot change the vector table, which increases security and stability of WHDLoad greatly. Some installed programs/slaves will not correctly work with a moved VBR. The reason for this is that the installed program may do some strange stuff which is not supported by a moved VBR or the author of the install was too lame to support a moved VBR. In such a case, this option must be set to prevent WHDLoad from moving the VBR.
Another feature of the moved VBR is that WHDLoad can check the keyboard each time an Autovector interrupt occurs. With this check WHDLoad is able to terminate the installed program independently from the work of installed program/slave if QuitKey/S or DebugKey/S is pressed (similarly the installed program can be interrupted when FreezeKey/S is pressed).
The VBR moving feature requires at least a 68010 to work. On a 68000 this option has no effect, because the VBR is always at $0 and cannot be moved.

#### NoWriteCache/S

This option disables the disk write cache feature of WHDLoad. Without this option WHDLoad will try to cache all write operations in memory and defer them until program exit to avoid unnecessary switches to the operating system.

#### NTSC/S

If selected, WHDLoad will use an NTSC display (60Hz) for the installed program. On a PAL Amiga, the NTSC monitor driver must be installed in "`DEVS:Monitors/`".

#### PAL/S

If selected, WHDLoad will use a PAL display (50Hz) for the installed program. On an NTSC Amiga, the PAL monitor driver must be installed in "`DEVS:Monitors/`".

#### Preload/S

If this option is enabled, WHDLoad will load as many files and disk images as possible into memory (depending on how much memory is free) at startup. This increases performance when the installed program is running, because it avoids switching to the OS to load data directly from the harddisk. This option should always be enabled.

#### PreloadSize/N

This option tells WHDLoad how much data has to be preloaded. It is used only to calculate the Preload progress bar. If the installed program is started from the Workbench WHDLoad will itself set/update this option as ToolType after returning to the operating system. The PreloadSize count is not only the sum of the filesize for all files.

#### QuitKey/K/N

Sets the rawkey code to quit the program, this works only if the VBR is moved by WHDLoad (NoVBRMove/S must not be set and the cpu must be at least a 68010) or the Slave itself supports it.

#### ReadDelay/K/N

This option specifies the time in 1/50ths of a second that WHDLoad will wait after it has loaded data from disks, and will also wait this time after Preload has finished. This solves problems with drives (e.g. CD drives) which want do something after reading (e.g. switching the motor off).

#### RestartKey/K/N

Using this option you can setup a rawkey code on which pressed WHDLoad will restart the installed program.

#### SaveDir/K

This option specifies the sub directory for write operations of the installed program in conjunction with the SavePath/K option. It may be required to set it explicit instead of letting WHDLoad determine it if you have installed multiple versions of a game which use the same Slave but have incompatible save files. It may be also useful if the Slave doesn't contain the name of the game and the filename of the Slave is not what you like to have as the save directory name.

#### SavePath/K

This option forces WHDLoad to redirect all write operations by the installed program to a different location on disk. This option specifies the base directory for all installed programs. Each installed program will have its own sub directory therein. The sub directory will be created by WHDLoad if it doesn't exist (during the first write operation). The name of the sub directory can be specified using the SaveDir/K option or when not set will be derived by WHDLoad from the infos of the Slave (ws_name or the Slave filename). Internally this save directory is handled as a additional Data directory.

#### ShowRegs/K/N

This option is only useful in conjunction with the option Expert/S. With this option the program can be specified which will be used by WHDLoad to display the register dump if the Show Regs button in an error requester by WHDLoad will be pressed. WHDLoad will append the filename of the temporarly saved file (currently `T:.whdl_register`) onto the specified command string.

#### Slave

Name of the Slave which should be used by WHDLoad. The Slave contains the interface code which is required for communication between the installed program and WHDLoad.

#### Snoop/S, SnoopAGA/S, SnoopECS/S, SnoopOCS/S

These options enables the Cia/Custom register snoop feature of WHDLoad.

#### SplashDelay/K/N

This option specifies the time in 1/50 seconds that WHDLoad shows the information window at startup. If SplashDelay/K/N is lower than ReadDelay/K/N it is ignored and the window is displayed using the time from ReadDelay/K/N. The window is displayed at least as long as Preload/S is processing.
If the option is set to 0 no window will be displayed at all. If the option is set to -1 a Start button is added to the window and it remains open until this button has been pressed. The splash window can also be closed by pressing Space, Return or Enter. If Esc is pressed WHDLoad will stop Preload/S and immediately quit. See also ConfigDelay/K/N.

#### StoreBuffer/S

This option enables the Store Buffer of the 68060. On other CPU-types it has no effect.
The option has no effect if NoCache/S is also set.

#### SuperScalar/S

This option enables the ability of the 68060 to execute multiple instructions per machine cycle. On other CPU-types it has no effect.
The option has no effect if NoCache/S is also set.

#### TimeOut/K/N

If set lets WHDLoad and the installed program quit after the specified time. Requires that option NoVBRMove/S is not set and that the installed program does not modify the `ciaa.ciatod` timer. The time after to quit is specified in 1/50ths of a second. To measure that time for a demo or game enable option Expert/S and set a DebugKey/K/N, when the point you want to the quit the program is reached press the debug key. Now look into the created .whdl-register file and search the `ciaa-event` value. If your Power Supply Frequency is 50 Hz then it's the value you have to set with TimeOut/K/N, if the Frequency is 60 Hz you have to multiply the value with 5/6.

#### WriteDelay/K/N

This option specifies the time in 1/50 seconds that WHDLoad will wait after writing anything physically to disk. It affects all resload_Save#? functions and the FileLog/S feature. This makes sense because filesystems will not usually write data immedately to disk. It takes some time (1..3 sec) until all structures of the filesystem have been successfully updated. The default value for WriteDelay is 150 which lets WHDLoad wait 3 seconds after each write to the harddisk. You can set this value to 0, but then you should never exit by a reset from the installed program because saved data may not be written correctly to disk.