@database "disk"
@master "ADCD_v1.2:Inc&AD2.1/Includes/doc/disk.doc"

@Node Main "disk.doc"
@TOC 2.1Includes_Autodocs/Autodocs

@{" AllocUnit() " Link "AllocUnit()"}    @{" GetUnit() " Link "GetUnit()"}      @{" GiveUnit() " Link "GiveUnit()"}
@{" FreeUnit() " Link "FreeUnit()"}     @{" GetUnitID() " Link "GetUnitID()"}    @{" ReadUnitID() " Link "ReadUnitID()"}

@EndNode

@Node "AllocUnit()" "disk.resource/AllocUnit"

NAME
    AllocUnit - allocate a unit of the disk

SYNOPSIS
    Success = AllocUnit( unitNum ), DRResource
    D0                   D0         A6

    BOOL AllocUnit(LONG);

FUNCTION
    This routine allocates one of the units of the disk.  It should
    be called before trying to use the disk (via GetUnit).

    In reality, it is perfectly fine to use @{"GetUnit/GiveUnit" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/disk/GiveUnit()"} if AllocUnit
    fails.  Do NOT call @{"FreeUnit" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/disk/FreeUnit()"} if AllocUnit did not succeed.  This
    has been the case for all revisions of disk.resource.

INPUTS
    unitNum -- a legal unit number (zero through three)

RESULTS
    Success -- nonzero if successful.  zero on failure.

EXCEPTIONS

SEE ALSO

BUGS

@EndNode

@Node "FreeUnit()" "disk.resource/FreeUnit"

NAME
    FreeUnit - deallocate the disk

SYNOPSIS
    FreeUnit( unitNum ), DRResource
              D0         A6

    void FreeUnit(LONG);

FUNCTION
    This routine deallocates one of the units of the disk.  It should
    be called when done with the disk.  Do not call it if you did
    no successfully allocate the disk (there is no protection -- you
    will probably crash the disk system).

INPUTS
    unitNum -- a legal unit number (zero through three)

RESULTS

EXCEPTIONS

SEE ALSO
    FreeUnit

BUGS
    Doesn't check if you own the unit, or even if anyone owns it.

@EndNode

@Node "GetUnit()" "disk.resource/GetUnit"

NAME
    GetUnit - allocate the disk for a driver

SYNOPSIS
    lastDriver = GetUnit( unitPointer ), DRResource
    D0                     A1             A6

    struct @{"DiscResourceUnit" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/disk.h/Main" 40} *GetUnit(struct @{"DiscResourceUnit" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/disk.h/Main" 40} *);

FUNCTION
    This routine allocates the disk to a driver.  It is either
    immediately available, or the request is saved until the disk
    is available.  When it is available, your unitPointer is
    sent back to you (via ReplyMsg).  You may then reattempt the
    GetUnit.

    Allocating the disk allows you to use the disk's resources.
    @{"Remember" Link "ADCD_v1.2:Inc&AD2.1/Includes/intuition/intuition.h/Main" 1231} however that there are four units to the disk; you are
    only one of them.  Please be polite to the other units (by never
    selecting them, and by not leaving interrupts enabled, etc.).

    When you are done, please leave the disk in the following state:
        dmacon dma bit ON
        dsklen dma bit OFF (write a #DSKDMAOFF to dsklen)
        adkcon disk bits -- any way you want
        entena:disk sync and disk block interrupts -- Both DISABLED
        @{"CIA" Link "ADCD_v1.2:Inc&AD2.1/Includes/hardware/cia.h/Main" 28} resource index interrupt -- DISABLED
        8520 outputs -- doesn't matter, because all bits will be
            set to inactive by the resource.
        8520 data direction regs -- restore to original state.

    NOTE: GetUnit() does NOT turn on the interrupts for you.
          You must use @{"AbleICR" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/cia/AbleICR()"} (for the index interrupt) or intena
          (for the diskbyte and diskblock interrupts) to turn them
          on.  You should turn them off before calling @{"GiveUnit" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/disk/GiveUnit()"},
          as stated above.

INPUTS
    unitPtr - a pointer you your disk resource unit structure.
            Note that the message filed of the structure MUST
            be a valid message, ready to be replied to.  Make sure
            ln_Name points to a null-terminated string, preferably
            one that identifies your program.

            You need to set up the three interrupt structures,
            in particular the IS_DATA and IS_CODE fields.  Set them
            to NULL if you don't need that interrupt.  Also, set
            the ln_Type of the interrupt structure to NT_INTERRUPT.
            WARNING: don't turn on a disk resource interrupt unless
            the IS_CODE for that interrupt points to executable code!

            IS_CODE will be called with IS_DATA in A1 when the
            interrupt occurs.  Preserve all regs but D0/D1/A0/A1.
            Do not make assumptions about A0.

RESULTS
    lastDriver - if the disk is not busy, then the last unit
            to use the disk is returned.  This may be used to
            see if a driver needs to reset device registers.
            (If you were the last user, then no one has changed
            any of the registers.  If someone else has used it,
            then any allowable changes may have been made).  If the
            disk is busy, then a null is returned.

EXCEPTIONS

SEE ALSO
    @{"GiveUnit" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/disk/GiveUnit()"}

BUGS

@EndNode

@Node "GetUnitID()" "disk.resource/GetUnitID"

NAME
    GetUnitID - find out what type of disk is out there

SYNOPSIS
    idtype = GetUnitID( unitNum ), DRResource
    D0                  D0         A6

    LONG GetUnitID(LONG);

FUNCTION
    Gets the drive ID for a given unit.  Note that this value may
    change if someone calls @{"ReadUnitID" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/disk/ReadUnitID()"}, and the drive id changes.

INPUTS
    unitNum -- a legal unit number (zero through three)

RESULTS
    idtype -- the type of the disk drive.  Standard types are
            defined in the resource include file.

EXCEPTIONS

SEE ALSO
    @{"ReadUnitID" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/disk/ReadUnitID()"}

BUGS

@EndNode

@Node "GiveUnit()" "disk.resource/GiveUnit"

NAME
    GiveUnit - Free the disk back up

SYNOPSIS
    GiveUnit(), DRResource
                A6

    void GiveUnit();

FUNCTION
    This routine frees the disk after a driver is done with it.
    If others are waiting, it will notify them.

INPUTS

RESULTS

EXCEPTIONS

SEE ALSO
    @{"GetUnit" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/disk/GetUnit()"}

BUGS
    In pre-V36, GiveUnit didn't check if you owned the unit.  A patch
    for this was part of 1.3.1 SetPatch.  Fixed in V36.

@EndNode

@Node "ReadUnitID()" "disk.resource/ReadUnitID"

NAME
    ReadUnitID - reread and return the type of drive (V37)

SYNOPSIS
    idtype = ReadUnitID( unitNum ), DRResource
    D0                     D0         A6

    ULONG ReadUnitID(LONG);

FUNCTION
    Rereads the drive id for a specific unit (for handling drives
    that change ID according to what sort of disk is in them.  You
    MUST have done a @{"GetUnit" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/disk/GetUnit()"} before calling this function!

INPUTS
    unitNum -- a legal unit number (zero through three)

RESULTS
    idtype -- the type of the disk drive.  Standard types are
            defined in the resource include file.

EXCEPTIONS

SEE ALSO
    @{"GetUnitID" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/disk/GetUnitID()"}

BUGS

@EndNode

