AllocUnit()
Synopsis
BOOL AllocUnit(
LONG unitNum );
Function
Reserve a floppy drive unit in disk.resource's allocation bitmap.
This reservation is separate from ownership of the shared disk
hardware, which is acquired with GetUnit().
Result
TRUE if the unit was free and has now been reserved; FALSE if it
was already reserved. No task ownership is recorded.
Notes
Balance a successful reservation with FreeUnit(). The unit number
is not checked. The bitmap update has no internal critical section;
callers must serialize competing allocation and release operations.
FreeUnit()
Synopsis
void FreeUnit(
LONG unitNum );
Function
Clear the allocation bit for a floppy drive unit previously
reserved with AllocUnit().
Notes
This does not release shared hardware ownership, stop disk I/O,
remove an interrupt descriptor or wake a GetUnit() waiter. Finish
using the unit and separately release any shared hardware ownership
with GiveUnit().
Neither the unit number nor ownership is checked. The bitmap
update has no internal critical section; callers must serialize
competing allocation and release operations.
GetUnit()
Synopsis
struct DiscResourceUnit* GetUnit(
struct DiscResourceUnit* unitPointer );
Function
Try to acquire the shared floppy disk hardware for the calling
task. If it is available, install the supplied descriptor as the
current interrupt descriptor. Otherwise append its message to the
resource's waiting list and return immediately.
Result
On success, a non-NULL pointer to the previous current descriptor.
If no descriptor was previously installed, unitPointer is returned.
The returned descriptor is borrowed; ownership is not transferred.
NULL means the hardware was busy and dru_Message has been queued.
Wait for and remove the reply to that message before retrying.
A reply is a notification to retry, not a grant of ownership.
Notes
Call from task context. This is not a recursive acquisition:
calling again while already owning the hardware queues a request
rather than granting another ownership level. Do not enqueue the
same descriptor twice. On successful acquisition, the same task
must eventually call GiveUnit().
The descriptor, reply port and interrupt code/data must remain
valid while queued or installed. GiveUnit() retains the current
descriptor pointer: do not free it merely because ownership was
released. In the native Amiga implementation the disk interrupt
handlers use that pointer even while the resource is inactive.
Queue and ownership updates are protected with Disable()/Enable().
The function returns without waiting for ownership; it does not
perform disk I/O or reserve a drive number.
Bugs
The previous descriptor is sampled before the ownership critical
section. If another task changes the current descriptor before
acquisition, the returned pointer need not identify the immediately
preceding owner. Do not use it as a synchronized ownership record.
GetUnitID()
Synopsis
ULONG GetUnitID(
LONG unitNum );
Function
Return the cached hardware identification value for a floppy
drive. This function does not probe the drive or test for a disk.
Result
The cached ULONG identification value. Defined values in
<resources/disk.h> include DRT_AMIGA, DRT_37422D2S, DRT_EMPTY and
DRT_150RPM. Other bit patterns are returned unchanged.
Notes
The native Amiga resource fills the cache during initialization;
ReadUnitID() refreshes it. The unit number is not checked. There
is no separate error result, allocation or wait in this call.
GiveUnit()
Synopsis
void GiveUnit();
Function
Release the shared floppy disk hardware owned by the calling
task. Remove the first waiting descriptor, if any, from the waiting
list and ReplyMsg() its dru_Message. The notified task must retry
GetUnit() to obtain ownership.
Result
None. If the calling task is not the recorded owner, no state is
changed and no waiter is notified.
Notes
Finish disk transfers and arrange the hardware/interrupt state
for relinquishing ownership before calling. This function only
updates resource ownership and notifies a waiter; it does not stop
DMA or disable disk interrupts.
The current descriptor pointer is retained, and native Amiga disk
interrupt dispatch still consults it. Releasing ownership does not
release the descriptor's storage or make it safe to free its
interrupt code/data. Drive allocations made by AllocUnit() remain
in force until FreeUnit().
Call from the task that successfully acquired GetUnit(). Ownership
and waiting-list updates use Disable()/Enable(); the reply is sent
after Enable().
ReadUnitID()
Synopsis
ULONG ReadUnitID(
LONG unitNum );
Function
Invoke the architecture-specific drive identification routine and
return the cached identification value for the selected drive.
On native Amiga hardware this reads the 32-bit drive ID stream
through the CIA motor and drive-select lines and updates the cache.
Result
The resulting cached ULONG ID. See the DRT_* constants in
<resources/disk.h>. This is a drive identification value, not a
media-change or disk-presence result. There is no separate error
status.
Notes
The native Amiga implementation changes motor/select control
lines and does not acquire shared disk hardware ownership itself.
Obtain ownership with GetUnit() and coordinate with other users
before probing; release ownership with GiveUnit() afterwards.
No unit-range check or wait is performed by this function.
On native Amiga, an all-ones response for unit 0 is treated as
DRT_AMIGA on machines without the CD32 Akiko identification. On
CD32 it remains DRT_EMPTY. Other ID bit patterns are preserved.
The generic architecture backend does not implement probing or
resource initialization; availability requires a working backend.
