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
- 5 - Preload has been canceled via the Esc key in the splash window
- 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.
If a option is specified global and local the local one has precedence,
i.e. it will overwrite the global one. For example you can set a global QuitKey as default for all installed programs and set an
individual QuitKey for single installs in their icon via
If started from the Workbench via an icon WHDLoad will try to update the
icon regarding the options PreloadSize, Config and possible options changed in the splash window. If
such operation is wished also when started from the command line tools like
WBRun (contained in OS3.5/3.9) must be used to simulate a start from the
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 ("
List of available options
there are three types of options:
||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 "
||the value of the option is a string
||option will be enabled if specified (boolean)
The column Local shows if the option can be used on the command line 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 the special WHDLoadCD32. The column CD≥≤ shows if the option is
present in this special WHDLoad version.
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 fast HD/RAM loading compared to slow disk
BranchCache/S This option enables the
branch cache of the 68060. On other CPU-types it has no effect.
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. On the 68030 also the
instruction burst will be enabled. If the MMU is used by WHDLoad it marks the
Chip-Memory as Cacheable Writethrough (imprecise).
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.
ChkAudPt/S This option checks that pointers
written to the Custom audio data pointers are valid chip memory addresses. The
pointers must be not null and inside BaseMem. That feature works only in
conjunction with one of the SnoopOCS/SnoopECS/SnoopAGA
options. This feature should help to diagnose problems with audio replay
ChkBltHog/S This option checks that all the
bltpri) bit in the custom.dmacon
register is not set. That feature works only in conjuction with one of the SnoopOCS/SnoopECS/SnoopAGA options. Enabling of
blthog gives the blitter priority over the cpu regarding memory
accesses, which may cause problems on some hardware configuration. Also
sometimes it can be more performant to grant the processor some bus cycles.
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
All blitter operations will be checked except the line mode.
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
color bit in the
custom.bplcon0 register is
set. That feature works only in conjunction with one of the SnoopOCS/SnoopECS/SnoopAGA options. Some hardware
especially flickerfixer require that this bit is set to output a proper video
signal. Therefore for best compatibility this bit should always be set. Checked
are direct writes to
custom.bplcon0 and all Copper lists.
ChkCopCon/S This option checks that the
installed program does not enable the Copper access to DMA registers via
custom.copcon. That feature works only in conjunction
with one of the SnoopOCS/SnoopECS/SnoopAGA options.
It may sometimes useful to detect if programs use the Copper to control
ChkInts/S This option checks on each interrupt
occuring if there is a matching pair in
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
the same time an interrupt occurs this has been implemented as a switchable
option. Starting with WHDLoad version 17.1 this option enables also all
sanity and keyboard checks for the interrupt levels 4-6 which are normally
only performed in the levels 1-3.
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 variable 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 or 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/50ths 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.
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, Enter or the fire button on the joystick in port #1. If
Esc is pressed WHDLoad will stop Preload/S and
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
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/SThis option is 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
instruction contained in the Slave to jump in the freezer.
Data/KUsing 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 occur 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. On the 68030 also the instruction
burst will be enabled. If the MMU is used by WHDLoad it marks the Chip-Memory
as Cacheable Writethrough (imprecise).
The option has no effect if NoCache/S is also set.
DebugKey/K/N Sets the
rawkey code to quit the installed program with writing 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.
Using the system command Execute also a script can be executed.
An example script is contained in the WHDLoad package ("
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, like a IP or
USB stack. See the Bugs chapter for further infos.
Using the system command Execute also a script can be executed.
An example script is contained in the WHDLoad package ("
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 information 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 from the splash window are saved to
the icon if started from the workbench.
ExpChip/S, ExpLocal/S, Exp24Bit/SIf 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
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
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 WHDLoad's memory protection. With this option selected such faults
cannot harm the host operating system because the chip memory is saved and
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.
FullChip/S cannot be enabled together with option ExpChip/S. If both are set FullChip/S is ignored.
LogBuffer/K/N Using this option the internal
buffer of WHDLoad used to carry log messages from the FileLog/S facility and the resload_Log function can be specified.
The default length for the buffer is 4096 bytes. This buffer is only allocated
if the FileLog/S option has been specified. If the
buffer is full, WHDLoad will interrupt the installed program and switch
to the operating system to flush the buffer and write the contents to the log
file. To avoid such switches the size of the buffer should be choosen large
enough to hold as many entries as possible.
MMU/S This option must be used on 68030 machines to
get the MMU related features working (memory
protection, improved cache management, 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 a 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. But note that this option does not
heal the broken hardware which creates such interrupts. Some installed programs
may still not work correctly on such hardware also with this option enabled. So
better would be to remove (or fix if possible) the hardware which creates the
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
This option disables Preload/S.
NoFilter/S Disables the audio filter. Note that
this option only affects the initialization 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 resources
like libraries, fonts etc. from memory. Using this option WHDLoad will not
flush the memory. It may be used on systems with a lot of free memory to avoid
reloading resident resources 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 (e.g.
configs using memory in the PCMCIA slot of the A600/A1200 as fast memory,
configs with a M-Tec 1230/8 MiB OS3.0). The reason for these 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 is always active on Kickstart 2.0 (V37) due an implementation bug
in this Kickstart possible freezing during exec.AllocMem.
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.
NoNetwork/S If this option is set WHDLoad will
not try to connect to the Internet to perform an update
check for the used Slave and WHDLoad itself.
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, separate window but instead 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 destroy
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 an install behaves strange or crashes WHDLoad without this
option, but works fine with this option enabled 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.
NoVBRMove/SBy default WHDLoad moves the vector
table using the VBR (Vector Base Register) to a different memory location. This
has the advantage that the installed program cannot change the vector table,
which increases security and stability of WHDLoad greatly. Some installed
programs will not correctly work with a moved vector table. The reason for this
may be that the installed program uses processor exceptions or is doing other
strange stuff. In such a case, this option must be used to prevent WHDLoad
from moving the vector base.
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 assistance of the
installed program if QuitKey/S or DebugKey/S is pressed or to enter a Monitor 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 there is no VBR and the vector table always
starts at $0 and cannot be moved. On a 68000 WHDLoad supports some special
hardware (ACA500, Zeus) which allows to place the Autovector interrupt vectors
on a different memory location to be able to always support the QuitKey/S feature. These special hardware features are not
used if this option has been enabled.
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.
NoWriteInfo/S If this option is set WHDLoad
will not update the .info file if started from the Workbench. Normally WHDLoad
updates the PreloadSize Tooltype if changed or not present and updates options
like Custom1-5/K/N and ButtonWait/S if changed via the splash window.
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 "
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 "
Preload/S If this option is enabled, WHDLoad
will load as many files and disk images as possible into memory at startup. If
during preload the free memory is not sufficient for a file preloading will
stop. Then only a part of the files are preloaded. 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 be enabled always.
PreloadSize/N This option tells WHDLoad how
much data can be preloaded. It is used only to calculate
the Preload progress bar in the splash window. If the installed program is
started from the Workbench WHDLoad will itself set/update this option as a
ToolType after returning to the operating system (unless option NoWriteInfo is used). The PreloadSize count is not only
the sum of the filesize for all files. So you can hardly calculate the value
There are two possible phases of Preload which are shown by different
colors of the preload progress bar. Only if the Slave has the flag WHDLF_Examine set WHDLoad will collect
filesystem meta data for files to preload. The color for this first phase
defaults to black. The second phase is always active if the Preload option is set. The color for this second phase
defaults to blue.
Proxy/K Using this option a HTTP-Proxy can be
specified which will be used by WHDLoad to connect to the
Internet. This makes only sense if a direct connection is not possible
because WHDLoad will do only a single simple HTTP-request. The syntax for the
proxy specification is [user:password@]hostname[:port]. The hostname of the
proxy is required. The port for the proxy is optional and defaults to 80 if not
specified. If the proxy requires an authentication the user and password for
that must be prepended. WHDLoad only supports the basic authentication type.
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. It will also wait this time after Preload/S 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
explicitly 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 an additional
(primary) 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 temporary 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. If "*" is specified as
Slave WHDLoad will search the current directory for a file matching the pattern
"#?.slave" and will use the first one matching. If no file matches the default
"WHDLoad.Slave" will be used to display the error message.
Snoop/S, SnoopAGA/S, SnoopECS/S, SnoopOCS/S
These options enable the CIA/Custom register
snoop feature of WHDLoad.
SplashDelay/K/N This option specifies the
time in 1/50ths 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, Enter or the
fire button on the joystick in port #1. 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.
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
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
WriteCache/S This option enables the disk
write cache feature of WHDLoad. As this feature is enabled by default the use
of this options only makes sense to overwrite a active global option NoWriteCache/S. So you can disable the feature for all
installs and enable it only for a selection of installs.
WriteDelay/K/N This option specifies the time
in 1/50ths 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 usually not write data immedately to disk. It takes some time
(1..3 seconds) 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.