# CARD_ReadRomAsync

## C Specification

  `#include <nitro/card.h>`
  `void CARD_ReadRomAsync(u32 dma, const void *src, void *dst, u32 len, MIDmaCallback callback, void *arg);`

## Arguments

dma

The DMA channel to be used for transfer.
If the specified value is out of range, the process will execute by CPU transfer.If a valid DMA channel is specified, that DMA channel will not be available for any other task until transfer is complete.
The card access transfer source is an IO register, so DMA Channel 0 cannot be specified.

src | The transfer source CARD ROM address.
dst | Transfer destination memory address
len | Byte length of data being read
callback | The callback function for when process has completed. If not necessary, specify NULL. If a valid DMA channel has been specified, this callback is called from inside the DMA interrupt handler.
arg | Argument passed to the callback function when the process completes. If NULL has been specified for the callback, this value is simply ignored.

## Return Values

None.

## 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 old version of this function, the transfer source, transfer destination, and transfer size were restricted by hardware. These restrictions no longer exist.

## Note

If a valid DMA channel is specified by this function, that DMA channel will not be available until transfer is complete.
Note that because this function uses interrupts internally, the process will not complete if it attempts to run while interrupts are prohibited.

## Internal Operation

`This function operates asynchronously using DMA transfers and the IRQ handler only if the following conditions are satisfied:
In that case, transfers of card data can be done in parallel with CPU processing.`

- The transfer destination range can be accessed by DMA and is 32-byte aligned.
- The transfer source range is aligned to CARD_ROM_PAGE_SIZE bytes.
- The transfer size is aligned to CARD_ROM_PAGE_SIZE bytes.

If these conditions are not all met, the process will be executed asynchronously by a CPU process using a CARD library internal thread regardless of whether DMA transfer has been specified or not.
For more information on this thread, see the description for the `CARD_GetThreadPriority` function.
Here are some main points you need to be aware of with the application in order to ensure that the conditions for DMA transfer are satisfied:

- Do not specify an automatic variable as transfer destination. (By default, the stack is allocated from DTCM, so DMA access is impossible.)
- Specify Align or AlignAll in the RomSpec section of the RSF file, and place the file so it has 512 byte alignment.
- If the size of the file is not an integral multiple of 512 bytes, divide up the file so it is read in segments that are integral multiples of 512 bytes.

## See Also

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

## Revision History

05/10/2006 Changed specifications so that DMA transfer is not performed unless the transfer destination range is aligned at 32-byte boundaries.
08/22/2005 Made substantial corrections to the Internal Operation section.
06/01/2005 Added explanation that callback is called from interrupt handler.
04/28/2005 Added section noting that DMA channel 0 cannot be specified.
12/09/2004 Made correction, changing "IO processor" to "ARM7 processor."
11/02/2004 Corrected argument names to be same as in header file.
07/28/2004 Corrected the callback type.
07/19/2004 Changed the explanation of internal operations.
07/09/2004 Corrected description due to function format changes and added an explanation of internal operations.
07/05/2004 Initial version.

CONFIDENTIAL