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

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

@{" BeginCardAccess() " Link "BeginCardAccess()"}    @{" CardProgramVoltage() " Link "CardProgramVoltage()"}    @{" GetCardMap() " Link "GetCardMap()"}
@{" CardAccessSpeed() " Link "CardAccessSpeed()"}    @{" CardResetCard() " Link "CardResetCard()"}         @{" IfAmigaXIP() " Link "IfAmigaXIP()"}
@{" CardChangeCount() " Link "CardChangeCount()"}    @{" CardResetRemove() " Link "CardResetRemove()"}       @{" OwnCard() " Link "OwnCard()"}
@{" CardForceChange() " Link "CardForceChange()"}    @{" CopyTuple() " Link "CopyTuple()"}             @{" ReadCardStatus() " Link "ReadCardStatus()"}
@{" CardInterface() " Link "CardInterface()"}      @{" DeviceTuple() " Link "DeviceTuple()"}           @{" ReleaseCard() " Link "ReleaseCard()"}
@{" CardMiscControl() " Link "CardMiscControl()"}    @{" EndCardAccess() " Link "EndCardAccess()"}

@EndNode

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

NAME
    BeginCardAccess -- Called before you begin credit-card memory access

SYNOPSIS
    result=BeginCardAccess( handle )
    d0                      a1

    BOOL BeginCardAccess( struct @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 29} * );

FUNCTION
    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.

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

RETURNS
    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).

NOTES
    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.

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

@EndNode

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

NAME
    CardAccessSpeed -- Select best possible memory access speed.

SYNOPSIS
    result=CardAccessSpeed( handle, nanoseconds );
    d0                       a1      d0

    ULONG CardAccessSpeed( struct @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 29} *, ULONG );

FUNCTION
    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).

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

    nanoseconds - Preferred access speed in nanoseconds.

RETURNS
    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.

NOTES
    This function may be called from within a task, or from a level 1
    or level 2 interrupt.

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

@EndNode

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

NAME
    CardChangeCount -- Obtain card change count.

SYNOPSIS
    count = CardChangeCount( VOID )
    d0

    ULONG CardChangeChange( VOID );

FUNCTION
    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).

RESULT
    The change count number.

NOTES
    This function may be called from a task, or any level interrupt.

SEE ALSO

@EndNode

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

NAME
    CardForceChange -- Force a card change.

SYNOPSIS
    success = CardForceChange( VOID )
    d0

    BOOL CardForceChange( VOID );

FUNCTION
    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.

RESULT
    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.

NOTES
    This function should only be called from a task.

SEE ALSO

@EndNode

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

NAME
    CardInterface -- Determine the type of card interface.

SYNOPSIS
    return = CardInterface()
    d0

    ULONG CardInterface( void );

FUNCTION
    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.

RETURN
    A ULONG value as defined in card.h/i.

NOTES
    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.  The interrupt should also be cleared on
    the card at this time.  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.

    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()"}).

SEE ALSO
    @{"CardMiscControl()" Link "CardMiscControl()"}, resources/card.i, @{"resources/card.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 0}

@EndNode

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

NAME
    CardMiscControl -- Set/Clear miscellaneous control bits

SYNOPSIS
    control_bits=CardMiscControl( handle, control_bits );
    d0                              a1              d1

    UBYTE CardMiscControl( struct @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 29} *, UBYTE );

FUNCTION
    Used to set/clear miscellaneous control bits (generally for
    use with I/O cards).

INPUTS
    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.

RETURNS
    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).

NOTES
    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.

SEE ALSO
    @{"CardInterface()" Link "CardInterface()"}, @{"resources/card.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 0}, resources/card.i

@EndNode

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

NAME
    CardProgramVoltage -- Set programming voltage.

SYNOPSIS
    success=CardProgramVoltage( handle, voltage );
                                    a1      d0

    LONG CardProgramVoltage( struct @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 29} *, ULONG );

FUNCTION
    Used to set programming voltages (e.g., for FLASH-ROM/EPROM
    cards).

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

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

RETURNS
    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.

NOTES
    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 "ADCD_v1.2:Inc&AD2.1/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.

SEE ALSO
    @{"OwnCard()" Link "OwnCard()"}, @{"resources/card.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 0}, resources/card.i

@EndNode

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

NAME
    CardResetCard -- Reset credit-card.

SYNOPSIS
    success=CardResetCard( handle );
                            a1

    BOOL CardResetCard( struct @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 29} * );

FUNCTION
    Used to reset a credit-card.  Some cards, such as some
    configurable cards can be reset.

    Asserts credit-card reset for at least 10us.

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

RETURNS
    TRUE  - Successful.

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

NOTES
    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).

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

@EndNode

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

NAME
    CardResetRemove -- Set/Clear reset on card removal.

SYNOPSIS
    success=CardResetRemove( handle, flag );
                             a1      d0

    BOOL CardResetRemove( struct @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 29} *, ULONG );

FUNCTION
    Used to set/clear HARDWARE RESET on card change detect.

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

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

    flag - TRUE if you want to SET HARDWARE RESET on credit
           card removal.  FALSE if you want to CLEAR HARDWARE
           RESET.

RETURNS
    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.

NOTES
    This function should only be called from a task.

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

@EndNode

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

NAME
    CopyTuple -- Find/copy a credit card tuple.

SYNOPSIS
    success = CopyTuple( @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 29}, buffer, tuplecode, size );
    d0                      a1       a0      d1         d0

    BOOL CopyTuple( struct @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 29} *, UBYTE *, ULONG, ULONG );

FUNCTION
    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.

INPUTS
    @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/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.

RETURNS
    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.

NOTES
    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.

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

@EndNode

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

NAME
    DeviceTuple -- Decode a device tuple

SYNOPSIS
    return=DeviceTuple( tuple_data, storage)
                        a0          a1

    ULONG DeviceTuple( UBYTE *, struct @{"DeviceTData" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 37} *);

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

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

    storage - Pointer to a @{"DeviceTData" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 37} structure in which results
    are to be stored.

    struct  @{"DeviceTData" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 37} {
            ULONG   dtd_DTsize;             /* Size of card (bytes) */
            ULONG   dtd_DTspeed;            /* Speed in nanoseconds */
            UBYTE   dtd_DTtype;             /* Type of card         */
            UBYTE   dtd_DTflags;            /* Other flags          */
    };

RETURN
    SIZE (same as dtd_DTsize) if the @{"Device" Link "ADCD_v1.2:Inc&AD2.1/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.

NOTES
    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.

SEE ALSO
    @{"CopyTuple()" Link "CopyTuple()"}, @{"resources/card.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 0}, resources/card.i

@EndNode

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

NAME
    EndCardAccess -- Called at the end of credit-card memory access

SYNOPSIS
    result=EndCardAccess( handle )
    d0                      a1

    ULONG EndCardAccess( struct @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 29} * );

FUNCTION
    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()"}.

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

RETURNS
    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).

NOTES
    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.

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

@EndNode

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

NAME
    GetCardMap -- Obtain pointer to @{"CardMemoryMap" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 44} structure

SYNOPSIS
    pointer=GetCardMap()
    d0

    struct @{"CardMemoryMap" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 44} *GetCardMap( void );

FUNCTION
    Obtain pointer to a @{"CardMemoryMap" Link "ADCD_v1.2:Inc&AD2.1/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.

RETURNS
    Pointer to @{"CardMemoryMap" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 44} structure -

            struct @{"CardMemoryMap" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 44} {
            UBYTE   *cmm_CommonMemory;
            UBYTE   *cmm_AttributeMemory;
            UBYTE   *cmm_IOMemory;
            };

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

SEE ALSO
    @{"resources/card.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 0}, resources/card.i

@EndNode

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

NAME
    IfAmigaXIP -- Check if a card is an Amiga execute-in-place card.

SYNOPSIS
    result=IfAmigaXIP( handle )
    d0                     a2

    struct @{"Resident" Link "ADCD_v1.2:Inc&AD2.1/Includes/exec/resident.h/Main" 17} *IfAmigaXIP( struct @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 29} * );

FUNCTION
    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 "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 121} {
            UBYTE   TPL_CODE;
            UBYTE   TPL_LINK;
            UBYTE   TP_XIPLOC[4];
            UBYTE   TP_XIPFLAGS;
            UBYTE   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 "ADCD_v1.2:Inc&AD2.1/Autodocs/exec/InitResident()"} function.

    The system examines the return code from @{"InitResident()" Link "ADCD_v1.2:Inc&AD2.1/Autodocs/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 "ADCD_v1.2:Inc&AD2.1/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.

RETURNS
    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.

NOTES
    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.

SEE ALSO
    @{"OwnCard()" Link "OwnCard()"}, @{"resources/card.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 0}, resources/card.i

@EndNode

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

NAME
    OwnCard -- Own credit card registers, and memory

SYNOPSIS
    return = OwnCard( handle )
    d0              a1

    struct @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 29} *OwnCard( struct @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 29} * );

FUNCTION
    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.

INPUTS
    handle - pointer to a @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 29} structure.

            struct @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 29} {
            struct @{"Node" Link "ADCD_v1.2:Inc&AD2.1/Includes/exec/nodes.h/Main" 21}                  cah_CardNode;
            struct @{"Interrupt" Link "ADCD_v1.2:Inc&AD2.1/Includes/exec/interrupts.h/Main" 21}       *cah_CardRemoved;
            struct @{"Interrupt" Link "ADCD_v1.2:Inc&AD2.1/Includes/exec/interrupts.h/Main" 21}       *cah_CardInserted;
            struct @{"Interrupt" Link "ADCD_v1.2:Inc&AD2.1/Includes/exec/interrupts.h/Main" 21}       *cah_CardStatus;
            UBYTE                    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 "ADCD_v1.2:Inc&AD2.1/Includes/exec/nodes.h/Main" 21} field is used by the resource to
            add your handle to a sorted list of @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/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 "ADCD_v1.2:Inc&AD2.1/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 "ADCD_v1.2:Inc&AD2.1/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()!

    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 "ADCD_v1.2:Inc&AD2.1/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 "ADCD_v1.2:Inc&AD2.1/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.

    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 "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 29} (see @{"ReleaseCard()" Link "ReleaseCard()"}), make the changes, and then call
    OwnCard() again.

RESULTS
     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 "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 29}
          structure which owns the credit card.

NOTES
    This function should only be called from a task.

    @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/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.

SEE ALSO
    @{"ReleaseCard()" Link "ReleaseCard()"}, @{"ReadCardStatus()" Link "ReadCardStatus()"}, resources/card.i, @{"resources/card.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 0}

@EndNode

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

NAME
    ReadCardStatus -- Read credit card status register

SYNOPSIS
    status=ReadCardStatus()
    d0

    UBYTE ReadCardStatus( void );

FUNCTION
    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.

RETURNS
    A UBYTE value to be interpreted as status bits.

NOTES
    This function may be called from within a task, or from any level
    interrupt.

SEE ALSO
    @{"resources/card.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 0}, resources/card.i

@EndNode

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

NAME
    ReleaseCard -- Release ownership of credit card

SYNOPSIS
    ReleaseCard( handle, flags )
                 a1      d0

    void ReleaseCard( struct @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 29} *, ULONG );

FUNCTION
    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).

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

    flags - Optional flags.

            - CARDB_REMOVEHANDLE means you want remove your
            @{"CardHandle" Link "ADCD_v1.2:Inc&AD2.1/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 "ADCD_v1.2:Inc&AD2.1/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.

NOTES
    This function should only be called from a task.

SEE ALSO
    @{"OwnCard()" Link "OwnCard()"}, resources/card.i, @{"resources/card.h" Link "ADCD_v1.2:Inc&AD2.1/Includes/resources/card.h/Main" 0}

@EndNode

