# CARD_ReadRomAsync

## C Specification

      #include <nitro/card.h>

      void CARD_ReadRomAsync(
          u32                 dma,
          const void          *src,
          void                *dst,
          u32                 len,
          MIDmaCallback       callback,
          void                *arg);

## Description

This function asynchronously loads data from a device that has ROM. The access bus must be locked before using this function.

If a valid DMA channel is specified, this function uses that channel after explicitly stopping it with the `MI_StopDma` function.

If the previous access has not completed, this function waits until the previous access completes.

If this function explicitly specifies CPU transfer, it behaves the same as the synchronous version, the `CARD_ReadRom` function.

In the previous version of this function, the transfer source, transfer destination, and transfer size were restricted by hardware. This restriction no longer exists.

## Internal Operation

This function uses the IRQ handler to operate asynchronously only if the following conditions are True:

- DMA is enabled
- Direct card access is possible
- The transfer destination is word aligned
- The transfer source is set to an integer multiple of `CARD_ROM_PAGE_SIZE`
- The transfer size is set to an integer multiple of `CARD_ROM_PAGE_SIZE`

If any of these conditions are not met, `CARD_ReadRomAsync` uses an internal thread for asynchronous processing.

For more information on this thread, see the description in the `CARD_GetThreadPriority` function.

The following table shows the ROM access methods for each execution environment:

Operating Environment | ROM device | Operation
--- | --- | ---
TS | (Always game card) | Directly accesses the card using DMA.
TEG | Game Card | Because the main processor cannot access a card in the TEG environment, the transfer request is sent to the IO processor via PXI.
Game Pak | Directly access the game pak using DMA or CPU transfer.

## Caution

If a valid DMA channel is specified by this function, that DMA channel is not available until the transfer is complete.

Note: Because this function uses interrupts internally, the process does not complete if it attempts to run while interrupts are prohibited.

## Arguments

`dma` | The DMA channel to be used for transfer. If a DMA channel that is out of range is specified for transfer, the CPU transfers. If a valid DMA channel is specified, that DMA channel is not available for any other task until the transfer is complete.
`src` | Transfer source CARD ROM address
`dst` | Transfer destination memory address
`len` | Length of the read data in bytes
`callback` | Completion-time callback function. Specify `NULL` when not needed.
`arg` | This is ignored if `NULL` is specified in the `callback` argument passed to the completion-time callback function.

## Return Values

None.

## See Also

`CARD_ROM_PAGE_SIZE, CARD_LockRom, CARD_ReadRom, CARD_TryWaitRomAsync, CARD_WaitRomAsync, CARD_GetThreadPriority, MI_StopDma`

## Revision History

11/02/2004 Corrected an argument name.
07/28/2004 Corrected the callback types and the `GetThreadPriority` link.
07/19/2004 Changed description of internal operation.
07/09/2004 Due to function format change, revised description / added description of internal operation.
07/05/2004 Initial version.