BeginCardAccess()
Synopsis
BOOL BeginCardAccess(
struct CardHandle *handle)
Function
Test whether handle owns a card currently marked present by the
m68k-Amiga resource.
Result
TRUE if handle equals the current owner and the card is not marked
removed; otherwise FALSE.
Notes
This call does not acquire or release a lock, change ownership, map
memory or reserve access. TRUE is a snapshot, not a guarantee that
the card remains present. Continue to handle removal notifications.
CardAccessSpeed()
Synopsis
ULONG CardAccessSpeed(
struct CardHandle *handle, ULONG nanoseconds)
Function
Set the m68k-Amiga card-memory access timing.
Result
The selected access time in nanoseconds, or zero if the request
exceeds 720 ns or the ownership/presence check fails.
Notes
Requires a non-NULL handle that currently owns the inserted card.
The ownership test does not protect against subsequent removal.
Rejected requests leave the configuration unchanged. The
programming-voltage bits are preserved. A zero request selects 100
ns; it does not query the current timing.
CardChangeCount()
Synopsis
ULONG CardChangeCount(
)
Function
Read the m68k-Amiga resource's processed-change counter.
Result
The current ULONG counter value.
Notes
The resource task increments the counter after waking for a change,
before debouncing and processing it. Multiple signals may coalesce.
CardForceChange() does not increment it directly, and counter
equality does not prove that the same card is still present. Use the
value as a change indicator; it can wrap.
CardForceChange()
Synopsis
BOOL CardForceChange(
)
Function
Initiate a simulated m68k-Amiga card removal and, if still present,
reinsertion.
Result
FALSE if removal-reset mode is enabled or the card is already marked
removed. Otherwise TRUE after initiating the change.
Notes
Call from task context. The function resets card configuration,
marks the card removed and invokes the current owner's removal
callback with task switching forbidden. The callback must arrange to
release ownership.
If hardware still reports a card, a synchronous card-reset sequence
runs and the resource task is signalled to process reinsertion.
Otherwise interrupts are re-enabled without signalling that task.
TRUE does not mean reinsertion, ownership reassignment or a counter
update has completed. The synchronous reset busy-waits on the
display beam without a timeout.
CardMiscControl()
Synopsis
UBYTE CardMiscControl(
struct CardHandle *handle, UBYTE control_bits)
Function
Update m68k-Amiga card status controls and selected interrupt
enables.
Result
The requested bits masked to the supported controls, including
CARD_INTF_SETCLR, or zero if the ownership/presence check fails.
Zero is also a valid successful request.
Notes
Requires a non-NULL handle that currently owns the inserted card.
The ownership test does not protect against subsequent removal.
Status controls are replaced on every call, including calls intended
only to alter interrupts. Unselected interrupt enables are
preserved. The result is the masked request, not the previous state
or a hardware readback.
CardProgramVoltage()
Synopsis
LONG CardProgramVoltage(
struct CardHandle *handle, ULONG voltage)
Function
Set the m68k-Amiga card programming voltage.
Result
1 after applying a supported selector; -1 for an unsupported
selector, including CARD_VOLTAGE_12V; 0 if the ownership/presence
check fails.
Notes
Requires a non-NULL handle that currently owns the inserted card.
The ownership test does not protect against subsequent removal.
Rejected requests leave the configuration unchanged. Access-timing
bits are preserved. Ownership failure takes precedence over selector
validation.
CardResetCard()
Synopsis
BOOL CardResetCard(
struct CardHandle *handle)
Function
Pulse the m68k-Amiga card-reset controls.
Result
TRUE after the reset sequence; FALSE if the ownership/presence check
fails.
Notes
Requires a non-NULL handle that currently owns the inserted card.
The ownership test does not protect against subsequent removal.
Call from task context. The sequence busy-waits for two groups of
ten display-beam cycles and temporarily disables Gayle interrupt
enables. It restores the saved enables and removal-reset setting. No
card-ready status is checked and no timeout is provided; TRUE does
not establish that the card is operational.
CardResetRemove()
Synopsis
BOOL CardResetRemove(
struct CardHandle *handle, ULONG flag)
Function
Enable or disable machine reset on m68k-Amiga card-detect changes.
Result
TRUE after applying the setting; FALSE if the ownership/presence
check fails.
Notes
Requires a non-NULL handle that currently owns the inserted card.
The ownership test does not protect against subsequent removal.
Enabling this setting permits a card-detect change to reset the
machine. It is not a request to reset only the card. The bus-error
control bit is cleared when the setting is written.
CopyTuple()
Synopsis
BOOL CopyTuple(
struct CardHandle *handle, UBYTE *buffer, ULONG tuplecode, ULONG size)
Function
Search the m68k-Amiga card's CIS chains and copy a matching tuple.
Result
With a buffer, TRUE when a matching tuple is selected; FALSE when
none is found, ownership is absent or traversal fails before
selection. The buffer is unchanged on those FALSE paths. With NULL,
TRUE only when traversal reaches an end with no further link; no
tuple selection is made.
Notes
Requires a non-NULL handle that currently owns the inserted card.
The ownership test does not protect against subsequent removal.
The first two output bytes are the tuple code and its original link
length. At most min(size, link length) data bytes follow. The link
byte is not reduced after truncation, and the function returns no
separate copied-byte count.
Traversal starts in attribute memory and can follow long links into
attribute or common memory. It temporarily selects 720 ns timing
with the programming voltage cleared, then restores the previous
configuration before returning. Task switching is forbidden during
traversal. A NULL buffer prints tuples to the diagnostic log;
tuplecode and size do not filter that traversal.
Bugs
After finding a tuple, individual read failures are ignored and
failed reads supply zero bytes. TRUE does not certify a complete or
valid tuple, especially after removal. Cyclic long links are not
detected and can prevent the call from returning while task
switching remains forbidden. Do not use this function as validation
of untrusted CIS data.
DeviceTuple()
Synopsis
ULONG DeviceTuple(
UBYTE *tuple_data, struct DeviceTData *storage)
Function
Decode the first device descriptor of a m68k-Amiga CISTPL_DEVICE or
CISTPL_DEVICE_A tuple.
Result
Nonzero if the implemented decoder accepts the descriptor; zero for
an unsupported tuple code, zero link length, unsupported device type
or reserved speed encoding. On all calls, size, speed and flags are
first cleared. Type may be changed before failure; output is not
transactional.
Notes
Types 0-7 and 13 are accepted. Fixed speed encodings produce 250,
200, 150 or 100 ns; encoding 0 leaves speed zero. Extended-speed
encoding derives a value from its mantissa and exponent. Size is
expressed in bytes; when a size byte is read, it is (512 << (2 *
(byte & 7))) * ((byte >> 3) + 1). An I/O descriptor without a size
byte receives size 1. Flags are always zero.
This decoder reads caller memory; it does not access the card,
require ownership or retain either pointer.
Bugs
The decoder compares the payload length with offsets that include
the header, so it can skip valid trailing descriptor data and still
succeed. A long extended-speed chain can wrap the 8-bit offset and
cause header bytes to be decoded as size data. Reserved mantissa
values are not rejected. TRUE does not establish a complete or
correct card-memory description.
EndCardAccess()
Synopsis
BOOL EndCardAccess(
struct CardHandle *handle)
Function
Test whether handle owns a card currently marked present by the
m68k-Amiga resource.
Result
TRUE if handle equals the current owner and the card is not marked
removed; otherwise FALSE.
Notes
This call does not acquire or release a lock, change ownership, map
memory or reserve access. TRUE is a snapshot, not a guarantee that
the card remains present. Continue to handle removal notifications.
GetCardMap()
Synopsis
struct CardMemoryMap * GetCardMap(
)
Function
Return the fixed m68k-Amiga Gayle PCMCIA address windows.
Result
A borrowed pointer to an immutable CardMemoryMap: common memory at
0x00600000, size 0x00400000; attribute memory at 0x00A00000, size
0x00020000; I/O memory at 0x00A20000, size 0x00010000.
Notes
Do not modify or free the map. It remains valid for the lifetime of
card.resource. Returning the map does not acquire a card or
establish its presence. Claim the card before accessing its windows
and stop access on removal. Attribute bytes occupy alternate
addresses.
IfAmigaXIP()
Synopsis
struct Resident * IfAmigaXIP(
struct CardHandle *handle)
Function
Inspect the m68k-Amiga card's execute-in-place tuple without
returning a resident.
Notes
When the ownership/presence check succeeds, the function calls
CopyTuple() for CISTPL_AMIGAXIP and decodes its location field. No
resident is validated or executed. CopyTuple() traversal and
blocking limitations apply.
Bugs
Execute-in-place support is incomplete. NULL does not distinguish an
absent tuple, a read failure or a tuple that this implementation
cannot use.
OwnCard()
Synopsis
struct CardHandle * OwnCard(
struct CardHandle *handle)
Function
Request ownership of the m68k-Amiga PCMCIA slot, or queue a handle
for a later card.
Result
With CARDF_DELAYOWNERSHIP, returns (struct CardHandle *)-1 after
queueing the handle, even if ownership and its insertion callback
occur immediately. Otherwise returns -1 when the card is marked
removed. With CARDF_IFAVAILABLE and an existing owner, returns that
owner's borrowed handle. Other paths return NULL; see BUGS.
Notes
CARDF_DELAYOWNERSHIP takes precedence over CARDF_IFAVAILABLE and
queues by node priority. An immediate claim adds the handle at the
head of the queue without calling its insertion callback.
CARDF_RESETREMOVE selects machine-reset behaviour on card-detect
changes when ownership is granted. CARDF_POSTSTATUS requests a
second status callback with mask zero after interrupt
acknowledgement.
Insertion and removal callbacks execute with task switching
forbidden, from resource-task or caller context. They must not wait.
The status callback executes in interrupt context; it returns the
interrupt mask to acknowledge. Use the AROS_CARDH/AROS_CARDFUNC and
AROS_CARDC conventions from resources/card.h.
Remove a registered handle with ReleaseCard(handle,
CARDF_REMOVEHANDLE) before freeing its storage. Serialize
registration and release; the ownership decision and registration
are not one atomic operation.
Bugs
Without CARDF_IFAVAILABLE or CARDF_DELAYOWNERSHIP, an existing owner
causes NULL to be returned without registering or acquiring the
supplied handle. NULL alone therefore does not prove ownership;
BeginCardAccess() checks the current handle. Re-registering a linked
handle can corrupt the queue.
ReadCardStatus()
Synopsis
UBYTE ReadCardStatus(
)
Function
Read the m68k-Amiga Gayle card-status signals.
Result
A mask containing CARD_STATUSF_CCDET, CARD_STATUSF_BVD1,
CARD_STATUSF_BVD2, CARD_STATUSF_WR and CARD_STATUSF_BSY as read from
the status register. Other bits are cleared.
Notes
BVD1, BVD2 and BSY share their bit positions with SC, DA and IRQ for
I/O cards. Interpret the signals for the card type. The call does
not clear pending interrupts or check card ownership. A returned
snapshot does not reserve access.
ReleaseCard()
Synopsis
void ReleaseCard(
struct CardHandle *handle, ULONG flags)
Function
Release a handle's m68k-Amiga card ownership and optionally unlink
the handle.
Notes
If handle owns the card, ownership is cleared and card configuration
and interrupts are reset. When a card remains inserted, another
eligible handle can receive ownership and its insertion callback
before this call returns. Without CARDF_REMOVEHANDLE, the released
handle remains queued but is marked used for the current card.
No handle or callback storage is freed. Serialize release with other
operations on the handle. Call only after registration is known to
have occurred; a failed OwnCard() attempt does not necessarily
register it.
A removal callback must arrange to release ownership: notifying a
client of removal does not itself clear the resource's owner
pointer.
Bugs
Unlinking is unconditional when CARDF_REMOVEHANDLE is set. Passing
an unregistered or already removed handle can corrupt a list.