@database "disk"
@master "AMIDEV:NDK/Autodocs/disk.doc"

@Node Main "disk.doc"
@toc "Autodocs/AG/INDEX/Main"
    @{" AllocUnit() " Link "AllocUnit()"}
    @{" FreeUnit() " Link "FreeUnit()"}
    @{" GetUnit() " Link "GetUnit()"}
    @{" GetUnitID() " Link "GetUnitID()"}
    @{" GiveUnit() " Link "GiveUnit()"}
    @{" ReadUnitID() " Link "ReadUnitID()"}
@EndNode

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

@{b}   NAME@{ub}
       AllocUnit - allocate a unit of the disk

@{b}   SYNOPSIS@{ub}
       Success = AllocUnit( unitNum ), DRResource
	D0     	             D0         A6

	@{"BOOL" Link "INCLUDE:exec/types.h/Main" 168} AllocUnit(LONG);

@{b}   FUNCTION@{ub}
	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 "disk/GiveUnit()"} if AllocUnit
	fails.  Do NOT call @{"FreeUnit" Link "disk/FreeUnit()"} if AllocUnit did not succeed.  This
	has been the case for all revisions of disk.resource.

@{b}   INPUTS@{ub}
	unitNum -- a legal unit number (zero through three)

@{b}   RESULTS@{ub}
	Success -- nonzero if successful.  zero on failure.

@{b}   EXCEPTIONS@{ub}

@{b}   SEE ALSO@{ub}

@{b}   BUGS@{ub}

@EndNode

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

@{b}   NAME@{ub}
       FreeUnit - deallocate the disk

@{b}   SYNOPSIS@{ub}
       FreeUnit( unitNum ), DRResource
		  D0         A6

	void FreeUnit(LONG);

@{b}   FUNCTION@{ub}
	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).

@{b}   INPUTS@{ub}
	unitNum -- a legal unit number (zero through three)

@{b}   RESULTS@{ub}

@{b}   EXCEPTIONS@{ub}

@{b}   SEE ALSO@{ub}
	FreeUnit

@{b}   BUGS@{ub}
	Doesn't check if you own the unit, or even if anyone owns it.

@EndNode

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

@{b}   NAME@{ub}
       GetUnit - allocate the disk for a driver

@{b}   SYNOPSIS@{ub}
       lastDriver = GetUnit( unitPointer ), DRResource
       D0		      A1             A6

	struct @{"DiscResourceUnit" Link "INCLUDE:resources/disk.h/Main" 37} *GetUnit(struct @{"DiscResourceUnit" Link "INCLUDE:resources/disk.h/Main" 37} *);

@{b}   FUNCTION@{ub}
	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 "INCLUDE:intuition/intuition.h/Main" 1503} 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 "INCLUDE:hardware/cia.h/Main" 27} 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 "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 "disk/GiveUnit()"},
	      as stated above.

@{b}   INPUTS@{ub}
	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" Link "rexxsupport/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.

@{b}   RESULTS@{ub}
	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.

@{b}   EXCEPTIONS@{ub}

@{b}   SEE ALSO@{ub}
	@{"GiveUnit" Link "disk/GiveUnit()"}

@{b}   BUGS@{ub}

@EndNode

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

@{b}   NAME@{ub}
       GetUnitID - find out what type of disk is out there

@{b}   SYNOPSIS@{ub}
       idtype = GetUnitID( unitNum ), DRResource
	D0	            D0         A6

	@{"LONG" Link "INCLUDE:exec/types.h/Main" 112} GetUnitID(LONG);

@{b}   FUNCTION@{ub}
	Gets the drive ID for a given unit.  Note that this value may
	change if someone calls @{"ReadUnitID" Link "disk/ReadUnitID()"}, and the drive id changes.

@{b}   INPUTS@{ub}
	unitNum -- a legal unit number (zero through three)

@{b}   RESULTS@{ub}
	idtype -- the type of the disk drive.  Standard types are
		defined in the resource include file.

@{b}   EXCEPTIONS@{ub}

@{b}   SEE ALSO@{ub}
	@{"ReadUnitID" Link "disk/ReadUnitID()"}

@{b}   BUGS@{ub}

@EndNode

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

@{b}   NAME@{ub}
       GiveUnit - Free the disk back up

@{b}   SYNOPSIS@{ub}
       GiveUnit(), DRResource
           	    A6

	void GiveUnit();

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

@{b}   INPUTS@{ub}

@{b}   RESULTS@{ub}

@{b}   EXCEPTIONS@{ub}

@{b}   SEE ALSO@{ub}
	@{"GetUnit" Link "disk/GetUnit()"}

@{b}   BUGS@{ub}
	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"

@{b}   NAME@{ub}
       ReadUnitID - reread and return the type of drive (V37)

@{b}   SYNOPSIS@{ub}
       idtype = ReadUnitID( unitNum ), DRResource
	D0	               D0         A6

	ULONG ReadUnitID(LONG);

@{b}   FUNCTION@{ub}
	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 "disk/GetUnit()"} before calling this function!

@{b}   INPUTS@{ub}
	unitNum -- a legal unit number (zero through three)

@{b}   RESULTS@{ub}
	idtype -- the type of the disk drive.  Standard types are
		defined in the resource include file.

@{b}   EXCEPTIONS@{ub}

@{b}   SEE ALSO@{ub}
	@{"GetUnitID" Link "disk/GetUnitID()"}

@{b}   BUGS@{ub}

@EndNode