home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 11 / AACD11.ISO / AACD / System / xfd / autodoc / xfdsub.doc < prev   
Text File  |  2000-06-27  |  13KB  |  340 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.         (V39) xfdmaster.library automatically allocates the buffer when not
  101.         supplied by caller program. You need to set XFDPFF_USERTARGET to use
  102.         that feature. When the Recog function return buffer size -1 (no size
  103.         detection case), buffer allocation is skipped. If the slave returns
  104.         -1 in some cases, you still need to do self-allocation, when
  105.         XFDFF_USERTARGET is not set.
  106.  
  107.    INPUTS
  108.         bufferinfo - A valid xfdBufferInfo structure that successfully went
  109.                      through a call to xfdRecogBuffer().
  110.  
  111.    RESULT
  112.         result - TRUE if decrunching succeeded, FALSE if something went wrong.
  113.  
  114.    NOTE
  115.         You have to initialize xfds_DecrunchBuffer with a pointer to your
  116.         DecrunchBufferXYZ routine.
  117.  
  118.    SEE ALSO
  119.         Example sourcecodes.
  120.  
  121. xfdSlave/DecrunchSegmentXYZ                       xfdSlave/DecrunchSegmentXYZ
  122.  
  123.    NAME
  124.         DecrunchSegmentXYZ -- Decrunch segment list.
  125.  
  126.    SYNOPSIS
  127.         result = DecrunchSegmentXYZ(segmentinfo)
  128.           D0                             A0
  129.  
  130.         BOOL DecrunchSegmentXYZ(struct xfdSegmentInfo *);
  131.  
  132.    FUNCTION
  133.         There are two possibilities how to decrunch a segment list. The
  134.         first one works like this:
  135.         - Modify decrunch header to make it return to the caller.
  136.         - Call decrunch header.
  137.         - dos.library/UnloadSeg() whole seglist and clear xfdsi_SegList
  138.           if an error occurs and the seglist has already been altered
  139.           in any way.
  140.         - Otherwise only release segments that are no longer necessary.
  141.         - Store BPTR to first hunk of decrunched segment list in
  142.           xfdsi_SegList.
  143.         - Set xfdsi_Error if an error occurs.
  144.  
  145.         The second possibility works the same way as the first with
  146.         the difference that you don't jump to the original code, but you
  147.         include all necessary parts of it (decrunch routine, relocator)
  148.         in your own routine. The big advantage is that you can handle
  149.         error conditions much better because most of the standard decrunch
  150.         headers in executable files have problems with low memory etc.
  151.  
  152.         (V34) If the decruncher allows it, always support XFDPFB_RELMODE.
  153.         That way the caller can determine the type of memory the segments
  154.         should be placed in by initializing xfdsi_RelMode with XFDREL_#?.
  155.  
  156.         Many crunchers don't change the hunk structure of the crunched
  157.         data. If this is the case, you can simply call the decrunch code
  158.         in the segment list and then use xfdRelocate() (V34).
  159.  
  160.    INPUTS
  161.         segmentinfo - A valid xfdSegmentInfo structure that successfully went
  162.                       through a call to xfdRecogSegment().
  163.  
  164.    RESULT
  165.         result - TRUE if decrunching succeeded, FALSE if something went wrong.
  166.  
  167.    NOTE
  168.         You have to initialize xfds_DecrunchSegment with a pointer to your
  169.         DecrunchSegmentXYZ routine.
  170.  
  171.    SEE ALSO
  172.         Example sourcecodes.
  173.  
  174. xfdSlave/RecogBufferXYZ                               xfdSlave/RecogBufferXYZ
  175.  
  176.    NAME
  177.         RecogBufferXYZ -- Recognize crunched file in buffer.
  178.  
  179.    SYNOPSIS
  180.         result = RecogBufferXYZ(buffer, length, rr(V38))
  181.           D0                      A0      D0    A1
  182.  
  183.         BOOL RecogBufferXYZ(APTR, ULONG, struct xfdRecogResult * (V38));
  184.  
  185.    FUNCTION
  186.         This routine should examine the buffer for a crunched file.
  187.         First thing is to check if the size of the file allows it to
  188.         be crunched with the packer in question. After that, simply
  189.         do some compares to figure out if the file has been crunched
  190.         or not.
  191.  
  192.         (V36) You don't have to do any size comparisons if you set
  193.         xfds_MinBufferSize to the minimum amount of bytes that are
  194.         necessary for a file to be crunched with that packer.
  195.  
  196.         (V38) If it's easily possible to determine the length of the
  197.         uncrunched file and the required memory for decrunching already
  198.         in crunched state (only within xfds_MinBufferSize bytes),
  199.         initialize the xfdRecogResult structure with the correct values.
  200.         Set the XFDPFF_RECOGLEN flag in your slave in that case.
  201.         If it's not sure that you can extract the correct lengths only
  202.         from within the given buffer (eg. PowerPacker data files), set
  203.         the flag, support xfdRecogResult and set xfdrr_MinTargetLen and
  204.         xfdrr_FinalTargetLen to -1.
  205.         
  206.         (V39) Set xfdrr_MinSourceLen to source length to allow buffer
  207.         truncation checks. The master library checks the source buffer
  208.         size against that value before calling the decrunch function.
  209.         Remember: the size includes header size!
  210.         Ignore that field if you do not know source data size.
  211.  
  212.    INPUTS
  213.         buffer - Pointer to a buffer that holds the crunched file.
  214.         length - Length of that buffer.
  215.         rr     - (V38) Pointer to xfdRecogResult structure.
  216.  
  217.    RESULT
  218.         result - TRUE if packer has been recognized, else FALSE.
  219.  
  220.    NOTE
  221.         You have to initialize xfds_RecogBuffer with a pointer to your
  222.         RecogBufferXYZ routine.
  223.  
  224.         (V38) The determined xfdrr_MinTargetLen value should be exactly
  225.         correct, otherwise the whole thing is quite meaningless.
  226.  
  227.    SEE ALSO
  228.         Example sourcecodes.
  229.  
  230. xfdSlave/RecogSegmentXYZ                             xfdSlave/RecogSegmentXYZ
  231.  
  232.    NAME
  233.         RecogSegmentXYZ -- Recognize crunched segment list.
  234.  
  235.    SYNOPSIS
  236.         result = RecogSegmentXYZ(seglist)
  237.           D0                       A0
  238.  
  239.         BOOL RecogSegmentXYZ(BPTR);
  240.  
  241.    FUNCTION
  242.         This routine should examine if a segment list is crunched.
  243.         You can check the whole segment list for correct lengths of hunks
  244.         and for contents of hunks if you like. There should be at least
  245.         3 comparations to determine the cruncher.
  246.  
  247.    INPUTS
  248.         seglist - BPTR to first segment.
  249.  
  250.    RESULT
  251.         result - TRUE if packer has been recognized, else FALSE.
  252.  
  253.    NOTE
  254.         You have to initialize xfds_RecogSegment with a pointer to your
  255.         RecogSegmentXYZ routine.
  256.  
  257.    SEE ALSO
  258.         Example sourcecodes.
  259.  
  260. xfdSlave/ScanDataXYZ                                     xfdSlave/ScanDataXYZ
  261.  
  262.    NAME
  263.         ScanDataXYZ -- Recognize crunched data in buffer.
  264.  
  265.    SYNOPSIS
  266.         result = ScanDataXYZ(buffer, length)
  267.           D0                   A0      D0
  268.  
  269.         BOOL ScanDataXYZ(APTR, ULONG);
  270.  
  271.    FUNCTION
  272.         This routine should only test for the usual data ID at exactly the
  273.         address given as buffer. The length is the amount of bytes until
  274.         the end of the whole buffer and is of minor use in this context.
  275.         You may use it if the ID is several bytes long to test if buffer
  276.         is already at its end.
  277.  
  278.    EXAMPLE
  279.         ScanDataS400    moveq   #0,d0
  280.                         cmp.l   #'S400',(a0)    ;StoneCracker Data ID
  281.                         bne.s   .Exit
  282.                         moveq   #1,d0
  283.         .Exit           rts
  284.  
  285.    INPUTS
  286.         buffer - Pointer to a address to scan at.
  287.         length - Length of whole buffer.
  288.  
  289.    RESULT
  290.         result - TRUE if crunched data has been recognized, else FALSE.
  291.  
  292.    NOTE
  293.         You have to initialize xfds_ScanData with a pointer to your
  294.         ScanDataXYZ routine.
  295.  
  296. xfdSlave/VerifyDataXYZ                                 xfdSlave/VerifyDataXYZ
  297.  
  298.    NAME
  299.         VerifyDataXYZ -- Check crunched data and return length.
  300.  
  301.    SYNOPSIS
  302.         length = VerifyDataXYZ(buffer, length)
  303.           D0                     A0      D0
  304.  
  305.         ULONG VerifyDataXYZ(APTR, ULONG);
  306.  
  307.    FUNCTION
  308.         This routine is called after ScanDataXYZ and first has to check if
  309.         the data ID found while scanning is part of a valid data file or
  310.         just some piece of code etc.
  311.  
  312.         If it is a valid data file, it has to calculate the final length
  313.         of the data file starting at the ID until the end. This value will
  314.         then be used for the xfdScanNode structure.
  315.  
  316.    EXAMPLE
  317.         VerifyDataS400  moveq   #$c,d1
  318.                         add.l   8(a0),d1        ;crlen
  319.                         cmp.l   d0,d1           ;crlen > buflen ??
  320.                         bgt.s   .Exit
  321.                         move.l  4(a0),d0
  322.                         sub.l   8(a0),d0        ;cr > uncr ??
  323.                         bmi.s   .Exit
  324.                         move.l  d1,d0
  325.                         rts
  326.         .Exit           moveq   #0,d0
  327.                         rts
  328.  
  329.    INPUTS
  330.         buffer - Pointer to start address of possible data file.
  331.         length - Length of whole buffer.
  332.  
  333.    RESULT
  334.         length - Final length of found data file, else NULL.
  335.  
  336.    NOTE
  337.         You have to initialize xfds_VerifyData with a pointer to your
  338.         VerifyDataXYZ routine.
  339.  
  340.