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.
Example
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.