[Main] [Docs] [Installs] [Search] [Team] [Guestbook] [Links]

TABLE OF CONTENTS

WHDLoad/--Overview--
WHDLoad/resload_Abort
WHDLoad/resload_Control
WHDLoad/WHDLTAG_CBAF_SET
WHDLoad/WHDLTAG_CBSWITCH_SET
WHDLoad/WHDLTAG_CUST
WHDLoad/WHDLTAG_IOERR_GET
WHDLoad/resload_CRC16
WHDLoad/resload_Decrunch
WHDLoad/resload_Delay
WHDLoad/resload_DeleteFile
WHDLoad/resload_Delta
WHDLoad/resload_DiskLoad
WHDLoad/resload_DiskLoadDev
WHDLoad/resload_Examine
WHDLoad/resload_ExNext
WHDLoad/resload_FlushCache
WHDLoad/resload_GetCustom
WHDLoad/resload_GetFileSize
WHDLoad/resload_GetFileSizeDec
WHDLoad/resload_ListFiles
WHDLoad/resload_LoadFile
WHDLoad/resload_LoadFileDecrunch
WHDLoad/resload_LoadFileOffset
WHDLoad/resload_LoadKick
WHDLoad/resload_Log
WHDLoad/resload_Patch
WHDLoad/resload_PatchSeg
WHDLoad/resload_ProtectRead
WHDLoad/resload_ProtectReadWrite
WHDLoad/resload_ProtectRemove
WHDLoad/resload_ProtectSMC
WHDLoad/resload_ProtectWrite
WHDLoad/resload_ReadJoyPort
WHDLoad/resload_Relocate
WHDLoad/resload_SaveFile
WHDLoad/resload_SaveFileOffset
WHDLoad/resload_SetCACR
WHDLoad/resload_SetCPU
WHDLoad/resload_VSNPrintF
WHDLoad.Slave/--Overview--


WHDLoad/--Overview--

The calling conventions for all functions are similar to the OS-Library
concept. Parameters are provided in registers (except for 'resload_Abort'),
return codes come in D0 (on some functions additionally in D1). After a
function call the registers D0-D1/A0-A1 are destroyed (D0, D1 may contain a
return code). These are so called scratch registers. All other registers are
preserved. Some resload functions do preserve all registers (e.g.
resload_FlushCache), see NOTE of the respective function to find out. The
condition codes on returning from a function are set matching D0.L.
The base of the JMP tower in WHDLoad is similar to a Library-Base. In
difference to the OS the base must not be loaded into A6 on calling a function,
but it is recommended to call all functions relative to a address register
like:

        move.l  (_resload,pc),a5
        jsr     (resload_Decrunch,a5)

During the execution of resload functions interrupts are normally allowed. For
some internal operations they will be disabled for a short time. If the option
NoResInt/S is used the interrupts are disabled the whole time during executing
a resload function.

The resload functions will not use the registers A5 and A6 while interrupts are
allowed. Therefore interrupts of the installed program may assume that these
both registers contain previously set values. This is not true for all other
registers. If the interrupts assume constants in other registers (e.g. A4)
either the interrupt code must be patched accordingly or the interrupts must be
disabled before calling resload functions.

If option NoResInt/S is used all registers except D0-D1/A0-A1 remain unchanged
as long as interrupts are allowed. But remember that option NoResInt/S is only
for testing purposes and not to be used in public released installs.

The resload base is over given in A0 on calling the Slave first via
ws_GameLoader (see chapter WHDLoad.Slave/--Overview--).

All file names used with resload functions must be relative and must not access
any higher-level directories. That means that file names must not start or end
with a slash '/', must not contain multiple slashes '//' and must not contain a
colon ':'. These restrictions are enforced starting WHDLoad v16.9. Earlier
versions of WHDLoad will accept all names at the loss of being able to preload
them.

some terms used in this document:

 Slave          file which contains the install specific interface code
                (see section WHDLoad.Slave/--Overview--)

 BaseMem        the memory which is used by the installed program, this memory
                is always Chip-memory and starts at address $0, BaseMem is at
                the same time the size and the end address of the used
                Chip-memory, BaseMem is specified in the Slave-structure in
                the field 'ws_BaseMemSize'

 ExpMem         is the expansion memory, an extra memory area which can
                optionally requested by the Slave-structure, it may be Chip- or
                Fast-memory dependently on what is available,
                ExpMem is supported starting WHDLoad version 8

 Disk Image     a floppy disk stored as a file on hard disk

logical values used for return codes (see dos/dos.i):
 TRUE = -1 (or better <>0)
 FALSE = 0


WHDLoad/resload_Abort

   NAME
        resload_Abort -- quit and return to operating system

   SYNOPSIS
        resload_Abort( success, primary, secondary)
                         (a7)    (4,a7)    (8,a7)
                        ULONG    ULONG     ULONG

   FUNCTION
        This aborts and terminates the installed program and causes WHDLoad to
        return to the operating system.

   INPUTS
        the 'success' parameter must be always provided, the 'primary' and
        'secondary' parameter are only required by some TDREASON_#?
        success -   the reason for aborting
                    one of TDREASON_#? defined in the include file 'whdload.i',
                    depending on this value WHDLoad continues differently
                TDREASON_OK
                    a normal exit will be performed
                TDREASON_DEBUG
                    WHDLoad will create dump files (.whdl_dump, .whdl_expmem,
                    .whdl_memory, .whdl_register) and exits
                TDREASON_#? (except the above)
                    WHDLoad will show a requester explaining the reason of
                    aborting and requests the user to choose one of the options
                    'Quit', 'Restart' and 'Make CoreDump'
        primary -   the primary return code further describes the reason of
                    aborting
                TDREASON_DELETEFILE, TDREASON_DISKLOAD, TDREASON_DISKLOADDEV,
                TDREASON_DOSLIST, TDREASON_DOSREAD, TDREASON_DOSWRITE
                    DOS or Trackdisk error code
                TDREASON_DEBUG
                    program counter (so it can by written to the dump files)
                TDREASON_OSEMUFAIL
                    name of the failed subsystem
                TDREASON_FAILMSG
                    custom message to display
                TDREASON_MUSTNTSC, TDREASON_MUSTPAL, TDREASON_MUSTREG,
                TDREASON_OK, TDREASON_REQ68020, TDREASON_REQAGA,
                TDREASON_WRONGVER
                    unused (can be omitted)
        secondary - the secondary return code further describes the reason of
                    aborting
                TDREASON_DELETEFILE, TDREASON_DOSREAD, TDREASON_DOSWRITE
                    name of file failed
                TDREASON_DISKLOAD
                    disk number
                TDREASON_DOSLIST
                    name of directory scanned
                TDREASON_DEBUG
                    status register (so it can by written to the dump files)
                TDREASON_OSEMUFAIL
                    error number, depending on the primary return code
                TDREASON_DISKLOADDEV, TDREASON_FAILMSG, TDREASON_MUSTNTSC,
                TDREASON_MUSTPAL, TDREASON_MUSTREG, TDREASON_OK,
                TDREASON_REQ68020, TDREASON_REQAGA, TDREASON_WRONGVER
                    unused (can be omitted)

   RESULT
        nothing, WHDLoad will never return from this call

   EXAMPLE
        to simply quit:
                ...
                ; primary and secondary are not needed with TDREASON_OK
                pea     TDREASON_OK
                move.l  (_resload,pc),a0
                jmp     (resload_Abort,a0)

        to quit because reading of a file has failed:
                ...
                move.l  a0,-(a7)                        ;a0 = filename
                move.l  d0,-(a7)                        ;d0 = DOS error code
                move.l  #TDREASON_DOSREAD,-(a7)
                move.l  (_resload,pc),-(a7)
                addq.l  #resload_Abort,(a7)
                rts

   BUGS

   NOTE
        This routine is the only one which must be called via JMP and not JSR
        because the parameters are located on the stack (that has the
        advantage that when aborting with TDREASON_DEBUG all registers can be
        preserved and written to the dump files by WHDLoad for later
        diagnostics)

   SEE ALSO
        example Slave sources provided with the WHDLoad developer package


WHDLoad/resload_Control

   NAME
        resload_Control -- get/set various variables, control WHDLoad

   SYNOPSIS
        success = resload_Control(tags)
          D0                       A0
         BOOL                    STRUCT

   FUNCTION
        control function of WHDLoad, allows to get and set various variables
        concerning the software and hardware configuration and to control the
        behavior of some WHDLoad operations

   INPUTS
        tags - pointer to a table of tag items

        the following items are currently supported:

        WHDLTAG_ATTNFLAGS_GET   - gets the AttnFlags describing the current
                                  CPU, FPU and MMU, the returned value is
                                  similar to execbase.AttnFlags but not equal
                                  because WHDLoad uses some additional bits,
                                  the Slave is allowed to only use the defines
                                  from the NDK include file 'exec/execbase.i'
                                  for testing
        WHDLTAG_BPLCON0_GET     - gets the system value of custom.bplcon0 as
                                  stored in graphics.library base
                                  gb_system_bplcon0, it can be used to reuse
                                  genlock and lace mode
        WHDLTAG_BUILD_GET       - gets WHDLoad build number
        WHDLTAG_BUTTONWAIT_GET  - returns -1 if WHDLoad option ButtonWait/S
                                  has been enabled, otherwise returns 0
        WHDLTAG_CBAF_SET        - sets a function which will be executed when
                                  an access fault exception occurs (see
                                  section WHDLoad/WHDLTAG_CBAF_SET for further
                                  information)
        WHDLTAG_CBSWITCH_SET    - sets a function which will be executed when
                                  WHDLoad switches from the operating system
                                  to the installed program (see section
                                  WHDLoad/WHDLTAG_CBSWITCH_SET for further
                                  information)
        WHDLTAG_CHIPREVBITS_GET - gets the ChipRevBits describing the present
                                  custom chips, see NDK include file
                                  'graphics/gfxbase.i' for further info
        WHDLTAG_CHKBLTHOG       - enables the 'dmacon.blthog' check, requires
                                  a active Snoop option and WHDLoad v13
        WHDLTAG_CHKBLTSIZE      - enables the 'blitter size' check, requires a
                                  active Snoop option and WHDLoad v13
        WHDLTAG_CHKBLTWAIT      - enables the 'blitter wait' check, requires a
                                  active Snoop option and WHDLoad v13
        WHDLTAG_CHKCOLBST       - enables the 'bplcon0.color' check, requires
                                  a active Snoop option and WHDLoad v13
        WHDLTAG_CHKCOPCON       - enables the 'copcon' check, requires
                                  a active Snoop option and WHDLoad v15.2
        WHDLTAG_CUST_DISABLE
        WHDLTAG_CUST_READ
        WHDLTAG_CUST_STROBE
        WHDLTAG_CUST_WRITE      - modifies the properties of custom registers
                                  in conjunction with the Snoop*/S features,
                                  thus making registers (not) readable or
                                  writable (see section WHDLoad/WHDLTAG_CUST
                                  for further information)
        WHDLTAG_CUSTOM1_GET
        WHDLTAG_CUSTOM2_GET
        WHDLTAG_CUSTOM3_GET
        WHDLTAG_CUSTOM4_GET
        WHDLTAG_CUSTOM5_GET     - returns the numerical value of the
                                  appropriate WHDLoad option Custom1/N ..
                                  Custom5/N
        WHDLTAG_DBGADR_SET      - sets a base address for debugging, this is
                                  only used for error messages generated by
                                  WHDLoad, on an error it will additionally
                                  output the offset of the faulted address to
                                  this base, useful if you have program code
                                  somewhere (e.g. in ExpMem) and like to know
                                  at which offset in the program it has happen
                                  (without calculating it manually)
                                  requires WHDLoad v14.5
        WHDLTAG_DBGSEG_SET      - nearly the same as WHDLTAG_DBGADR_SET, but
                                  instead of a memory address a BCPL pointer to
                                  a dos.library Segment is given, on an error
                                  WHDLoad will display the offset in the
                                  relocated executable like you would see it in
                                  a dis/reassembler
                                  requires WHDLoad v15.0
        WHDLTAG_ECLOCKFREQ_GET  - gets the EClockFrequency, which is the
                                  frequency the custom chips operate on, the
                                  value is taken from the execbase (see NDK
                                  include file 'exec/execbase.i')
        WHDLTAG_IOERR_GET       - gets the DOS error code of a previously
                                  called resload function
        WHDLTAG_KEYTRANS_GET    - get a pointer to a table to perform a 'rawkey
                                  to ascii' conversion, the table has a length
                                  of 512 bytes and contains 4 sub tables, first
                                  128 bytes representing the keys pressed
                                  without any modifier, then 128 bytes with
                                  Shift, then 128 bytes with Alt and at last
                                  128 bytes with Shift and Alt
                                  the tables are created from the actual
                                  system keymap, dead keys are mapped like
                                  pressing Space afterwards, keys resulting in
                                  multibyte characters (F-Keys, Esc, ...) are
                                  set to 0 in the tables
        WHDLTAG_LANG_GET        - get language provided by lowlevel.library,
                                  see 'libraries/lowlevel.i' for further info
                                  requires WHDLoad v13.2
        WHDLTAG_MONITOR_GET     - gets the used monitor/video mode, the
                                  value returned is one of NTSC_MONITOR_ID and
                                  PAL_MONITOR_ID (defined in the NDK include
                                  file 'graphics/modeid.i'), the WHDLoad
                                  options PAL/S and NTSC/S are affecting the
                                  monitor/video mode
        WHDLTAG_REVISION_GET    - gets WHDLoad minor version number
        WHDLTAG_TIME_GET        - gets the time and date when WHDLoad has been
                                  started, returned will be a pointer to a
                                  filled whdload_time structure which is
                                  described in the include file 'whdload.i'
        WHDLTAG_VERSION_GET     - gets WHDLoad major version number

   RESULT
        success - true if all items in the taglist has been successfully
                  processed

   EXAMPLE
        check if the present CPU is at least a MC68020:
                ...
                clr.l   -(a7)                           ;TAG_DONE
                clr.l   -(a7)                           ;data to fill
                move.l  #WHDLTAG_ATTNFLAGS_GET,-(a7)
                move.l  a7,a0
                move.l  (_resload,pc),a2
                jsr     (resload_Control,a2)
                move.w  (6,a7),d0                       ;D0 = AttnFlags
                lea     (12,a7),a7                      ;restore sp
                btst    #AFB_68020,d0
                beq     .no68020
                ...
        get video mode and CPU:
                ...
                lea     (_tags,pc),a0
                move.l  (_resload,pc),a2
                jsr     (resload_Control,a2)
                move.l  (_mon,pc),d0                    ;D0 = video mode
                cmp.l   #NTSC_MONITOR_ID,d0
                beq     .ntsc
                ...
        _tags   dc.l    WHDLTAG_MONITOR_GET
        _mon    dc.l    0
                dc.l    WHDLTAG_ATTNFLAGS_GET
                dc.w    0                               ;padding
        _attn   dc.w    0
                dc.l    0                               ;TAG_DONE

   BUGS
        if an unknown tag is encountered (e.g. because an older WHDLoad
        version is used) the tag list processing stops and all following
        tags are ignored

   NOTE
        requires ws_Version >= 5

   SEE ALSO


WHDLoad/WHDLTAG_CBAF_SET

   NAME
        WHDLTAG_CBAF_SET -- set Call Back Access Fault

   SYNOPSIS
        tag to be used with resload_Control to set call back on access fault

        cont, adr,  data = CBAF(mode, size,  pc,  adr,  data/regs)
         D0    A1    A2          D0    D1    A0    A1      A2
        LONG  APTR  APTR        LONG  LONG  APTR  APTR    APTR

   FUNCTION
        Using this tag a function can be set which gets executed when an
        access fault exception occurs which is not handled by WHDLoad itself.
        It may be used to locate specific accesses in conjunction with
        resload_Protect and to walk around invalid accesses during the
        development process.
        on the 68030 all access faults can be caught except:
         - instruction stream faults
         - faults caused by WHDLoad's blitwait and blitsize checks
        on the 68040/60 only these access faults can be caught:
         - faults caused by resload_Protect
        The routine being set must not change any registers except the ones
        holding a return value. The routine must return via RTS. On entering
        the routine all interrupts are disabled (sr=$27xx).

   INPUTS
        The tag item data field contains a pointer to the function which is
        called by WHDLoad with the following parameters:
        mode - transfer mode of the faulted access
                0 - read
                1 - modify (only 68060)
                2 - write
        size - operand size of the attempted access
                1 - Byte
                2 - Word
                4 - Long
        pc   - program counter of the instruction which has faulted
               (warning: on the write faults this often points to the
               instruction after the one which has faulted (on the 68040 it
               may also point two instructions ahead), read the appropriate
               microprocessor user manual for further information)
        adr  - the address which has been attempted to access
        data - on the 68030/68040 valid only on write faults: the given memory
               address contains the data which has been tried to write
               on the 68060 on read/write faults: contains a pointer to memory
               where the saved registers D0-A6 are stored

   RESULT
        The function has to return the following values:
        cont - how to continue
                0 - terminate, WHDLoad will show a requester notifying the
                    access fault
                1 - proceed, the faulted access will be emulated by the
                    handler inside WHDLoad
        adr  - only on 68030: in case of cont=proceed the address which will be
               accessed
        data - only on 68030/68040: in case of cont=proceed and mode=write a
               pointer to the data which will be written

   EXAMPLE
        If you want to get informed at which point the installed program
        writes the value 42 to the address $BABE the following code can be
        used. It allows any write <> 42 to $BABE but will fault if 42 is
        written (works on 68030/40 only):
                ...
                clr.l   -(a7)                           ;TAG_DONE
                pea     (_af,pc)                        ;function
                move.l  #WHDLTAG_CBAF_SET,-(a7)         ;tag
                move.l  a7,a0
                move.l  (_resload,pc),a2
                jsr     (resload_Control,a2)
                lea     (12,a7),a7                      ;restore sp
                moveq   #2,d0                           ;length
                lea     ($BABE),a0                      ;address
                jsr     (resload_ProtectWrite,a2)       ;protect area
                ...
     _af        cmp.l   #$BABE,a1                       ;correct address?
                bne     .term
                cmp.w   #2,d1                           ;size
                bne     .term
                cmp.w   #42,(a2)                        ;valid on 68030/40 only
                beq     .term
                moveq   #1,d0                           ;proceed
                rts
    .term       moveq   #0,d0                           ;terminate
                rts
        If want you to redirect an access from $24 to the address $300, use the
        following code (works on 68030 only):
                ...
                clr.l   -(a7)                           ;TAG_DONE
                pea     (_af,pc)                        ;function
                move.l  #WHDLTAG_CBAF_SET,-(a7)         ;tag
                move.l  a7,a0
                move.l  (_resload,pc),a2
                jsr     (resload_Control,a2)
                lea     (12,a7),a7                      ;restore sp
                moveq   #4,d0                           ;length
                lea     ($24),a0                        ;address
                jsr     (resload_ProtectWrite,a2)       ;protect area
                ...
     _af        cmp.l   #$24,a1                         ;correct address?
                bne     .term
                lea     ($300),a1
                moveq   #1,d0                           ;proceed
                rts
    .term       moveq   #0,d0                           ;terminate
                rts

   BUGS
        fully supported is only the 68030, limited support for 68040/60

   NOTE
        requires ws_Version >= 9
        on the 68040 it's supported starting WHDLoad 18.0
        on the 68060 it's supported starting WHDLoad 16.1
        the parameter a2=regs on the 68060 is supported since WHDLoad 16.4
        MUST not be used in public releases, use it during development process
        only

   SEE ALSO
        resload_Control


WHDLoad/WHDLTAG_CBSWITCH_SET

   NAME
        WHDLTAG_CBSWITCH_SET -- set Call Back on switch mode

   SYNOPSIS
        tag to be used with resload_Control to set call back on Switch Mode

        CBSWITCH()

   FUNCTION
        Using this tag a routine can be set which will executed each time
        WHDLoad switches from the operating system to the installed program.
        Such a routine is sometimes necessary because during the switch
        between the installed program and the operating system some hardware
        registers are modified by the operating system.
        Known registers getting modified are cop2lc, bltafwm and bltalwm (maybe
        there are more of them).
        The routine must not change any registers except D0-D1, must not use
        any stack and has to return via 'jmp (a0)'. At execution time of the
        routine all interrupts and DMAs are disabled and the memory setup of
        the installed program is active.

   INPUTS
        The tag item data field contains a pointer to the routine which
        should be called by WHDLoad during a Switch Mode. A value equal 0
        disables the execution of a routine.

   EXAMPLE
                ...
                clr.l   -(a7)                           ;TAG_DONE
                pea     (_cbswitch,pc)                  ;function
                move.l  #WHDLTAG_CBSWITCH_SET,-(a7)     ;tag
                move.l  a7,a0
                move.l  (_resload,pc),a2
                jsr     (resload_Control,a2)
                lea     (12,a7),a7                      ;restore sp
                ...
     _cbswitch  move.l  (_c2,pc),(_custom+cop2lc)
                jmp     (a0)                            ;return
     _cb2       dc.l    $10e80

   EXAMPLE
        if stack is required, an own stack must be set:

     _cbswitch  move.l  a7,d0                           ;save a7
                lea     (.stack,pc),a7                  ;temporary stack
                movem.l d0/a0-a1,-(a7)
                ...
                jsr     ...
                ...
                movem.l (a7),d0/a0-a1
                move.l  d0,a7                           ;restore a7
                jmp     (a0)                            ;return

                ds.l    64                              ;how much needed?
     .stack

   NOTE
        requires ws_Version >= 7

   SEE ALSO
        resload_Control


WHDLoad/WHDLTAG_CUST

   NAME
        WHDLTAG_CUST_DISABLE - forbid all accesses
        WHDLTAG_CUST_READ - allow reads
        WHDLTAG_CUST_STROBE - allow reads and writes
        WHDLTAG_CUST_WRITE - allow writes

   SYNOPSIS
        tag to be used with resload_Control
        the tag data is the address of the custom register to be modified

   FUNCTION
        Using this tag the state of the specified custom register can be
        modified regarding the readability and/or writability in WHDLoad.
        WHDLoad knows about what custom registers can be read/written on the
        existing chipsets OCS, ECS and AGA. These abilities are enforced when
        using one of the options SnoopOCS/S, SnoopECS/S or SnoopAGA/S.
        Sometimes it may be useful to allow read/writes to other registers then
        the default to be able to use the Snoop#?/S feature without having to
        fix all bad accesses present in an alien program.
        Sometimes it may be useful to forbid access to valid custom registers
        to detect specific operations in a program.
        Using this function it is not possible to change the behavior of byte
        write operations because such accesses are handled by WHDLoad in a
        special way.

   INPUTS
        The tag item data field contains the custom register address which
        should be modified. The address must be even and between 0 and $1fe.

   EXAMPLE
        Allow write access to the dummy register 'noop':
                ...
                clr.l   -(a7)                           ;TAG_DONE
                pea     $1fe                            ;noop
                move.l  #WHDLTAG_CUST_WRITE,-(a7)
                move.l  a7,a0
                move.l  (_resload,pc),a2
                jsr     (resload_Control,a2)
                lea     (12,a7),a7                      ;restore sp
                ...
        Detect any writes to the vposw, vhposw and copjmp registers:
                ...
                lea     (_tags,pc),a0
                move.l  (_resload,pc),a2
                jsr     (resload_Control,a2)
                ...
        _tags   dc.l    WHDLTAG_CUST_DISABLE,vhposw
                dc.l    WHDLTAG_CUST_DISABLE,vposw
                dc.l    WHDLTAG_CUST_DISABLE,copjmp1
                dc.l    WHDLTAG_CUST_DISABLE,copjmp2
                dc.l    0

   BUGS
        some custom registers are handled in a special way by WHDLoad, these
        registers may remain unaffected by this facility, these registers are:
                dmacon, cop1lc.l, cop2lc.l, aud*pt.l (if ChkAudPt is used),
                bplpt*.l, bplcon1.l, bplcon2, all blitter registers (if
                ChkBltSize/Wait is used), bplcon0 (if ChkColBst is used),
                copcon and vhposw.l (if ChkCopCon is used)
        changing custom registers which are also read/written by WHDLoad
        itself may cause faults by WHDLoad or deadlocks
        setting existing custom registers to disabled will also cause these
        registers getting no longer displayed in the register dump file

   NOTE
        supported starting WHDLoad 18.0
        should not be used in public releases, use it during development
        process only

   SEE ALSO
        resload_Control


WHDLoad/WHDLTAG_IOERR_GET

   NAME
        WHDLTAG_IOERR_GET -- get IO Error code

   SYNOPSIS
        tag to be used with resload_Control to get the last DOS error code

   FUNCTION
        This tag can be used to get the DOS error code of the last called
        resload function. All resload functions except resload_Control will
        set/reset this error code.
        Two resload functions are special in that way:
            resload_GetFileSize
                If a file with the specified name cannot be opened via
                dos.Open, the error code will be set to the value returned
                from dos.IoErr. So the error code may contain values like
                ERROR_OBJECT_NOT_FOUND, ERROR_OBJECT_WRONG_TYPE,
                ERROR_READ_PROTECTED or similar (see NDK include file
                dos/dos.i). The error code can be used to distinguish between
                a file with the size of 0 and a nonexistent file.
            resload_ListFiles
                If the specified buffer to fill is not large enough to hold
                all file names from the scanned directory, the error code will
                be set to ERROR_NO_FREE_STORE.

   RESULT
        The tag item data field contains the last DOS error code.

   EXAMPLE
                ...
                clr.l   -(a7)                           ;TAG_DONE
                clr.l   -(a7)                           ;data to fill
                move.l  #WHDLTAG_IOERR_GET,-(a7)        ;tag
                move.l  a7,a0
                move.l  (_resload,pc),a2
                jsr     (resload_Control,a2)
                move.l  (4,a7),d0                       ;D0 = IoErr
                lea     (12,a7),a7                      ;restore sp
                ...

   NOTE
        requires ws_Version >= 8

   SEE ALSO
        resload_Control, resload_GetFileSize, resload_ListFiles


WHDLoad/resload_CRC16

   NAME
        resload_CRC16 -- calculate ANSI conform 16 bit CRC checksum

   SYNOPSIS
        checksum = resload_CRC16(length,address)
           D0                      D0     A0
         UWORD                   ULONG   APTR

   FUNCTION
        calculate ANSI conform 16 bit CRC checksum
        mostly used to differentiate between various program/data versions

   INPUTS
        length  - length of region to calculate sum over
        address - pointer to region

   RESULT
        checksum - 16 bit CRC

   EXAMPLE
                ...
                lea     $1000,a0                ;at address $1000
                move.l  #256,d0                 ;up to address $1100
                move.l  (_resload,pc),a2
                jsr     (resload_CRC16,a2)
                cmp.w   #$f2b7,d0
                bne     .false_version
                ...

   NOTE
        requires ws_Version >= 3

   SEE ALSO


WHDLoad/resload_Decrunch

   NAME
        resload_Decrunch -- uncompress data in memory

   SYNOPSIS
        size = resload_Decrunch(source, destination)
         D0                       A0        A1
        ULONG                    APTR      APTR

   FUNCTION
        This unpacks compressed data in memory. Known compressed data formats
        are RNC1, RNC2, IMP!, ATN!, TPWM and Cr[Mm][!2].
        If the data source doesn't point to a known compressed format size=0
        will be returned. Else the data will be unpacked to the destination
        and the size of the decompressed data is returned.
        Source and destination can be equal. In that case the packed data will
        be overwritten. Also in this case some memory before (RNC1old,Cr*) or
        after (RNC1/2,TPWM) the decompressed data may be temporarly
        overwritten and at the end restored!

        RNC1:   Rob Northen compressor - emphasis on packed size
                Supported is the old and the new format. Both formats are using
                the same id but different file formats and compression
                algorithms. The function uses some heuristic checks to
                determine the correct format. The decompressor for the new
                common format is highly optimized and contains separate code
                for the 68000/10 and for 68020+. On the 68060 it's faster than
                the Imploder decompressor.
        RNC2:   Rob Northen compressor - emphasis on unpacking speed
                It's the fastest supported decompressor.
        IMP!:   Imploder (FImp)
                The packed data must not overlap the destination. The
                destination must be either equal to the source or completely
                outside the source data. In difference to the original explode
                routine resload_Decrunch does not destroy the source data (if
                source is unequal to the destination).
        ATN!:   identical to IMP! only id is different
        TPWM:   Turbo Packer Wolfgang Mayerle
                Supported starting WHDLoad v11. Because the file header does
                not contain the length of the packed data there is no
                integrity check performed.
        Cr[Mm][!2]: Crunch-Mania by Thomas Schwarz
                Supported starting WHDLoad v17. The packed source data must be
                located on a word aligned address for 68000/10 compatibility!

        All decompression routines have been modified to not modify the
        registers A5 and A6 and to use nearly no stack space.
        All decompression routines are performing a check if the decompression
        was successful. On a failure the installed program will be terminated
        and WHDLoad will display a message telling this.

   INPUTS
        source      - address of source in memory
        destination - address of destination in memory (can be equal to source)

   RESULT
        size - the size of the uncompressed data or 0 if is not compressed
               with a known format

   NOTE
        the routine performs automatically a resload_FlushCache before
        returning

   SEE ALSO
        resload_LoadFileDecrunch


WHDLoad/resload_Delay

   NAME
        resload_Delay -- wait some time or for a user action

   SYNOPSIS
        resload_Delay(time)
                       D0
                      ULONG

   FUNCTION
        Waits the specified time or until any button/key is pressed. All
        possible buttons (LMB, MMB, RMB) of both controllers (port 0/1) and the
        keyboard is checked. After the time runs out or something has been
        pressed the function waits until the pressed controller button has been
        released. But it does not wait for a keyboard key up.
        The wait routine is based on the raster beam. But checks the current
        display and therefore waits the same time on PAL and NTSC displays.

   INPUTS
        time - time to wait in 1/10 seconds

   RESULT
        nothing, all registers are preserved

   EXAMPLE
                ...
                moveq   #30,d0                  ;3 seconds
                move.l  (_resload,pc),a2
                jsr     (resload_Delay,a2)
                ...

   NOTE
        in difference to most others resload_#? function this routine is
        granted to preserve all registers
        requires ws_Version >= 8

   SEE ALSO


WHDLoad/resload_DeleteFile

   NAME
        resload_DeleteFile -- delete a file

   SYNOPSIS
        success,errorcode = resload_DeleteFile(name)
          D0       D1                           A0
         BOOL    ULONG                         CPTR

   FUNCTION
        This function deletes the file with the specified name.
        If there are multiple data directories used the file to delete
        must be located in the first data directory. Otherwise deleting
        will fail with a DOS error code ERROR_OBJECT_NOT_FOUND.
        If option SavePath/K is used and the save path is not yet created
        or the file doesn't exist in the save path the function will
        return with success without deleting a file.
        If WHDLoad has been started from a read-only filesystem (not if
        SavePath/K is used) the function will return with success without
        deleting a file.

   INPUTS
        name - name of the file to delete

   RESULT
        success   - TRUE on success
        errorcode - 0 on success
                    otherwise a DOS error code from dos.IoErr()
        if WHDLF_NoError is set, the function only returns on success

   EXAMPLE
                ...
                lea     (_name,pc),a0
                move.l  (_resload,pc),a2
                jsr     (resload_DeleteFile,a2)
                ...
        _name   dc.b    "C/WHDLoad",0

   NOTE
        requires ws_Version >= 8
        upto WHDLoad version 18.2 it was possible to delete also directories
        using this function, now it will always fail with DOS error code
        ERROR_DIRECTORY_NOT_EMPTY in this case

   SEE ALSO


WHDLoad/resload_Delta

   NAME
        resload_Delta -- apply WDelta file

   SYNOPSIS
        resload_Delta(src,  dest, delta)
                       A0    A1    A2
                      APTR  APTR  APTR

   FUNCTION
        Applies the differences provided via the delta data onto the source
        data and creates the destination data.
        WDelta is a tool to calculate a binary differences file from two data
        files (like scompare/spatch). It can be found on aminet
        (http://main.aminet.net/util/cli/WDelta.lha).
        This function can be used to support different versions of data or
        program files by converting them into one single version.

   INPUTS
        src   - source data
        dest  - destination memory
        delta - wdelta data

   EXAMPLE
                ...
                lea     ($10000),a0             ;source
                lea     ($400),a1               ;destination
                lea     ($40000),a2             ;wdelta
                move.l  (_resload,pc),a3
                jsr     (resload_Delta,a3)
                ...

   NOTE
        The source, the delta and the destination data will be CRC checked.
        If an error occurs WHDLoad will quit with an appropriate requester.
        requires ws_Version >= 11

   SEE ALSO


WHDLoad/resload_DiskLoad

   NAME
        resload_DiskLoad -- load part of a disk image

   SYNOPSIS
        success,errorcode = resload_DiskLoad(offset,size,diskno,dest)
          D0       D1                          D0    D1    D2    A0
         BOOL    ULONG                        ULONG ULONG UBYTE APTR

   FUNCTION
        Loads a part from a disk image as specified by the parameters.
        The name of the disk images is expected as 'disk.' followed by the
        number of the disk (e.g. 'Disk.1').
        The size of the disk image is variable. An attempt to read data
        outside of the disk image will result in a DOS error ERROR_SEEK_ERROR.

   INPUTS
        offset - offset in the disk image (relative to the beginning)
        size   - amount of bytes to read
        diskno - disk number
        dest   - destination address

   RESULT
        success   - TRUE on success
        errorcode - 0 on success
                    otherwise a DOS error code from dos.IoErr()
        if WHDLF_NoError is set, the function only returns on success

   EXAMPLE
                ...
                move.l  #880*512,d0             ;from block 880
                move.l  #2*512,d1               ;2 blocks
                moveq   #1,d2                   ;disk 1
                lea     $80000,a0               ;destination
                move.l  (_resload,pc),a2
                jsr     (resload_DiskLoad,a2)
                ...

   NOTE
        The routine performs automatically a resload_FlushCache before
        returning.
        Starting WHDLoad version 17.1 there is a new functionality: if bit #31
        of the diskno is set and the options FileLog/S and Expert/S are enabled
        each loaded file part is saved to the first data directory using the
        generated file name "D<disk number> <start offset on disk>-<end offset
        on disk> @<destination address>". Starting WHDLoad version 18.1 the
        destination address if located in ExpMem will be prepended with a "E "
        and the offset in ExpMem is used.

   SEE ALSO
        resload_LoadFileOffset


WHDLoad/resload_DiskLoadDev

   NAME
        resload_DiskLoadDev -- load part from a floppy disk

   SYNOPSIS
        success,errorcode = resload_DiskLoadDev(offset, size,  dest,  tags)
          D0        D1                            D0     D1     A0     A1
         BOOL     ULONG                         ULONG  ULONG  UBYTE  STRUCT

   FUNCTION
        Loads a given amount of data from a floppy device.

   INPUTS
        offset - offset on the disk (must be a multiple of 512 bytes)
        size   - amount of bytes to read (must be a multiple of 512 bytes)
        dest   - destination address (must be aligned to 512 bytes)
        tags   - pointer to a taglist, starting WHDLoad version 16.0
                 there is one supported tag WHDLTAG_TDUNIT which
                 specifies the trackdisk.device unit to read from, default
                 is unit 0 (DF0:)

   RESULT
        success   - TRUE on success
        errorcode - 0 on success
                    otherwise a Trackdisk error code
        if WHDLF_NoError is set, the function only returns on success

   EXAMPLE
                ...
                move.l  #880*512,d0             ;from block 880
                move.l  #2*512,d1               ;2 blocks
                lea     $80000,a0               ;destination
                sub.l   a1,a1                   ;tag list
                move.l  (_resload,pc),a2
                jsr     (resload_DiskLoadDev,a2)
                ...

   NOTE
        requires ws_Version >= 2
        At the moment all parameters (offset, size, address) must be aligned
        to 512 bytes due restrictions of trackdisk.device.
        The routine performs automatically a resload_FlushCache before
        returning.

   SEE ALSO


WHDLoad/resload_Examine

   NAME
        resload_Examine -- get information about a file or directory

   SYNOPSIS
        success,errorcode = resload_Examine(name, FileInfoBlock)
          D0        D1                       A0         A1
         BOOL     ULONG                     CPTR       APTR

   FUNCTION
        Fills the supplied FileInfoBlock with information about the
        specified file or directory. See NDK include file dos/dos.i for the
        structure of the FileInfoBlock.

   INPUTS
        name - name of the object to get info about
        fib  - memory buffer of 260 bytes for the infos

   RESULT
        success - is true (-1) on success and false (0) on failure
        errorcode - contains DOS error code (e.g. ERROR_OBJECT_NOT_FOUND)

   EXAMPLE
                ...
                lea     (_filename,pc),a0
                sub.l   #fib_SIZEOF,a7
                move.l  a7,a1
                move.l  (_resload,pc),a2
                jsr     (resload_Examine,a2)
                ...
                add.l   #fib_SIZEOF,a7
                ...

   BUGS
        Relative path names (starting/ending with '/' or containing '//') are
        not supported. The name must also not contain a ':'.
        The fib_Size will be incorrect if the file is more than two times
        compressed using XPK or compressed using XPK and afterwards encrypted
        using XPK.

   NOTE
        This function requires that the flag WHDLF_Examine is set in the Slave
        structure which tells WHDLoad to collect the information returned by
        this function before running the Slave. Starting with WHDLoad 18.6
        calling this function without WHDLF_Examine set will terminate WHDLoad
        with an appropriate error message.
        The FileInfoBlock is not required to start at a long aligned address
        as it is the case with dos.Examine.
        requires ws_Version >= 15

   SEE ALSO
        resload_GetFileSize, resload_GetFileSizeDec, resload_ExNext


WHDLoad/resload_ExNext

   NAME
        resload_ExNext -- get information about next directory entry

   SYNOPSIS
        success,errorcode = resload_Examine(FileInfoBlock)
          D0        D1                          A0
         BOOL     ULONG                        APTR

   FUNCTION
        Fills the supplied FileInfoBlock with information about the next
        directory entry. The FileInfoBlock must be previously initialized by
        a call to resload_Examine.

   INPUTS
        fib - memory buffer of 260 bytes for the infos

   RESULT
        success - is true (-1) on success and false (0) on failure
        errorcode - if there are no more entries left it contains
        ERROR_NO_MORE_ENTRIES

   EXAMPLE
                ...
                lea     (_dirname,pc),a0
                sub.l   #fib_SIZEOF,a7
                move.l  a7,a1
                move.l  (_resload,pc),a2
                jsr     (resload_Examine,a2)
                tst.l   d0
                beq     .end
   .next        move.l  a7,a0
                jsr     (resload_ExNext,a2)
                tst.l   d0
                beq     .end
                ...
                bra     .next
   .end         add.l   #fib_SIZEOF,a7
                ...

   BUGS
        The fib_Size will be incorrect if the file is more than two times
        compressed using XPK or compressed using XPK and afterwards encrypted
        using XPK.

   NOTE
        requires ws_Version >= 15

   SEE ALSO
        resload_Examine


WHDLoad/resload_FlushCache

   NAME
        resload_FlushCache -- flush and clear the CPU caches

   SYNOPSIS
        resload_FlushCache()

   FUNCTION
        clears all CPU caches

   NOTE
        In difference to most other resload_#? functions this routine is
        granted to preserve all registers.
        It's safe to call this routine from User and Supervisor mode and
        independent of the actual CPU type (also on 68000/010).
        It uses the CACR on 68020/30 and a 'cpusha bc' on 68040/60 to flush
        the caches.

   SEE ALSO
        resload_SetCPU


WHDLoad/resload_GetCustom

   NAME
        resload_GetCustom -- get Custom argument

   SYNOPSIS
        success = resload_GetCustom(buflen, reserved, buffer)
          D0                          D0       D1       A0
         ULONG                       ULONG    ULONG    CPTR

   FUNCTION
        Get the string which has been specified via the Custom/S option.
        The buffer is filled as far as possible. If buffer was not large
        enough false will be returned.

   INPUTS
        buflen   - size of buffer
        reserved - currently not used, must be set to 0
        buffer   - memory area to fill

   RESULT
        success - false if buffer was too small

   EXAMPLE
                ...
                move.l  #$100,d0
                moveq   #0,d1
                lea     ($1000),a0
                move.l  (_resload,pc),a2
                jsr     (resload_GetCustom,a2)
                tst.l   d0
                beq     .error
                ...

   NOTE
        requires ws_Version >= 15

   SEE ALSO


WHDLoad/resload_GetFileSize

   NAME
        resload_GetFileSize -- get the size of a file

   SYNOPSIS
        size = resload_GetFileSize(name)
         D0                         A0
        ULONG                      CPTR

   FUNCTION
        Gets the size of a file (checks if a file exists).
        To distinguish between a file with a size of 0 and a nonexistent
        file the tag WHDLTAG_IOERR_GET must be used in conjunction with
        resload_Control afterwards.

   INPUTS
        name - name of the file to get the size of

   RESULT
        size - the size of the file or 0 if does not exist

   EXAMPLE
                ...
                lea     (_filename,pc),a0
                move.l  (_resload,pc),a2
                jsr     (resload_GetFileSize,a2)
                tst.l   d0
                bne     .file_exist
                clr.l   -(a7)                           ;TAG_DONE
                clr.l   -(a7)                           ;data to fill
                move.l  #WHDLTAG_IOERR_GET,-(a7)
                move.l  a7,a0
                jsr     (resload_Control,a2)
                tst.l   (4,a7)
                lea     (12,a7),a7                      ;restore sp, no cc
                beq     .file_exist
                ...

   NOTE
        This routine returns the file size obtained from the filesystem. If the
        file is compressed and is loaded later via resload_LoadFileDecrunch the
        loaded file size will differ!
        If WHDLF_Examine is set in the Slave and the file was not preloaded and
        the file is more than two times compressed using XPK or compressed
        using XPK and afterwards encrypted using XPK the returned size will be
        incorrect.

   SEE ALSO
        resload_Control, resload_GetFileSizeDec, resload_LoadFile,
        resload_LoadFileDecrunch


WHDLoad/resload_GetFileSizeDec

   NAME
        resload_GetFileSizeDec -- get the size of a packed file

   SYNOPSIS
        size = resload_GetFileSizeDec (name)
         D0                         A0
        ULONG                      CPTR

   FUNCTION
        Gets the uncompressed size of a packed file (checks if a file exists).
        The routine knows about the same decrunchers as resload_Decrunch.
        To distinguish between a file with a size of 0 and a nonexistent
        file the tag WHDLTAG_IOERR_GET must be used in conjunction with
        resload_Control afterwards.

   INPUTS
        name - name of the file to get the size of

   RESULT
        size - the size of the file or 0 if does not exist

   EXAMPLE
                ...
                lea     (_filename,pc),a0
                move.l  (_resload,pc),a2
                jsr     (resload_GetFileSizeDec,a2)
                tst.l   d0
                beq     .file_not_exist
                ...

   NOTE
        requires ws_Version >= 11

   SEE ALSO
        resload_Control, resload_GetFileSize, resload_LoadFile,
        resload_LoadFileDecrunch


WHDLoad/resload_ListFiles

   NAME
        resload_ListFiles -- list file names in a directory

   SYNOPSIS
        amount,errorcode = resload_ListFiles(buffersize, name, buffer)
          D0      D1                             D0       A0     A1
        ULONG   ULONG                          ULONG     CPTR   APTR

   FUNCTION
        Writes the names of all files in the specified directory to the
        buffer. The file names are separated with a 0 character.
        Only files are listed, directories are skipped.
        If the buffer to fill is not large enough to hold all names the
        routine fills it as far as possible. The errorcode or the tag
        WHDLTAG_IOERR_GET in conjunction with resload_Control can be used
        afterwards to check if all file names did fit into the buffer.
        If multiple data directories are used, only the first data directory
        will be scanned.
        If the first data directory is a VFS file the function does return
        entries only if all files were preloaded. Direct list files from a VFS
        is not implemented.

   INPUTS
        buffersize - the size of the buffer to fill
        name       - the name of the directory to scan
        buffer     - pointer to the buffer to fill (up to WHDLoad v16.8 the
                     buffer must be located inside the Slave, from WHDLoad
                     v16.9 on it can also be located in ExpMem)

   RESULT
        amount    - amount of listed files in the buffer
        errorcode - 0 on success
                    otherwise a DOS error code from dos.IoErr()
        if WHDLF_NoError is set, the function only returns on success

   EXAMPLE
                ...
                move.l  #_bufend-_buf,d0
                lea     (_savepath,pc),a0
                lea     (_buf,pc),a1
                move.l  (_resload,pc),a2
                jsr     (resload_ListFiles,a2)
                ...
        _buf      ds.b    1000
        _bufend
        _savepath dc.b  "save",0


   NOTE
        Before WHDLoad release 18.7 a call to this resload function always
        caused a switch to the operating system because the information to
        provide is not cached. To avoid this switch resload_Examine and
        resload_ExNext could be used instead (but will require some additional
        memory for the Directory PreLoad).
        Starting WHDLoad release 18.7 the file cache created by the option
        Preload will be used but only if all files could be preloaded.
        In releases 18.7 and 18.8 reading from the file cache was unable to
        handle the install root directory (a0="") correctly and returned
        nothing with this argument. Fixed in release 18.9.

   SEE ALSO
        resload_Control


WHDLoad/resload_LoadFile

   NAME
        resload_LoadFile -- load a file into memory

   SYNOPSIS
        length,errorcode = resload_LoadFile(name, address)
          D0      D1                         A0      A1
        ULONG    ULONG                      CPTR    APTR

   FUNCTION
        Loads the file to the specified memory address.

   INPUTS
        name    - name of the file to load
        address - memory address to load the file on

   RESULT
        length    - the size of the loaded file, or 0 on error
        errorcode - 0 on success
                    otherwise a DOS error code from dos.IoErr()
        if WHDLF_NoError is set, the function only returns on success

   EXAMPLE
                ...
                lea     (_filename),a0          ;name
                lea     $1000.w,a1              ;destination
                move.l  (_resload,pc),a2
                jsr     (resload_LoadFile,a2)
                ...

   NOTE
        The routine performs automatically a resload_FlushCache before
        returning.

   SEE ALSO
        resload_LoadFileDecrunch, resload_LoadFileOffset


WHDLoad/resload_LoadFileDecrunch

   NAME
        resload_LoadFileDecrunch -- load a file and uncompress it

   SYNOPSIS
        length,errorcode = resload_LoadFileDecrunch(name, address)
          D0      D1                                 A0      A1
        ULONG    ULONG                              CPTR    APTR

   FUNCTION
        Loads the specified file into memory and unpack it if compressed using
        one of the supported formats. Supported are the same formats as with
        resload_Decrunch.
        Using this routine instead of resload_LoadFile allows it easily to add
        support for compressed data files to an installed program. Because of
        the transparent decompression the installed program will not notify if
        the loaded files were compressed on disk or not. The only thing which
        must be considered is that files which are written using
        resload_SaveFileOffset or loaded via resload_LoadFileOffset must not
        be compressed.

   INPUTS
        name    - name of the file to load
        address - memory address to load the file on

   RESULT
        length    - the size of the loaded file
                    if an error occurs 0 is returned
        errorcode - 0 on success
                    otherwise a DOS error code from dos.IoErr()
        if WHDLF_NoError is set, the function only returns on success

   EXAMPLE
                ...
                lea     (_filename),a0          ;name
                lea     $1000.w,a1              ;destination
                move.l  (_resload,pc),a2
                jsr     (resload_LoadFileDecrunch,a2)
                ...

   NOTE
        The routine performs automatically a resload_FlushCache before
        returning.

   SEE ALSO
        resload_Decrunch, resload_LoadFile, resload_LoadFileOffset,
        resload_SaveFile, resload_SaveFileOffset


WHDLoad/resload_LoadFileOffset

   NAME
        resload_LoadFileOffset -- loads a part of a file into memory

   SYNOPSIS
        success,error = resload_LoadFileOffset(size, offset, name, address)
          D0     D1                             D0     D1     A0      A1
         BOOL   ULONG                          ULONG  ULONG  CPTR    APTR

   FUNCTION
        Loads a part of a file into memory. The part of the file is specified
        by an offset in the file and a byte count to read. The routine is
        nearly identical to resload_DiskLoad but instead of specifying the
        number of the disk to read from a filename is used to select the file.

   INPUTS
        size    - amount of bytes to read
        offset  - offset in the file
        name    - name of file
        address - memory address to load the data on

   RESULT
        success   - TRUE on success
        errorcode - 0 on success
                    otherwise a DOS error code from dos.IoErr()
        if WHDLF_NoError is set, the function only returns on success

   EXAMPLE
                ...
                move.l  #512,d0                 ;size
                move.l  #$4000,d1               ;offset
                lea     (_repo,pc),a0           ;name
                lea     $5ac20,a1               ;destination
                move.l  (_resload,pc),a2
                jsr     (resload_LoadFileOffset,a2)
                ...
        _repo   dc.b    "repository",0

   NOTE
        The routine performs automatically a resload_FlushCache before
        returning.
        requires ws_Version >= 6

   SEE ALSO
        resload_DiskLoad, resload_LoadFile


WHDLoad/resload_LoadKick

   NAME
        resload_LoadKick -- load Kickstart image

   SYNOPSIS
        resload_LoadKick(size, crc16,  name)
                          D0     D1     A0
                         ULONG  UWORD  CPTR

   FUNCTION
        Loads the Kickstart image with the specified name into ExpMem.

   INPUTS
        size    - size of Kickstart image
        crc16   - CRC16 of Kickstart image
        name    - base name of Kickstart image

   RESULT
        the function only returns on success

   EXAMPLE
                ...
                move.l  #$40000,d0              ;size
                move.w  #$f20b,d1               ;crc16
                lea     (_kick,pc),a0           ;name
                move.l  (_resload,pc),a2
                jsr     (resload_LoadKick,a2)
                ...
        _kick   dc.b    "34005.a500",0

   NOTE
        requires ws_Version >= 11
        This function is depreciated since WHDLoad v16 because loading a
        Kickstart this way will cause a switch to the operation system.
        Starting with WHDLoad v16 the Kickstart image to load can be
        specified in the Slave structure and when used WHDLoad will load it
        before the Slave will called.

   SEE ALSO


WHDLoad/resload_Log

   NAME
        resload_Log -- put custom message into log file

   SYNOPSIS
        resload_Log(format, data stream)
                      A0    (4,a7), ...
                     CPTR    va_list

   FUNCTION
        This function puts a formatted message into the WHDLoad log file
        '.whdl_log' which is also used by the FileLog/K/N facility.
        The format string supports printf/exec.RawDoFmt like formatting
        options. See resload_VSNPrintF for available formatting options.
        To get something into the log file the WHDLoad option FileLog/K/N must
        be enabled. To avoid switches to the operating system because of
        overflows of the internal log buffer it is recommended to specify a
        large LogBuffer/K/N in the global WHDLoad configuration file.
        Arguments for the formatted log message are provided on the stack and
        must be freed yourself after returning from this function.
        If LogBuffer/K/N is not large enough for the single message to log
        WHDLoad will abort with an 'illegal arguments' reason.

   INPUTS
        format      - format string containing '%' commands
        data stream - a stream of data interpreted according the parameters in
                      the format string

   RESULT
        nothing, all registers are preserved

   EXAMPLE
        log the files and the loading destination addresses processed by a game
                ...
                move.l  a0,-(a7)                ;file name
                move.l  a1,-(a7)                ;loading address
                lea     _logmsg,a0
                move.l  (_resload),a2
                jsr     (resload_Log,a2)
                add.w   #8,a7                   ;free parameters
                ...
   _logmsg      dc.b    "%5lx %s",0

   NOTE
        requires ws_Version >= 18
        In difference to most other resload_#? functions this routine is
        granted to preserve all registers.

   SEE ALSO
        resload_VSNPrintF


WHDLoad/resload_Patch

   NAME
        resload_Patch -- apply patch list

   SYNOPSIS
        resload_Patch(patchlist, destination)
                         A0          A1
                        APTR        APTR

   FUNCTION
        Modifies memory using commands from the specified patch list.
        To make an installed program work under WHDLoad it must be patched.
        That means the program must be modified so that it will load data via
        WHDLoad instead of using its own loader routines. Often also various
        other things must be changed to make it working.
        The modifying of the installed program can be done using this routine.
        A patch list will be build using macros from the include file
        'whdload.i'. Each entry in the patch list contains a command to
        perform, an address to apply the command on and optional extra data.
        resload_Patch is especially useful if the memory to modify is located
        in ExpMem and therefore the destination address in only known at
        runtime and not at creation time of the Slave.

   INPUTS
        patchlist   - list of commands describing the patches to apply
        destination - address of memory region to patch

        The following commands are supported in a patch list:

        Commands to organize the patch lists:
        PL_START        starts a patch list, this will create a label which is
                        later used to calculate offsets in the slave (the
                        label is local, multiple patch lists must be separated
                        by a global label to avoid name collisions)
        PL_END          terminates a patch list
        PL_NEXT lbl     continues with another patch list at the address
                        where lbl points to in the slave, terminates current
                        list
        PL_IFBW         starts a conditional block which is executed only if
                        option ButtonWait/S has been specified
        PL_IFC?         starts a conditional block which is executed only if
                        option Custom?/N has been specified, ? can be 1..5
        PL_IFC?X bit    starts a conditional block which is executed only if
                        the specified bit is set in the option Custom?/N,
                        ? can be 1..5, bit must be 0..31
        PL_ELSE         start a block which is executed alternatively to the
                        previous if condition block
        PL_ENDIF        closes the previous IF/ELSE block
        IF condition blocks can be nested 31 times.

        Commands which modify the patch destination area:
        PL_A off1,off2  writes the address of destination+offset2 to
                        destination+offset1 (address)
        PL_AB off,byte  adds the byte at destination+offset
        PL_AL off,long  adds the long at destination+offset
        PL_AW off,word  adds the word at destination+offset
        PL_B off,byte   writes the given byte to destination+offset
        PL_C off,len    clears the memory at destination+offset in the given
                        length, max 65536 bytes
        PL_CB off       clears the byte at destination+offset
        PL_CL off       clears the long at destination+offset
        PL_CW off       clears the word at destination+offset
        PL_DATA off,len,... writes the data following the command with the
                        given length to destination+offset, next command must
                        be word aligned, see example below
        PL_I off        writes the opcode for the ILLEGAL instruction ($4afc)
                        to destination+offset
        PL_L off,long   writes the given long to destination+offset
        PL_NOP off,len  fills the memory at destination+offset with NOP
                        ($4e71) instructions in the given length
        PL_NOPS off,cnt fills the memory at destination+offset with the
                        given count of NOP instructions ($4e71)
        PL_ORB off,byte ors the byte at destination+offset
        PL_ORL off,long ors the long at destination+offset
        PL_ORW off,word ors the word at destination+offset
        PL_P off,lbl    writes the opcode for the JMP instruction ($4ef9) and
                        the address where lbl points to in the slave to
                        destination+offset (patch)
        PL_PA off,lbl   writes the address where lbl points to in the slave
                        to destination+offset (patch address)
        PL_PS off,lbl   writes the opcode for the JSR instruction ($4eb9) and
                        the address where lbl points to in the slave to
                        destination+offset (patch sub)
        PL_PSS off,lbl,len writes the opcode for the JSR instruction ($4eb9)
                        and the address where lbl points to in the slave to
                        destination+offset followed by NOP instructions
                        ($4e71) in the given length, len doesn't include the
                        length of JSR (patch sub skip)
        PL_R off        writes the opcode for the RTS instruction ($4e75) to
                        destination+offset (return)
        PL_S off,dist   writes the opcode for the BRA instruction ($6000) and
                        the distance given to destination+offset, will always
                        use word branches (skip)
        PL_STR off,str  writes the given string to destination+offset, see
                        example below (string)
        PL_STR0 off,str writes the given string plus a 0-byte to destination+
                        offset, see example below (string 0-terminated)
        PL_W off,word   writes the given word to destination+offset

        Other commands which do not really change the patch destination:
        PL_BELL off,tim similar to PL_BKPT but instead of entering a freezer a
                        color cycle will be shown for the given time or LMB
                        pressed, time is given in 1/10s (ring the bell)
        PL_BKPT off     lets WHDload write an ILLEGAL ($4afc) to
                        destination+offset and saving the original contents,
                        when the ILLEGAL is executed the original contents is
                        restored, a NMI stackframe is created and the detected
                        freezer called, if there is no freezer nothing will be
                        done, the VBR should be moved by WHDLoad to allow
                        catching the illegal instruction exception (breakpoint)
        PL_GA off,lbl   writes the address of destination+offset to where lbl
                        points to in the slave (get address)

   RESULT
        the function only returns on success

   EXAMPLE
                ...
                lea     (_pl,pc),a0             ;patch list
                lea     ($10000),a1             ;destination
                move.l  (_resload,pc),a2
                jsr     (resload_Patch,a2)
                ...

        _pl1    PL_START
                PL_R    $2046                   ;copylock
                PL_PS   $560,_load              ;replace the loading routine
                PL_P    $1460,_getx             ;provide value x
                PL_S    $696,8                  ;skip 8 bytes
                PL_I    $100                    ;break if reached
                PL_IFC1                         ;if Custom1 option is not null
                PL_B    $3500,$44               ;write byte
                PL_ELSE
                PL_B    $3500,$55               ;write byte
                PL_ENDIF
                PL_IFC2X 3                      ;if Custom2 bit #3 is set
                PL_W    $3510,$4444             ;write word
                PL_ENDIF
                PL_L    $3520,$44444444         ;write long
                PL_A    $20000,$10              ;write #$10010 to $30000
                PL_PA   $500,_data              ;write address _data
                PL_NOP  $3000,$36               ;fill with nops
                PL_NOPS $4000,5                 ;write 5 nops
                PL_C    $30,7000                ;clear 7000 bytes
                PL_CB   $79                     ;clear one byte
                PL_PSS  $8700,_load,4           ;jsr + skip 4 bytes
                PL_NEXT _pl2                    ;goto second patch list

        _load   ...
                rts
        _getx   ...
                rts
        _data   dc.l    0

        _pl2    PL_START
                PL_CL   $90
                PL_AB   $100,'A'                ;add byte
                PL_DATA $350,.stop-.strt
        .strt   move.w  #67,$100                ;write code
                dc.b    2,3,$ff,'x',0           ;write data
        .stop   EVEN                            ;align!
                PL_STR  $90000,<NewString>      ;write a string
                PL_ORB  $710,$55                ;or byte
                PL_GA   $18644,_adr1            ;get the address
                PL_BKPT $5124                   ;set breakpoint
                PL_BELL $9710,50                ;visual bell for 5 seconds
                PL_END

        _adr1   dc.l    0                       ;filled with $28644

   NOTE
        The routine performs automatically a resload_FlushCache before
        returning.
        requires ws_Version >= 10, some patch commands require a more recent
        version of WHDLoad, if WHDLoad encounters unknown patch commands it
        will show a requester

   SEE ALSO
        resload_PatchSeg


WHDLoad/resload_PatchSeg

   NAME
        resload_PatchSeg -- apply patch list to a segment list

   SYNOPSIS
        resload_PatchSeg(patchlist, seglist)
                           A0          A1
                          APTR        BPTR

   FUNCTION
        This function is similar to resload_Patch. But instead of patching a
        memory block at a specific address a segment list will be modified. A
        segment list is list of linked memory regions and usually returned by
        dos.LoadSeg or resload_Relocate with WHDLTAG_LOADSEG.

   INPUTS
        patchlist - list of commands describing the patches to apply, see
                    function resload_Patch for supported commands
        seglist   - list of segments as returned by dos.LoadSeg or
                    resload_Relocate (that is a BCPL pointer!)

   RESULT
        the function only returns on success

   EXAMPLE
                ...
                lea     (_name,pc),a0
                move.l  a0,d1                   ;filename
                move.l  (_dosbase,pc),a6
                jsr     (_LVOLoadSeg,a6)
                lea     (_pl,pc),a0             ;patch list
                move.l  d1,a1                   ;segment list
                move.l  (_resload,pc),a2
                jsr     (resload_PatchSeg,a2)
                ...

        _pl     PL_START
                PL_P    $560,_loadfile          ;the loading routine
                PL_R    $2046                   ;copylock
                PL_END
        _name   dc.b    "program",0

   NOTE
        The routine performs automatically a resload_FlushCache before
        returning.
        requires ws_Version >= 15

   SEE ALSO
        resload_Patch


WHDLoad/resload_ProtectRead

   NAME
        resload_ProtectRead -- mark memory as read protected

   SYNOPSIS
        resload_ProtectRead(length, address)
                              D0      A0
                             ULONG   APTR

   FUNCTION
        Protects the specified memory against reading by the processor.
        The memory to protect must be located inside BaseMem or ExpMem.
        This can be used for debugging to detect accesses to specific memory
        locations.

   INPUTS
        length  - size of the memory area to protect
        address - start address of the memory area to protect
        The area to protect must be located inside the BaseMem or ExpMem.

   RESULT
        An "Exception 'Access Fault'" WHDLoad requester if the protected memory
        has been read.

   EXAMPLE
                ...
                moveq   #4,d0                   ;one longword
                lea     $4070,a0                ;address
                move.l  (_resload,pc),a2
                jsr     (resload_ProtectRead,a2)
                ...

   BUGS
        The amount of protected areas is currently limited to 16.
        The page where the SSP points to must not be protected. Because then
        the CPU will be unable to write the stack frame if an exception occurs.
        Only reset will recover from the resulting Double Bus Fault.
        Limitations on MC68020+MC68851:
          This hardware is currently not supported.
        Limitations on MC68030:
          - 3-byte transfers are not supported (occurring on misaligned
            longword accesses to page boundaries e.g. 'tst.l $fff' (assumed
            4KByte page size))
          - locked accesses (tas/cas/cas2) are not supported
        Limitations on MC68040:
          - instructions which are located on a protected page can read the
            protected area without getting detected because these instructions
            will cause an access fault for the instruction fetch and then get
            executed by the WHDLoad handler without the protection enabled,
            under some conditions this may also happen on writes
          - locked accesses (tas/cas/cas2) are not supported
          - instructions which are located on a protected page and access the
            supervisor portion of the status register will be executed wrong
            (these instructions will always see the trace bit as 1 and the
            interrupt level as 7, any modification of the status register
            supervisor portion will be without effect)
          - movem instructions which read the memory may access a protected
            area without creating a Access Fault exception (only the first bus
            cycle of the execution unit will be verified to match the protected
            area)
          - move16 and double precision operations (FPU) are unsupported
        Limitations on MC68060:
          - instructions which are located on a protected page can access the
            protected area without getting detected because these instructions
            will cause an access fault for the instruction fetch and then get
            executed by the WHDLoad handler without the protection enabled!
          - misaligned access are not supported (occurring on accesses through
            a page boundary, for example 'tst.l ($ffe)' (assumed 4 KByte page
            size))
          - locked accesses (tas/cas) are not supported
          - instructions which are located on a protected page and access the
            supervisor portion of the status register will be executed wrong
            (these instructions will always see the trace bit as 1 and the
            interrupt level as 7, any modification of the status register
            supervisor portion will be without effect)
          - movem instruction may access a protected area without creating a
            Access Fault exception (only the first bus cycle of the execution
            unit will be verified to match the protected area)
          - move16 and double precision operations (FPU) are unsupported
          - a 'move (mem),(mem)' with overlapping source and destination
            address which generates an Access Fault because Misalignment
            will be executed wrong, for example 'move.l ($ffc),($ffe)' where
            page $1000..$1fff is protected and memory before execution
            contains ($ffc)=$11112222,($1000)=$33334444, after execution
            $1000 contains $11114444 and not $22224444)
        Unsupported accesses will result in a "Exception 'Access Fault'"
        WHDLoad requester.

   NOTE
        requires ws_Version >= 6, for the 68040 requires ws_Version >= 18
        The MMU must be in use by WHDLoad, otherwise you will get WHDLoad
        requester 'Unacceptable Arguments'.
        Only accesses to the user and supervisor data stream are affected
        (this means not affected are: CPU space accesses (e.g. getting values
        from the vector table) and instruction stream accesses).

   SEE ALSO
        resload_ProtectReadWrite, resload_ProtectWrite, resload_ProtectRemove


WHDLoad/resload_ProtectReadWrite

   NAME
        resload_ProtectReadWrite -- mark memory as read and write protected

   SYNOPSIS
        resload_ProtectReadWrite(length, address)
                                   D0      A0
                                  ULONG   APTR

   FUNCTION
        Protects the specified memory against reading and writing by the
        processor.
        The memory to protect must be located inside BaseMem or ExpMem.
        This can be used for debugging to detect accesses to specific memory
        locations.

   INPUTS
        length  - size of the memory area to protect
        address - start address of the memory area to protect
        The area to protect must be located inside the BaseMem or ExpMem.

   RESULT
        An "Exception 'Access Fault'" WHDLoad requester if the protected memory
        is accessed.

   EXAMPLE
                ...
                moveq   #4,d0                   ;one longword
                lea     $64,a0                  ;address
                move.l  (_resload,pc),a2
                jsr     (resload_ProtectReadWrite,a2)
                ...

   BUGS
        The amount of protected areas is currently limited to 16.
        The page where the SSP points to must not be protected. Because then
        the CPU will be unable to write the stack frame if an exception occurs.
        Only reset will recover from the resulting Double Bus Fault.
        Limitations on MC68020+MC68851:
          This hardware is currently not supported.
        Limitations on MC68030:
          - 3-byte transfers are not supported (occurring on misaligned
            longword accesses to page boundaries e.g. 'tst.l $fff' (assumed
            4 KByte page size))
          - locked accesses (tas/cas/cas2) are not supported
        Limitations on MC68040:
          - instructions which are located on a protected page can read the
            protected area without getting detected because these instructions
            will cause an access fault for the instruction fetch and then get
            executed by the WHDLoad handler without the protection enabled,
            under some conditions this may also happen on writes
          - locked accesses (tas/cas/cas2) are not supported
          - instructions which are located on a protected page and access the
            supervisor portion of the status register will be executed wrong
            (these instructions will always see the trace bit as 1 and the
            interrupt level as 7, any modification of the status register
            supervisor portion will be without effect)
          - movem instructions which read the memory may access a protected
            area without creating a Access Fault exception (only the first bus
            cycle of the execution unit will be verified to match the protected
            area)
          - move16 and double precision operations (FPU) are unsupported
        Limitations on MC68060:
          - instructions which are located on a protected page can access the
            protected area without getting detected because these instructions
            will cause an access fault for the instruction fetch and then get
            executed by the WHDLoad handler without the protection enabled!
          - misaligned access are not supported (occurring on accesses trough
            a page boundary, for example 'tst.l ($ffe)' (assumed 4 KByte page
            size))
          - locked accesses (tas/cas) are not supported
          - instructions which are located on a protected page and access the
            supervisor portion of the status register will be executed wrong
            (these instructions will always see the trace bit as 1 and the
            interrupt level as 7, any modification of the status register
            supervisor portion will be without effect)
          - movem instruction may access a protected area without creating a
            Access Fault exception (only the first bus cycle of the execution
            unit will be verified to match the protected area)
          - move16 and double precision operations (FPU) are unsupported
          - a 'move (mem),(mem)' with overlapping source and destination
            address which generates an Access Fault because Misalignment
            will be executed wrong, for example 'move.l ($ffc),($ffe)' where
            page $1000..$1fff is protected and memory before execution
            contains ($ffc)=$11112222,($1000)=$33334444, after execution
            $1000 contains $11114444 and not $22224444)
        Unsupported accesses will result in a "Exception 'Access Fault'"
        WHDLoad requester.

   NOTE
        requires ws_Version >= 6, for the 68040 requires ws_Version >= 18
        The MMU must be in use by WHDLoad, otherwise you will get WHDLoad
        requester 'Unacceptable Arguments'.
        Only accesses to the user and supervisor data stream are affected
        (this means not affected are: CPU space accesses (e.g. getting values
        from the vector table) and instruction stream accesses).

   SEE ALSO
        resload_ProtectRead, resload_ProtectWrite, resload_ProtectRemove


WHDLoad/resload_ProtectRemove

   NAME
        resload_ProtectRemove -- remove protection from memory area

   SYNOPSIS
        resload_ProtectRemove(length, address)
                                D0      A0
                               ULONG   APTR

   FUNCTION
        Remove a previously set protection.
        The specified area must exactly match the previously protected area.

   INPUTS
        length  - size of the memory area to protect
        address - start address of the memory area to protect

   RESULT
        the function only returns on success

   EXAMPLE
                ...
                moveq   #4,d0                   ;one longword
                lea     $64,a0                  ;address
                move.l  (_resload,pc),a2
                jsr     (resload_ProtectRemove,a2)
                ...

   NOTE
        requires ws_Version >= 6

   SEE ALSO
        resload_ProtectRead, resload_ProtectWrite, resload_ProtectWrite


WHDLoad/resload_ProtectSMC

   NAME
        resload_ProtectSMC -- detect self modifying code

   SYNOPSIS
        resload_ProtectSMC(length, address)
                             D0      A0
                            ULONG   APTR

   FUNCTION
        Enables automatic detection of self modifying code (SMC) in the
        selected area. The selected area will be write protected using the
        resload_ProtectWrite mechanism. Additional the trace mode will be
        activated and a special handler for trace exceptions installed.
        Each write access to the selected area will be logged to a private
        memory location. On each instruction executed inside the selected
        memory the trace handler verifies, if the instruction has been
        previously modified. If an executed instruction has been altered
        the installed program will be terminated and WHDLoad will show an
        requester informing about the SMC-detection.

        To determine the size of an instructions a table is used. This table
        contains the opcode size in words depending on the first instruction
        word. If the trace exception handler encounters a instruction with an
        unknown size WHDLoad will abort displaying 'Internal Error #3'. The
        reason for this may be an illegal instruction, an instruction available
        only in higher processors than 68000 or an incompleteness of the
        internal instruction size table (IST). To check the reason make a
        coredump and see which instruction has caused the problem (the
        instruction before the actual PC because trace exception occurs after
        the execution of the traced instruction). Depending on the reason you
        can aid this:
        - If it is an illegal instruction you have to fix the installed
          program by patching its code.
        - If it's caused by a 68020+ instruction we have a problem, because
          the IST is designed for 68000 instructions only, where the size of a
          instruction can be estimated by the first word and the largest
          possible instruction is 5 words. If the instruction size can be
          estimated by the first word you may add the instruction to a own
          IST (see below).
        - If it is a valid 68000 instruction please inform the WHDLoad
          author that he adds this instruction to the default IST inside
          WHDLoad. For the moment you may add this instruction to an own
          IST (see below)
        Using an own IST: During the initialization of this function
        WHDLoad searches first for an external IST. This external IST must be
        located in the same directory where the WHDLoad executable resides and
        is searched as 'PROGDIR:WHDLoad.IST'. If there is no external IST the
        internal one is used. The assembler source of the internal IST is
        included in the developer archive and can be used to build a external
        IST.

        Due the large exception overhead the execution speed in the selected
        area will considerable slow down. To improve performance it is
        therefore recommend to relocate the SSP to a Fast-Memory location using
        ws_ExpMem and an appropriate initialistion and modification of the
        installed program.
        To maximize performance when using this facility already during the
        initialization of this function the BaseMem area will be set to NC, the
        ExpMem and Slave to CB and all caches will be enabled (resload_SetCPU).

   INPUTS
        length  - size of the memory area to protect
        address - start address of the memory area to protect
        The area to protect must be located inside the BaseMem or ExpMem.

   RESULT
        A "SMC detected" WHDLoad requester if previously modified memory is
        tried to execute.

   EXAMPLE
        enable SMC-detection for the area $10000..$3e000:
                ...
                move.l  #$2e000,d0              ;length
                lea     $10000,a0               ;address
                move.l  (_resload,pc),a2
                jsr     (resload_ProtectSMC,a2)
                ...

   BUGS
        Currently supported is the 68030-68060. For limitations and
        restrictions regarding the MMU related part of operation see the BUGS
        section of resload_ProtectWrite.
        You must not protect the page where the SSP points to, if you do so
        an Double Bus Fault will occur because the CPU will be unable to
        write the exception stack frame. Only reset will recover from a Double
        Bus Fault.

   NOTE
        requires ws_Version >= 10
        The MMU must be in use by WHDLoad, otherwise you will get WHDLoad
        requester 'Unacceptable Arguments'.
        There must be no other resload_Protect* active at the same time.

   SEE ALSO
        resload_ProtectWrite, resload_SetCPU


WHDLoad/resload_ProtectWrite

   NAME
        resload_ProtectWrite -- mark memory as write protected

   SYNOPSIS
        resload_ProtectWrite(length, address)
                               D0      A0
                              ULONG   APTR

   FUNCTION
        Protects the selected area against writing by the processor.
        The area to protect must be located inside BaseMem or ExpMem.
        This can be used for debugging to detect accesses to specific memory
        locations.

   INPUTS
        length  - size of the memory area to protect
        address - start address of the memory area to protect
        The area to protect must be located inside the BaseMem or ExpMem.

   RESULT
        An "Exception 'Access Fault'" WHDLoad requester if the protected memory
        is written.

   EXAMPLE
                ...
                moveq   #4,d0                   ;one longword
                lea     $64,a0                  ;address
                move.l  (_resload,pc),a2
                jsr     (resload_ProtectWrite,a2)
                ...

   BUGS
        The amount of protected areas is currently limited to 16.
        The page where the SSP points to must not be protected. Because then
        the CPU will be unable to write the stack frame if an exception occurs.
        Only reset will recover from the resulting Double Bus Fault.
        limitations on MC68020+MC68851:
          This hardware is currently not supported.
        limitations on MC68030:
          - 3-byte transfers are not supported (occurring on misaligned
            longword accesses to page boundaries e.g. 'tst.l $fff' (assumed
            4 KByte page size))
          - locked accesses (tas/cas/cas2) are not supported
        limitations on MC68040:
          - locked accesses (tas/cas/cas2) are not supported
          - move16 and double precision operations (FPU) are unsupported
        limitations on MC68060:
          - misaligned access are not supported (occurring on accesses trough
            a page boundary, for example 'tst.l ($ffe)' (assumed 4 KByte page
            size))
          - locked accesses (tas/cas) are not supported
          - instructions which are located on a protected page and access the
            supervisor portion of the status register will be executed wrong
            (these instructions will always see the trace bit as 1 and the
            interrupt level as 7, any modification of the status register
            supervisor portion will be without effect)
          - movem instruction may access a protected area without creating a
            Access Fault exception (only the first bus cycle of the execution
            unit will be verified to match the protected area)
          - move16 and double precision operations (FPU) are unsupported
          - a 'move (mem),(mem)' with overlapping source and destination
            address which generates an Access Fault because Misalignment
            will be executed wrong, for example 'move.l ($ffc),($ffe)' where
            page $1000..$1fff is protected and memory before execution
            contains ($ffc)=$11112222,($1000)=$33334444, after execution
            $1000 contains $11114444 and not $22224444)
        Unsupported accesses will result in a "Exception 'Access Fault'"
        WHDLoad requester.

   NOTE
        requires ws_Version >= 6, for the 68040 requires ws_Version >= 18
        The MMU must be in use by WHDLoad, otherwise you will get WHDLoad
        requester 'Unacceptable Arguments'.
        Only accesses to the user and supervisor data stream are affected
        (this means not affected are: CPU space accesses (e.g. getting values
        from the vector table) and instruction stream accesses).

   SEE ALSO
        resload_ProtectRead, resload_ProtectReadWrite, resload_ProtectRemove


WHDLoad/resload_ReadJoyPort

   NAME
        resload_ReadJoyPort -- return the state of the selected joy/mouse port

   SYNOPSIS
        state = resload_ReadJoyPort(flags)
         D0                          D0
        ULONG                       ULONG

   FUNCTION
        Gets the uncompressed size of a packed file (checks if a file exists).
        The routine knows about the same decrunchers as resload_Decrunch.
        To distinguish between a file with a size of 0 and a nonexistent
        file the tag WHDLTAG_IOERR_GET must be used in conjunction with
        resload_Control afterwards.

   INPUTS
        flags - port to read, in the range 0 to 3 plus optional flags
                possible flags are:
                RJPF_Detect - detect connected device, returned is the state
                        with all supported buttons pressed

   RESULT
        state - controller type and state:
                bit #31-28: type of controller
                        1 = joypad
                        2 = mouse
                        3 = joystick
                #23 = RJP_BLUE pad-blue/stop, mouse-right, stick-2nd-fire
                #22 = RJP_RED pad-red/select, mouse-left, stick-fire
                #21 = RJP_YELLOW pad-yellow/repeat
                #20 = RJP_GREEN pad-green/shuffle
                #19 = RJP_FORWARD pad-forward
                #18 = RJP_REVERSE pad-reverse
                #17 = RJP_PLAY pad-play/pause, mouse-middle

   EXAMPLE
                ...
                moveq   #0,d0
                move.l  (_resload,pc),a2
                jsr     (resload_ReadJoyPort,a2)
                btst    #,d0
                ...

   NOTE
        requires ws_Version >= 19


WHDLoad/resload_Relocate

   NAME
        resload_Relocate -- relocate an AmigaDOS executable

   SYNOPSIS
        size = resload_Relocate(address, tags)
         D0                       A0      A1
        ULONG                    APTR   STRUCT

   FUNCTION
        Relocates a standard AmigaDOS executable in memory. By default the
        excutable will be relocated over itself using a multi pass technique.

   INPUTS
        address - the start address of the executable in memory, this is the
                  source and also the destination address, i.e.
                  resload_Relocate will relocates the executable over itself
        tags    - there are two valid tags starting WHDLoad version 14.1
                  WHDLTAG_CHIPPTR - specifies a extra memory location where
                    to put hunks with the memory flag MEMF_CHIP
                  WHDLTAG_FASTPTR - specifies a extra memory location where
                    to put hunks with the memory flag MEMF_FAST
                  the different memory locations must not overlap, WHDLoad
                  will check that and report 'illegal args' if they do
                  starting WHDLoad version 15.1 there is another tag:
                  WHDLTAG_ALIGN - it specifies an alignment for the hunks,
                    the number given must be an positive integer which is
                    a power of 2, all hunk lengths will be rounded up to
                    a multiple of this value, useful is 8 to be compatible
                    with exec.AllocMem used by dos.LoadSeg
                  starting WHDLoad version 16.3 there is another tag:
                  WHDLTAG_LOADSEG - if specified the function creates a
                    segment list as if loaded via dos.LoadSeg,
                    resload_PatchSeg can be used to modify the relocated
                    segment list

   RESULT
        size - size of the relocated executable
               (this may be more or less than the size of the executable,
               depending on the presence and size of BSS hunks)
               if WHDLTAG_CHIPPTR or WHDLTAG_FASTPTR is used the returned size
               excludes the size of the hunks relocated to different memory
               destinations
        tags - for WHDLTAG_CHIPPTR and WHDLTAG_FASTPTR the ti_Data field will
               be overwritten with the length of data stored in this area
        the function only returns on success

   EXAMPLE
        simply relocate a executable over itself
                ...
                lea     (_main,pc),a0           ;name
                lea     $400,a3                 ;A3 = address for program
                move.l  a3,a1                   ;destination
                move.l  (_resload,pc),a2
                jsr     (resload_LoadFileDecrunch,a2)
                move.l  a3,a0                   ;address
                sub.l   a1,a1                   ;tags
                jsr     (resload_Relocate,a2)
                ...
                jmp     (a3)                    ;start the program
                ...

        _main   dc.b    "main-program",0

        the executable is loaded to ExpMem, but the CHIP hunks will be
        relocated to BaseMem, also align like dos.LoadSeg/exec.AllocMem
                ...
                move.l  (_freefast),a0          ;address of executable
                clr.l   -(a7)                   ;TAG_DONE
                move.l  (_freechip),-(a7)       ;chip area
                pea     WHDLTAG_CHIPPTR
                pea     8                       ;8 byte alignment
                pea     WHDLTAG_ALIGN
                move.l  a7,a1                   ;tags
                move.l  (_resload,pc),a2
                jsr     (resload_Relocate,a2)
                add.l   d0,(_freefast)
                add.l   (12,a7),(_freechip)
                add.w   #20,a7
                ...

        use segment lists and resload_PatchSeg
                ...
                move.l  (_freemem),a0           ;address
                clr.l   -(a7)                   ;TAG_DONE
                pea     -1                      ;true
                pea     WHDLTAG_LOADSEG
                pea     8                       ;8 byte alignment
                pea     WHDLTAG_ALIGN
                move.l  a7,a1                   ;tags
                move.l  (_resload,pc),a2
                jsr     (resload_Relocate,a2)
                add.w   #5*4,a7
                lea     (_patchlist),a0
                move.l  (_freemem),d0
                addq.l  #4,d0                   ;segment starts at offset 4
                lsr.l   #2,d0                   ;make BPTR
                move.l  d0,a1
                jsr     (resload_PatchSeg,a2)
                ...

   BUGS
        The routine supports all hunks supported by Kickstart 1.3 except
        OVERLAY. Anyway it is only tested with a limited amount of
        executables, please report any problems or bugs.

   NOTE
        requires ws_Version >= 8
        The function uses several stack for variables. The amount depends on
        the number of hunks in the executable and can be calculated as
        'used stack = hunks * 20 + 40'.
        Upto WHDLoad version 16.9 the executable must not contain more than 256
        hunks. Starting WHDLoad version 17.0 512 hunks are supported. Beware of
        the stack space, for 512 hunks more than 10 KiB stack are required.
        The routine performs automatically a resload_FlushCache before
        returning.

   SEE ALSO
        resload_Patch, resload_PatchSeg


WHDLoad/resload_SaveFile

   NAME
        resload_SaveFile -- write memory to a file

   SYNOPSIS
        success,errorcode = resload_SaveFile(size, name, address)
          D0       D1                         D0    A0      A1
         BOOL     ULONG                     ULONG  CPTR    APTR

   FUNCTION
        Writes specified memory area to a file using the specified file name.
        If multiple data directories are used the file will be created
        always in the first data directory. Possible missing sub directories
        are only created by WHDLoad if the option SavePath/S is in use.

   INPUTS
        size    - amount of bytes to write
        name    - name of file to write
        address - memory address of buffer to write

   RESULT
        success   - TRUE on success
        errorcode - 0 on success
                    otherwise a DOS error code from dos.IoErr()
        If WHDLF_NoError is set, the function only returns on success.

   EXAMPLE
                ...
                move.l  #512,d0                 ;size
                lea     (_save,pc),a0           ;name
                lea     $5ac20,a1               ;source
                move.l  (_resload,pc),a2
                jsr     (resload_SaveFile,a2)
                ...
        _save   dc.b    "saved",0

   SEE ALSO
        resload_SaveFileOffset


WHDLoad/resload_SaveFileOffset

   NAME
        resload_SaveFileOffset -- write memory to a file at given offset

   SYNOPSIS
        success,error = resload_SaveFileOffset(size, offset, name, address)
          D0     D1                             D0     D1     A0      A1
         BOOL   ULONG                          ULONG  ULONG  CPTR    APTR

   FUNCTION
        Writes specified memory area to a file at specified offset using the
        specified file name.
        If the file does previously not exist or is shorter than the given
        offset the missing space before the write is filled with the
        character $DD.
        If multiple data directories are used always the file in the first
        data directory will be written. If the file exist in an other data
        directory than the first it will be copied to the first directory
        before performing the save operation.
        Possible missing sub directories are only created by WHDLoad if the
        option SavePath/S is in use.

   INPUTS
        size    - amount of bytes to write
        offset  - offset in the file to write
        name    - name of file to write
        address - memory address of buffer to write

   RESULT
        success   - TRUE on success
        errorcode - 0 on success
                    otherwise a DOS error code from dos.IoErr()
        If WHDLF_NoError is set, the function only returns on success.

   EXAMPLE
                ...
                move.l  #512,d0                 ;size
                move.l  #$4000,d1               ;offset
                lea     (_save,pc),a0           ;name
                lea     $5ac20,a1               ;source
                move.l  (_resload,pc),a2
                jsr     (resload_SaveFileOffset,a2)
                ...

        _save   dc.b    "saved",0

   NOTE
        requires ws_Version >= 5

   SEE ALSO
        resload_SaveFile


WHDLoad/resload_SetCACR

   NAME
        resload_SetCACR -- set cacheability for BaseMem

   SYNOPSIS
        old = resload_SetCACR(new, mask)
         D0                    D0   D1
       ULONG                 ULONG ULONG

   FUNCTION
        This function enables/disables the CPU caches.
        The changes will affect the CACR (Cache Control Register) and
        the MMU-tables if the MMU is used by WHDLoad.

   INPUTS
        new  - new cache status
        mask - status bits to change
        valid values for new and mask are:
                CACRF_EnableI - instruction cache
                CACRF_EnableD - data cache
        (bits are defined in the NDK include file 'exec/execbase.i')

   RESULT
        old - old cache status

   EXAMPLE
        to enable instruction cache:
                ...
                move.l  #CACRF_EnableI,d0       ;new status
                move.l  d0,d1                   ;status to change
                move.l  (_resload,pc),a2
                jsr     (resload_SetCACR,a2)
                ...

   NOTE
        It is safe to call this routine from User or Supervisor mode and
        independent from the actual CPU type (also on 68000/010).
        If WHDLoad is launched with the option NoCache/S this routine will
        return without changing anything (all memory is always noncacheable).
        Don't be surprised if you see in the coredump or in a freezer that
        caches are enabled even if not enabled by the Slave. Because if the
        MMU is used by WHDLoad and no caches are switched on by the Slave,
        WHDLoad marks the BaseMem using the MMU as noncacheable-serialized
        and enables both caches so that the memory of WHDLoad and the Slave
        are still cacheable to increase the performance.
        The caches are flushed after returning from this routine.
        This routine internal calls resload_SetCPU.

   SEE ALSO
        resload_SetCPU, resload_FlushCache


WHDLoad/resload_SetCPU

   NAME
        resload_SetCPU -- control CPU setup

   SYNOPSIS
        old = resload_SetCPU(new, mask)
         D0                   D0   D1
       ULONG                ULONG ULONG

   FUNCTION
        This function changes the cacheability of memory areas and changes the
        CPU setup. It is possible to set the memory of BaseMem, ExpMem and the
        Slave. Also specific caches can be set.
        The changes will affect the CACR (Cache Control Register) on 68020-60,
        the PCR (Processor Configuration Register) on 68060 and the MMU-tables
        if the MMU is used by WHDLoad.
        Check the WHDLoad manual section 'CPU Cache Handling' for further
        information. See the include file 'whdload.i' for supported bit sets.

   INPUTS
        new  - new setup
        mask - parts of the current setup to change

   RESULT
        old - the setup before

   EXAMPLE
        to enable the only instruction cache for BaseMem and ExpMem:
                ...
                move.l  #WCPUF_Base_WT|WCPUF_Exp_CB|WCPUF_IC,d0
                move.l  #WCPUF_Base|WCPUF_Exp|WCPUF_IC|WCPUF_DC,d1
                move.l  (_resload,pc),a2
                jsr     (resload_SetCPU,a2)
                ...

   NOTE
        requires ws_Version >= 10
        It is safe to call this routine from User or Supervisor mode and
        independent from the actual CPU type (also on 68000/010).
        If WHDLoad is launched with the option NoCache/S this routine will
        return without changing anything (all memory is always noncacheable).
        Don't be surprised if you see in the coredump or in a freezer that
        caches are enabled even if not enabled by the Slave. Because if the
        MMU is used by WHDLoad and caches are disabled by the Slave,
        WHDLoad marks the memory using the MMU as noncacheable-serialized
        and enables both caches so that the memory of WHDLoad is still
        cacheable to increase the performance.
        The caches are flushed after returning from this routine.

   SEE ALSO


WHDLoad/resload_VSNPrintF

   NAME
        resload_VSNPrintF -- format data into a character stream

   SYNOPSIS
        length,end = resload_VSNPrintF(buflen, buffer, format, data stream)
          D0   A0                        D0      A0      A1        A2
        ULONG CPTR                     ULONG    APTR    CPTR      APTR

   FUNCTION
        This function performs a exec.RawDoFmt/C.sprintf-like formatting of
        data stream values according to the provided format string. Where %
        formatting commands found in the format string are replaced with the
        corresponding elements in the data stream. %% must be used in the
        format string if a % is desired in the output.
        Formatting commands have the form:

        %[flags][width][.limit][length]type

        flags  - supported flags are:
                 '0' zero padding; the converted value is padded with zeros
                     rather than blanks
                 '-' negative field with; converted value is to be left
                     adjusted on the filed boundary, a '-' overrides a '0' if
                     both are given
        width  - field width; if the converted value has fewer characters
                 than the field width, it will be padded with spaces on the
                 left to fill out the field width
        limit  - maximum number of characters to output from a string (only
                 valid for %s)
        length - length modifier; specifies size of the data value from the
                 data stream, defaults to WORD for types d, x and c, 'l'
                 changes this to long (32-bit)
        type   - supported types are:
                 'b' - BSTR, 32-bit BPTR to byte count followed by a byte
                       string, or NULL terminated byte string
                       a NULL BPTR is treated as an empty string
                 'B' - BPTR, BCPL pointer, 32-bit value * 4 will by printed
                       hexadecimal
                 'd' - decimal
                 'u' - unsigned decimal
                 'x' - hexadecimal
                 's' - string, a 32-bit pointer to a NULL terminated byte
                       string. a NULL pointer is treated as an empty string
                 'c' - single character (WORD)

   INPUTS
        buflen - length of the provided buffer
        buffer - buffer to fill with the character stream
        format - string containing formatting options using the % char
        data stream - a stream of values (WORDs/LONGs) which are interpreted
                according to the format string

   RESULT
        length - the amount of characters which would have been written to the
                 buffer in case the buffer length were unlimited, not
                 including the final '\0' character
        end    - points to the final '\0' character written to the buffer (if
                 buflen>0)

   EXAMPLE
        Format a single number:
                ...
                lea     (_buf,pc),a0            ;buffer
                moveq   #80,d0                  ;buffer length
                lea     (_fmt,pc),a1            ;format
                lea     (_val,pc),a2
                move.l  (_resload,pc),a6
                jsr     (resload_VSNPrintF,a6)
                ...
        _val    dc.w    842
        _fmt    dc.b    "NumberDecimal=%d",0
        _buf    ds.b    80
                ...
        Format a text message containing some variables on the stack:
                ...
                lea     (_fmt,pc),a1            ;format
                move.l  (_adr,pc),-(a7)         ;put vars on stack, last first
                pea     (_nam2,pc)
                move.l  (_seq,pc),-(a7)
                move.l  a7,a2                   ;arguments
                moveq   #200,d0                 ;buffer length
                sub.l   d0,a7                   ;reserve buffer on stack
                move.l  a7,a0                   ;buffer
                move.l  (_resload,pc),a6
                jsr     (resload_VSNPrintF,a6)
                move.l  a7,a0
                jsr     (_DoSomethingWithStringA0)
                add.w   #212,a7                 ;free vars and buffer
                ...
        _fmt    dc.b    "[%04ld] %s=$%lx",0
                ...

   NOTE
        requires ws_Version >= 18

   SEE ALSO


WHDLoad.Slave/--Overview--

The WHDLoad.Slave contains the interface code which makes the installed
program able to load his files from harddisk. Additional it should provide
a possibility to quit the program to return to the OS.

   FORMAT
        Is a standard AmigaDOS executable. But:
        The Slave MUST consist of only ONE hunk (ONE section).
        The Slave MUST be 100% PC-relative (must not contain relocations).
        It may contain debug/symbol hunks which are ignored.

   STRUCTURE
        At the beginning of the Slave is the 'WHDLoadSlave' structure. After
        it follows the specific code and data.

             STRUCTURE  WHDLoadSlave,0
                STRUCT  ws_Security,4
                STRUCT  ws_ID,8
                UWORD   ws_Version
                UWORD   ws_Flags
                ULONG   ws_BaseMemSize
                ULONG   ws_ExecInstall
                RPTR    ws_GameLoader
                RPTR    ws_CurrentDir
                RPTR    ws_DontCache
             (  LABEL   ws_SIZEOF_pre_v4  )
                UBYTE   ws_keydebug
                UBYTE   ws_keyexit
             (  LABEL   ws_SIZEOF_pre_v8  )
                ULONG   ws_ExpMem
             (  LABEL   ws_SIZEOF_pre_v10 )
                RPTR    ws_name
                RPTR    ws_copy
                RPTR    ws_info
             (  LABEL   ws_SIZEOF_pre_v16 )
                RPTR    ws_kickname
                ULONG   ws_kicksize
                UWORD   ws_kickcrc
             (  LABEL   ws_SIZEOF_pre_v17 )
                RPTR    ws_config
                LABEL   ws_SIZEOF

        ws_Security
                Contains the code
                        moveq #-1,d0
                        rts
                to avoid problems if someone executes the Slave directly.

        ws_ID
                Contains the string 'WHDLOADS' to identify the program as a
                WHDLoad Slave.

        (the macro SLAVE_HEADER defined in the include file 'whdload.i' can be
        used to create the entries ws_Security and ws_ID)

        ws_Version
                Contains the version of WHDLoad that is required by the Slave.
                Some resload functions need at least a specific version of
                WHDLoad. E.g. to use resload_CRC16 you must set ws_Version
                to 3 or higher.
                On the other side the size of the WHDLoad Slave structure
                differs for different Slave versions. I.e. if you set
                ws_Version to 16 or higher you MUST also initialize the fields
                up to ws_kickcrc (even if you don't use a Kickstart image).

        ws_Flags
                WHDLF_Disk / WHDLB_Disk
                   This flag should be enabled if the program uses disk images.
                   As a result Preload/S is working slightly different.
                   (starting WHDLoad 0.143 this flag is obsolete and ignored)
                WHDLF_NoError / WHDLB_NoError
                   If enabled every error occurring in a resload_#? function
                   forces WHDLoad to quit immediately and showing an error
                   requester about the reason.
                   Using this flag makes it unnecessary for the Slave to check
                   the return codes of resload_#? functions. The Slave can then
                   be sure that if a function returns it was successful which
                   simplifies the Slave code.
                WHDLF_EmulTrap / WHDLB_EmulTrap
                   This flag has an effect only if the VBR is moved by WHDLoad
                   (i.e. the machine is at least a 68010 and the tooltype
                   NoVBRMove is not set).
                   If the flag is set all 'Trap #0..15's are emulated by the
                   exception handler inside WHDLoad. I.e. the handler checks
                   if the appropriate trap vector ($80-$bc) is initialized,
                   and if the routine at the vector address will be called by
                   WHDLoad.
                WHDLF_NoDivZero / WHDLB_NoDivZero
                   This flag has an effect only if the VBR is moved by WHDLoad
                   (i.e. the machine is at least a 68010 and the tooltype
                   NoVBRMove is not set).
                   If the flag is set and a 'Division by Zero' exception
                   occurs WHDLoad will not quit with an requester, but perform
                   a RTE.
                   This maybe useful if the demo/game creates randomly
                   divisions by zero.
                WHDLF_Req68020 / WHDLB_Req68020
                   This flag indicates that the Slave/installed program
                   requires at least a MC68020 CPU. WHDLoad will check at the
                   startup if this requirement is fulfilled. If it doesn't the
                   program will be terminated with an appropriate requester.
                WHDLF_ReqAGA / WHDLB_ReqAGA
                   This flag indicates that the Slave/installed program
                   requires at least the AGA chipset. WHDLoad will check at the
                   startup if this requirement is fulfilled. If it doesn't the
                   program will be terminated with an appropriate requester.
                WHDLF_NoKbd / WHDLB_NoKbd
                   This flag tells WHDLoad that it doesn't should acknowledge
                   the keyboard if a key was pressed. This must be used with
                   programs which doesn't check the keyboard from the PORTS
                   interrupt ($68). Background information: In normal
                   operation when NoVBRMove is inactive, WHDLoad checks if a
                   key was pressed on each interrupt. If a key has been
                   pressed it checks the rawkey code against QuitKey, DebugKey
                   and FreezeKey. If it doesn't match any of them it checks if
                   there is an initialized PORTS interrupt ($68). If there is
                   no one it replies the keyboard that the keycode has been
                   received. Therefore when the installed program later checks
                   the keyboard from e.g. the VBI, it will never receive any
                   keycodes. This flag avoids the keyboard acknowledge done by
                   WHDLoad.
                WHDLF_EmulLineA / WHDLB_EmulLineA
                   This flag has an effect only if the VBR is moved by WHDLoad
                   (i.e. the machine is at least a 68010 and the tooltype
                   NoVBRMove is not set).
                   If the flag is set all exceptions 'Line-A' (caused by
                   opcodes starting with %1010) are emulated by the
                   exception handler inside WHDLoad. I.e. the handler checks
                   if the vector ($28) is initialized and if the routine to
                   which the vector points will be called by WHDLoad.
                WHDLF_EmulTrapV / WHDLB_EmulTrapV
                   This flag has an effect only if the VBR is moved by WHDLoad
                   (i.e. the machine is at least a 68010 and the tooltype
                   NoVBRMove is not set).
                   If the flag is set all exceptions caused by a 'TrapV'
                   instruction are emulated by the exception handler inside
                   WHDLoad. I.e. the handler checks if the vector ($1C) is
                   initialized and if the routine to which the vector points
                   will be called by WHDLoad.
                WHDLF_EmulChk / WHDLB_EmulChk
                   This flag has an effect only if the VBR is moved by WHDLoad
                   (i.e. the machine is at least a 68010 and the tooltype
                   NoVBRMove is not set).
                   If the flag is set all exceptions caused by a 'Chk/Chk2'
                   instruction are emulated by the exception handler inside
                   WHDLoad. I.e. the handler checks if the vector ($18) is
                   initialized and if the routine to which the vector points
                   will be called by WHDLoad.
                WHDLF_EmulPriv / WHDLB_EmulPriv
                   This flag has an effect only if the VBR is moved by WHDLoad
                   (i.e. the machine is at least a 68010 and the tooltype
                   NoVBRMove is not set).
                   If the flag is set all privilege violation exceptions are
                   emulated by the exception handler inside WHDLoad. I.e. the
                   handler checks if the vector ($20) is initialized and if
                   the routine to which the vector points will be called by
                   WHDLoad.
                WHDLF_EmulLineF / WHDLB_EmulLineF
                   This flag has an effect only if the VBR is moved by WHDLoad
                   (i.e. the machine is at least a 68010 and the tooltype
                   NoVBRMove is not set).
                   If the flag is set all exceptions 'Line-F' (caused by
                   opcodes starting with %1111) are emulated by the
                   exception handler inside WHDLoad. I.e. the handler checks
                   if the vector ($2C) is initialized and if the routine to
                   which the vector points will be called by WHDLoad.
                WHDLF_ClearMem / WHDLB_ClearMem
                   If that flag is set WHDLoad will not init BaseMem with the
                   pattern $CCCCCCCC and ExpMem with $DDDDDDDD but simply
                   clear these memories.
                WHDLF_Examine / WHDLB_Examine
                   This flag must be set if the functions
                   resload_Examine/ExNext will be used. It causes WHDLoad to
                   cache information about all files and directories. This
                   consumes memory and takes time at startup. Therefore it
                   shouldn't be used without necessity.
                WHDLF_EmulDivZero / WHDLB_EmulDivZero
                   This flag has an effect only if the VBR is moved by WHDLoad
                   (i.e. the machine is at least a 68010 and the tooltype
                   NoVBRMove is not set).
                   If the flag is set all division by zero exceptions are
                   emulated by the exception handler inside WHDLoad. I.e. the
                   handler checks if the vector ($14) is initialized and if
                   the routine to which the vector points to will be called by
                   WHDLoad.
                   This flag has precedence over the flag NoDivZero.
                WHDLF_EmulIllegal / WHDLB_EmulIllegal
                   This flag has an effect only if the VBR is moved by WHDLoad
                   (i.e. the machine is at least a 68010 and the tooltype
                   NoVBRMove is not set).
                   If the flag is set all illegal instruction exceptions are
                   emulated by the exception handler inside WHDLoad. I.e. the
                   handler checks if the vector ($10) is initialized and if
                   the routine to which the vector points will be called by
                   WHDLoad.

        ws_BaseMemSize
                The size of the memory that is required by the program.
                The BaseMemory starts at $00000000 and ends at ws_BaseMemSize.
                BaseMemory is always ChipMem.
                This value must be multiple of $1000.
                The valid minimum is $2000 and the maximum is $200000.

        ws_ExecInstall
                obsolete, must be set to 0

        ws_GameLoader
                A relative (to the start of the structure) 16-bit pointer
                to the start code of the Slave. This is the entry point of the
                Slave code.

        ws_CurrentDir
                A relative (to the start of the structure) 16-bit pointer
                to a 0 terminated string which is the name of the path
                where all files are stored (sub directory).
                If no sub directory should be used this must be initialized
                with 0.
                The path to the sub directory must be relative (must not
                contain ':').

        ws_DontCache
                A relative (to the start of the structure) 16-bit pointer
                to a 0 terminated string which is a standard AmigaDOS
                pattern (dos.ParsePattern, dos.MatchPattern).
                All files matching this pattern will not by cached by WHDLoad.
                If not in use it must be set to 0.

      The following variables are only evaluated by WHDLoad if ws_Version
      is set to >= 4. The following variables MUST be initialized if you set
      ws_Version to >= 4.

        ws_keydebug
                The raw key code to exit with writing debug files.
                This variable will be overwritten by WHDLoad using the value
                specified with the option DebugKey/K/N if set.
                If the Slave provides an own handler to support a debug option
                via the keyboard it should use this value for comparison. So
                it will be possible for the user to change the key suggested
                by the Slave.
                WHDLoad itself also checks for this key code on each interrupt
                if the VBR is moved (requires 68010+ and that NoVBRMove/S is
                not set).
                If this variable is set to 0 the WHDLoad default will be used.
                Starting WHDLoad version 17.0 the contents of this variable
                is ignored. It is always overwritten by WHDLoad with the
                default or the specified DebugKey/K/N.
                The recommended value is 0.

        ws_keyexit
                The raw key code to exit.
                This variable will be overwritten by WHDLoad using the value
                specified with the option QuitKey/K/N if set.
                If the Slave provides an own handler to support a quit option
                via the keyboard it should use this value for comparison. So
                it will be possible to the user to change the key suggested
                by the Slave.
                WHDLoad itself also checks for this key code on each interrupt
                if the VBR is moved (requires 68010+ and that NoVBRMove/S is
                not set).
                The recommended value is $59 = 'F10'.

      The following variables are only evaluated by WHDLoad if ws_Version
      is set to >= 8. The following variables MUST be initialized if you set
      ws_Version to >= 8.

        ws_ExpMem
                If the installed program requires expansion memory, the size
                must be specified here. WHDLoad will allocate a memory block
                of this size and writes a pointer to the start of the
                allocated memory back to this entry. The memory is granted to
                be aligned to $1000 (4096 bytes). The size specified must be
                a multiple of $1000 (4096). If WHDLoad fails to allocate
                this memory it terminates with an appropriate error requester.
                That means the Slave will always get a valid pointer here.
                Starting WHDLoad version 10.2 the value can be negative. A
                negative size means that the memory is optional and not
                required. WHDLoad will try to allocate it and if it fails it
                will set ws_ExpMem to zero. Therefore the Slave has to check
                the contents of ws_ExpMem.

      The following variables are only evaluated by WHDLoad if ws_Version
      is set to >= 10. The following variables MUST be initialized if you set
      ws_Version to >= 10.

        ws_name
                A relative (to the start of the structure) 16-bit pointer
                to a 0 terminated string containing the name of the installed
                program. e.g. 'Super Hang Off'.
                The name is used in the splash window and in conjunction with
                the SavePath/K feature.

        ws_copy
                A relative (to the start of the structure) 16-bit pointer
                to a 0 terminated string containing the copyright of the
                installed program. The string should start with the year
                followed by the companies holding the copyright. Multiple years
                or companies should be separated with ', '.
                e.g. '1983 Schega, 1989 Bad Dreams'
                The copyright is displayed in the splash window.

        ws_info
                A relative (to the start of the structure) 16-bit pointer
                to a 0 terminated string containing additional infos about the
                installed program. The string may also contain line feeds
                ($0a). The character -1 has a special meaning. It results in
                a line feed and an additional vertical skip of the half font
                height. e.g.:
                        dc.b    "installed & fixed by Wepl",10
                        dc.b    "version 1.4 (06.06.2066)",-1
                        dc.b    "greetings to the world",0
                The infos are displayed in the splash window.

      The following variables are only evaluated by WHDLoad if ws_Version
      is set to >= 16. The following variables MUST be initialized if you set
      ws_Version to >= 16.

        ws_kickname
                A relative (to the start of the structure) 16-bit pointer
                to a 0 terminated string containing the name of the Kickstart
                image to be loaded by WHDLoad into ExpMem. The path
                'DEVS:Kickstarts/' will be prepended by WHDLoad to find the
                file. The name should be something like  'kick34005.A500'.

        ws_kicksize
                The size of the Kickstart image to load.

        ws_kickcrc
                The CRC16 checksum for the Kickstart image to load.

        Starting WHDLoad 16.1 there is a special mode which supports multiple
        Kickstart images within the same Slave. The special mode is activated
        by using -1 as the value for ws_kickcrc. ws_kickname contains then a
        relative pointer to a table which contains pairs of CRC16 and relative
        pointers to a Kickstart name. The table is terminated with a CRC16 of
        0. WHDLoad will try to load Kickstarts from the table until it finds
        one with the correct CRC16. After the successful load the CRC16 of the
        loaded Kickstart image will be placed in ws_kickcrc (overwriting the
        -1) so the Slave can recognize which Kickstart image has been loaded.

      The following variables are only evaluated by WHDLoad if ws_Version
      is set to >= 17. The following variables MUST be initialized if you set
      ws_Version to >= 17.

        ws_config
                A relative (to the start of the structure) 16-bit pointer
                to a 0 terminated string containing infos about configuration
                items to be displayed in the WHDLoad startup splash window.
                Possible items are the options ButtonWait and Custom1-5. For
                each item specified here a gadget will be added to the splash
                window, allowing the user easily to modify this option.
                The syntax in a EBNF is as follows:

                Config = ConfigOption { ";" ConfigOption } ;
                ConfigOption = Option [ ":" Type ":" Label [ ":" Spec ] ] ;
                Option = "BW" | "C1" | "C2" | "C3" | "C4" | "C5" ;
                        (* BW - ButtonWait, without Type  *)
                        (* C1..C5 - Custom1..5, requires Type *)
                Type = "B" | "L" | "X" ;
                        (* B - Boolean *)
                        (* L - List of values, cycle gadget, Spec is list of
                               SpecOptions *)
                        (* X - Boolean only 1 bit used, Spec is the bit number
                               0-31 *)
                Spec = Number | ( SpecOption { "," SpecOption } ) ;
                Number = [0-9] ;
                SpecOption = Label ;
                Label = CHR(32..255) except [,:;] ;

                On Type=Boolean (also ButtonWait) the result will be 0 for
                unchecked and 1 for checked. On Type=List the result will be
                0 for the first SpecOption and is incremented by 1 for each
                subsequent SpecOption.

                Example:

                dc.b    "BW;"
                dc.b    "C1:B:Skip Intro;"
                dc.b    "C2:X:Activate Trainer:0;"
                dc.b    "C3:L:Load Game Position:None,1,2,3,4,5,6,7,8,9;"
                dc.b    "C4:L:Brightness:default,+50%,+100%"
                dc.b    0

   CONVENTIONS for ws_GameLoader
        The state of the whole system at the time when ws_GameLoader is called
        is as follows:

        CPU:
                SR   = $2000           Supervisor-mode, all interrupts enabled
                SSP  = ws_BaseMemSize  at the end of BaseMem
                USP  = SSP-$400        at the end of BaseMem - 1024
                A0   = Resload         pointer to the Jump-Tower in WHDLoad
                D0-D7/A1-A6 random     (D0=$d0d0d0d0 D1=...)

                Nothing more is interesting from the Slave programmers point
                of view. All special registers like VBR,SFC,DFC,CAAR,CACR,MSP,
                TC,MMUSR,CRP,SRP,URP,TT0,TT1,DTT0,DTT1,ITT0,ITT1,PCR,BUSCR are
                WHDLoad private and MUST NOT BE CHANGED.

        FPU:
                At the moment not initialized by WHDLoad.

        BaseMem:
                $00000000.l = 0
                $00000004.l = $f0000001
                        an odd value to make any try to use it (the execbase)
                        creating an 'Address Error' or 'Access Fault' exception
                $00000008...$00000400
                        if WHDLoad has moved the VBR it contains $CCCCCCCC
                        else it contains a pointer to an exception handler
                        inside WHDLoad
                $00000400...ws_BaseMemSize
                        contains $CCCCCCCC, this memory fill pattern is used to
                        easily recognize modified memory
                $00001000.l = $FFFFFFFE
                        the copper instruction 'CWAIT $ff,$1fe' (CEND)

        ExpMem:
                the memory is filled with the pattern $DDDDDDDD

        custom registers:
                dmacon = 0             all DMAs off
                intena = 0             all interrupts off
                cop1lc = cop2lc = $1000
                an AGA-machine is switched to OCS mode

        cias:
                ------- ciaa ------     ------- ciab ------
                pra in  = %00000000     pra in  = %00000000
                pra out = %11111100     pra out = %11111000
                ddra    = %00000011     ddra    = %11000000
                prb in  = %00000000     prb in  = %00000000
                prb out = %00000000     prb out = %11111111
                ddrb    = %00000000     ddrb    = %11111111
                ta      =     $21ff     ta      =     $ffff
                tb      =     $21ff     tb      =     $ffff
                event   =   $000000     event   =   $000000
               (alarm   =   $ffffff     alarm   = execbase.EClockFrequency
                        the alarm values are no longer initialized starting
                        WHDLoad version 13.1 to avoid compatibility problems
                        on Kickstart 2.0)
                sdr     =       $00     sdr     =       $00
                icr     = %00000000     icr     = %00000000
                icm     = %00001000     icm     = %00000000
                cra     = %00000000     cra     = %00000000
                crb     = %00000000     crb     = %00000000

   SEE ALSO
        example Slaves

[Main] [Docs] [Installs] [Search] [Team] [Guestbook] [Links]