home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / TRSICAT.LZX / CATS_CD2_TRSI / Inc&AD2.1 / Text_Autodocs / disk.doc < prev    next >
Encoding:
Text File  |  1992-09-11  |  6.0 KB  |  230 lines
  1. TABLE OF CONTENTS
  2.  
  3. disk.resource/AllocUnit
  4. disk.resource/FreeUnit
  5. disk.resource/GetUnit
  6. disk.resource/GetUnitID
  7. disk.resource/GiveUnit
  8. disk.resource/ReadUnitID
  9. disk.resource/AllocUnit                               disk.resource/AllocUnit
  10.  
  11.    NAME
  12.        AllocUnit - allocate a unit of the disk
  13.  
  14.    SYNOPSIS
  15.        Success = AllocUnit( unitNum ), DRResource
  16.     D0                      D0         A6
  17.  
  18.     BOOL AllocUnit(LONG);
  19.  
  20.    FUNCTION
  21.     This routine allocates one of the units of the disk.  It should
  22.     be called before trying to use the disk (via GetUnit).
  23.  
  24.     In reality, it is perfectly fine to use GetUnit/GiveUnit if AllocUnit
  25.     fails.  Do NOT call FreeUnit if AllocUnit did not succeed.  This
  26.     has been the case for all revisions of disk.resource.
  27.  
  28.    INPUTS
  29.     unitNum -- a legal unit number (zero through three)
  30.  
  31.    RESULTS
  32.     Success -- nonzero if successful.  zero on failure.
  33.  
  34.    EXCEPTIONS
  35.  
  36.    SEE ALSO
  37.  
  38.    BUGS
  39.  
  40. disk.resource/FreeUnit                                 disk.resource/FreeUnit
  41.  
  42.    NAME
  43.        FreeUnit - deallocate the disk
  44.  
  45.    SYNOPSIS
  46.        FreeUnit( unitNum ), DRResource
  47.           D0         A6
  48.  
  49.     void FreeUnit(LONG);
  50.  
  51.    FUNCTION
  52.     This routine deallocates one of the units of the disk.  It should
  53.     be called when done with the disk.  Do not call it if you did
  54.     no successfully allocate the disk (there is no protection -- you
  55.     will probably crash the disk system).
  56.  
  57.    INPUTS
  58.     unitNum -- a legal unit number (zero through three)
  59.  
  60.    RESULTS
  61.  
  62.    EXCEPTIONS
  63.  
  64.    SEE ALSO
  65.     FreeUnit
  66.  
  67.    BUGS
  68.     Doesn't check if you own the unit, or even if anyone owns it.
  69.  
  70. disk.resource/GetUnit                                   disk.resource/GetUnit
  71.  
  72.    NAME
  73.        GetUnit - allocate the disk for a driver
  74.  
  75.    SYNOPSIS
  76.        lastDriver = GetUnit( unitPointer ), DRResource
  77.        D0              A1             A6
  78.  
  79.     struct DiscResourceUnit *GetUnit(struct DiscResourceUnit *);
  80.  
  81.    FUNCTION
  82.     This routine allocates the disk to a driver.  It is either
  83.     immediately available, or the request is saved until the disk
  84.     is available.  When it is available, your unitPointer is
  85.     sent back to you (via ReplyMsg).  You may then reattempt the
  86.     GetUnit.
  87.     
  88.     Allocating the disk allows you to use the disk's resources.
  89.     Remember however that there are four units to the disk; you are
  90.     only one of them.  Please be polite to the other units (by never
  91.     selecting them, and by not leaving interrupts enabled, etc.).
  92.  
  93.     When you are done, please leave the disk in the following state:
  94.         dmacon dma bit ON
  95.         dsklen dma bit OFF (write a #DSKDMAOFF to dsklen)
  96.         adkcon disk bits -- any way you want
  97.         entena:disk sync and disk block interrupts -- Both DISABLED
  98.         CIA resource index interrupt -- DISABLED
  99.         8520 outputs -- doesn't matter, because all bits will be
  100.         set to inactive by the resource.
  101.         8520 data direction regs -- restore to original state.
  102.  
  103.     NOTE: GetUnit() does NOT turn on the interrupts for you.
  104.           You must use AbleICR (for the index interrupt) or intena
  105.           (for the diskbyte and diskblock interrupts) to turn them
  106.           on.  You should turn them off before calling GiveUnit,
  107.           as stated above.
  108.  
  109.    INPUTS
  110.     unitPtr - a pointer you your disk resource unit structure.
  111.         Note that the message filed of the structure MUST
  112.         be a valid message, ready to be replied to.  Make sure
  113.         ln_Name points to a null-terminated string, preferably
  114.         one that identifies your program.
  115.  
  116.         You need to set up the three interrupt structures,
  117.         in particular the IS_DATA and IS_CODE fields.  Set them
  118.         to NULL if you don't need that interrupt.  Also, set
  119.         the ln_Type of the interrupt structure to NT_INTERRUPT.
  120.         WARNING: don't turn on a disk resource interrupt unless
  121.         the IS_CODE for that interrupt points to executable code!
  122.  
  123.         IS_CODE will be called with IS_DATA in A1 when the
  124.         interrupt occurs.  Preserve all regs but D0/D1/A0/A1.
  125.         Do not make assumptions about A0.
  126.  
  127.    RESULTS
  128.     lastDriver - if the disk is not busy, then the last unit
  129.         to use the disk is returned.  This may be used to
  130.         see if a driver needs to reset device registers.
  131.         (If you were the last user, then no one has changed
  132.         any of the registers.  If someone else has used it,
  133.         then any allowable changes may have been made).  If the
  134.         disk is busy, then a null is returned.
  135.  
  136.    EXCEPTIONS
  137.  
  138.    SEE ALSO
  139.     GiveUnit
  140.  
  141.    BUGS
  142.  
  143. disk.resource/GetUnitID                               disk.resource/GetUnitID
  144.  
  145.    NAME
  146.        GetUnitID - find out what type of disk is out there
  147.  
  148.    SYNOPSIS
  149.        idtype = GetUnitID( unitNum ), DRResource
  150.     D0                D0         A6
  151.  
  152.     LONG GetUnitID(LONG);
  153.  
  154.    FUNCTION
  155.     Gets the drive ID for a given unit.  Note that this value may
  156.     change if someone calls ReadUnitID, and the drive id changes.
  157.  
  158.    INPUTS
  159.     unitNum -- a legal unit number (zero through three)
  160.  
  161.    RESULTS
  162.     idtype -- the type of the disk drive.  Standard types are
  163.         defined in the resource include file.
  164.  
  165.    EXCEPTIONS
  166.  
  167.    SEE ALSO
  168.     ReadUnitID
  169.  
  170.    BUGS
  171.  
  172. disk.resource/GiveUnit                                 disk.resource/GiveUnit
  173.  
  174.    NAME
  175.        GiveUnit - Free the disk back up
  176.  
  177.    SYNOPSIS
  178.        GiveUnit(), DRResource
  179.                    A6
  180.  
  181.     void GiveUnit();
  182.  
  183.    FUNCTION
  184.     This routine frees the disk after a driver is done with it.
  185.     If others are waiting, it will notify them.
  186.  
  187.    INPUTS
  188.  
  189.    RESULTS
  190.  
  191.    EXCEPTIONS
  192.  
  193.    SEE ALSO
  194.     GetUnit
  195.  
  196.    BUGS
  197.     In pre-V36, GiveUnit didn't check if you owned the unit.  A patch
  198.     for this was part of 1.3.1 SetPatch.  Fixed in V36.
  199.  
  200. disk.resource/ReadUnitID                             disk.resource/ReadUnitID
  201.  
  202.    NAME
  203.        ReadUnitID - reread and return the type of drive (V37)
  204.  
  205.    SYNOPSIS
  206.        idtype = ReadUnitID( unitNum ), DRResource
  207.     D0                   D0         A6
  208.  
  209.     ULONG ReadUnitID(LONG);
  210.  
  211.    FUNCTION
  212.     Rereads the drive id for a specific unit (for handling drives
  213.     that change ID according to what sort of disk is in them.  You
  214.     MUST have done a GetUnit before calling this function!
  215.  
  216.    INPUTS
  217.     unitNum -- a legal unit number (zero through three)
  218.  
  219.    RESULTS
  220.     idtype -- the type of the disk drive.  Standard types are
  221.         defined in the resource include file.
  222.  
  223.    EXCEPTIONS
  224.  
  225.    SEE ALSO
  226.     GetUnitID
  227.  
  228.    BUGS
  229.  
  230.