@database "cardres"
@master "Projekt:CD-ROM/Reference/Includes_&_Autodocs/autodocs/cardres.doc"

@Node Main "cardres.doc"
@toc "Includes_&_Autodocs/Main"
    @{" BeginCardAccess() " Link "BeginCardAccess()"}
    @{" CardAccessSpeed() " Link "CardAccessSpeed()"}
    @{" CardChangeCount() " Link "CardChangeCount()"}
    @{" CardForceChange() " Link "CardForceChange()"}
    @{" CardInterface() " Link "CardInterface()"}
    @{" CardMiscControl() " Link "CardMiscControl()"}
    @{" CardProgramVoltage() " Link "CardProgramVoltage()"}
    @{" CardResetCard() " Link "CardResetCard()"}
    @{" CardResetRemove() " Link "CardResetRemove()"}
    @{" CopyTuple() " Link "CopyTuple()"}
    @{" DeviceTuple() " Link "DeviceTuple()"}
    @{" EndCardAccess() " Link "EndCardAccess()"}
    @{" GetCardMap() " Link "GetCardMap()"}
    @{" IfAmigaXIP() " Link "IfAmigaXIP()"}
    @{" OwnCard() " Link "OwnCard()"}
    @{" ReadCardStatus() " Link "ReadCardStatus()"}
    @{" ReleaseCard() " Link "ReleaseCard()"}
@EndNode

@Node "BeginCardAccess()" "card.resource/BeginCardAccess"

@{b}   NAME@{ub}
	BeginCardAccess -- Called before you begin credit-card memory access
   
@{b}   SYNOPSIS@{ub}
	result=BeginCardAccess( handle )
	d0			a1

	@{"BOOL" Link "includes/exec/types.h/Main" 68} BeginCardAccess( struct @{"CardHandle" Link "includes/resources/card.h/Main" 29} * );

@{b}   FUNCTION@{ub}
	This function should be called before you begin access
	to credit-card memory.

	Its effect will depend on the type of Amiga machine your
	code happens to be running on.  On some machines it
	will cause an access light to be turned ON.

@{b}   INPUTS@{ub}
	handle - Same handle as that used when @{"OwnCard()" Link "OwnCard()"} was called.

@{b}   RETURNS@{ub}
	TRUE if you are still the owner of the credit-card, and
	memory access is permitted.  FALSE if you are no longer
	the owner of the credit-card (usually indicating that
	the card was removed).

@{b}   NOTES@{ub}
	This function may be called from within a task, or from a level 1
	or level 2 interrupt.

	It is highly recommended that you call this function
	before accessing credit-card memory, as well as checking
	the return value.  If it is a return value of FALSE, you
	should stop accessing credit-card memory.

@{b}   SEE ALSO@{ub}
	@{"OwnCard()" Link "OwnCard()"}, @{"EndCardAccess()" Link "EndCardAccess()"}

@EndNode

@Node "CardAccessSpeed()" "card.resource/CardAccessSpeed"

@{b}   NAME@{ub}
	CardAccessSpeed -- Select best possible memory access speed.
   
@{b}   SYNOPSIS@{ub}
	result=CardAccessSpeed( handle, nanoseconds );
	d0			 a1      d0

	ULONG CardAccessSpeed( struct @{"CardHandle" Link "includes/resources/card.h/Main" 29} *, ULONG );

@{b}   FUNCTION@{ub}
	This function is used to set memory access speed for all CPU
	accesses to card memory.

	Typically this information would be determined by first examining
	the Card Information Structure.

	Then you would use this function to let the card.resource
	select the best possible access speed for you, however note
	that the range of possible access speeds may vary on some
	machines (depending on the type of credit-card interface
	hardware being provided).

@{b}   INPUTS@{ub}
	handle - Same handle as that used when @{"OwnCard()" Link "OwnCard()"} was called.

	nanoseconds - Preferred access speed in nanoseconds.

@{b}   RETURNS@{ub}
	Speed - Access speed selected by resource (in nanoseconds). 

	0  - Not successful.  Either because the credit-card was
	removed, or the access speed you requested is slower than
	that supported by the credit-card interface hardware.

@{b}   NOTES@{ub}
	This function may be called from within a task, or from a level 1
	or level 2 interrupt.

@{b}   SEE ALSO@{ub}
	@{"OwnCard()" Link "OwnCard()"}

@EndNode

@Node "CardChangeCount()" "card.resource/CardChangeCount"

@{b}   NAME@{ub}
	CardChangeCount -- Obtain card change count.
   
@{b}   SYNOPSIS@{ub}
	count = CardChangeCount( VOID )
	d0

	ULONG CardChangeChange( VOID );

@{b}   FUNCTION@{ub}
	This function returns the card change count.  The
	counter is incremented by one for every removal, and
	for every successful insertion (a card which is inserted
	long enough to be debounced before it is removed again).

@{b}   RESULT@{ub}
	The change count number.

@{b}   NOTES@{ub}
	This function may be called from a task, or any level interrupt.

@{b}   SEE ALSO@{ub}

@EndNode

@Node "CardForceChange()" "card.resource/CardForceChange"

@{b}   NAME@{ub}
	CardForceChange -- Force a card change.
   
@{b}   SYNOPSIS@{ub}
	success = CardForceChange( VOID )
	d0

	@{"BOOL" Link "includes/exec/types.h/Main" 68} CardForceChange( VOID );

@{b}   FUNCTION@{ub}
	This function is not intended for general use.  Its
	purpose is to force a credit-card change as if
	the user had removed, or inserted a card.
	
	This function is intended to be used by a utility program
	which needs to force the current card owner to release
	ownership of the card, thereby allowing the utility an
	opportunity to own the credit-card.

@{b}   RESULT@{ub}
	TRUE if the function succeeded, FALSE if card change is
	not allowed.  This function will generally succeed, unless
	someone is using the card in reset remove mode at the time
	this function is called.

@{b}   NOTES@{ub}
	This function should only be called from a task.

@{b}   SEE ALSO@{ub}

@EndNode

@Node "CardInterface()" "card.resource/CardInterface"

@{b}   NAME@{ub}
	CardInterface -- Determine the type of card interface.
   
@{b}   SYNOPSIS@{ub}
	return = CardInterface()
	d0

	ULONG CardInterface( void );

@{b}   FUNCTION@{ub}
	This function is used to determine the type of credit-card
	(hardware) interface available.  For the most part the
	card.resource hides the hardware details from devices within its
	function calls.  However should we need to provide a work-around
	because of differences, or limitations imposed by future interface
	hardware, this function must be used to identify which interface
	is available.

@{b}   RETURN@{ub}
	A ULONG value as defined in card.h/i.

@{b}   NOTES@{ub}
	In general only I/O devices (e.g., a device which interfaces
	with a modem card) would need to provide work-arounds,
	or alternative code.  An example would be a change in the way
	interrupt requests from the card are handled.  Specific details
	will be provided as need in the future.  I/O devices) should abort
	properly if this function returns a value which is unknown.

	Current implementations (see card.h/i) -

	CARD_INTERFACE_AMIGA_0
	-------------------------------------------------------------

	The card slot can be configured for use as an I/O interface
	by using the @{"CardMiscControl()" Link "CardMiscControl()"} function.

	The card slot inhibits writes to cards which do not negate
	the WP status bit.  This can be overridden by using the
	@{"CardMiscControl()" Link "CardMiscControl()"} function.

	Changes in the interrupt request line are latched by a gate-array,
	and have to be obtained via the status change mechanism provided
	when you call the @{"OwnCard()" Link "OwnCard()"} function.  The interrupt is cleared
	when you return from the status change interrupt.  A level 2
	interrupt is generated.  Usually you will want to clear the
	interrupt on the card at this time, and @{"Signal()" Link "exec/Signal()"} a task.  The IRQ
	line is the same as the RDY/BSY line.

	Changes in BVD1, WP, and RDY/BSY are also latched by the gate-array,
	and are obtainable via the status change mechanism provided by
	the @{"OwnCard()" Link "OwnCard()"} function.  A level 2 interrupt is generated.

	Changes in BVD2 (also used for digital audio) have to be
	monitored via polling.  Generally this will cause no problem.
	Monitoring changes in BVD1 & BVD2 to monitor for low battery
	condition can be handled by a low priority tool which periodically
	checks the condition of both lines using the @{"ReadCardStatus()" Link "ReadCardStatus()"}
	function.

	As of card.resource V39 (check VERSION in resource base), the
	@{"CardMiscControl()" Link "CardMiscControl()"} function can be used to enable/disable
	status change interrupts for changes in BVD1, BVD2, and the
	RDY/BSY status line.  Status change interrupts for WR
	(Write-protect enable/disable) are always enabled.  The default
	state of enabled/disabled status change interrupts noted above
	are unchanged, and automatically reset to the defaults when
	a card is removed, or when even a task releases ownership
	of the card.

	Some PC oriented eight (8) bit cards may require you read
	odd-byte I/O address registers at the corresponding even-byte
	address plus 64K.  There is sufficient I/O address space
	provided that exceeding I/O address space should not be a problem.

	Your code should wait at least 1 millisecond for Vpp to stabilize
	after voltage change (see @{"CardProgramVoltage()" Link "CardProgramVoltage()"}).

@{b}    SEE ALSO@{ub}
	@{"CardMiscControl()" Link "CardMiscControl()"}, resources/card.i, @{"resources/card.h" Link "includes/resources/card.h/Main" 0}

@EndNode

@Node "CardMiscControl()" "card.resource/CardMiscControl"

@{b}   NAME@{ub}
	CardMiscControl -- Set/Clear miscellaneous control bits
   
@{b}   SYNOPSIS@{ub}
	control_bits=CardMiscControl( handle, control_bits );
	d0			 	a1      	d1

	@{"UBYTE" Link "includes/exec/types.h/Main" 46} CardMiscControl( struct @{"CardHandle" Link "includes/resources/card.h/Main" 29} *, @{"UBYTE" Link "includes/exec/types.h/Main" 46} );

@{b}   FUNCTION@{ub}
	Used to set/clear miscellaneous control bits (generally for
	use with I/O cards).

@{b}   INPUTS@{ub}
	handle - Same handle as that used when @{"OwnCard()" Link "OwnCard()"} was called.

	control_bits - A mask value of control bits to be turned on/off.

	The bit values which might be usable are defined in card.h/i.

	For example, to enable digital audio, and disable hardware
	write-protect (if supported), you would call this function with these
	values --

	CARDF_DISABLE_WP|CARDF_ENABLE_DIGAUDIO
	
	Then to turn off digital audio, but leave write-protect
	disable, you would use a value of --

	CARDF_DISABLE_WP

	Finally too reenable write protect, call this function with
	a mask value of 0.

@{b}   RETURNS@{ub}
	control_bits - The same mask value you called this function
	with if successful.  If one, or more bits has been cleared
	in the return mask, this would indicate that the control bit
	is not being supported, or that the card has been removed
	by the user.

	For example, if you called this function with a mask value
	of --

	CARDF_DISABLE_WP|CARDF_ENABLE_DIGAUDIO

	And this function returned a value of --

	CARDF_DISABLE_WP

	This would indicate that it is not possible to enable digital
	audio (most likely because this feature has not been implemented).
	
@{b}   NOTES@{ub}
	This function may be called from within a task, or from a level 1
	or level 2 interrupt.

	!!!IMPORTANT!!!

	You should ALWAYS try to enable digital audio for I/O cards
	as this will also configure the card socket for the I/O
	interface (if supported).

	Not all cards will connect the write-enable line (e.g.,
	some I/O cards).  On some machines (e.g., the A600) it will
	not be possible to write to such cards unless you disable
	write-protection by using this function.

	!!!NEW!!!

	For card.resource V39 (check resource base for VERSION before
	using), new bits have been defined which let you enable/disable
	particular status change interrupts.  See @{"CardInterface()" Link "CardInterface()"} for
	defaults.  These new bits are backwards compatable with V37
	for which only the CARDB_DISABLE_WP, and CARDB_ENABLE_DIGAUDIO
	bits were defined.  These new bits allow you to enable, or
	disable specific status change interrupts including BVD1/SC,
	BVD2/DA, and BSY/IRQ.  The defaults for these status change
	interrupts are unchanged from V37, and WR (Write-protect) status
	change interrupts are always enabled as they use to be.

	An example of use:

	CARD_INTF_SETCLR!CARD_INTF_BVD1

	Would enable BVD1/SC status change interrupts, and not change
	the enable/disable state for BVD2/DA or BSY/IRQ status change
	interrupts.  If the change was made successfully, the
	CARD_INTB_BVD1 bit would be set in register D0 when this function
	returns.

@{b}   SEE ALSO@{ub}
	@{"CardInterface()" Link "CardInterface()"}, @{"resources/card.h" Link "includes/resources/card.h/Main" 0}, resources/card.i

@EndNode

@Node "CardProgramVoltage()" "card.resource/CardProgramVoltage"

@{b}   NAME@{ub}
	CardProgramVoltage -- Set programming voltage.
   
@{b}   SYNOPSIS@{ub}
	success=CardProgramVoltage( handle, voltage );
					a1      d0

	@{"LONG" Link "includes/exec/types.h/Main" 35} CardProgramVoltage( struct @{"CardHandle" Link "includes/resources/card.h/Main" 29} *, ULONG );

@{b}   FUNCTION@{ub}
	Used to set programming voltages (e.g., for FLASH-ROM/EPROM
	cards).

@{b}   INPUTS@{ub}
	handle - Same handle as that used when @{"OwnCard()" Link "OwnCard()"} was called.

	voltage - See card.i/h for valid values.

@{b}   RETURNS@{ub}
	1  - Successful.

	0  - Not successful.  Most likely because the credit-card
	card has been removed, and you are no longer the owner.

	-1 - This function is not being supported.  On some machines
	with a minimal (hardware) credit-card interface, this feature
	may not be possible.

@{b}   NOTES@{ub}
	This function may be called from within a task, or from a level 1
	or level 2 interrupt.

       !!!WARNING!!!

	Flash-ROM programming requires careful coding to prevent
	leaving the Erase command on too long.  Failure to observe
	the maximum time between the Erase command, and the Erase-Verify
	command can make a Flash-ROM card unusable.  Some Flash-ROM cards
	may provide an internal watch-dog timer which protects the card.

	Because of the relatively long time (e.g., 10ms) between Erase, and
	Erase-Verify which must be observed, the need for such critical
	timing can be problematic on a multi-tasking machine.

	Vendors of Flash-ROM's recommend a high priority interrupt
	generated by a 10ms timer be used to turn off Erase.  On the
	Amiga this can be accomplished by using a CIA-B interval timer.
	The timer.device also provides a mechanism for generating a low
	priority interrupt.  The timer.device is easier to use than @{"CIA" Link "includes/hardware/cia.h/Main" 28}
	interval timers, though not as accurate or as safe.

	Even if the Flash-ROM card provides an internal watch-dog timer,
	implementation of the code during Erase should assume that
	the Flash-ROM does not.

@{b}   SEE ALSO@{ub}
	@{"OwnCard()" Link "OwnCard()"}, @{"resources/card.h" Link "includes/resources/card.h/Main" 0}, resources/card.i

@EndNode

@Node "CardResetCard()" "card.resource/CardResetCard"

@{b}   NAME@{ub}
	CardResetCard -- Reset credit-card.
   
@{b}   SYNOPSIS@{ub}
	success=CardResetCard( handle );
				a1

	@{"BOOL" Link "includes/exec/types.h/Main" 68} CardResetCard( struct @{"CardHandle" Link "includes/resources/card.h/Main" 29} * );

@{b}   FUNCTION@{ub}
	Used to reset a credit-card.  Some cards, such as some
	configurable cards can be reset.

	Asserts credit-card reset for at least 10us.

@{b}   INPUTS@{ub}
	handle - Same handle as that used when @{"OwnCard()" Link "OwnCard()"} was called.

@{b}   RETURNS@{ub}
	TRUE  - Successful.

	FALSE  - Not successful.  Most likely because the credit-card
	card has been removed, and you are no longer the owner.

@{b}   NOTES@{ub}
	This function may be called from within a task, or from a level 1
	or level 2 interrupt.

	***IMPORTANT***

	It is the responsibility of the card owner to reset
	configurable cards, or any other type of card such as
	some I/O cards before calling @{"ReleaseCard()" Link "ReleaseCard()"} if the owner
	has made use of that card such that it is no longer in its
	reset state (unless you are releasing the card because it
	has been removed).

	If the card manufacturer indicates that a certain amount
	of time must elapse between end of reset, and completion
	of card initialization, you should wait at least that long
	before releasing the card (unless you are releasing the card
	because it has been removed).

@{b}   SEE ALSO@{ub}
	@{"OwnCard()" Link "OwnCard()"}, @{"ReleaseCard()" Link "ReleaseCard()"}

@EndNode

@Node "CardResetRemove()" "card.resource/CardResetRemove"

@{b}   NAME@{ub}
	CardResetRemove -- Set/Clear reset on card removal.
   
@{b}   SYNOPSIS@{ub}
	success=CardResetRemove( handle, flag );
				 a1      d0

	@{"BOOL" Link "includes/exec/types.h/Main" 68} CardResetRemove( struct @{"CardHandle" Link "includes/resources/card.h/Main" 29} *, ULONG );

@{b}   FUNCTION@{ub}
	Used to set/clear HARDWARE @{"RESET" Link "exec/RESET"} on card change detect.

	This function should generally not be used by devices
	which support HOT-REMOVAL.  HARDWARE @{"RESET" Link "exec/RESET"} on removal
	is generally intended for execute-in-place software, or
	ram cards whose memory has been added as system ram.

@{b}   INPUTS@{ub}
	handle - Same handle as that used when @{"OwnCard()" Link "OwnCard()"} was called.

	flag - TRUE if you want to SET HARDWARE @{"RESET" Link "exec/RESET"} on credit
	       card removal.  FALSE if you want to CLEAR HARDWARE
	       @{"RESET" Link "exec/RESET"}.

@{b}   RETURNS@{ub}
	1  - Success.

	0  - Function failed (most likely because the card was removed
	     by the user, and you are no longer the owner of the card).

	-1 - This function is not being made available.

@{b}   NOTES@{ub}
	This function should only be called from a task.

@{b}   SEE ALSO@{ub}
	@{"OwnCard()" Link "OwnCard()"}

@EndNode

@Node "CopyTuple()" "card.resource/CopyTuple"

@{b}   NAME@{ub}
	CopyTuple -- Find/copy a credit card tuple.
   
@{b}   SYNOPSIS@{ub}
	success = CopyTuple( @{"CardHandle" Link "includes/resources/card.h/Main" 29}, buffer, tuplecode, size );
	d0			a1	 a0	 d1	    d0

	@{"BOOL" Link "includes/exec/types.h/Main" 68} CopyTuple( struct @{"CardHandle" Link "includes/resources/card.h/Main" 29} *, @{"UBYTE" Link "includes/exec/types.h/Main" 46} *, ULONG, ULONG );

@{b}   FUNCTION@{ub}
	This function scans credit-card memory for a tuple, and
	if found, copies it into a supplied buffer.  The entire
	tuple (including the tuple code, and link) are copied to
	the supplied buffer.  The number of bytes copied to the
	buffer will be 2 bytes, plus the argument "size", or the
	value in the tuple LINK field (whichever is SMALLER).

	The software calling this function is responsible for
	examining the copy of the tuple (e.g., recognition of
	fields, recognition of stop bytes, etc. within the tuple).
	
	This function does the best job it can to find a tuple
	in attribute, or common memory.  It follows tuple chains,
	and skips odd bytes in attribute memory.

	This function monitors for credit-card removal while reading data.
	If the credit-card is removed while a byte is being read, it will
	stop searching, and return FALSE.

	This function does not protect against another task writing
	to credit-card memory while data is being read.  The device
	is responsible for single-threading reads/writes to the
	credit card as needed.

	This function can be used to find multiple tuple codes; this
	is a very rare case, so the mechanism provided for doing so is
	unusual.  See INPUTS below for more information.

	This function does not read bytes within the body of any tuples
	except for the tuple you want copied, and the basic compatibility
	tuples this function understands (see list below).

	On some machines this function may slow down memory access
	speed while reading the tuple chain.  This is done to prevent
	potential problems on slow cards.  By examining the CISTPL_DEVICE,
	and CISTPL_DEVICE_A tuples, you can determine the best possible
	memory access speed for the type of card inserted.  Because memory
	access speed may be slowed down, calls to this function should
	be single-threaded.

	The Card Information Structure must start with a CISTPL_DEVICE
	tuple stored as the first tuple in attribute memory.  If not,
	this function will search for a CISTPL_LINKTARGET tuple
	stored at byte 0 of common memory.  Therefore it is possible
	to store a CIS on cards which do not have any writeable
	attribute memory, though this may cause problems for other
	software implemented on other machines.  For example, some
	SRAM cards do not come with writeable attribute memory, and/or
	some may have OPTIONAL EEPROM memory which may not have been
	initialized by the card manufacturer.  While it could be
	argued that such cards do not conform to the PCMCIA PC Card
	Standard, such cards are cheaper, and therefore likely to be
	used.

@{b}   INPUTS@{ub}
	@{"CardHandle" Link "includes/resources/card.h/Main" 29} - Same handle as that used when @{"OwnCard()" Link "OwnCard()"} was
	called.

	buffer - Pointer to a buffer where the tuple will be copied.

	The buffer should be at least as large as "size" + 8 (see
	use of "size" argument below).  Therefore the minimum buffer
	size is 8 bytes.  See NOTES below.

	tuplecode - The tuple code you want to search for.  This is
	a ULONG value.  The upper 16 bits should be 0, or a number between
	1-32K where a value of 0 means you want to find the first tuple
	match, a value of 1 the second, etc.  For example -

	0x41 means find the FIRST tuple equal to $41.

	((1<<16)|(0x41)) means find the SECOND tuple equal to $41.

	((2<<16)|(0x41)) means find the THIRD tuple equal to $41.

	size - The maximum number of bytes you want copied (not
	       including the tuple code, and link).  The actual number
	       of bytes copied may be less than "size" if the tuple
	       link field is less than "size".

	       A size of 0 will result in only the tuple code, and
	       link being copied to your buffer if the tuple is found.

	       If you do not care how many bytes are copied, any unsigned
	       value of 255 or greater will do.  In this case a maximum
	       of 257 bytes might be copied to your buffer (if the
	       tuple link field is the maximum of 255).

	       Other sizes are useful if you know the size of the tuple
	       you want copied, or you know there are active registers
	       stored within the tuple, and only want to copy a portion
	       of a tuple.

@{b}   RETURNS@{ub}

	TRUE if the tuple was found, and copied, else FALSE.
	This function may also return false if the CIS is believed
	to be corrupt, or if the card is removed while reading the
	tuples.

@{b}   NOTES@{ub}

	This function can be called multiple times (adjusting the "size"
	argument) to read a tuple of variable length, or unknown size.

	Your supplied buffered is used by this function for working
	storage - the contents of it will be modified even if this
	function fails to find the tuple you want a copy of.

	This function should NOT be used to find/copy tuples of type :

	- CISTPL_LONGLINK_A
	- CISTPL_LONGLINK_C
	- CISTPL_NO_LINK
	- CISTPL_LINKTARGET
	- CISTPL_NULL
	- CISTPL_END
	
	These tuples are automatically handled for you by this function.

@{b}   SEE ALSO@{ub}
	@{"OwnCard()" Link "OwnCard()"}

@EndNode

@Node "DeviceTuple()" "card.resource/DeviceTuple"

@{b}   NAME@{ub}
	DeviceTuple -- Decode a device tuple
   
@{b}   SYNOPSIS@{ub}
	return=DeviceTuple( tuple_data, storage)
		   	    a0		a1	

	ULONG DeviceTuple( @{"UBYTE" Link "includes/exec/types.h/Main" 46} *, struct @{"DeviceTData" Link "includes/resources/card.h/Main" 37} *);

@{b}   FUNCTION@{ub}
	Extracts SIZE, TYPE, and SPEED from a device tuple (generally
	obtained with @{"CopyTuple()" Link "CopyTuple()"}).

@{b}   INPUTS@{ub}
	tuple_data - Pointer to a CISTPL_DEVICE tuple (generally obtained
	with @{"CopyTuple()" Link "CopyTuple()"}).

	storage - Pointer to a @{"DeviceTData" Link "includes/resources/card.h/Main" 37} structure in which results
	are to be stored.

	struct	@{"DeviceTData" Link "includes/resources/card.h/Main" 37} {
		ULONG	dtd_DTsize;		/* Size of card (bytes)	*/
		ULONG	dtd_DTspeed;		/* Speed in nanoseconds	*/
		@{"UBYTE" Link "includes/exec/types.h/Main" 46}	dtd_DTtype;		/* Type of card		*/
		@{"UBYTE" Link "includes/exec/types.h/Main" 46}	dtd_DTflags;		/* Other flags		*/
	};


@{b}   RETURN@{ub}
	SIZE (same as dtd_DTsize) if the @{"Device" Link "includes/exec/devices.h/Main" 23} Tuple could be decoded.
	FALSE (0) if the tuple is believed to be invalid.  The tuple is
	considered to be invalid if:

		The tuple link value is 0.

		The device type/speed byte is $00, or $FF.

		The device type is DTYPE_EXTEND, which is undefined
		as of this writing.

		The extended speed byte is a value which is
		undefined as of this writing.

		The extended speed byte is extended again which is
		undefined as of this writing.

		The device Size byte is $FF.

@{b}   NOTES@{ub}
	Some cards may not have a size specified in the device
	tuple.  An example would be an I/O card.  The size would be
	returned as one (1) in this case.

	You should not call this function with a partial CISTPL_DEVICE
	tuple, or the return values may be junk.

@{b}   SEE ALSO@{ub}
	@{"CopyTuple()" Link "CopyTuple()"}, @{"resources/card.h" Link "includes/resources/card.h/Main" 0}, resources/card.i

@EndNode

@Node "EndCardAccess()" "card.resource/EndCardAccess"

@{b}   NAME@{ub}
	EndCardAccess -- Called at the end of credit-card memory access
   
@{b}   SYNOPSIS@{ub}
	result=EndCardAccess( handle )
	d0			a1

	ULONG EndCardAccess( struct @{"CardHandle" Link "includes/resources/card.h/Main" 29} * );

@{b}   FUNCTION@{ub}
	This function should be called when you are done accessing
	credit-card memory.

	Its effect will depend on the type of Amiga machine your
	code happens to be running on.  On some machines it
	will cause an access light to be turned OFF in approximately
	1/2 second.

	On machines which support an access light, the light will
	automatically be turned off when you call @{"ReleaseCard()" Link "ReleaseCard()"}.

@{b}   INPUTS@{ub}
	handle - Same handle as that used when @{"OwnCard()" Link "OwnCard()"} was called.

@{b}   RETURNS@{ub}
	TRUE if you are still the owner of the credit-card.  FALSE
	if you are no longer the owner of the credit-card (usually
	indicating the card was removed).

@{b}   NOTES@{ub}
	This function may be called from within a task, or from a level 1
	or level 2 interrupt.

	It is highly recommended that you call this function
	after accessing credit-card memory, as well as checking
	the return value.  If it is a return value of FALSE, you
	should stop accessing credit-card memory, and conclude
	that the card was removed before this function was called.

	On some machines it is possible that the credit-card will be
	removed before you receive the removed interrupt.

@{b}   SEE ALSO@{ub}
	@{"OwnCard()" Link "OwnCard()"}, @{"ReleaseCard()" Link "ReleaseCard()"}, @{"BeginCardAccess()" Link "BeginCardAccess()"}

@EndNode

@Node "GetCardMap()" "card.resource/GetCardMap"

@{b}   NAME@{ub}
	GetCardMap -- Obtain pointer to @{"CardMemoryMap" Link "includes/resources/card.h/Main" 44} structure
   
@{b}   SYNOPSIS@{ub}
	pointer=GetCardMap()
	d0

	struct @{"CardMemoryMap" Link "includes/resources/card.h/Main" 44} *GetCardMap( void );

@{b}   FUNCTION@{ub}
	Obtain pointer to a @{"CardMemoryMap" Link "includes/resources/card.h/Main" 44} structure.  The structure
	is READ only.

	Devices should never assume credit-card memory appears
	at any particular place in memory.  By using this function
	to obtain pointers to the base memory locations of the various
	credit-card memory types, your device will continue to work
	properly should credit cards appear in different memory
	locations in future hardware.

@{b}   RETURNS@{ub}
	Pointer to @{"CardMemoryMap" Link "includes/resources/card.h/Main" 44} structure -

		struct @{"CardMemoryMap" Link "includes/resources/card.h/Main" 44} {
		@{"UBYTE" Link "includes/exec/types.h/Main" 46}	*cmm_CommonMemory;
		@{"UBYTE" Link "includes/exec/types.h/Main" 46}	*cmm_AttributeMemory;
		@{"UBYTE" Link "includes/exec/types.h/Main" 46}	*cmm_IOMemory;
		};

	As of card.resource V39, this structure has been extended to
	include the size of these memory regions.  See card.h/card.i
	for the new fields.  If card.resource V39, use the constants
	in the @{"CardMemoryMap" Link "includes/resources/card.h/Main" 44} structure rather than hard coded constants
	for memory region size.

@{b}   NOTES@{ub}
	If any pointer in the structure is NULL, it means this type
	of credit-card memory is not being made available.

@{b}   SEE ALSO@{ub}
	@{"resources/card.h" Link "includes/resources/card.h/Main" 0}, resources/card.i

@EndNode

@Node "IfAmigaXIP()" "card.resource/IfAmigaXIP"

@{b}   NAME@{ub}
	IfAmigaXIP -- Check if a card is an Amiga execute-in-place card.
   
@{b}   SYNOPSIS@{ub}
	result=IfAmigaXIP( handle )
	d0		       a2

	struct @{"Resident" Link "includes/exec/resident.h/Main" 17} *IfAmigaXIP( struct @{"CardHandle" Link "includes/resources/card.h/Main" 29} * );

@{b}   FUNCTION@{ub}
	Check to see if a card in the slot is an Amiga execute-in-place
	card.  The Card Information Structure must have a valid
	CISTPL_AMIGAXIP tuple.
	
	Tuples can be treated like structures.  The format of a
	CISTPL_AMIGAXIP tuple is -
	

 	struct @{"TP_AmigaXIP" Link "includes/resources/card.h/Main" 163} {
		@{"UBYTE" Link "includes/exec/types.h/Main" 46}	TPL_CODE;
		@{"UBYTE" Link "includes/exec/types.h/Main" 46}	TPL_LINK;
		@{"UBYTE" Link "includes/exec/types.h/Main" 46}	TP_XIPLOC[4];
		@{"UBYTE" Link "includes/exec/types.h/Main" 46}	TP_XIPFLAGS;
		@{"UBYTE" Link "includes/exec/types.h/Main" 46}	TP_XIPRESRV;
	};


	The TPL_CODE field must be equal to CISTPL_AMIGAXIP (0x91).

	The TPL_LINK field must be equal to the length of the body
	of a CISTPL_AMIGAXIP tuple (0x06).

	The TP_XIPLOC array is the memory location of your ROM-TAG
	stored in little-endian order.  This value is stored as an
	"offset" into common memory as is the standard for storing 32 bit
	bit pointers in tuples.

	For example, a pointer to a ROM-TAG stored at an offset of
	0x00000200 would be stored as four bytes like so:

		0x00, 0x02, 0x00, 0x00

	Currently credit-card common memory is mapped starting at
	memory location 0x600000.  Because a ROM-TAG is used,
	it is implied that execute-in-place code can be compiled/linked
	to use absolute references.  It is believed that most developers
	will not want to have to write pc-relative code only.

	The TP_XIPFLAGS field is treated as a set of flag bits.
	See card.i/h for defined bits.  All undefined bits MUST be
	0.

	The TP_XIPRESRV field must be 0 for now.
	

	The system polls for cards which have a CISTPL_AMIGAXIP tuple
	at the same time that it searches for devices to boot off.
	When a card with a valid CISTPL_AMIGAXIP tuple is found, the
	system will call your ROM-TAG via Exec's @{"InitResident()" Link "exec/InitResident()"} function.

	The system examines the return code from @{"InitResident()" Link "exec/InitResident()"}.  A
	NULL return in D0 means you are done with the card, and it can
	be removed by the user.  A successful return indicates you are
	still using the card.  Some programs (e.g., some games) may
	never return.  The only requirement is that if you do return,
	you must leave the system in a "good" state (including returning
	most of, or all the memory you allocated).  The standard
	convention for preserving registers apply.

	Note that your execute-in-place code will not be called
	a second time, unless you have returned a non-successful
	result.  In this case your execute-in-place code MUST
	assume the user can remove, and insert your card again.
	There are a variety of ways to check for re-insertion
	(e.g., search for a message port, device, library, task,
	etc., that you created).

	Note that your execute-in-place code runs in an environment
	similar to boot block games; before DOS has been initialized!

	Your execute-in-place code should NOT try to initialize DOS
	because DOS requires a suitable disk-like device be at
	the head of the expansion base mountlist to boot off.

	If you need DOS, it is possible to boot off a credit-card using
	carddisk.device.  Such cards will require a valid
	CISTPL_DEVICE tuple, and CISTPL_FORMAT tuple.  A portion
	of the card can be used for a minimal number of data blocks
	like the method described above.

	However this method is not recommended, though it is anticipated
	that some developers will have thought of, and used this
	method anyway.  If you must do this, at least use the
	@{"CardHandle" Link "includes/resources/card.h/Main" 29} returned by @{"OwnCard()" Link "OwnCard()"} to set hardware reset
	on removal else the machine will likely crash anyway if
	the card is removed while your execute-in-place code is running.

@{b}   RETURNS@{ub}
	Pointer to a ROM-TAG on the card, or NULL indicating that:

	o The card does not meet the above requirements, or
	o The card has been removed, or
	o You are not the owner of the credit-card.

@{b}   NOTES@{ub}
	This function is being made public so developers can test
	test that their execute-in-place credit-cards meet the
	requirements for an Amiga execute-in-place card.  In general
	there is no reason for devices, or applications to use this
	function.

	Amiga execute-in-place software is identified via a tuple code
	reserved for manufacturer specific use, therefore the manufacturer
	of the card may freely use the CISTPL_VERS_1, or CISTPL_VERS_2
	tuples to place identification information on the credit-card.

	No attempt has been made to make use of the MS-DOS execute-in-place
	method; it is believed that most manufacturers of Amiga
	execute-in-place software will prefer a simple, and small
	scheme for running their execute-in-place code.

@{b}   SEE ALSO@{ub}
	@{"OwnCard()" Link "OwnCard()"}, @{"resources/card.h" Link "includes/resources/card.h/Main" 0}, resources/card.i

@EndNode

@Node "OwnCard()" "card.resource/OwnCard"

@{b}   NAME@{ub}
	OwnCard -- Own credit card registers, and memory
   
@{b}   SYNOPSIS@{ub}
	return = OwnCard( handle )
	d0		a1

	struct @{"CardHandle" Link "includes/resources/card.h/Main" 29} *OwnCard( struct @{"CardHandle" Link "includes/resources/card.h/Main" 29} * );

@{b}   FUNCTION@{ub}
	This function is used to obtain immediate, or deferred
	ownership of a credit-card in the credit-card slot.

	Typically an EXEC STYLE DEVICE will be written to interface
	between an application, and a credit card in the slot.  While
	applications, and libraries can attempt to own a credit-card
	in the card slot, the rest of this documentation assumes a
	device interface will be used.

	Because credit-cards can be inserted, or removed by the user at
	any time (otherwise known as HOT-INSERTION, and HOT-REMOVAL),
	the card.resource provides devices with a protocol which
	lets many devices bid for ownership of a newly inserted card.

	In general, devices should support HOT-REMOVAL, however there
	are legitimate cases where HOT-REMOVAL is not practical.  For
	these cases this function allows you to own the resource using
	the CARDB_RESETREMOVE flag.  If the card is removed before your
	device calls @{"ReleaseCard()" Link "ReleaseCard()"}, the machine will @{"RESET" Link "exec/RESET"}.

@{b}   INPUTS@{ub}
	handle - pointer to a @{"CardHandle" Link "includes/resources/card.h/Main" 29} structure.

		struct @{"CardHandle" Link "includes/resources/card.h/Main" 29} {
		struct @{"Node" Link "includes/exec/nodes.h/Main" 21} 		 cah_CardNode;
		struct @{"Interrupt" Link "includes/exec/interrupts.h/Main" 21}	*cah_CardRemoved;
		struct @{"Interrupt" Link "includes/exec/interrupts.h/Main" 21}	*cah_CardInserted;
		struct @{"Interrupt" Link "includes/exec/interrupts.h/Main" 21}	*cah_CardStatus;
		@{"UBYTE" Link "includes/exec/types.h/Main" 46}			 cah_CardFlags;
		};

	The following fields in the structure must be filled
	in by the application before calling OwnCard() -

	cah_CardNode.ln_Pri -

		See table below.  The @{"Node" Link "includes/exec/nodes.h/Main" 21} field is used by the resource to
		add your handle to a sorted list of @{"CardHandle" Link "includes/resources/card.h/Main" 29} structures. 
		This list is used by the resource to notify devices when the
		device owns the credit-card.

		Your device will only be notified (at most) one time
		per card insertion, and perhaps less often if some
		higher priority device on the notification list retains
		ownership of a card in the slot.

	Priority	Comments
	--------------------------------------------------
		>= 21	Reserved for future use

		10-20	To be used by third party devices (e.g.,
			I/O CARD manufacturers) which look for
			specific card tuples to identify credit-cards.

		01-19	Reserved for future use

		00	To be used by general purpose devices which
			have loose card specification requirements.

		<= -1	Reserved for future use

		  
	cah_CardNode.ln_Type -

		Must be set to 0 for now.  This field may be used in the
		future to identify an extended @{"CardHandle" Link "includes/resources/card.h/Main" 29} structure.

	cah_CardNode.ln_Name -

		Must be initialized to NULL, or name of device which owns
		this structure.

	cah_CardRemoved -

		Pointer to an initialized interrupt structure.  Only the
		is_Data, and is_Code fields need to be initialized.  This
		is the interrupt code which will be called when a credit-card
		which your device owns is removed.  Once you receive this
		interrupt, all credit-card interface control registers are
		reset (e.g., programming voltage, access speed, etc.), and 
		you should stop accessing the card as soon as possible.

		Because your code is called on interrupt time, you
		should do the least amount possible, and use little
		stack space.

		This pointer can be NULL if you have asked for reset
		on card-removal, and you never turn reset off.

	cah_ CardInserted -

		Pointer to an initialized interrupt structure.  Only the
		is_Data, and is_Code fields need to be initialized.  This
		is the code which will be called when your @{"CardHandle" Link "includes/resources/card.h/Main" 29} owns
		the credit-card in the slot.

		Note that your code may be called on the context of
		an interrupt, or a task in FORBID, therefore you should
		do the least amount possible, and use little stack space.

		Note that it is possible to receive a card removed
		interrupt immediately before you receive this interrupt if
		the card is removed while your CardInserted interrupt
		is being called.
		
		Your device owns the credit-card until the card is manually
		removed by the user, or you release the card by calling
		@{"ReleaseCard()" Link "ReleaseCard()"}.

		Your device should examine the card in the slot (e.g., look
		for specific tuples), and decide if the card is of a type your
		device understands.

		If not, release ownership of the card by calling
		@{"ReleaseCard()" Link "ReleaseCard()"} so that other devices will be given a chance to
		examine the current card in the credit-card slot.

	cah_CardStatus -

		Pointer to an initialized interrupt structure.  Only the
		is_Data, and is_Code fields need to be initialized.

		Note that your code will be called on the context of
		an interrupt, therefore you should do the least
		amount possible, and use little stack space.

		Note that it is possible to receive a card removed
		interrupt immediately before you receive this interrupt
		if the card is removed during this interrupt.
		
		If this pointer is NULL, you will not receive card status
		change interrupts.

		Your interrupt code will be called with a mask value in
		register D0, and a pointer to your data in A1.

		The mask value in D0 can be interpreted using the same bit
		definitions returned by @{"ReadCardStatus()" Link "ReadCardStatus()"}.  Note that more
		than one bit may be set, and the mask only tells you what has
		changed, not the current state.

		Use @{"ReadCardStatus()" Link "ReadCardStatus()"} if you need to determine the current
		state of the status bits.

		Not all status change interrupts will necessarily be
		enabled on all systems.  For example, on some systems
		BVD2/DA status change interrupts will not be enabled so
		that digital audio can occur without generating many
		interrupts.  Status change interrupts are typically meant
		to be used for monitoring BSY/IRQ, WR, and BVD1/SC.  Battery
		voltage low detection would best be done by a separate
		utility which periodically polls BVD1 & BVD2 by using the
		@{"ReadCardStatus()" Link "ReadCardStatus()"} function.

		Typically the mask value in D0 MUST be returned unchanged
		on exit from your code.  The return value in D0 is then used
		to clear the source(s) of the interrupt.

		In the rare case that you need to keep a status change
		interrupt active, clear the appropriate bit(s) in D0 before
		returning via RTS.  Clear no bits other than those defined
		as valid bits for ReadCardStatus()!

		!!!NEW FOR V39!!!

		See definition of CARDB_POSTSTATUS below.

	cah_CardFlags -

		Optional flags (all other bits must be 0).

		- CARDB_RESETREMOVE means you want the machine to
		  reset if the credit-card in the slot is removed
		  while you own the credit-card.

		- CARDB_IFAVAILABLE means you only want ownership of
		  the credit-card in the slot if it is immediately
		  available.

		If it is available, your @{"CardHandle" Link "includes/resources/card.h/Main" 29} structure will be added
		to a list so that you can be notified via an interrupt when
		the credit-card is removed by the user.

		If the credit-card is not immediately available (either
		because there is no credit-card in the slot, or because some
		other device owns the credit-card), your @{"CardHandle" Link "includes/resources/card.h/Main" 29} structure
		will NOT be added to the notification list.

		- CARDB_DELAYOWNERSHIP means you never want a successful
		  return from OwnCard() even if the credit-card is
		  available.  Rather you will be notified of ownership
		  via your cah_CardInserted interrupt.  If you use this flag,
		  OwnCard() will always return -1.  This flag cannot be used
		  with the CARDB_IFAVAILABLE flag.

		- CARDB_POSTSTATUS is new for V39 card.resource (check
		  resource base VERSION before using).  It is meant to be
		  used by drivers which want to service the card hardware
		  AFTER the status change interrupt has been cleared on the
		  gate array.  Previously a PORTS interrupt server had 
		  to be added to do this; this is somewhat more efficient, and
		  easier to use.  Your status change interrupt is first called
		  with status change bits in register D0.  You would examine
		  these bits, and set a flag(s) for the POST callback.  When
		  you return from the status change interrupt, the interrupt
		  on the gate array is cleared (based on what you return in
		  register D0), and your status change interrupt is immediately 
		  called again, but this time with 0 in D0.  The value you
		  return in D0 for the POST callback case is ignored.
		  

	ALL other fields are used by the resource, and no fields in the
	structure may be modified while the structure is in use by the
	resource.  If you need to make changes, you must remove your
	@{"CardHandle" Link "includes/resources/card.h/Main" 29} (see @{"ReleaseCard()" Link "ReleaseCard()"}), make the changes, and then call
	OwnCard() again.

@{b}   RESULTS@{ub}
	 0  - indicates success, your device owns the credit card.

	-1  - indicates that the card cannot be owned (most likely 
	      because there is no card in the credit card slot).

	ptr - indicates failure.  Returns pointer to the @{"CardHandle" Link "includes/resources/card.h/Main" 29}
	      structure which owns the credit card.

@{b}   NOTES@{ub}
	This function should only be called from a task.

  	@{"CardHandle" Link "includes/resources/card.h/Main" 29} interrupts are called with a pointer to your data
	in A1, and a pointer to your code in A5.  With the exception
	of status change interrupts, D0-D1, A0-A1, and A5-A6 may be
	treated as scratch registers.  Status change interrupts are
	also called with meaningful data in D0, and expect D0 be
	preserved upon RTS from your code.  No other registers are
	guaranteed to contain initialized data.  All other registers
	must be preserved.

@{b}    SEE ALSO@{ub}
	@{"ReleaseCard()" Link "ReleaseCard()"}, @{"ReadCardStatus()" Link "ReadCardStatus()"}, resources/card.i, @{"resources/card.h" Link "includes/resources/card.h/Main" 0}

@EndNode

@Node "ReadCardStatus()" "card.resource/ReadCardStatus"

@{b}   NAME@{ub}
	ReadCardStatus -- Read credit card status register
   
@{b}   SYNOPSIS@{ub}
	status=ReadCardStatus()
	d0

	@{"UBYTE" Link "includes/exec/types.h/Main" 46} ReadCardStatus( void );

@{b}   FUNCTION@{ub}
	Returns current state of the credit card status register.

	See card.h/i for bit definitions.

	Note that the meaning of the returned status bits may vary
	depending on the type of card inserted in the slot, and
	mode of operation.  Interpretation of the bits is left
	up to the application.

@{b}   RETURNS@{ub}
	A @{"UBYTE" Link "includes/exec/types.h/Main" 46} value to be interpreted as status bits.

@{b}   NOTES@{ub}
	This function may be called from within a task, or from any level
	interrupt.

@{b}   SEE ALSO@{ub}
	@{"resources/card.h" Link "includes/resources/card.h/Main" 0}, resources/card.i

@EndNode

@Node "ReleaseCard()" "card.resource/ReleaseCard"

@{b}   NAME@{ub}
	ReleaseCard -- Release ownership of credit card
   
@{b}   SYNOPSIS@{ub}
	ReleaseCard( handle, flags )
		     a1	     d0

	void ReleaseCard( struct @{"CardHandle" Link "includes/resources/card.h/Main" 29} *, ULONG );

@{b}   FUNCTION@{ub}
	This function releases ownership of the credit card in the
	slot.

	The access light (if any) is automatically turned off
	(if it was turned on) when you release ownership of
	a card you owned, and all credit-card control registers
	are reset to their default state.

	You must call this function if -

	You own the credit-card, and want to release it so that
	other devices on the notification list will have a chance
	to examine the credit-card in the card slot.

	You took a Card Removed interrupt while you owned the
	credit-card.  If so, you MUST call this function, else
	no other task will be notified of newly inserted cards.  On
	some machines the credit-card interface hardware may also
	be left disabled until you respond to the card removed interrupt
	by calling this function.

	You want to remove yourself from the notification list (see
	optional flags below).

@{b}   INPUTS@{ub}
	handle - Same handle as that used when @{"OwnCard()" Link "OwnCard()"} was called.

	flags - Optional flags.

		- CARDB_REMOVEHANDLE means you want remove your
		@{"CardHandle" Link "includes/resources/card.h/Main" 29} structure from the notification list
		whether or not you currently own the credit-card
		in the card slot.  The node structure in your
		@{"CardHandle" Link "includes/resources/card.h/Main" 29} will be removed from the notification
		list, and ownership will be released if you were
		the owner of the card.

@{b}   NOTES@{ub}
	This function should only be called from a task.

@{b}    SEE ALSO@{ub}
	@{"OwnCard()" Link "OwnCard()"}, resources/card.i, @{"resources/card.h" Link "includes/resources/card.h/Main" 0}

@EndNode

