1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html> 3 4<head> 5<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 6<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.0.0 for Windows"> 7<META http-equiv="Content-Style-Type" content="text/css"> 8<title>CARD_ReadRomAsync</title> 9<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css"> 10</head> 11 12<body> 13 14<h1 align="left">CARD_ReadRomAsync <img src="../../image/NTR.gif"align="middle"><img src="../../image/TWL.gif" align="middle"></H1> 15<H2>Syntax</H2> 16 17<dl> 18 <dd> 19<CODE>#include <nitro/card.h></CODE><BR> 20 <BR> 21 <CODE>void CARD_ReadRomAsync(u32 dma, const void *src, void *dst, u32 len, 22 MIDmaCallback callback, void *arg);</CODE><br> 23 <br> 24 </dd> 25</dl> 26<h2>Arguments</h2> 27<TABLE border="1" width="100%"> 28 <TBODY> 29 <TR> 30<TD width="13%"><SPAN class="argument">dma</SPAN></TD> 31<TD width="87%">The DMA channel to use for the transfer between 0 and <CODE>MI_DMA_MAX_NUM</CODE>.<br />If the program is running in TWL mode, the parent DMA channel can be specified in the range of <CODE>(MI_DMA_USING_NEW+0)</CODE> to <CODE>(MI_DMA_USING_NEW+MI_DMA_MAX_NUM)</CODE>.<br />The CPU processes the transfer directly without using DMA transfer if an out-of-range channel has been specified or if <CODE>MI_DMA_NOT_USE</CODE> has been explicitly specified.</TD> 32 </TR> 33 <TR> 34<TD width="13%"><SPAN class="argument">src</SPAN></TD> 35<TD width="87%">The transfer source CARD ROM address.</TD> 36 </TR> 37 <TR> 38<TD width="13%"><SPAN class="argument">dst</SPAN></TD> 39<TD width="87%">Transfer destination memory address.</TD> 40 </TR> 41 <TR> 42<TD width="13%"><SPAN class="argument">len</SPAN></TD> 43<TD width="87%">Length of data being read, in bytes.</TD> 44 </TR> 45 <TR> 46<TD width="13%"><SPAN class="argument">callback</SPAN></TD> 47<TD width="87%">Completion-time callback function.<br />Specify <CODE>NULL</CODE> when not needed.<br>This callback will be invoked from the DMA interrupt handler when a valid DMA channel is specified.</TD> 48 </TR> 49 <TR> 50<TD width="13%"><SPAN class="argument">arg</SPAN></TD> 51<TD width="87%">Argument passed to the callback function.<BR>When <CODE>NULL</CODE> has been specified for the callback, this is simply ignored</TD> 52 </TR> 53 </TBODY> 54</TABLE> 55 56<h2>Return Values</h2> 57<p>None.</p> 58 59<H2>Description</H2> 60<P>Asynchronously loads data from a device that has ROM. If a valid DMA channel has been specified, this function uses that channel after explicitly stopping it with the <A href="../../mi/dma/MI_StopDma.html"><CODE>MI_StopDma</CODE></A> function. The transfer will be blocked until the previous access completes.<BR><BR> If a CPU transfer is explicitly specified, this function behaves identically to the synchronous version, <A href="CARD_ReadRom.html"><CODE>CARD_ReadRom</CODE></A>. <BR> 61</P> 62 63<h2>Note</h2> 64<p> 65<ul style='color:red;'> 66<li>To use this function, you must first lock the access bus with the <a href="CARD_LockRom.html"><CODE>CARD_LockRom</CODE></A> function.</li> 67<li>If a valid DMA channel is specified by this function, that DMA channel will not be available until transfer is complete.</li> 68<li>The transfer source for Card access is an IO register, so you cannot specify DMA channel 0 unless the program is running in TWL mode and the <a href="../../scfg/scfg/SCFG_IsDmacFixed.html"><code>SCFG_IsDmacFixed</code></a> function has returned <CODE>TRUE</CODE>.</li> 69<li>Note that this function uses interrupts internally, so processing will not complete if it continues to wait while interrupts are prohibited.</li> 70</ul> 71</p> 72 73<h2>Internal Operation</h2> 74<p><CODE>This function operates asynchronously using DMA transfers and the IRQ handler only if the following conditions are satisfied: <BR>In that case, transfers of card data can be done in parallel with CPU processing. 75</p> 76<ul> 77<li>The destination range of the transfer is DMA-accessible and 32-byte aligned.<br> 78<li>The source range of the transfer is aligned to <A href="../card_rom_page_size_const.html"><CODE>CARD_ROM_PAGE_SIZE</CODE></A> bytes. 79<li>The transfer size is aligned to <A href="../card_rom_page_size_const.html"><CODE>CARD_ROM_PAGE_SIZE</CODE></A> bytes. 80</ul> 81<p>If these conditions are not all met, the process is executed asynchronously by a CPU process using a CARD library internal thread regardless of whether DMA transfer has been specified or not.<br> For more information on this thread, see the description for the <A href="../common/CARD_GetThreadPriority.html"><CODE>CARD_GetThreadPriority</CODE></A> function. Here are some main points you need to be aware of with the application to ensure that the conditions for DMA transfer are satisfied: 82</p> 83<ul> 84<li>Do not specify an automatic variable as the transfer destination (the stack is allocated from DTCM by default, so DMA access is not possible). 85<li>Specify <CODE>Align</CODE> or <CODE>AlignAll</CODE> in the RomSpec section of the RSF file and place the file so that it is 512-byte aligned. 86<li>If the file size is not an integer multiple of 512 bytes, divide the file so that it is read in segments that are integer multiples of 512 bytes. 87</ul> 88<BR></CODE></p> 89<BR> 90<h2>See Also</h2> 91<p><A href="../card_rom_page_size_const.html"><CODE>CARD_ROM_PAGE_SIZE</CODE></A><BR> <A href="CARD_LockRom.html"><CODE>CARD_LockRom</CODE></A><BR> <A href="CARD_ReadRom.html"><CODE>CARD_ReadRom</CODE></A><BR> <A href="CARD_TryWaitRomAsync.html"><CODE>CARD_TryWaitRomAsync</CODE></A><BR> <A href="CARD_WaitRomAsync.html"><CODE>CARD_WaitRomAsync</CODE></A><BR> <A href="../common/CARD_GetThreadPriority.html"><CODE>CARD_GetThreadPriority</CODE></A></p> 92 93<H2>Revision History</H2> 94<P> 952008/11/19 Added information about the relationship between the DMA channel range and the operating mode.<br /> 2008/01/24 Added a note on the range specified for DMA channels.<br /> 2006/05/10 Changed specifications so that DMA transfers are not performed unless the transfer destination range is aligned at 32-byte boundaries.<br /> 2005/08/22 Made substantial corrections to <B>Internal Operation</B>.<br /> 2005/06/01 Explained that the callback is invoked from the interrupt handler. <br />2005/04/28 Noted that DMA channel 0 cannot be specified.<br /> 2004/12/09 Changed "IO processor" to "ARM7 processor."<br /> 2004/11/02 Corrected argument names to match the header file.<br /> 2004/07/28 Corrected the callback type.<br> 2004/07/19 Changed the explanation for internal operations.<br> 2004/07/09 Corrected descriptions due to function format changes and added <B>Internal Operation</B>.<br> 2004/07/05 Initial version.<br> 96</P> 97<hr><p>CONFIDENTIAL</p></body> 98</html> 99
