home *** CD-ROM | disk | FTP | other *** search
/ The Best of Mecomp Multimedia 2 / MECOMP-CD-II.iso / amiga / tools / libs / xfd / developper / autodoc / xfdsub.doc < prev   
Encoding:
Text File  |  1998-03-01  |  11.1 KB  |  327 lines
  1. TABLE OF CONTENTS
  2.  
  3. xfdForeman/--Overview--
  4. xfdSlave/--Overview--
  5. xfdSlave/DecrunchBufferXYZ
  6. xfdSlave/DecrunchSegmentXYZ
  7. xfdSlave/RecogBufferXYZ
  8. xfdSlave/RecogSegmentXYZ
  9. xfdSlave/ScanDataXYZ
  10. xfdSlave/VerifyDataXYZ
  11.  
  12. xfdForeman/--Overview--                               xfdForeman/--Overview--
  13.  
  14. The xfdForeman structure is just some kind of header for external slaves.
  15. It protects the slaves from being executed accidentally by having a small
  16. piece of code (moveq #-1,d0 : rts) in the first 4 bytes.
  17. The master can identify a valid bunch of external slaves by checking the
  18. first few bytes of the file for the foreman identification.
  19. Finally, a foreman holds the pointer to a linked list of slaves and thus
  20. enables the master to work with these slaves.
  21.  
  22. xfdSlave/--Overview--                                   xfdSlave/--Overview--
  23.  
  24. The xfdSlave structure is the heart of the whole library system. Each slave
  25. enables the master to recognize and decrunch packed files. Additionally,
  26. slaves of the type XFDPFB_RELOC can recognize and decrunch segments.
  27. Slaves with XFDPFB_DATA flag set contain routines for data scanning and data
  28. verification.
  29.  
  30. Therefore each slave contains 4 routines that are called from the master.
  31. Pointers to these are stored in xfds_RecogBuffer and xfds_DecrunchBuffer.
  32. XFDPFB_RELOC slaves have xfds_RecogSegment and xfds_DecrunchSegment
  33. initialized, XFDPFB_DATA slaves use xfds_ScanData and xfds_VerifyData.
  34.  
  35. All routines have one thing in common: the CPU registers D0/D1/A0/A1 are
  36. so-called scratch registers, they may change during execution, all other
  37. registers must remain unchanged. CPU register A6 holds a pointer to the
  38. xfdMasterBase structure. See chapters below for a description of the slave
  39. routines.
  40.  
  41. ALL SLAVE ROUTINES MUST BE REENTRANT! NEVER STORE ANY DATA IN STATIC MEMORY
  42. AREAS, USE THE STACK OR SOME ALLOCATED MEMORY INSTEAD! REMEMBER THAT THE
  43. ROUTINES MIGHT BE CALLED BY SEVERAL PROGRAMS AT THE SAME TIME!
  44.  
  45. The name of the packer that is supported by the slave and the flags that
  46. describe the packer are stored in xfds_PackerName and xfds_PackerFlags.
  47.  
  48. (V36) Internal slaves all have an unique ID value stored in xfds_SlaveID.
  49. This field should be set to NULL for external slaves.
  50.  
  51. (V36) If you have written a slave that should replace an internal one
  52. because it's faster or otherwise enhanced, simply put the ID of the slave
  53. to be replaced in xfds_ReplaceID. The old slave will then be taken out of
  54. the list of used slaves. Otherwise, xfds_ReplaceID must be NULL.
  55.  
  56. (V36) xfdRecogBuffer() usually only requires a quite small part of a file
  57. to recognize it properly. To avoid reading the whole file for recognition
  58. purposes, you may set xfds_MinBufferSize to the minimum amount of bytes
  59. that is required to recognize the crunched file correctly.
  60. Note that xfdRecogBuffer() uses this value internally to decide whether
  61. a file might be crunched with a packer or not, so you don't have to do
  62. an extra size comparison in your xfds_RecogBuffer function any more.
  63. For packer headers with non-constant sizes, simply set xfds_MinBufferSize
  64. to a value that will ensure correct recognition of all possible files.
  65.  
  66. Whenever you intend to use features of the xfdmaster.library in your slaves
  67. that are marked (V34) or higher, make sure to set xfds_MasterVersion to
  68. the desired version number, otherwise an old library version might crash
  69. while using the new slave.
  70.  
  71. xfdSlave/DecrunchBufferXYZ                         xfdSlave/DecrunchBufferXYZ
  72.  
  73.    NAME
  74.     DecrunchBufferXYZ -- Decrunch file from buffer to buffer.
  75.  
  76.    SYNOPSIS
  77.     result = DecrunchBufferXYZ(bufferinfo)
  78.       D0                           A0
  79.  
  80.     BOOL DecrunchBufferXYZ(struct xfdBufferInfo *);
  81.  
  82.    FUNCTION
  83.     The typical steps of such a routine are:
  84.     - Get length of decrunched file (exactly or a bit too much).
  85.     - Allocate memory (with memtype from xfdbi_TargetBufMemType).
  86.     - Decrunch file from xfdbi_SourceBuffer to xfdbi_TargetBuffer.
  87.     - Initialize all necessary parts of the xfdBufferInfo structure.
  88.     - Set xfdbi_Error if an error occurs.
  89.  
  90.     (V38) It's possible to support decrunching to user buffers.
  91.     This looks something like that:
  92.     - Decrunch file from xfdbi_SourceBuffer to xfdbi_UserTargetBuf.
  93.     - Initialize all necessary parts of the xfdBufferInfo structure.
  94.     - Set xfdbi_Error if an error occurs.
  95.     The XFDPFF_USERTARGET flag must be set in the xfdSlave structure if
  96.     it supports this feature. Whether to allocate an own buffer or use
  97.     the given buffer by the user is determined with XFDFF_USERTARGET in
  98.     the xfdBufferInfo structure.
  99.  
  100.    INPUTS
  101.     bufferinfo - A valid xfdBufferInfo structure that successfully went
  102.                  through a call to xfdRecogBuffer().
  103.  
  104.    RESULT
  105.     result - TRUE if decrunching succeeded, FALSE if something went wrong.
  106.  
  107.    NOTE
  108.     You have to initialize xfds_DecrunchBuffer with a pointer to your
  109.     DecrunchBufferXYZ routine.
  110.  
  111.    SEE ALSO
  112.     Example sourcecodes.
  113.  
  114. xfdSlave/DecrunchSegmentXYZ                       xfdSlave/DecrunchSegmentXYZ
  115.  
  116.    NAME
  117.     DecrunchSegmentXYZ -- Decrunch segment list.
  118.  
  119.    SYNOPSIS
  120.     result = DecrunchSegmentXYZ(segmentinfo)
  121.       D0                             A0
  122.  
  123.     BOOL DecrunchSegmentXYZ(struct xfdSegmentInfo *);
  124.  
  125.    FUNCTION
  126.     There are two possibilities how to decrunch a segment list. The
  127.     first one works like this:
  128.     - Modify decrunch header to make it return to the caller.
  129.     - Call decrunch header.
  130.     - dos.library/UnloadSeg() whole seglist and clear xfdsi_SegList
  131.       if an error occurs and the seglist has already been altered
  132.       in any way.
  133.     - Otherwise only release segments that are no longer necessary.
  134.     - Store BPTR to first hunk of decrunched segment list in
  135.       xfdsi_SegList.
  136.     - Set xfdsi_Error if an error occurs.
  137.  
  138.     The second possibility works the same way as the first with
  139.     the difference that you don't jump to the original code, but you
  140.     include all necessary parts of it (decrunch routine, relocator)
  141.     in your own routine. The big advantage is that you can handle
  142.     error conditions much better because most of the standard decrunch
  143.     headers in executable files have problems with low memory etc.
  144.  
  145.     (V34) If the decruncher allows it, always support XFDPFB_RELMODE.
  146.     That way the caller can determine the type of memory the segments
  147.     should be placed in by initializing xfdsi_RelMode with XFDREL_#?.
  148.  
  149.     Many crunchers don't change the hunk structure of the crunched
  150.     data. If this is the case, you can simply call the decrunch code
  151.     in the segment list and then use xfdRelocate() (V34).
  152.  
  153.    INPUTS
  154.     segmentinfo - A valid xfdSegmentInfo structure that successfully went
  155.                   through a call to xfdRecogSegment().
  156.  
  157.    RESULT
  158.     result - TRUE if decrunching succeeded, FALSE if something went wrong.
  159.  
  160.    NOTE
  161.     You have to initialize xfds_DecrunchSegment with a pointer to your
  162.     DecrunchSegmentXYZ routine.
  163.  
  164.    SEE ALSO
  165.     Example sourcecodes.
  166.  
  167. xfdSlave/RecogBufferXYZ                               xfdSlave/RecogBufferXYZ
  168.  
  169.    NAME
  170.     RecogBufferXYZ -- Recognize crunched file in buffer.
  171.  
  172.    SYNOPSIS
  173.     result = RecogBufferXYZ(buffer, length, rr(V38))
  174.       D0                      A0      D0    A1
  175.  
  176.     BOOL RecogBufferXYZ(APTR, ULONG, struct xfdRecogResult * (V38));
  177.  
  178.    FUNCTION
  179.     This routine should examine the buffer for a crunched file.
  180.     First thing is to check if the size of the file allows it to
  181.     be crunched with the packer in question. After that, simply
  182.     do some compares to figure out if the file has been crunched
  183.     or not.
  184.  
  185.     (V36) You don't have to do any size comparisons if you set
  186.     xfds_MinBufferSize to the minimum amount of bytes that are
  187.     necessary for a file to be crunched with that packer.
  188.  
  189.     (V38) If it's easily possible to determine the length of the
  190.     uncrunched file and the required memory for decrunching already
  191.     in crunched state (only within xfds_MinBufferSize bytes),
  192.     initialize the xfdRecogResult structure with the correct values.
  193.     Set the XFDPFF_RECOGLEN flag in your slave in that case.
  194.     If it's not sure that you can extract the correct lengths only
  195.     from within the given buffer (eg. PowerPacker data files), set
  196.     the flag, support xfdRecogResult and set xfdrr_MinTargetLen and
  197.     xfdrr_FinalTargetLen to -1.
  198.  
  199.    INPUTS
  200.     buffer - Pointer to a buffer that holds the crunched file.
  201.     length - Length of that buffer.
  202.     rr     - (V38) Pointer to xfdRecogResult structure.
  203.  
  204.    RESULT
  205.     result - TRUE if packer has been recognized, else FALSE.
  206.  
  207.    NOTE
  208.     You have to initialize xfds_RecogBuffer with a pointer to your
  209.     RecogBufferXYZ routine.
  210.  
  211.     (V38) The determined xfdrr_MinTargetLen value should be exactly
  212.     correct, otherwise the whole thing is quite meaningless.
  213.  
  214.    SEE ALSO
  215.     Example sourcecodes.
  216.  
  217. xfdSlave/RecogSegmentXYZ                             xfdSlave/RecogSegmentXYZ
  218.  
  219.    NAME
  220.     RecogSegmentXYZ -- Recognize crunched segment list.
  221.  
  222.    SYNOPSIS
  223.     result = RecogSegmentXYZ(seglist)
  224.       D0                       A0
  225.  
  226.     BOOL RecogSegmentXYZ(BPTR);
  227.  
  228.    FUNCTION
  229.     This routine should examine if a segment list is crunched.
  230.     You can check the whole segment list for correct lengths of hunks
  231.     and for contents of hunks if you like. There should be at least
  232.     3 comparations to determine the cruncher.
  233.  
  234.    INPUTS
  235.     seglist - BPTR to first segment.
  236.  
  237.    RESULT
  238.     result - TRUE if packer has been recognized, else FALSE.
  239.  
  240.    NOTE
  241.     You have to initialize xfds_RecogSegment with a pointer to your
  242.     RecogSegmentXYZ routine.
  243.  
  244.    SEE ALSO
  245.     Example sourcecodes.
  246.  
  247. xfdSlave/ScanDataXYZ                                     xfdSlave/ScanDataXYZ
  248.  
  249.    NAME
  250.     ScanDataXYZ -- Recognize crunched data in buffer.
  251.  
  252.    SYNOPSIS
  253.     result = ScanDataXYZ(buffer, length)
  254.       D0                   A0      D0
  255.  
  256.     BOOL ScanDataXYZ(APTR, ULONG);
  257.  
  258.    FUNCTION
  259.     This routine should only test for the usual data ID at exactly the
  260.     address given as buffer. The length is the amount of bytes until
  261.     the end of the whole buffer and is of minor use in this context.
  262.     You may use it if the ID is several bytes long to test if buffer
  263.     is already at its end.
  264.  
  265.    EXAMPLE
  266.     ScanDataS400    moveq    #0,d0
  267.             cmp.l    #'S400',(a0)    ;StoneCracker Data ID
  268.             bne.s    .Exit
  269.             moveq    #1,d0
  270.     .Exit        rts
  271.  
  272.    INPUTS
  273.     buffer - Pointer to a address to scan at.
  274.     length - Length of whole buffer.
  275.  
  276.    RESULT
  277.     result - TRUE if crunched data has been recognized, else FALSE.
  278.  
  279.    NOTE
  280.     You have to initialize xfds_ScanData with a pointer to your
  281.     ScanDataXYZ routine.
  282.  
  283. xfdSlave/VerifyDataXYZ                                 xfdSlave/VerifyDataXYZ
  284.  
  285.    NAME
  286.     VerifyDataXYZ -- Check crunched data and return length.
  287.  
  288.    SYNOPSIS
  289.     length = VerifyDataXYZ(buffer, length)
  290.       D0                     A0      D0
  291.  
  292.     ULONG VerifyDataXYZ(APTR, ULONG);
  293.  
  294.    FUNCTION
  295.     This routine is called after ScanDataXYZ and first has to check if
  296.     the data ID found while scanning is part of a valid data file or
  297.     just some piece of code etc.
  298.  
  299.     If it is a valid data file, it has to calculate the final length
  300.     of the data file starting at the ID until the end. This value will
  301.     then be used for the xfdScanNode structure.
  302.  
  303.    EXAMPLE
  304.     VerifyDataS400    moveq    #$c,d1
  305.             add.l    8(a0),d1    ;crlen
  306.             cmp.l    d0,d1        ;crlen > buflen ??
  307.             bgt.s    .Exit
  308.             move.l    4(a0),d0
  309.             sub.l    8(a0),d0    ;cr > uncr ??
  310.             bmi.s    .Exit
  311.             move.l    d1,d0
  312.             rts
  313.     .Exit        moveq    #0,d0
  314.             rts
  315.  
  316.    INPUTS
  317.     buffer - Pointer to start address of possible data file.
  318.     length - Length of whole buffer.
  319.  
  320.    RESULT
  321.     length - Final length of found data file, else NULL.
  322.  
  323.    NOTE
  324.     You have to initialize xfds_VerifyData with a pointer to your
  325.     VerifyDataXYZ routine.
  326.  
  327.