home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 13 / AACD13.ISO / AACD / Games / WHDLoad / Autodoc / whdload.doc
Text File  |  2000-08-09  |  83KB  |  2,162 lines
  1. TABLE OF CONTENTS
  2.  
  3. WHDLoad/--Overview--
  4. WHDLoad/resload_Abort
  5. WHDLoad/resload_Control
  6. WHDLoad/WHDLTAG_CBAF_SET
  7. WHDLoad/WHDLTAG_CBSWITCH_SET
  8. WHDLoad/WHDLTAG_IOERR_GET
  9. WHDLoad/resload_CRC16
  10. WHDLoad/resload_Decrunch
  11. WHDLoad/resload_Delay
  12. WHDLoad/resload_Delta
  13. WHDLoad/resload_DeleteFile
  14. WHDLoad/resload_DiskLoad
  15. WHDLoad/resload_DiskLoadDev
  16. WHDLoad/resload_FlushCache
  17. WHDLoad/resload_GetFileSize
  18. WHDLoad/resload_GetFileSizeDec
  19. WHDLoad/resload_ListFiles
  20. WHDLoad/resload_LoadFile
  21. WHDLoad/resload_LoadFileDecrunch
  22. WHDLoad/resload_LoadFileOffset
  23. WHDLoad/resload_LoadKick
  24. WHDLoad/resload_Patch
  25. WHDLoad/resload_ProtectRead
  26. WHDLoad/resload_ProtectReadWrite
  27. WHDLoad/resload_ProtectRemove
  28. WHDLoad/resload_ProtectSMC
  29. WHDLoad/resload_ProtectWrite
  30. WHDLoad/resload_Relocate
  31. WHDLoad/resload_SaveFile
  32. WHDLoad/resload_SaveFileOffset
  33. WHDLoad/resload_SetCACR
  34. WHDLoad/resload_SetCPU
  35. WHDLoad.Slave/--Overview--
  36.  
  37. WHDLoad/--Overview--
  38.  
  39. The calling conventions for all functions are similar to the OS-Library-
  40. concept. Parameters are provided in registers (except "resload_Abort"),
  41. return codes comes in D0 (on some functions also in D1). After a function call
  42. the registers D0-D1/A0-A1 are destroyed (D0,D1 may contain a returncode) they
  43. are so called scratch registers. All other registers are preserved.
  44. The base of the JMP tower in WHDLoad is similar to a LibraryBase. In
  45. difference to the OS the base must not stand in A6 on calling a function, but
  46. it is recommend to call all functions relative to a address register like
  47.         move.l  (_resload,pc),a5
  48.         jsr     (resload_Decrunch,a5)
  49. The resload base is overgiven in A0 on calling the Slave first via
  50. ws_GameLoader (see chapter WHDLoad.Slave/--Overview--).
  51.  
  52.  
  53. some keywords used in this document:
  54.  
  55.  Slave          the file which contains the interface code
  56.                 (see section WHDLoad.Slave/--Overview--)
  57.  
  58.  BaseMem        the memory which is used by the installed program, because
  59.                 this memory is always Chip-memory and starts at address
  60.                 $00000000, BaseMem is at the same time the size and the end
  61.                 address of the used Chip-memory BaseMem is specified in the
  62.                 Slave-structure in field "ws_BaseMemSize"
  63.  
  64.  ExpMem         is the expansions memory, a extra memory area which can
  65.                 optionally requested by the Slave-structure, it may be
  66.                 Chip- or Fast-memory dependedly on what is available
  67.                 ExpMem is supported starting WHDLoad version 8
  68.  
  69.  DiskImage      a floppy disk stored as a file on hard disk
  70.  
  71. logical values used for returncodes (see dos/dos.i):
  72.  TRUE = -1 (or better <>0)
  73.  FALSE = 0
  74.  
  75. WHDLoad/resload_Abort
  76.  
  77.    NAME
  78.         resload_Abort -- quit and return to operating system
  79.  
  80.    SYNOPSIS
  81.         resload_Abort( success, primary, secondary)
  82.                          (a7)    (4,a7)    (8,a7)
  83.                         ULONG    ULONG     ULONG
  84.  
  85.    FUNCTION
  86.         aborts and terminates the installed program and cause WHDLoad to
  87.         return to the operating system
  88.  
  89.    INPUTS
  90.         success -   the reason for aborting
  91.                     one of TDREASON_#? defined in the include file "whdload.i"
  92.                     depending on this value WHDLoad continues different
  93.                 TDREASON_OK
  94.                     a normal exit will performed
  95.                 TDREASON_DEBUG
  96.                     WHDLoad will create dump files (.whdl_dump, .whdl_memory,
  97.                     .whdl_register) and exit
  98.                 TDREASON_#? (except the above)
  99.                     WHDLoad will show an requester which displays the reason
  100.                     of aborting and requests the user to choose between
  101.                     "Quit", "Restart" and "Make CoreDump"
  102.         primary -   the primary return code further describing the reason of
  103.                     aborting
  104.                 TDREASON_DOSREAD, TDREASON_DOSWRITE, TDREASON_DOSLIST,
  105.                 TDREASON_DISKLOAD, TDREASON_DISKLOADDEV, TDREASON_DELETEFILE
  106.                     dos or trackdisk errorcode
  107.                 TDREASON_DEBUG
  108.                     program counter (so it can by written to the dump files)
  109.                 TDREASON_OSEMUFAIL
  110.                     name of the filed subsystem
  111.                 TDREASON_OK, TDREASON_WRONGVER, TDREASON_REQ68020,
  112.                 TDREASON_REQAGA, TDREASON_MUSTNTSC, TDREASON_MUSTPAL,
  113.                 TDREASON_MUSTREG
  114.                     unused (can be omitted)
  115.         secondary - the secondary return code further describing the reason of
  116.                     aborting
  117.                 TDREASON_DOSREAD, TDREASON_DOSWRITE, TDREASON_DELETEFILE
  118.                     filename
  119.                 TDREASON_DISKLOAD
  120.                     disk number
  121.                 TDREASON_DOSLIST
  122.                     name of directory scanned
  123.                 TDREASON_DEBUG
  124.                     status register (so it can by written to the dump files)
  125.                 TDREASON_OSEMUFAIL
  126.                     error number, depending on the primary return code
  127.                 TDREASON_OK, TDREASON_DISKLOADDEV, TDREASON_WRONGVER,
  128.                 TDREASON_REQ68020, TDREASON_REQAGA, TDREASON_MUSTNTSC,
  129.                 TDREASON_MUSTPAL, TDREASON_MUSTREG
  130.                     unused (can be omitted)
  131.  
  132.    EXAMPLE
  133.         to simply quit:
  134.                 ;primary and secondary wont be needed
  135.                 move.l  #TDREASON_OK,-(a7)
  136.                 move.l  (_resload,pc),a0
  137.                 jmp     (resload_Abort,a0)
  138.         to quit because reading of a file has failed:
  139.                 move.l  a0,-(a7)                        ;a0 = filename
  140.                 move.l  d0,-(a7)                        ;d0 = doserror code
  141.                 move.l  #TDREASON_DOSREAD,-(a7)
  142.                 move.l  (_resload,pc),-(a7)
  143.                 add.l   #resload_Abort,(a7)
  144.                 rts
  145.  
  146.    RESULT
  147.         nothing because WHDLoad will never return from this call
  148.  
  149.    BUGS
  150.  
  151.    NOTE
  152.         this routine is the only one which must be called via JMP and not JSR
  153.         because the parameters are located on the stack (this has the
  154.         advantage that if aborting because TDREASON_DEBUG all registers can be
  155.         preserved and written to the dump files by WHDLoad for further
  156.         diagnostics)
  157.  
  158.    SEE ALSO
  159.         example Slave sources provided with the WHDLoad developer package
  160.  
  161. WHDLoad/resload_Control
  162.  
  163.    NAME
  164.         resload_Control
  165.  
  166.    SYNOPSIS
  167.         success = resload_Control(tags)
  168.           D0                       A0
  169.          BOOL                    STRUCT
  170.  
  171.    FUNCTION
  172.         control function of WHDLoad, allows to get and set various variables
  173.         concerning the software and hardware configuration and to control the
  174.         behavior of some WHDLoad operations
  175.  
  176.    INPUTS
  177.         tags - pointer to a table of tagitems
  178.  
  179.         the following items are currently supported:
  180.  
  181.         WHDLTAG_ATTNFLAGS_GET   - gets the AttnFlags describing the current
  182.                                   CPU, FPU and MMU, the returned value is
  183.                                   similar to execbase.AttnFlags but not equal
  184.                                   because WHDLoad uses some additional bits,
  185.                                   the Slave is only allowed to the use the
  186.                                   defines from the standard include file
  187.                                   "exec/execbase.i" for testing the returned
  188.                                   value
  189.         WHDLTAG_BUILD_GET       - gets WHDLoad build number
  190.         WHDLTAG_BUTTONWAIT_GET  - returns -1 if WHDLoad option ButtonWait/S
  191.                                   has been enabled, otherwise returns 0
  192.         WHDLTAG_CBAF_SET        - sets a function which will be executed when
  193.                                   an access fault exception occurs (see
  194.                                   section WHDLoad/WHDLTAG_CBAF_SET for further
  195.                                   informations)
  196.         WHDLTAG_CBSWITCH_SET    - sets a function which will be executed when
  197.                                   WHDLoad switches from the operating system
  198.                                   to the installed program (see section
  199.                                   WHDLoad/WHDLTAG_CBSWITCH_SET for further
  200.                                   informations)
  201.         WHDLTAG_CHIPREVBITS_GET - gets the ChipRevBits describing the current
  202.                                   custom chips, see standard include file
  203.                                   "graphics/gfxbase.i" for further explanation
  204.         WHDLTAG_CUSTOM1_GET
  205.         WHDLTAG_CUSTOM2_GET
  206.         WHDLTAG_CUSTOM3_GET
  207.         WHDLTAG_CUSTOM4_GET
  208.         WHDLTAG_CUSTOM5_GET     - returns numerical value of WHDLoad option
  209.                                   Custom1/N .. Custom5/N
  210.         WHDLTAG_ECLOCKFREQ_GET  - gets the EClockFrequency, which is the
  211.                                   frequency the custom chips operate on, the
  212.                                   value is taken from the execbase (see
  213.                                   standard include file "exec/execbase.i")
  214.         WHDLTAG_IOERR_GET       - gets the dos errorcode of the previously
  215.                                   executed resload function
  216.         WHDLTAG_KEYTRANS_GET    - get pointer to a table for 'rawkey to ascii'
  217.                                   conversion, the table has a length of 256
  218.                                   bytes and contains 4 sub tables, first 64
  219.                                   bytes representing the keys pressed without
  220.                                   any modifier, then 64 bytes with Shift, then
  221.                                   64 bytes with Alt and last 64 Bytes with
  222.                                   Shift and Alt
  223.                                   the tables are created from the actual
  224.                                   system keymap, dead keys are mapped like
  225.                                   followed pressing Space, keys resulting in
  226.                                   multibyte characters (F-Keys, Esc, ...) are
  227.                                   set to 0 in the tables
  228.         WHDLTAG_MONITOR_GET     - gets the used monitor/video mode, the
  229.                                   returned value is one of NTSC_MONITOR_ID and
  230.                                   PAL_MONITOR_ID (defined in the standard
  231.                                   include file "graphics/modeid.i"), the
  232.                                   WHDLoad options PAL/S and NTSC/S are
  233.                                   affecting the monitor/video mode
  234.         WHDLTAG_REVISION_GET    - gets WHDLoad minor version number
  235.         WHDLTAG_TIME_GET        - gets current time and date, returned will be
  236.                                   a pointer to a filled whdload_time structure
  237.                                   which is decribed in the include file
  238.                                   "whdload.i"
  239.         WHDLTAG_VERSION_GET     - gets WHDLoad major version number
  240.  
  241.    EXAMPLE
  242.         check if current CPU is at least an MC68020:
  243.                 ...
  244.                 clr.l   -(a7)                           ;TAG_DONE
  245.                 clr.l   -(a7)                           ;data to fill
  246.                 move.l  #WHDLTAG_ATTNFLAGS_GET,-(a7)
  247.                 move.l  a7,a0
  248.                 move.l  (_resload,pc),a2
  249.                 jsr     (resload_Control,a2)
  250.                 move.w  (6,a7),d0                       ;D0 = AttnFlags
  251.                 lea     (12,a7),a7                      ;restore sp
  252.                 btst    #AFB_68020,d0
  253.                 beq     .no68020
  254.                 ...
  255.         get video mode and CPU:
  256.                 ...
  257.                 lea     (_tags,pc),a0
  258.                 move.l  (_resload,pc),a2
  259.                 jsr     (resload_Control,a2)
  260.                 move.l  (_mon,pc),d0                    ;D0 = video mode
  261.                 cmp.l   #NTSC_MONITOR_ID,d0
  262.                 beq     .ntsc
  263.                 ...
  264.  
  265.         _tags   dc.l    WHDLTAG_MONITOR_GET
  266.         _mon    dc.l    0
  267.                 dc.l    WHDLTAG_ATTNFLAGS_GET
  268.                 dc.w    0                               ;padding
  269.         _attn   dc.w    0
  270.                 dc.l    0                               ;TAG_DONE
  271.  
  272.    RESULT
  273.         success is true if all items in the taglist has been successfully
  274.         processed
  275.  
  276.    BUGS
  277.  
  278.    NOTE
  279.         requires ws_Version >= 5
  280.  
  281.    SEE ALSO
  282.  
  283. WHDLoad/WHDLTAG_CBAF_SET
  284.  
  285.    NAME
  286.         WHDLTAG_CBAF_SET
  287.  
  288.    SYNOPSIS
  289.         to be used with resload_Control
  290.  
  291.         cont, adr,  data = CBAF(mode, size,  pc,  adr,  data)
  292.          D0    A1    A2          D0    D1    A0    A1    A2
  293.         LONG  APTR  APTR        LONG  LONG  APTR  APTR  APTR
  294.  
  295.    FUNCTION
  296.         using this tag a function can be set which will executed when an
  297.         access fault exception occurs which is not handled by WHDLoad itself,
  298.         it may be used to locate specific accesses in conjunction with
  299.         resload_Protect and to walk around invalid accesses during the
  300.         development process
  301.         using this tag all access faults can be catched except:
  302.          - instruction stream faults
  303.          - faults caused by WHDLoad's blitwait and blitsize checks
  304.         the routine set using this tag must not change any registers except
  305.         the ones holding a return value, the routine must return via RTS, on
  306.         entering the routine all interrupts are disabled (sr=$27xx)
  307.  
  308.    INPUTS
  309.         mode - transfer mode of the faulted access
  310.                 0 - read
  311.                 1 - modify (only 68040/060)
  312.                 2 - write
  313.         size - operand size of the attempted access
  314.                 1 - Byte
  315.                 2 - Word
  316.                 4 - LongWord
  317.         pc   - program counter of the instruction which has faulted
  318.                (warning this may sometimes already the instruction after the
  319.                one which has faulted, read the appropriate microprocessor user
  320.                manual for further informations)
  321.         adr  - the address which has been attempted to access
  322.         data - valid only on write operations, the given memory address
  323.                contains the data which has been tried to write
  324.  
  325.    RESULT
  326.         cont - how to continue
  327.                 0 - terminate, WHDLoad will show a requester notifying the
  328.                     access fault
  329.                 1 - proceed, the faulted access will be emulated by the
  330.                     handler inside great WHDLoad
  331.         adr  - in case of cont=proceed the address which will be accessed
  332.         data - in case of cont=proceed and mode=write a pointer to the data
  333.                which will be written (only 68030)
  334.  
  335.    EXAMPLE
  336.         if you want to get informed at which point the installed program
  337.         writes the value 42 to the address $BABE, use the following code:
  338.                 ...
  339.                 clr.l   -(a7)                           ;TAG_DONE
  340.                 pea     (_af,pc)                        ;function
  341.                 move.l  #WHDLTAG_CBAF_SET,-(a7)
  342.                 move.l  a7,a0
  343.                 move.l  (_resload,pc),a2
  344.                 jsr     (resload_Control,a2)
  345.                 lea     (12,a7),a7                      ;restore sp
  346.                 moveq   #2,d0
  347.                 lea     ($BABE),a0
  348.                 jsr     (resload_ProtectWrite,a2)       ;protect area
  349.                 ...
  350.  
  351.      _af        cmp.l   #$BABE,a1                       ;correct address ?
  352.                 bne     .term
  353.                 cmp.w   #2,d1                           ;size
  354.                 bne     .term
  355.                 cmp.w   #42,(a2)
  356.                 beq     .term
  357.                 moveq   #1,d0                           ;proceed
  358.                 rts
  359.  
  360.     .term       moveq   #0,d0                           ;terminate
  361.                 rts
  362.  
  363.    EXAMPLE
  364.         if want you to redirect an access to $24 to the address $300, use the
  365.         following code:
  366.                 ...
  367.                 clr.l   -(a7)                           ;TAG_DONE
  368.                 pea     (_af,pc)                        ;function
  369.                 move.l  #WHDLTAG_CBAF_SET,-(a7)
  370.                 move.l  a7,a0
  371.                 move.l  (_resload,pc),a2
  372.                 jsr     (resload_Control,a2)
  373.                 lea     (12,a7),a7                      ;restore sp
  374.                 moveq   #4,d0
  375.                 lea     ($24),a0
  376.                 jsr     (resload_ProtectWrite,a2)       ;protect area
  377.                 ...
  378.  
  379.      _af        cmp.l   #$24,a1                         ;correct address ?
  380.                 bne     .term
  381.                 lea     ($300),a1
  382.                 moveq   #1,d0                           ;proceed
  383.                 rts
  384.  
  385.     .term       moveq   #0,d0                           ;terminate
  386.                 rts
  387.  
  388.  
  389.    BUGS
  390.         currently only 68030 is supported
  391.  
  392.    NOTE
  393.         requires ws_Version >= 9
  394.         MUST not be used in public releases, use for development process only
  395.  
  396.    SEE ALSO
  397.         resload_Control
  398.  
  399. WHDLoad/WHDLTAG_CBSWITCH_SET
  400.  
  401.    NAME
  402.         WHDLTAG_CBSWITCH_SET
  403.  
  404.    SYNOPSIS
  405.         to be used with resload_Control
  406.  
  407.         CBSWITCH()
  408.  
  409.    FUNCTION
  410.         using this tag a routine can be set which will executed each time
  411.         WHDLoad switches from the operating system to the installed program
  412.         such a routine is sometimes necessary because during the switch
  413.         between the installed program and the operating system some hardware
  414.         registers are modified by the operating system
  415.         known registers to be modified are cop2lc, bltafwm and bltalwm, maybe
  416.         there are more of them
  417.         the routine must not change any registers, must not use any stack and
  418.         has to return via "jmp (a0)", at execution time of the routine all
  419.         interrupts and dma's are disabled and the memory setup of the
  420.         installed program is active
  421.  
  422.    INPUTS
  423.         pointer to the routine to execute during switch, a value equal 0
  424.         disables the execution of a routine
  425.  
  426.    EXAMPLE
  427.                 ...
  428.                 clr.l   -(a7)                           ;TAG_DONE
  429.                 pea     (_cbswitch,pc)                  ;function
  430.                 move.l  #WHDLTAG_CBSWITCH_SET,-(a7)
  431.                 move.l  a7,a0
  432.                 move.l  (_resload,pc),a2
  433.                 jsr     (resload_Control,a2)
  434.                 lea     (12,a7),a7                      ;restore sp
  435.                 ...
  436.  
  437.      _cbswitch  move.l  (_c2,pc),(_custom+cop2lc)
  438.                 jmp     (a0)
  439.  
  440.      _cb2       dc.l    $10e80
  441.  
  442.    RESULT
  443.         none
  444.  
  445.    BUGS
  446.  
  447.    NOTE
  448.         requires ws_Version >= 7
  449.  
  450.    SEE ALSO
  451.         resload_Control
  452.  
  453. WHDLoad/WHDLTAG_IOERR_GET
  454.  
  455.    NAME
  456.         WHDLTAG_IOERR_GET
  457.  
  458.    SYNOPSIS
  459.         to be used with resload_Control
  460.  
  461.    FUNCTION
  462.         this tag can be used to get the dos errorcode of the last called
  463.         resload function, all resload functions except resload_Control will
  464.         set/reset this error code
  465.         two resload functions are special in that way:
  466.             resload_GetFileSize
  467.                 if a file with the specified name cannot be opened via
  468.                 dos.Open, the error code will be set to the value returned
  469.                 from dos.IoErr, so the error code may contain values like
  470.                 ERROR_OBJECT_NOT_FOUND, ERROR_OBJECT_WRONG_TYPE,
  471.                 ERROR_READ_PROTECTED or similar stuff from dos/dos.i
  472.                 the errorcode can be used to distinguish between a file with
  473.                 size of 0 and a nonexistent file
  474.             resload_ListFiles
  475.                 if the specified buffer to fill is not large enough to hold
  476.                 all filenames from the scanned directory, the error code will
  477.                 be set to ERROR_NO_FREE_STORE
  478.  
  479.    INPUTS
  480.         none
  481.  
  482.    EXAMPLE
  483.                 ...
  484.                 clr.l   -(a7)                           ;TAG_DONE
  485.                 clr.l   -(a7)                           ;data to fill
  486.                 move.l  #WHDLTAG_IOERR_GET,-(a7)
  487.                 move.l  a7,a0
  488.                 move.l  (_resload,pc),a2
  489.                 jsr     (resload_Control,a2)
  490.                 move.l  (4,a7),d0                       ;D0 = IoErr
  491.                 lea     (12,a7),a7                      ;restore sp
  492.                 ...
  493.  
  494.    RESULT
  495.         none
  496.  
  497.    BUGS
  498.  
  499.    NOTE
  500.         requires ws_Version >= 8
  501.  
  502.    SEE ALSO
  503.         resload_Control, resload_GetFileSize, resload_ListFiles
  504.  
  505. WHDLoad/resload_CRC16
  506.  
  507.    NAME
  508.         resload_CRC16 -- calculate ANSI conform 16 bit CRC checksum
  509.  
  510.    SYNOPSIS
  511.         checksum = resload_CRC16(length,address)
  512.            D0                      D0     A0
  513.          UWORD                   ULONG   APTR
  514.  
  515.    FUNCTION
  516.         calculate ANSI conform 16 bit CRC checksum
  517.         mostly used to difference between various program versions
  518.  
  519.    INPUTS
  520.         length  - length of area to calculate over
  521.         address - pointer to area
  522.  
  523.    EXAMPLE
  524.                 ...
  525.                 lea     $1000,a0                ;at address $1000
  526.                 move.l  #256,d0                 ;upto address $1100
  527.                 move.l  (_resload,pc),a2
  528.                 jsr     (resload_CRC16,a2)
  529.                 cmp.w   #$f2b7,d0
  530.                 bne     .false_version
  531.                 ...
  532.  
  533.    RESULT
  534.         checksum - 16 bit crc
  535.  
  536.    BUGS
  537.  
  538.    NOTE
  539.         requires ws_Version >= 3
  540.  
  541.    SEE ALSO
  542.  
  543. WHDLoad/resload_Decrunch
  544.  
  545.    NAME
  546.         resload_Decrunch -- uncompress data in memory
  547.  
  548.    SYNOPSIS
  549.         size = resload_Decrunch(source, destination)
  550.          D0                       A0        A1
  551.         ULONG                    APTR      APTR
  552.  
  553.    FUNCTION
  554.         unpack compressed data in memory, known compressed data formats are
  555.         RNC1, RNC2, IMP!, ATN! and TPWM
  556.         the function first checks if the data source points to is a known
  557.         compressed format, if not it returns with size=0, else the data will
  558.         be unpacked to the destination and the size of the decompressed data
  559.         is returned
  560.         source and destination can be equal, in that case the packed data will
  561.         be overwritten
  562.  
  563.         RNC1:   rob northen compressor - emphasis on packed size, supported is
  564.                 the old and the new format, both formats using the same id but
  565.                 different file formats and compressing algorithms, the
  566.                 function uses some heuristic checks to determinate the correct
  567.                 format, the decompressor for the new common format is highly
  568.                 optimized and contains a routine for 68000/010 and one for
  569.                 68020+, on 68060 it is faster than the IMP! decompressor!
  570.         RNC2:   rob northen compressor - emphasis on unpacking speed, the
  571.                 fastest supported decompressor
  572.         IMP!:   imploder (FImp), the packed data data must not overlap the
  573.                 destinaion for unpacking but the destination must be equal the
  574.                 source or outside the source data, in difference to the
  575.                 original explode routine resload_Decrunch does not destroy the
  576.                 source data (if source is not equal destination)
  577.         ATN!:   identical to IMP! only id is different
  578.         TPWM:   supported starting WHDLoad version 11, because the fileheader
  579.                 does not contain the length of the packed data there is no
  580.                 integrity check
  581.  
  582.         all decompressing routines has been modified to not modify the
  583.         registers A5 and A6 and to use nearly no stack space
  584.         all decompressing routines performing a check if the decompression was
  585.         successful, on a failure the installed program will be terminated and
  586.         WHDLoad will display a message concerning this
  587.  
  588.  
  589.    INPUTS
  590.         source      - address of source in memory
  591.         destination - address of destination in memory (can be equal to source)
  592.  
  593.    EXAMPLE
  594.  
  595.    RESULT
  596.         size - the size of the uncompressed data or 0 if is not compressed
  597.                with a known format
  598.  
  599.    BUGS
  600.  
  601.    NOTE
  602.         the routine performs automatically a resload_FlushCache before
  603.         returning
  604.  
  605.    SEE ALSO
  606.         resload_LoadFileDecrunch
  607.  
  608. WHDLoad/resload_Delay
  609.  
  610.    NAME
  611.         resload_Delay -- wait some time
  612.  
  613.    SYNOPSIS
  614.         resload_Delay(time)
  615.                        D0
  616.                       ULONG
  617.  
  618.    FUNCTION
  619.         wait the specified time or until a button is pressed, all possible
  620.         buttons (LMB, MMB, RMB) of both controllers (port 0/1) are checked,
  621.         after the time runs out or a button is pressed the function waits
  622.         until all buttons has been released
  623.         the wait routine is based on the raster beam, but checks the current
  624.         display and therefore waits the correct time on PAL and NTSC
  625.  
  626.    INPUTS
  627.         time - time to wait in 1/10 seconds
  628.  
  629.    EXAMPLE
  630.                 ...
  631.                 moveq   #30,d0                  ;3 seconds
  632.                 move.l  (_resload,pc),a2
  633.                 jsr     (resload_Delay,a2)
  634.                 ...
  635.  
  636.    RESULT
  637.         nothing, all registers are preserved
  638.  
  639.    BUGS
  640.  
  641.    NOTE
  642.         in difference to most others resload_#? function this routine is
  643.         granted to preserve all registers
  644.         requires ws_Version >= 8
  645.  
  646.    SEE ALSO
  647.  
  648. WHDLoad/resload_Delta
  649.  
  650.    NAME
  651.         resload_Delta -- apply WDelta file
  652.  
  653.    SYNOPSIS
  654.         resload_Delta(src,  dest, delta)
  655.                        A0    A1    A2
  656.                       APTR  APTR  APTR
  657.  
  658.    FUNCTION
  659.         applies the differences provided via delta onto the src and create
  660.         dest
  661.  
  662.    INPUTS
  663.         src   - source data
  664.         dest  - destination memory
  665.         delta - wdelta data
  666.  
  667.    EXAMPLE
  668.                 ...
  669.                 lea     ($10000),a0             ;source
  670.                 lea     ($400),a1               ;destination
  671.                 lea     ($40000),a2             ;wdelta
  672.                 move.l  (_resload,pc),a3
  673.                 jsr     (resload_Delta,a3)
  674.                 ...
  675.  
  676.    RESULT
  677.  
  678.    BUGS
  679.  
  680.    NOTE
  681.         the source and the destination will be crc checked
  682.         if an error occurs WHDLoad will quit with an appropriate requester
  683.         requires ws_Version >= 11
  684.  
  685.    SEE ALSO
  686.  
  687. WHDLoad/resload_DeleteFile
  688.  
  689.    NAME
  690.         resload_Delete -- delete file
  691.  
  692.    SYNOPSIS
  693.         success,errorcode = resload_DeleteFile(name)
  694.           D0       D1                           A0
  695.          BOOL    ULONG                         CPTR
  696.  
  697.    FUNCTION
  698.         deletes the file or directory with the specified name
  699.  
  700.    INPUTS
  701.         name - name of the file/directory to delete
  702.  
  703.    EXAMPLE
  704.                 ...
  705.                 lea     (_name,pc),a0
  706.                 move.l  (_resload,pc),a2
  707.                 jsr     (resload_DeleteFile,a2)
  708.                 ...
  709.  
  710.         _name   dc.b    "C:WHDLoad",0
  711.  
  712.    RESULT
  713.         success   - TRUE on success
  714.         errorcode - 0 on success
  715.                     otherwise a dos-errorcode from dos.IoErr()
  716.         if WHDLF_NoError is set, the function only returns on success
  717.  
  718.    BUGS
  719.  
  720.    NOTE
  721.         requires ws_Version >= 8
  722.  
  723.    SEE ALSO
  724.  
  725. WHDLoad/resload_DiskLoad
  726.  
  727.    NAME
  728.         resload_DiskLoad -- load part from a diskimage
  729.  
  730.    SYNOPSIS
  731.         success,errorcode = resload_DiskLoad(offset,size,diskno,dest)
  732.           D0       D1                          D0    D1    D2    A0
  733.          BOOL    ULONG                        ULONG ULONG UBYTE APTR
  734.  
  735.    FUNCTION
  736.         load part from a diskimage
  737.  
  738.    INPUTS
  739.         offset - offset in diskimage (relative to the beginning)
  740.         size   - amount of bytes to read
  741.         diskno - disk number
  742.         dest   - destination address
  743.  
  744.    EXAMPLE
  745.                 ...
  746.                 move.l  #880*512,d0             ;from block 880
  747.                 move.l  #2*512,d1               ;2 blocks
  748.                 moveq   #1,d2                   ;disk 1
  749.                 lea     $80000,a0               ;destination
  750.                 move.l  (_resload,pc),a2
  751.                 jsr     (resload_LoadDisk,a2)
  752.                 ...
  753.  
  754.    RESULT
  755.         success   - TRUE on success
  756.         errorcode - 0 on success
  757.                     otherwise a dos-errorcode from dos.IoErr()
  758.         if WHDLF_NoError is set, the function only returns on success
  759.  
  760.    BUGS
  761.  
  762.    NOTE
  763.         the name of the disk images must be "disk." followed by the disk
  764.         number (i.e. "Disk.1")
  765.         the size of the diskimages is variable, an attempt to read data
  766.         outside the disk image will result in a seek error
  767.         the routine performs automatically a resload_FlushCache before
  768.         returning
  769.  
  770.    SEE ALSO
  771.         resload_LoadFileOffset
  772.  
  773. WHDLoad/resload_DiskLoadDev
  774.  
  775.    NAME
  776.         resload_DiskLoadDev -- load part from a floppy disk
  777.  
  778.    SYNOPSIS
  779.         success,errorcode = resload_DiskLoadDev(offset, size,  dest,  tags)
  780.           D0       D1                             D0     D1     A0     A1
  781.          BOOL    ULONG                          ULONG  ULONG  UBYTE  STRUCT
  782.  
  783.    FUNCTION
  784.         load a given amount of bytes from a floppy like device
  785.  
  786.    INPUTS
  787.         offset - offset on the disk (relative to the beginning)
  788.         size   - amount of bytes to read (at the moment this must be a
  789.                  multiple of 512 bytes)
  790.         dest   - destination address (at the moment this must be aligned
  791.                  to 512 bytes)
  792.         tags   - pointer to a taglist (at the moment there are no valid
  793.                  tags, so this must be NULL)
  794.  
  795.    EXAMPLE
  796.                 ...
  797.                 move.l  #880*512,d0             ;from block 880
  798.                 move.l  #2*512,d1               ;2 blocks
  799.                 lea     $80000,a0               ;destination
  800.                 sub.l   a1,a1                   ;tag list
  801.                 move.l  (_resload,pc),a2
  802.                 jsr     (resload_LoadDisk,a2)
  803.                 ...
  804.  
  805.    RESULT
  806.         success   - TRUE on success
  807.         errorcode - 0 on success
  808.                     otherwise a trackdisk errorcode
  809.         if WHDLF_NoError is set, the function only returns on success
  810.  
  811.    BUGS
  812.  
  813.    NOTE
  814.         requires ws_Version >= 2
  815.         at the moment all (size, address) must be aligned to 512 bytes due
  816.         restrictions of trackdisk.device
  817.         the routine performs automatically a resload_FlushCache before
  818.         returning
  819.  
  820.    SEE ALSO
  821.  
  822. WHDLoad/resload_FlushCache
  823.  
  824.    NAME
  825.         resload_FluchCache -- clear CPU caches
  826.  
  827.    SYNOPSIS
  828.         resload_FlushCache()
  829.  
  830.    FUNCTION
  831.         clear all CPU caches
  832.  
  833.    INPUTS
  834.  
  835.    EXAMPLE
  836.  
  837.    RESULT
  838.  
  839.    BUGS
  840.  
  841.    NOTE
  842.         in difference to most others resload_#? function this routine is
  843.         granted to preserve all registers
  844.         it is safe to call this routine from User or Supervisor mode and
  845.         independend from the actual CPU type (also on 68000/010)
  846.         it uses the CACR on 68020/030 and a "cpusha bc" on 68040/060
  847.  
  848.    SEE ALSO
  849.         resload_SetCPU
  850.  
  851. WHDLoad/resload_GetFileSize
  852.  
  853.    NAME
  854.         resload_GetFileSize -- get size of a file
  855.  
  856.    SYNOPSIS
  857.         size = resload_GetFileSize(name)
  858.          D0                         A0
  859.         ULONG                      CPTR
  860.  
  861.    FUNCTION
  862.         get size of a file, or check if a file exists
  863.         to distinguish between a file with a size of 0 and an nonexisting
  864.         file the tag WHDLTAG_IOERR_GET must be used in conjunction with
  865.         resload_Control
  866.  
  867.    INPUTS
  868.         name - name of the file to get size from
  869.  
  870.    EXAMPLE
  871.                 ...
  872.                 lea     (_filename,pc),a0
  873.                 move.l  (_resload,pc),a2
  874.                 jsr     (resload_GetFileSize,a2)
  875.                 tst.l   d0
  876.                 bne     .file_not_exist
  877.                 ...
  878.  
  879.    RESULT
  880.         size - the size of the file, 0 if does not exist
  881.  
  882.    BUGS
  883.  
  884.    NOTE
  885.         this routine returns the filesize obtained by the filesystem, if the
  886.         file is compressed and is loaded later via resload_LoadFileDecrunch
  887.         the loaded filesize will differ!
  888.  
  889.    SEE ALSO
  890.         resload_Control, resload_GetFileSizeDec, resload_LoadFile,
  891.         resload_LoadFileDecrunch
  892.  
  893. WHDLoad/resload_GetFileSizeDec
  894.  
  895.    NAME
  896.         resload_GetFileSizeDec -- get size of a packed file
  897.  
  898.    SYNOPSIS
  899.         size = resload_GetFileSizeDec (name)
  900.          D0                         A0
  901.         ULONG                      CPTR
  902.  
  903.    FUNCTION
  904.         get size of a packed file, or check if a file exists
  905.         the routine knows the same decruncher that resload_Decrunch supports
  906.         to distinguish between a file with a size of 0 and an nonexisting
  907.         file the tag WHDLTAG_IOERR_GET must be used in conjunction with
  908.         resload_Control
  909.  
  910.    INPUTS
  911.         name - name of the file to get size from
  912.  
  913.    EXAMPLE
  914.                 ...
  915.                 lea     (_filename,pc),a0
  916.                 move.l  (_resload,pc),a2
  917.                 jsr     (resload_GetFileSizeDec,a2)
  918.                 tst.l   d0
  919.                 bne     .file_not_exist
  920.                 ...
  921.  
  922.    RESULT
  923.         size - the size of the file, 0 if does not exist
  924.  
  925.    BUGS
  926.  
  927.    NOTE
  928.  
  929.    SEE ALSO
  930.         resload_Control, resload_GetFileSize, resload_LoadFile,
  931.         resload_LoadFileDecrunch
  932.  
  933. WHDLoad/resload_ListFiles
  934.  
  935.    NAME
  936.         resload_ListFiles -- list filenames of a directory
  937.  
  938.    SYNOPSIS
  939.         amount,errorcode = resload_ListFiles(buffersize, name, buffer)
  940.           D0      D1                             D0       A0     A1
  941.         ULONG   ULONG                          ULONG     CPTR   APTR
  942.  
  943.    FUNCTION
  944.         writes the names of all files in the specified directory to the
  945.         buffer, the file names are separated with a $0 character
  946.         only files are listed, directories are skipped
  947.         if the buffer to fill is not large enough to hold all file names the
  948.         routine fills it as far as possible, the tag WHDLTAG_IOERR_GET in
  949.         conjunction with resload_Control can be used to check if all file
  950.         names have fit into the buffer
  951.  
  952.  
  953.    INPUTS
  954.         buffersize - the size of the buffer
  955.         name       - the name of the directory to scan
  956.         buffer     - pointer to the buffer (the buffer must be located inside
  957.                      the Slave)
  958.  
  959.    EXAMPLE
  960.                 ...
  961.                 move.l  #_bufend-_buf,d0
  962.                 lea     (_savepath,pc),a0
  963.                 lea     (_buf,pc),a1
  964.                 move.l  (_resload,pc),a2
  965.                 jsr     (resload_ListFiles,a2)
  966.                 ...
  967.  
  968.         _buf      ds.b    1000
  969.         _bufend
  970.         _savepath dc.b  "/save",0       ;this must be a relative path!
  971.  
  972.  
  973.    RESULT
  974.         amount    - amount of listed files in the buffer
  975.         errorcode - 0 on success
  976.                     otherwise a dos-errorcode from dos.IoErr()
  977.         if WHDLF_NoError is set, the function only returns on success
  978.  
  979.    BUGS
  980.  
  981.    NOTE
  982.  
  983.    SEE ALSO
  984.         resload_Control
  985.  
  986. WHDLoad/resload_LoadFile
  987.  
  988.    NAME
  989.         resload_LoadFile -- load file into memory
  990.  
  991.    SYNOPSIS
  992.         length,errorcode = resload_LoadFile(name, address)
  993.           D0      D1                         A0      A1
  994.         ULONG    ULONG                      CPTR    APTR
  995.  
  996.    FUNCTION
  997.         load file to the specified memory address
  998.  
  999.    INPUTS
  1000.         name    - name of the file to load
  1001.         address - memory address to load the file on
  1002.  
  1003.    EXAMPLE
  1004.                 ...
  1005.                 lea     (_filename),a0          ;name
  1006.                 lea     $1000.w,a1              ;destination
  1007.                 move.l  (_resload,pc),a2
  1008.                 jsr     (resload_LoadFile,a2)
  1009.                 ...
  1010.  
  1011.    RESULT
  1012.         length    - the size of the loaded file, or 0 on error
  1013.         errorcode - 0 on success
  1014.                     otherwise a dos-errorcode from dos.IoErr()
  1015.         if WHDLF_NoError is set, the function only returns on success
  1016.  
  1017.    BUGS
  1018.  
  1019.    NOTE
  1020.         the routine performs automatically a resload_FlushCache before
  1021.         returning
  1022.  
  1023.    SEE ALSO
  1024.         resload_LoadFileDecrunch, resload_LoadFileOffset
  1025.  
  1026. WHDLoad/resload_LoadFileDecrunch
  1027.  
  1028.    NAME
  1029.         resload_LoadFileDecrunch -- load file and uncompress
  1030.  
  1031.    SYNOPSIS
  1032.         length,errorcode = resload_LoadFileDecrunch(name, address)
  1033.           D0      D1                                 A0      A1
  1034.         ULONG    ULONG                              CPTR    APTR
  1035.  
  1036.    FUNCTION
  1037.         loads the specified file into memory and unpack it if it is in a
  1038.         supported compressed data format
  1039.         using this routine instead of resload_LoadFile easily allows it to add
  1040.         support for compressed data files to a installed program, the
  1041.         decompression is absolutely transparent, so the installed program will
  1042.         not detect if the files loaded are compressed on disk or not, the only
  1043.         thing which must be considered is that files that are written using
  1044.         resload_SaveFileOffset or loaded via resload_LoadFileOffset must not
  1045.         be compressed
  1046.  
  1047.    INPUTS
  1048.         name    - name of file to load
  1049.         address - memory address to load the file on
  1050.  
  1051.    EXAMPLE
  1052.                 ...
  1053.                 lea     (_filename),a0          ;name
  1054.                 lea     $1000.w,a1              ;destination
  1055.                 move.l  (_resload,pc),a2
  1056.                 jsr     (resload_LoadFileDecrunch,a2)
  1057.                 ...
  1058.  
  1059.    RESULT
  1060.         length    - the size of the loaded file
  1061.                     if an error occurs this is 0
  1062.         errorcode - 0 on success
  1063.                     otherwise a dos-errorcode from dos.IoErr()
  1064.         if WHDLF_NoError is set, the function only returns on success
  1065.  
  1066.    BUGS
  1067.  
  1068.    NOTE
  1069.         the routine performs automatically a resload_FlushCache before
  1070.         returning
  1071.  
  1072.    SEE ALSO
  1073.         resload_Decrunch, resload_LoadFile, resload_LoadFileOffset,
  1074.         resload_SaveFile, resload_SaveFileOffset
  1075.  
  1076. WHDLoad/resload_LoadFileOffset
  1077.  
  1078.    NAME
  1079.         resload_LoadFileOffset -- load data inside a file to memory
  1080.  
  1081.    SYNOPSIS
  1082.         success,error = resload_LoadFileOffset(size, offset, name, address)
  1083.           D0     D1                             D0     D1     A0      A1
  1084.          BOOL   ULONG                          ULONG  ULONG  CPTR    APTR
  1085.  
  1086.    FUNCTION
  1087.         load a part of a file into memory, the part of the file is specified
  1088.         by an offset in the file and a byte count to read, the routine is
  1089.         nearly identical to resload_DiskLoad but instead of specifying the
  1090.         number of the disk to read from a filename is used to select the file
  1091.  
  1092.    INPUTS
  1093.         size    - amount of bytes to read
  1094.         offset  - offset in the file
  1095.         name    - name of file
  1096.         address - memory address to load the file on
  1097.  
  1098.    EXAMPLE
  1099.                 ...
  1100.                 move.l  #512,d0                 ;size
  1101.                 move.l  #$4000,d1               ;offset
  1102.                 lea     (_save,pc),a0           ;name
  1103.                 lea     $5ac20,a1               ;source
  1104.                 move.l  (_resload,pc),a2
  1105.                 jsr     (resload_LoadFileOffset,a2)
  1106.                 ...
  1107.  
  1108.         _save   dc.b    "saved",0
  1109.  
  1110.    RESULT
  1111.         success   - TRUE on success
  1112.         errorcode - 0 on success
  1113.                     otherwise a dos-errorcode from dos.IoErr()
  1114.         if WHDLF_NoError is set, the function only returns on success
  1115.  
  1116.    BUGS
  1117.  
  1118.    NOTE
  1119.         the routine performs automatically a resload_FlushCache before
  1120.         returning
  1121.         requires ws_Version >= 6
  1122.  
  1123.    SEE ALSO
  1124.         resload_DiskLoad, resload_LoadFile
  1125.  
  1126. WHDLoad/resload_LoadKick
  1127.  
  1128.    NAME
  1129.         resload_LoadKick -- load kickstart image
  1130.  
  1131.    SYNOPSIS
  1132.         resload_LoadKick(size, crc16,  name)
  1133.                           D0     D1     A0
  1134.                          ULONG  UWORD  CPTR
  1135.  
  1136.    FUNCTION
  1137.         load kickstart image with the specified name into ExpMem
  1138.  
  1139.    INPUTS
  1140.         size    - size of kickstart image
  1141.         crc16   - CRC16 of kickstart image
  1142.         name    - basename of kickstart image
  1143.  
  1144.    EXAMPLE
  1145.                 ...
  1146.                 move.l  #$40000,d0              ;size
  1147.                 move.w  #$f20b,d1               ;crc16
  1148.                 lea     (_kick,pc),a0           ;name
  1149.                 move.l  (_resload,pc),a2
  1150.                 jsr     (resload_LoadKick,a2)
  1151.                 ...
  1152.  
  1153.         _kick   dc.b    "34005.a500",0
  1154.  
  1155.    RESULT
  1156.  
  1157.    BUGS
  1158.  
  1159.    NOTE
  1160.         requires ws_Version >= 11
  1161.  
  1162.    SEE ALSO
  1163.  
  1164. WHDLoad/resload_Patch
  1165.  
  1166.    NAME
  1167.         resload_Patch -- apply patchlist
  1168.  
  1169.    SYNOPSIS
  1170.         resload_Patch(patchlist, destination)
  1171.                          A0          A1
  1172.                         APTR        APTR
  1173.  
  1174.    FUNCTION
  1175.         modify memory using commands from a specified patch list,
  1176.         to make an installed program working under WHDLoad it must be patched,
  1177.         that means the program must be modified so that it will load data via
  1178.         WHDLoad instead of using its own loader routines, often also various
  1179.         other things must be changed to make it working
  1180.         the modifying of the installed program can be done using this routine,
  1181.         a patch list will be build by using macros from the include file
  1182.         "whdpatch.i", each entry in the patchlist specifies a command to
  1183.         perform, an address to apply the command on and optional extra data,
  1184.         resload_Patch is especially useful if the memory to modify is located
  1185.         in the ExpMem and therefore the destination address in only know at
  1186.         runtime and not at creation time of the Slave
  1187.  
  1188.    INPUTS
  1189.         patchlist   - list of commands describing the patches to apply
  1190.         destination - address of memory region to patch
  1191.  
  1192.    EXAMPLE
  1193.                 ...
  1194.                 lea     (_pl,pc),a0             ;patchlist
  1195.                 move.l  (_expmem,pc),a1         ;destination
  1196.                 move.l  (_resload,pc),a2
  1197.                 jsr     (resload_Patch,a2)
  1198.                 ...
  1199.  
  1200.         _pl     PL_START
  1201.                 PL_P    $560,_loadfile          ;the loading routine
  1202.                 PL_R    $2046                   ;copylock
  1203.                 PL_END
  1204.  
  1205.    RESULT
  1206.  
  1207.    BUGS
  1208.  
  1209.    NOTE
  1210.         the routine performs automatically a resload_FlushCache before
  1211.         returning
  1212.         requires ws_Version >= 10
  1213.  
  1214.    SEE ALSO
  1215.  
  1216. WHDLoad/resload_ProtectRead
  1217.  
  1218.    NAME
  1219.         resload_ProtectRead -- mark memory as read protected
  1220.  
  1221.    SYNOPSIS
  1222.         resload_ProtectRead(length, address)
  1223.                               D0      A0
  1224.                              ULONG   APTR
  1225.  
  1226.    FUNCTION
  1227.         protect the specified memory against reading by the processor
  1228.         the memory to protect must be located inside BaseMem or ExpMem
  1229.  
  1230.    INPUTS
  1231.         length  - size of the memory area to protected
  1232.         address - start address of the memory area to protected
  1233.  
  1234.    EXAMPLE
  1235.                 ...
  1236.                 moveq   #4,d0                   ;one longword
  1237.                 lea     $4070,a0                ;address
  1238.                 move.l  (_resload,pc),a2
  1239.                 jsr     (resload_ProtectRead,a2)
  1240.                 ...
  1241.  
  1242.    RESULT
  1243.         a "Exception 'Access Fault'" WHDLoad requester if the protected memory
  1244.         is accessed
  1245.  
  1246.    BUGS
  1247.         the amount of protected areas is currently limited to 16,
  1248.         the page where the SSP points to must not be protected, because if a
  1249.         Access Fault occurs the CPU will be unable in that case to write the
  1250.         exception stackframe, only reset will recover from the resulting
  1251.         Double Bus Fault
  1252.         limitations on MC68020+MC68851:
  1253.           this hardware is currently not supported
  1254.         limitations on MC68030:
  1255.           - 3-byte transfers are not supported (occuring on misaligned
  1256.             longword accesses to page boundaries eg. "tst.l $fff" (assumed
  1257.             4KByte page size))
  1258.           - locked accesses (tas/cas/cas2) are not supported
  1259.         limitations on MC68040:
  1260.           this hardware is currently not supported
  1261.         limitations on MC68060:
  1262.           - misaligned access are not supported (occuring on accesses trough a
  1263.             page boundary, for example "tst.l ($ffe)" (assumed 4KByte page
  1264.             size))
  1265.           - locked accesses (tas/cas) are not supported
  1266.           - instructions which are located on a protected page and access the
  1267.             supervisor portion of the status register will be executed wrong
  1268.             (these instructions will always see the trace bit as 1 and the
  1269.             interrupt level as 7, any modification of the status register
  1270.             supervisor portion will be without effect)
  1271.           - movem instruction may access a protected area without creating a
  1272.             Access Fault exception (only the first bus cycle of the excution
  1273.             unit will be verified for matching a protected area)
  1274.           - move16 and double precision operations (FPU) are unsupported
  1275.           - a "move (mem),(mem)" with overlapping source and destination
  1276.             address which generates an Access Fault because Misalignment
  1277.             will be executed wrong, for example "move.l ($ffc),($ffe)" where
  1278.             page $1000..$1fff is protected and memory before execution
  1279.             contains ($ffc)=$11112222,($1000)=$33334444, after execution
  1280.             $1000 contains $11114444 and not $22224444)
  1281.         unsupported accesses will result in a "Exception 'Access Fault'"
  1282.         WHDLoad requester
  1283.  
  1284.    NOTE
  1285.         requires ws_Version >= 6
  1286.         the MMU must be in use by WHDLoad, otherwise you will get WHDLoad
  1287.         requester "Unacceptible Arguments".
  1288.         only accesses to the user and supervisor data stream are affected
  1289.         (this means not affected are: CPU space accesses (eg getting values
  1290.         from the vector table) and instruction stream accesses)
  1291.  
  1292.    SEE ALSO
  1293.         resload_ProtectReadWrite, resload_ProtectWrite, resload_ProtectRemove
  1294.  
  1295. WHDLoad/resload_ProtectReadWrite
  1296.  
  1297.    NAME
  1298.         resload_ProtectReadWrite -- mark memory as read and write protected
  1299.  
  1300.    SYNOPSIS
  1301.         resload_ProtectReadWrite(length, address)
  1302.                                    D0      A0
  1303.                                   ULONG   APTR
  1304.  
  1305.    FUNCTION
  1306.         protect the specified memory against reading and writing by the
  1307.         processor
  1308.         the memory to protect must be located inside BaseMem or ExpMem
  1309.  
  1310.    INPUTS
  1311.         length  - size of the memory area to protected
  1312.         address - start address of the memory area to protected
  1313.  
  1314.    EXAMPLE
  1315.                 ...
  1316.                 moveq   #4,d0                   ;one longword
  1317.                 lea     $64,a0                  ;address
  1318.                 move.l  (_resload,pc),a2
  1319.                 jsr     (resload_ProtectReadWrite,a2)
  1320.                 ...
  1321.  
  1322.    RESULT
  1323.         a "Exception 'Access Fault'" WHDLoad requester if the protected memory
  1324.         is accessed
  1325.  
  1326.    BUGS
  1327.         the amount of protected areas is currently limited to 16,
  1328.         the page where the SSP points to must not be protected, because if a
  1329.         Access Fault occurs the CPU will be unable in that case to write the
  1330.         exception stackframe, only reset will recover from the resulting
  1331.         Double Bus Fault
  1332.         limitations on MC68020+MC68851:
  1333.           this hardware is currently not supported
  1334.         limitations on MC68030:
  1335.           - 3-byte transfers are not supported (occuring on misaligned
  1336.             longword accesses to page boundaries eg. "tst.l $fff" (assumed
  1337.             4KByte page size))
  1338.           - locked accesses (tas/cas/cas2) are not supported
  1339.         limitations on MC68040:
  1340.           this hardware is currently not supported
  1341.         limitations on MC68060:
  1342.           - misaligned access are not supported (occuring on accesses trough a
  1343.             page boundary, for example "tst.l ($ffe)" (assumed 4KByte page
  1344.             size))
  1345.           - locked accesses (tas/cas) are not supported
  1346.           - instructions which are located on a protected page and access the
  1347.             supervisor portion of the status register will be executed wrong
  1348.             (these instructions will always see the trace bit as 1 and the
  1349.             interrupt level as 7, any modification of the status register
  1350.             supervisor portion will be without effect)
  1351.           - movem instruction may access a protected area without creating a
  1352.             Access Fault exception (only the first bus cycle of the excution
  1353.             unit will be verified for matching a protected area)
  1354.           - move16 and double precision operations (FPU) are unsupported
  1355.           - a "move (mem),(mem)" with overlapping source and destination
  1356.             address which generates an Access Fault because Misalignment
  1357.             will be executed wrong, for example "move.l ($ffc),($ffe)" where
  1358.             page $1000..$1fff is protected and memory before execution
  1359.             contains ($ffc)=$11112222,($1000)=$33334444, after execution
  1360.             $1000 contains $11114444 and not $22224444)
  1361.         unsupported accesses will result in a "Exception 'Access Fault'"
  1362.         WHDLoad requester
  1363.  
  1364.    NOTE
  1365.         requires ws_Version >= 6
  1366.         the MMU must be in use by WHDLoad, otherwise you will get WHDLoad
  1367.         requester "Unacceptible Arguments".
  1368.         only accesses to the user and supervisor data stream are affected
  1369.         (this means not affected are: CPU space accesses (eg getting values
  1370.         from the vector table) and instruction stream accesses)
  1371.  
  1372.    SEE ALSO
  1373.         resload_ProtectRead, resload_ProtectWrite, resload_ProtectRemove
  1374.  
  1375. WHDLoad/resload_ProtectRemove
  1376.  
  1377.    NAME
  1378.         resload_ProtectRemove -- remove protection from memory area
  1379.  
  1380.    SYNOPSIS
  1381.         resload_ProtectRemove(length, address)
  1382.                                 D0      A0
  1383.                                ULONG   APTR
  1384.  
  1385.    FUNCTION
  1386.         remove a previously created protection
  1387.         the specified area must exactly match the previously protected area
  1388.  
  1389.    INPUTS
  1390.         length  - size of the memory area to protected
  1391.         address - start address of the memory area to protected
  1392.  
  1393.    EXAMPLE
  1394.                 ...
  1395.                 moveq   #4,d0                   ;one longword
  1396.                 lea     $64,a0                  ;address
  1397.                 move.l  (_resload,pc),a2
  1398.                 jsr     (resload_ProtectRemove,a2)
  1399.                 ...
  1400.  
  1401.    RESULT
  1402.  
  1403.    BUGS
  1404.  
  1405.    NOTE
  1406.         requires ws_Version >= 6
  1407.  
  1408.    SEE ALSO
  1409.         resload_ProtectRead, resload_ProtectWrite, resload_ProtectWrite
  1410.  
  1411. WHDLoad/resload_ProtectSMC
  1412.  
  1413.    NAME
  1414.         resload_ProtectSMC -- detect self modifying code
  1415.  
  1416.    SYNOPSIS
  1417.         resload_ProtectSMC(length, address)
  1418.                              D0      A0
  1419.                             ULONG   APTR
  1420.  
  1421.    FUNCTION
  1422.         Enables automatically detection of self modifying code (SMC) in the
  1423.         selected area. The selected area will be write protected using the
  1424.         resload_ProtectWrite mechanism, additional the trace mode will be
  1425.         activated and a special handler for trace exceptions installed.
  1426.         Each write access to the selected area will be logged to a private
  1427.         memory location. On each instruction executed inside the selected
  1428.         memory the trace handler verifies, if the instruction has been
  1429.         previosly modified. If an executed instruction has been altered
  1430.         the installed program will be terminated and WHDLoad will show an
  1431.         requester informing about the SMC-detection.
  1432.         To determinate the size of instructions a table is used. This table
  1433.         contains the opcode size in words depending on the first instruction
  1434.         word. If the trace exception handler encounters a instruction with
  1435.         unknown size WHDLoad aborts with an "Internal Error #3". The reason
  1436.         for this maybe an illegal instruction, an instruction available only
  1437.         in higher processors than 68000 or an incompleteness of the internal
  1438.         instruction size table (IST). To aid this, during the initialisation
  1439.         of this function WHDLoad searches first for an external IST. This
  1440.         must be located in the same directory where the WHDLoad executable
  1441.         resides and is searched as "PROGDIR:WHDLoad.IST". If there is no
  1442.         external IST the internal one is used. The source of the internal
  1443.         IST is included in source representation and can be used to build a
  1444.         external IST. If you encounter missing 68000 instructions in the
  1445.         current IST you are demand to inform the author of WHDLoad to
  1446.         include appropriate extensions in the next WHDLoad release.
  1447.         Due the large exception overhead the execution speed in the selected
  1448.         area will strongly slow down. To improve performance it is therefore
  1449.         recommend to relocate the SSP to a Fast-Memory location using
  1450.         ws_ExpMem and appropriate initialistion and modification of the
  1451.         installed program if required.
  1452.         To maximize performance during the initialisation of this function
  1453.         the BaseMem area will be set to NC, the ExpMem and Slave to CB and
  1454.         all caches will be enabled (resload_SetCPU).
  1455.         Because Resload functions cannot be executed in trace mode, the
  1456.         trace must disabled before and enabled after calling any Resload
  1457.         function following the SMC-detection has been setup (see example).
  1458.  
  1459.  
  1460.    INPUTS
  1461.         length  - size of the memory area to protected
  1462.         address - start address of the memory area to protected
  1463.  
  1464.         the area to protect must be located inside the BaseMem or ExpMem
  1465.  
  1466.    EXAMPLE
  1467.  
  1468.         enable SMC-detection for the area $10000..$3e000:
  1469.                 ...
  1470.                 move.l  #$2e000,d0              ;one longword
  1471.                 lea     $10000,a0               ;address
  1472.                 move.l  (_resload,pc),a2
  1473.                 jsr     (resload_ProtectSMC,a2)
  1474.                 ...
  1475.  
  1476.         load data after enabling the SMC-detection (assumed all time in
  1477.         supervisor mode!):
  1478.                 ...
  1479.                 move    sr,d3                   ;save sr
  1480.                 move    #$2000,sr               ;disable trace mode
  1481.                 move.l  (_resload,pc),a2
  1482.                 jsr     (resload_DiskLoad,a2)
  1483.                 move    d3,sr                   ;restore sr
  1484.                 ...
  1485.  
  1486.    RESULT
  1487.  
  1488.    BUGS
  1489.         Currently supported is only 68030 and 68060. For limitations and
  1490.         restrictions regarding the MMU related part of operation see the BUGS
  1491.         section of resload_ProtectWrite.
  1492.         You must not protect the page where the SSP points to, if you do so
  1493.         an Double Bus Fault will occure because the CPU will be unable to
  1494.         write the exception stackframe, only reset will recover from a Double
  1495.         Bus Fault
  1496.  
  1497.    NOTE
  1498.         requires ws_Version >= 10
  1499.         the MMU must be in use by WHDLoad, otherwise you will get WHDLoad
  1500.         requester "Unacceptible Arguments"
  1501.         there must no resload_Protect* active at the same time
  1502.  
  1503.    SEE ALSO
  1504.         resload_ProtectWrite, resload_SetCPU
  1505.  
  1506. WHDLoad/resload_ProtectWrite
  1507.  
  1508.    NAME
  1509.         resload_ProtectWrite -- mark memory as write protected
  1510.  
  1511.    SYNOPSIS
  1512.         resload_ProtectWrite(length, address)
  1513.                                D0      A0
  1514.                               ULONG   APTR
  1515.  
  1516.    FUNCTION
  1517.         protect the selected area against writing by the processor
  1518.         the area to protect must be located inside BaseMem or ExpMem
  1519.  
  1520.    INPUTS
  1521.         length  - size of the memory area to protected
  1522.         address - start address of the memory area to protected
  1523.  
  1524.    EXAMPLE
  1525.                 ...
  1526.                 moveq   #4,d0                   ;one longword
  1527.                 lea     $64,a0                  ;address
  1528.                 move.l  (_resload,pc),a2
  1529.                 jsr     (resload_ProtectWrite,a2)
  1530.                 ...
  1531.  
  1532.    RESULT
  1533.  
  1534.    BUGS
  1535.         the amount of protected areas is currently limited to 16,
  1536.         the page where the SSP points to must not be protected, because if a
  1537.         Access Fault occurs the CPU will be unable in that case to write the
  1538.         exception stackframe, only reset will recover from the resulting
  1539.         Double Bus Fault
  1540.         limitations on MC68020+MC68851:
  1541.           this hardware is currently not supported
  1542.         limitations on MC68030:
  1543.           - 3-byte transfers are not supported (occuring on misaligned
  1544.             longword accesses to page boundaries eg. "tst.l $fff" (assumed
  1545.             4KByte page size))
  1546.           - locked accesses (tas/cas/cas2) are not supported
  1547.         limitations on MC68040:
  1548.           this hardware is currently not supported
  1549.         limitations on MC68060:
  1550.           - misaligned access are not supported (occuring on accesses trough a
  1551.             page boundary, for example "tst.l ($ffe)" (assumed 4KByte page
  1552.             size))
  1553.           - locked accesses (tas/cas) are not supported
  1554.           - instructions which are located on a protected page and access the
  1555.             supervisor portion of the status register will be executed wrong
  1556.             (these instructions will always see the trace bit as 1 and the
  1557.             interrupt level as 7, any modification of the status register
  1558.             supervisor portion will be without effect)
  1559.           - movem instruction may access a protected area without creating a
  1560.             Access Fault exception (only the first bus cycle of the excution
  1561.             unit will be verified for matching a protected area)
  1562.           - move16 and double precision operations (FPU) are unsupported
  1563.           - a "move (mem),(mem)" with overlapping source and destination
  1564.             address which generates an Access Fault because Misalignment
  1565.             will be executed wrong, for example "move.l ($ffc),($ffe)" where
  1566.             page $1000..$1fff is protected and memory before execution
  1567.             contains ($ffc)=$11112222,($1000)=$33334444, after execution
  1568.             $1000 contains $11114444 and not $22224444)
  1569.         unsupported accesses will result in a "Exception 'Access Fault'"
  1570.         WHDLoad requester
  1571.  
  1572.    NOTE
  1573.         requires ws_Version >= 6
  1574.         the MMU must be in use by WHDLoad, otherwise you will get WHDLoad
  1575.         requester "Unacceptible Arguments".
  1576.         only accesses to the user and supervisor data stream are affected
  1577.         (this means not affected are: CPU space accesses (eg getting values
  1578.         from the vector table) and instruction stream accesses)
  1579.  
  1580.    SEE ALSO
  1581.         resload_ProtectRead, resload_ProtectReadWrite, resload_ProtectRemove
  1582.  
  1583. WHDLoad/resload_Relocate
  1584.  
  1585.    NAME
  1586.         resload_Relocate -- relocate AmigaDOS executable
  1587.  
  1588.    SYNOPSIS
  1589.         size = resload_Relocate(address, tags)
  1590.          D0                       A0      A1
  1591.         ULONG                    APTR   STRUCT
  1592.  
  1593.    FUNCTION
  1594.         relocate an standard AmigaDOS executable in memory
  1595.  
  1596.    INPUTS
  1597.         address - the start address of the executable in memory, this is the
  1598.                   source and also the destination address, i.e.
  1599.                   resload_Relocate will relocates the executable over itself
  1600.                   (a multi pass technique is used)
  1601.         tags    - currently there are no tags so this must be set to NULL
  1602.  
  1603.    EXAMPLE
  1604.                 ...
  1605.                 lea     (_main,pc),a0           ;name
  1606.                 lea     $400,a3                 ;A3 = address for program
  1607.                 move.l  a3,a1                   ;destination
  1608.                 move.l  (_resload,pc),a2
  1609.                 jsr     (resload_LoadFileDecrunch,a2)
  1610.                 move.l  a3,a0                   ;address
  1611.                 sub.l   a1,a1                   ;tags
  1612.                 jsr     (resload_Relocate,a2)
  1613.                 ...
  1614.                 jmp     (a3)                    ;start the program
  1615.                 ...
  1616.  
  1617.         _main   dc.b    "main-program",0
  1618.  
  1619.    RESULT
  1620.         size - size of the relocated executable
  1621.                (this may be more or less than the size of the executable file,
  1622.                depending on BSS hunks contained in the executable)
  1623.  
  1624.    BUGS
  1625.         the routine supports all hunks supported by Kickstart 1.3 except
  1626.         OVERLAY, anyway it is only tested with a limited amount of
  1627.         executables, so please report any problems or bugs
  1628.  
  1629.    NOTE
  1630.         the function uses stack for variables, the amount depends on the
  1631.         number of hunks in the executable and can be calculated as
  1632.         "used stack = hunks * 16 + 32"
  1633.         currently the executable must not contain more than 256 hunks (also
  1634.         AmigaDOS allows not more than 256 hunks)
  1635.         the routine performs automatically a resload_FlushCache before
  1636.         returning
  1637.  
  1638.    SEE ALSO
  1639.  
  1640. WHDLoad/resload_SaveFile
  1641.  
  1642.    NAME
  1643.         resload_SaveFile -- write memory to a file
  1644.  
  1645.    SYNOPSIS
  1646.         success,errorcode = resload_SaveFile(size, name, address)
  1647.           D0       D1                         D0    A0      A1
  1648.          BOOL     ULONG                     ULONG  CPTR    APTR
  1649.  
  1650.    FUNCTION
  1651.         write specified memory area to file using specified name
  1652.  
  1653.    INPUTS
  1654.         size    - amount of bytes to write
  1655.         name    - name of file to write
  1656.         address - memory address of buffer to write
  1657.  
  1658.    EXAMPLE
  1659.                 ...
  1660.                 move.l  #512,d0                 ;size
  1661.                 lea     (_save,pc),a0           ;name
  1662.                 lea     $5ac20,a1               ;source
  1663.                 move.l  (_resload,pc),a2
  1664.                 jsr     (resload_SaveFile,a2)
  1665.                 ...
  1666.  
  1667.         _save   dc.b    "saved",0
  1668.  
  1669.    RESULT
  1670.         success   - TRUE on success
  1671.         errorcode - 0 on success
  1672.                     otherwise a dos-errorcode from dos.IoErr()
  1673.         if WHDLF_NoError is set, the function only returns on success
  1674.  
  1675.    BUGS
  1676.  
  1677.    NOTE
  1678.  
  1679.    SEE ALSO
  1680.         resload_SaveFileOffset
  1681.  
  1682. WHDLoad/resload_SaveFileOffset
  1683.  
  1684.    NAME
  1685.         resload_SaveFileOffset -- write memory to a file at offset
  1686.  
  1687.    SYNOPSIS
  1688.         success,error = resload_SaveFileOffset(size, offset, name, address)
  1689.           D0     D1                             D0     D1     A0      A1
  1690.          BOOL   ULONG                          ULONG  ULONG  CPTR    APTR
  1691.  
  1692.    FUNCTION
  1693.         write specified memory area to file at specified offset using
  1694.         specified name
  1695.  
  1696.    INPUTS
  1697.         size    - amount of bytes to write
  1698.         offset  - offset in the file to write
  1699.         name    - name of file to write
  1700.         address - memory address of buffer to write
  1701.  
  1702.    EXAMPLE
  1703.                 ...
  1704.                 move.l  #512,d0                 ;size
  1705.                 move.l  #$4000,d1               ;offset
  1706.                 lea     (_save,pc),a0           ;name
  1707.                 lea     $5ac20,a1               ;source
  1708.                 move.l  (_resload,pc),a2
  1709.                 jsr     (resload_SaveFileOffset,a2)
  1710.                 ...
  1711.  
  1712.         _save   dc.b    "saved",0
  1713.  
  1714.    RESULT
  1715.         success   - TRUE on success
  1716.         errorcode - 0 on success
  1717.                     otherwise a dos-errorcode from dos.IoErr()
  1718.         if WHDLF_NoError is set, the function only returns on success
  1719.  
  1720.    BUGS
  1721.  
  1722.    NOTE
  1723.         requires ws_Version >= 5
  1724.  
  1725.    SEE ALSO
  1726.         resload_SaveFile
  1727.  
  1728. WHDLoad/resload_SetCACR
  1729.  
  1730.    NAME
  1731.         resload_SetCACR -- set cachebility for BaseMem
  1732.  
  1733.    SYNOPSIS
  1734.         old = resload_SetCACR(new, mask)
  1735.          D0                    D0   D1
  1736.        ULONG                 ULONG ULONG
  1737.  
  1738.    FUNCTION
  1739.         modifies the cachebility for BaseMem, using this routine the
  1740.         instruction and the data cache can be enabled and disabled,
  1741.         the changes will affect the CACR (Cache Control Register) and
  1742.         the MMU-tables if it is used by WHDLoad
  1743.  
  1744.    INPUTS
  1745.         new  - new cache status
  1746.         mask - status bits to change
  1747.  
  1748.         valid values for new and mask are:
  1749.                 CACRF_EnableI - instruction cache
  1750.                 CACRF_EnableD - data cache
  1751.         (bits are defined in the standard include file "exec/execbase.i")
  1752.  
  1753.    EXAMPLE
  1754.         to enable instruction cache:
  1755.                 ...
  1756.                 move.l  #CACRF_EnableI,d0       ;new status
  1757.                 move.l  d0,d1                   ;status to change
  1758.                 move.l  (_resload,pc),a2
  1759.                 jsr     (resload_SetCACR,a2)
  1760.                 ...
  1761.  
  1762.    RESULT
  1763.         old - old cache status
  1764.  
  1765.    BUGS
  1766.  
  1767.    NOTE
  1768.         it is safe to call this routine from User or Supervisor mode and
  1769.         independend from the actual CPU type (also on 68000/010)
  1770.         if WHDLoad is launched with the option NoCache/S this routine will
  1771.         return without changing anything (BaseMem is always noncacheable)
  1772.         don't wonder if you see in the coredump or in a freezer that caches
  1773.         are enabled even if not enabled by the Slave: if the MMU is used by
  1774.         WHDLoad and no caches are switched on by the Slave, WHDLoad marks the
  1775.         BaseMem using the MMU as noncacheable-serialized, and enables both
  1776.         caches so that the memory of WHDLoad and the Slave are cachable to
  1777.         increase performance
  1778.         the routine performs automatically a resload_FlushCache before
  1779.         returning
  1780.  
  1781.    SEE ALSO
  1782.         resload_SetCPU, resload_FlushCache
  1783.  
  1784. WHDLoad/resload_SetCPU
  1785.  
  1786.    NAME
  1787.         resload_SetCPC -- control CPU setup
  1788.  
  1789.    SYNOPSIS
  1790.         old = resload_SetCPU(new, mask)
  1791.          D0                   D0   D1
  1792.        ULONG                ULONG ULONG
  1793.  
  1794.    FUNCTION
  1795.         change cachebility of memory areas and change the CPU setup
  1796.         see include file "whdload.i" for supported bit sets
  1797.  
  1798.    INPUTS
  1799.         new  - new setup
  1800.         mask - parts of the current setup to change
  1801.  
  1802.    EXAMPLE
  1803.         to enable the only instruction cache for BaseMem and ExpMem:
  1804.                 ...
  1805.                 move.l  #WCPUF_Base_WT|WCPUF_Exp_CB|WCPUF_IC,d0
  1806.                 move.l  #WCPUF_Base|WCPUF_Exp|WCPUF_IC|WCPUF_DC,d1
  1807.                 move.l  (_resload,pc),a2
  1808.                 jsr     (resload_SetCPU,a2)
  1809.                 ...
  1810.  
  1811.    RESULT
  1812.         old - the setup before
  1813.  
  1814.    BUGS
  1815.  
  1816.    NOTE
  1817.         it is safe to call this routine from User or Supervisor mode and
  1818.         independend from the actual CPU type (also on 68000/010)
  1819.         if WHDLoad is launched with the option NoCache/S this routine will
  1820.         return without changing anything
  1821.         don't wonder if you see in the coredump or in a freezer that caches
  1822.         are enabled even if not enabled by the Slave: if the MMU is used by
  1823.         WHDLoad and no caches are switched on by the Slave, WHDLoad marks the
  1824.         memory of the installed program using the MMU as noncacheable-
  1825.         serialized, and enables both caches so that the memory of WHDLoad is
  1826.         cachable to increase performance
  1827.         the routine performs automatically a resload_FlushCache before
  1828.         returning
  1829.  
  1830.    SEE ALSO
  1831.  
  1832.  
  1833. WHDLoad.Slave/--Overview--
  1834.  
  1835. The WHDLoad.Slave contains the interface code which makes the installed
  1836. program able to load his files from harddisk. Additional it should realize
  1837. the possibility to quit the program to return to the OS.
  1838.  
  1839.    FORMAT
  1840.         is a standard amiga executable
  1841.    ATTENTION
  1842.         the Slave MUST consist of only ONE hunk (ONE section)
  1843.         the Slave MUST be 100% PC-relative
  1844.  
  1845.    STRUCTURE
  1846.         at the top of the Slave is "WHDLoadSlave" structure, after this
  1847.         follows the specific code and data
  1848.  
  1849.              STRUCTURE  WHDLoadSlave,0
  1850.                 STRUCT  ws_Security,4
  1851.                 STRUCT  ws_ID,8
  1852.                 UWORD   ws_Version
  1853.                 UWORD   ws_Flags
  1854.                 ULONG   ws_BaseMemSize
  1855.                 ULONG   ws_ExecInstall
  1856.                 RPTR    ws_GameLoader
  1857.                 RPTR    ws_CurrentDir
  1858.                 RPTR    ws_DontCache
  1859.              (  LABEL   ws_SIZEOF_pre_v4  )
  1860.                 UBYTE   ws_keydebug
  1861.                 UBYTE   ws_keyexit
  1862.              (  LABEL   ws_SIZEOF_pre_v8  )
  1863.                 ULONG   ws_ExpMem
  1864.              (  LABEL   ws_SIZEOF_pre_v10 )
  1865.                 RPTR    ws_name
  1866.                 RPTR    ws_copy
  1867.                 RPTR    ws_info
  1868.                 LABEL   ws_SIZEOF
  1869.  
  1870.         ws_Security
  1871.                 the code
  1872.                         moveq #-1,d0
  1873.                         rts
  1874.                 to avoid problems if somebody tries execute the Slave directly
  1875.  
  1876.         ws_ID
  1877.                 the string "WHDLOADS" to identify the program as a Slave
  1878.  
  1879.         (use the macro SLAVE_HEADER defined in the include file "whdload.i" to
  1880.         create the entries ws_Security and ws_ID)
  1881.  
  1882.         ws_Version
  1883.                 the version of WHDLoad that is required by the Slave,
  1884.                 some resload functions need at least a specific version of
  1885.                 WHDLoad, e.g. to use resload_CRC16 you must set ws_Version
  1886.                 to 3 or higher
  1887.                 on the other side the size of the WHDLoadSlave structure
  1888.                 differs for different Slave versions, e.g. if you set
  1889.                 ws_Version to 4 or higher you MUST initialize the fields
  1890.                 ws_keydebug and ws_keyexit and so on
  1891.  
  1892.         ws_Flags
  1893.                 WHDLF_Disk / WHDLB_Disk
  1894.                    this flag should enabled if the program uses
  1895.                    disk images (the result is a different working Preload/S)
  1896.                    (starting WHDLoad 0.143 this flag is obsolete)
  1897.                 WHDLF_NoError / WHDLB_NoError
  1898.                    if enabled every error occuring in a resload_#? function
  1899.                    lets WHDLoad immedately quit, and prompt an error requester
  1900.                    about the reason
  1901.                    using this flag it is not neccessary that the Slave checks
  1902.                    the return code resload_#? functions, it can be sure that
  1903.                    if a function returns it was successful (this will make the
  1904.                    Slave more simple)
  1905.                 WHDLF_EmulTrap / WHDLB_EmulTrap
  1906.                    this flag has only effect if the VBR is moved by WHDLoad
  1907.                    (i.e. the machine is at least a 68010 and the tooltype
  1908.                    NoVBRMove is not set)
  1909.                    if the flag is set all "trap #0..15"'s are emulated by the
  1910.                    exception handler in WHDLoad like the autovectors, i.e.
  1911.                    the handler checks if the vector ($80-$bc) is initialized
  1912.                    by the program, and if it is the routine will be called by
  1913.                    the handler
  1914.                 WHDLF_NoDivZero / WHDLB_NoDivZero
  1915.                    this flag has only effect if the VBR is moved by WHDLoad
  1916.                    (i.e. the machine is at least a 68010 and the tooltype
  1917.                    NoVBRMove is not set)
  1918.                    if the flag is set and a "Division by Zero" exception
  1919.                    occurs WHDLoad will not quit with an requester, but a
  1920.                    RTE will be performed
  1921.                    this maybe useful if you don't want use the option
  1922.                    NoVBRMove but the demo/game performs divisions by zero
  1923.                 WHDLF_Req68020 / WHDLB_Req68020
  1924.                    this flag indicates that the Slave/installed program
  1925.                    requires at least a MC68020 CPU, WHDLoad will check at
  1926.                    startup if this requirement matches, if it doesn't the
  1927.                    program will be terminated with an appropriate requester
  1928.                 WHDLF_ReqAGA / WHDLB_ReqAGA
  1929.                    this flag indicates that the Slave/installed program
  1930.                    requires at least the AGA chipset, WHDLoad will check at
  1931.                    startup if this requirement matches, if it doesn't the
  1932.                    program will be terminated with an appropriate requester
  1933.                 WHDLF_NoKbd / WHDLB_NoKbd
  1934.                    this flag says WHDLoad, that it doesn't should reply the
  1935.                    keyboard if a key was pressed, this must be used with
  1936.                    programs which doesn't check the keyboard from the PORTS
  1937.                    interrupt ($68), background: in normal operation when
  1938.                    NoVBRMove is inactive, WHDLoad checks if a key was pressed
  1939.                    on each interrupt, if a key has been pressed it checks the
  1940.                    rawkey code against QuitKey, DebugKey and FreezeKey, if it
  1941.                    doesn't match it looks if there is a initialized PORTS
  1942.                    interrupt ($68), if there is no, it replies the keyboard
  1943.                    that the keycode has been received, therefore the installed
  1944.                    program if it checks the keyboard from e.g. the VBI will
  1945.                    never receive any keycode, this flag avoids this behavior
  1946.                 WHDLF_EmulLineA / WHDLB_EmulLineA
  1947.                    this flag has only effect if the VBR is moved by WHDLoad
  1948.                    (i.e. the machine is at least a 68010 and the tooltype
  1949.                    NoVBRMove is not set)
  1950.                    if the flag is set all exceptions "Line-A" (caused by
  1951.                    opcodes starting with %1010) are emulated by the
  1952.                    exception handler in WHDLoad like the autovectors, i.e.
  1953.                    the handler checks if the vector ($28) is initialized
  1954.                    by the program, and if it is the routine which the vector
  1955.                    points to will be called by the handler
  1956.                 WHDLF_EmulTrapV / WHDLB_EmulTrapV
  1957.                    this flag has only effect if the VBR is moved by WHDLoad
  1958.                    (i.e. the machine is at least a 68010 and the tooltype
  1959.                    NoVBRMove is not set)
  1960.                    if the flag is set all exceptions caused by a TrapV
  1961.                    instruction are emulated by the exception handler in
  1962.                    WHDLoad like the autovectors, i.e. the handler checks if
  1963.                    the vector ($1C) is initialized by the program, and if it
  1964.                    is the routine which the vector points to will be called
  1965.                    by the handler
  1966.                 WHDLF_EmulChk / WHDLB_EmulChk
  1967.                    this flag has only effect if the VBR is moved by WHDLoad
  1968.                    (i.e. the machine is at least a 68010 and the tooltype
  1969.                    NoVBRMove is not set)
  1970.                    if the flag is set all exceptions caused by a Chk/Chk2
  1971.                    instruction are emulated by the exception handler in
  1972.                    WHDLoad like the autovectors, i.e. the handler checks if
  1973.                    the vector ($18) is initialized by the program, and if it
  1974.                    is the routine which the vector points to will be called
  1975.                    by the handler
  1976.                 WHDLF_EmulPriv / WHDLB_EmulPriv
  1977.                    this flag has only effect if the VBR is moved by WHDLoad
  1978.                    (i.e. the machine is at least a 68010 and the tooltype
  1979.                    NoVBRMove is not set)
  1980.                    if the flag is set all privilege violation exceptions are
  1981.                    emulated by the exception handler in WHDLoad like the
  1982.                    autovectors, i.e. the handler checks if the vector ($20) is
  1983.                    initialized by the program, and if it is the routine which
  1984.                    the vector points to will be called by the handler
  1985.                 WHDLF_EmulLineF / WHDLB_EmulLineF
  1986.                    this flag has only effect if the VBR is moved by WHDLoad
  1987.                    (i.e. the machine is at least a 68010 and the tooltype
  1988.                    NoVBRMove is not set)
  1989.                    if the flag is set all exceptions "Line-F" (caused by
  1990.                    opcodes starting with %1010) are emulated by the
  1991.                    exception handler in WHDLoad like the autovectors, i.e.
  1992.                    the handler checks if the vector ($2C) is initialized
  1993.                    by the program, and if it is the routine which the vector
  1994.                    points to will be called by the handler
  1995.  
  1996.         ws_BaseMemSize
  1997.                 the size of the memory that is required by the program
  1998.                 the BaseMemory starts an $00000000 and ends at ws_BaseMemSize
  1999.                 (BaseMemory is always ChipMem)
  2000.                 this value must be multiple of $1000
  2001.                 the valid minimum is $2000, the maximum $200000
  2002.  
  2003.         ws_ExecInstall
  2004.                 obsolete, must be set to 0
  2005.  
  2006.         ws_GameLoader
  2007.                 a relative (to the start of the structure) 16-bit pointer
  2008.                 to the start code of the Slave
  2009.  
  2010.         ws_CurrentDir
  2011.                 a relative (to the start of the structure) 16-bit pointer
  2012.                 to a 0 terminated string which is the name of the path
  2013.                 where all files are stored (sub directory)
  2014.                 if no sub directory is used initialize this with 0
  2015.                 WHDLoad will change into this directory on startup
  2016.                 the path must be relative; you MUST NOT use any fucking lame
  2017.                 assignments
  2018.             BACKGROUND: if the assignment is not active on runtime the
  2019.                 dos.library will try to show a "Insert Disk ..." requester,
  2020.                 but intuition.library is locked, -> the system will hang
  2021.                 (deadlock) the user has only one alternative -> REBOOT
  2022.  
  2023.         ws_DontCache
  2024.                 a relative (to the start of the structure) 16-bit pointer
  2025.                 to a 0 terminated string which is a standard AmigaDOS
  2026.                 pattern (dos.ParsePattern, dos.MatchPattern)
  2027.                 all files matching this pattern are not cached by WHDLoad
  2028.                 this may be useful for savegames
  2029.                 if you dont want to use set the entry to 0
  2030.                 starting WHDLoad version 0.107 this is obsolete, because saved
  2031.                 files will be written also to the file cache
  2032.  
  2033.       the following variables are only evaluated by WHDLoad if ws_Version
  2034.       is set to >= 4
  2035.       the following variables MUST be initialized if you set ws_Version
  2036.       to >= 4
  2037.  
  2038.         ws_keydebug
  2039.                 the raw key code to exit with debug
  2040.                 this variable will be overwritten by WHDLoad if the option
  2041.                 DebugKey= is set in the global config or as CLI argument or
  2042.                 ToolType with the specified value from there
  2043.                 if the Slave provides an own handler to support a debug option
  2044.                 via the keyboard it should use this entry for comparision, so
  2045.                 it will be possible for the user to change the default key
  2046.                 suggestion from the Slave
  2047.                 this entry is also used by WHDLoad's internal handler if the
  2048.                 VBR is moved (requires 68010+ and that NoVBRMove is not set)
  2049.                 (recommend is $58 = "F9")
  2050.  
  2051.         ws_keyexit
  2052.                 the raw key code to exit
  2053.                 similar to ws_keydebug
  2054.                 (recommend is $59 = "F10")
  2055.  
  2056.       the following variables are only evaluated by WHDLoad if ws_Version
  2057.       is set to >= 8
  2058.       the following variables MUST be initialized if you set ws_Version
  2059.       to >= 8
  2060.  
  2061.         ws_ExpMem
  2062.                 if the installed program requires expansion memory, the size
  2063.                 must be specified here, WHDLoad will allocate a memory block
  2064.                 of this size and writes a pointer to the start of the
  2065.                 allocated memory back to this entry, the memory is granted to
  2066.                 be aligned to $1000 (4096 bytes), the size specified must be
  2067.                 an multiple of $1000 (4096), if WHDLoad fails to allocate
  2068.                 this memory it terminates with an appropriate error requester,
  2069.                 that means the Slave will always get a valid pointer here
  2070.                 - starting WHDLoad version 10.2 the value can be negative,
  2071.                 which means that the memory is optional and not absolute
  2072.                 required, WHDLoad will try to allocate it and if it fails it
  2073.                 will set ws_ExpMem to zero, the Slave has to check ws_ExpMem
  2074.                 therefore
  2075.  
  2076.       the following variables are only evaluated by WHDLoad if ws_Version
  2077.       is set to >= 10
  2078.       the following variables MUST be initialized if you set ws_Version
  2079.       to >= 10
  2080.  
  2081.         ws_name
  2082.                 a relative (to the start of the structure) 16-bit pointer
  2083.                 to a 0 terminated string containing the name of the installed
  2084.                 program, e.g. "Super Hang Off"
  2085.         ws_copy
  2086.                 a relative (to the start of the structure) 16-bit pointer
  2087.                 to a 0 terminated string containing the copyright of the
  2088.                 installed program, the string should start with the year
  2089.                 followed by the company holding the copyright, multiple years
  2090.                 or companies should be separated with ", "
  2091.                 e.g. "1983 Schega, 1989 Bad Dreams"
  2092.         ws_info
  2093.                 a relative (to the start of the structure) 16-bit pointer
  2094.                 to a 0 terminated string containing addional infos about the
  2095.                 installed program, the string may also contain line feeds
  2096.                 ($0a), the character -1 has a special meaning - it results in
  2097.                 a line feed and an additional vertical skip of the half font
  2098.                 height, e.g.:
  2099.                         dc.b    "installed & fixed by Wepl",10
  2100.                         dc.b    "version 1.4 (06.06.2066)",-1
  2101.                         dc.b    "greetings to the world",0
  2102.  
  2103.  
  2104.    CONVENTIONS for ws_GameLoader
  2105.         the status of the system at the moment of calling ws_GameLoader:
  2106.  
  2107.         CPU:
  2108.                 SR   = $2000           Supervisor-mode, all interrupts enabled
  2109.                 SSP  = ws_BaseMemSize  at end of BaseMem
  2110.                 USP  = SSP-$400        at end of BaseMem - 1024
  2111.                 A0   = ResidentLoader  pointer to the resident Jump-Tower
  2112.                 D0-D7/A1-A6 random     (D0=$d0d0d0d0 D1=...)
  2113.  
  2114.                 nothing more is interesting from the Slave programmes point of
  2115.                 view, all special registers like VBR,SFC,DFC,CAAR,CACR,MSP,TC,
  2116.                 MMUSR,CRP,SRP,URP,TT0,TT1,DTT0,DTT1,ITT0,ITT1,PCR,BUSCR are
  2117.                 WHDLoad private and MUST NOT BE CHANGED.
  2118.  
  2119.         BaseMem:
  2120.                 $00000000 = 0
  2121.                 $00000004 = $f0000001  any try to use the execbase should
  2122.                                        create a "Address Error" exception
  2123.                 $00000008 - $00000400
  2124.                           = $CCCCCCCC  if WHDLoad has moved the VBR else
  2125.                           = Handler    the address of a exception handler
  2126.                                        inside WHDLoad
  2127.                 $00000400 - ws_BaseMemSize
  2128.                           = $CCCCCCCC  this memory fill pattern is used to
  2129.                                        easy recognize modified memory
  2130.                 $00001000 = $FFFFFFFE  the copper instruction "CWAIT $ff,$1fe"
  2131.  
  2132.         ExpMem:
  2133.                 the memory is filled with the pattern "$DDDDDDDD"
  2134.  
  2135.         custom:
  2136.                 dmacon = 0             all dma's off
  2137.                 intena = 0             all interrupts off
  2138.                 cop1lc = cop2lc = $1000
  2139.                 a AGA-machine is switched to OCS
  2140.  
  2141.         cia's:
  2142.                 ------- ciaa ------     ------- ciab ------
  2143.                 pra in  = %00000000     pra in  = %00000000
  2144.                 pra out = %11111100     pra out = %11111000
  2145.                 ddra    = %00000011     ddra    = %11000000
  2146.                 prb in  = %00000000     prb in  = %00000000
  2147.                 prb out = %00000000     prb out = %11111111
  2148.                 ddrb    = %00000000     ddrb    = %11111111
  2149.                 ta      =     $21ff     ta      =     $ffff
  2150.                 tb      =     $21ff     tb      =     $ffff
  2151.                 event   =   $000000     event   =   $000000
  2152.                 alarm   =   $ffffff     alarm   = execbase.EClockFrequency
  2153.                 sdr     =       $00     sdr     =       $00
  2154.                 icr     = %00000000     icr     = %00000000
  2155.                 icm     = %00001000     icm     = %00000000
  2156.                 cra     = %00000000     cra     = %00000000
  2157.                 crb     = %00000000     crb     = %00000000
  2158.  
  2159.    SEE ALSO
  2160.         example Slaves
  2161.  
  2162.