1 /*---------------------------------------------------------------------------*
2   Project:  TwlSDK - CARD - include
3   File:     rom.h
4 
5   Copyright 2007-2008 Nintendo. All rights reserved.
6 
7   These coded instructions, statements, and computer programs contain
8   proprietary information of Nintendo of America Inc. and/or Nintendo
9   Company Ltd., and are protected by Federal copyright law. They may
10   not be disclosed to third parties or copied or duplicated in any form,
11   in whole or in part, without the prior written consent of Nintendo.
12 
13   $Date:: 2008-12-05#$
14   $Rev: 9518 $
15   $Author: yosizaki $
16 
17  *---------------------------------------------------------------------------*/
18 #ifndef NITRO_CARD_ROM_H_
19 #define NITRO_CARD_ROM_H_
20 
21 
22 #include <nitro/card/types.h>
23 
24 #include <nitro/mi/dma.h>
25 #include <nitro/mi/exMemory.h>
26 
27 
28 #ifdef __cplusplus
29 extern "C"
30 {
31 #endif
32 
33 
34 /*---------------------------------------------------------------------------*/
35 /* Functions */
36 
37 /*---------------------------------------------------------------------------*
38   Name:         CARD_GetRomHeader
39 
40   Description:  Gets ROM header information from the Game Card that is currently inserted.
41 
42   Arguments:    None.
43 
44   Returns:      Pointer to a CARDRomHeader structure.
45  *---------------------------------------------------------------------------*/
46 const u8 *CARD_GetRomHeader(void);
47 
48 /*---------------------------------------------------------------------------*
49   Name:         CARD_GetOwnRomHeader
50 
51   Description:  Gets ROM header information for the currently running program.
52 
53   Arguments:    None.
54 
55   Returns:      Pointer to a CARDRomHeader structure.
56  *---------------------------------------------------------------------------*/
57 const CARDRomHeader *CARD_GetOwnRomHeader(void);
58 
59 #ifdef SDK_TWL
60 
61 /*---------------------------------------------------------------------------*
62   Name:         CARD_GetOwnRomHeaderTWL
63 
64   Description:  Gets TWL-ROM header information for the currently running program.
65 
66   Arguments:    None.
67 
68   Returns:      Pointer to a CARDRomHeaderTWL structure.
69  *---------------------------------------------------------------------------*/
70 const CARDRomHeaderTWL *CARD_GetOwnRomHeaderTWL(void);
71 
72 #endif // SDK_TWL
73 
74 /*---------------------------------------------------------------------------*
75   Name:         CARD_GetRomRegionFNT
76 
77   Description:  Gets FNT region information for the ROM header.
78 
79   Arguments:    None.
80 
81   Returns:      Pointer to FNT region information for the ROM header.
82  *---------------------------------------------------------------------------*/
CARD_GetRomRegionFNT(void)83 SDK_INLINE const CARDRomRegion *CARD_GetRomRegionFNT(void)
84 {
85     const CARDRomHeader *header = CARD_GetOwnRomHeader();
86     return &header->fnt;
87 }
88 
89 /*---------------------------------------------------------------------------*
90   Name:         CARD_GetRomRegionFAT
91 
92   Description:  Gets FAT region information for the ROM header.
93 
94   Arguments:    None.
95 
96   Returns:      Pointer to FAT region information for the ROM header.
97  *---------------------------------------------------------------------------*/
CARD_GetRomRegionFAT(void)98 SDK_INLINE const CARDRomRegion *CARD_GetRomRegionFAT(void)
99 {
100     const CARDRomHeader *header = CARD_GetOwnRomHeader();
101     return &header->fat;
102 }
103 
104 /*---------------------------------------------------------------------------*
105   Name:         CARD_GetRomRegionOVT
106 
107   Description:  Gets OVT region information for the ROM header.
108 
109   Arguments:    None.
110 
111   Returns:      Pointer to OVT region information for the ROM header.
112  *---------------------------------------------------------------------------*/
CARD_GetRomRegionOVT(MIProcessor target)113 SDK_INLINE const CARDRomRegion *CARD_GetRomRegionOVT(MIProcessor target)
114 {
115     const CARDRomHeader *header = CARD_GetOwnRomHeader();
116     return (target == MI_PROCESSOR_ARM9) ? &header->main_ovt : &header->sub_ovt;
117 }
118 
119 /*---------------------------------------------------------------------------*
120   Name:         CARD_LockRom
121 
122   Description:  Locks the card bus for ROM access.
123 
124   Arguments:    lock id
125 
126   Returns:      None.
127  *---------------------------------------------------------------------------*/
128 void    CARD_LockRom(u16 lock_id);
129 
130 /*---------------------------------------------------------------------------*
131   Name:         CARD_UnlockRom
132 
133   Description:  Unlocks a locked card bus.
134 
135   Arguments:    lock id which is used by CARD_LockRom()
136 
137   Returns:      None.
138  *---------------------------------------------------------------------------*/
139 void    CARD_UnlockRom(u16 lock_id);
140 
141 /*---------------------------------------------------------------------------*
142   Name:         CARD_TryWaitRomAsync
143 
144   Description:  Determines whether a ROM access function has completed.
145 
146   Arguments:    None.
147 
148   Returns:      TRUE if the ROM access function has completed.
149  *---------------------------------------------------------------------------*/
150 BOOL    CARD_TryWaitRomAsync(void);
151 
152 /*---------------------------------------------------------------------------*
153   Name:         CARD_WaitRomAsync
154 
155   Description:  Waits until a ROM access function has completed.
156 
157   Arguments:    None.
158 
159   Returns:      None.
160  *---------------------------------------------------------------------------*/
161 void    CARD_WaitRomAsync(void);
162 
163 /*---------------------------------------------------------------------------*
164   Name:         CARDi_ReadRom
165 
166   Description:  basic function of ROM read
167 
168   Arguments:    dma        DMA channel to use
169                 src        Transfer source offset
170                 dst        Transfer destination memory address
171                 len        Transfer size
172                 callback   Completion callback (NULL if not used)
173                 arg        Completion callback argument (ignored if not used)
174                 is_async   If set to asynchronous mode: TRUE
175 
176   Returns:      None.
177  *---------------------------------------------------------------------------*/
178 void    CARDi_ReadRom(u32 dma, const void *src, void *dst, u32 len,
179                       MIDmaCallback callback, void *arg, BOOL is_async);
180 
181 /*---------------------------------------------------------------------------*
182   Name:         CARD_ReadRom Async
183 
184   Description:  Asynchronous ROM read
185 
186   Arguments:    dma        DMA channel to use
187                 src        Transfer source offset
188                 dst        Transfer destination memory address
189                 len        Transfer size
190                 callback   Completion callback (NULL if not used)
191                 arg        Completion callback argument (ignored if not used)
192 
193   Returns:      None.
194  *---------------------------------------------------------------------------*/
CARD_ReadRomAsync(u32 dma,const void * src,void * dst,u32 len,MIDmaCallback callback,void * arg)195 SDK_INLINE void CARD_ReadRomAsync(u32 dma, const void *src, void *dst, u32 len,
196                                   MIDmaCallback callback, void *arg)
197 {
198     CARDi_ReadRom(dma, src, dst, len, callback, arg, TRUE);
199 }
200 
201 /*---------------------------------------------------------------------------*
202   Name:         CARD_ReadRom
203 
204   Description:  Synchronous ROM read.
205 
206   Arguments:    dma        DMA channel to use
207                 src        Transfer source offset
208                 dst        Transfer destination memory address
209                 len        Transfer size
210 
211   Returns:      None.
212  *---------------------------------------------------------------------------*/
CARD_ReadRom(u32 dma,const void * src,void * dst,u32 len)213 SDK_INLINE void CARD_ReadRom(u32 dma, const void *src, void *dst, u32 len)
214 {
215     CARDi_ReadRom(dma, src, dst, len, NULL, NULL, FALSE);
216 }
217 
218 /*---------------------------------------------------------------------------*
219   Name:         CARD_GetCacheFlushThreshold
220 
221   Description:  Gets the threshold value for determining whether to entirely or partially invalidate the cache.
222 
223   Arguments:    icache: Pointer to the threshold value for invalidating the instruction cache.
224                                   This is ignored if it is NULL.
225                 dcache: Pointer to the threshold value for invalidating the data cache.
226                                   This is ignored if it is NULL.
227 
228   Returns:      None.
229  *---------------------------------------------------------------------------*/
230 void    CARD_GetCacheFlushThreshold(u32 *icache, u32 *dcache);
231 
232 /*---------------------------------------------------------------------------*
233   Name:         CARD_SetCacheFlushThreshold
234 
235   Description:  Sets the threshold value for determining whether to entirely or partially invalidate the cache.
236 
237   Arguments:    icache: The threshold value for invalidating the instruction cache.
238                 dcache: The threshold value for invalidating the data cache.
239 
240   Returns:      None.
241  *---------------------------------------------------------------------------*/
242 void    CARD_SetCacheFlushThreshold(u32 icache, u32 dcache);
243 
244 /*---------------------------------------------------------------------------*
245   Name:         CARD_GetCacheFlushFlag
246 
247   Description:  Gets the flag that configures cache invalidation to be automatic or manual.
248 
249   Arguments:    icache: Pointer to the flag for automatically invalidating the instruction cache.
250                                   This is ignored if it is NULL.
251                 dcache: Pointer to the flag for automatically invalidating the data cache.
252                                   This is ignored if it is NULL.
253 
254   Returns:      None.
255  *---------------------------------------------------------------------------*/
256 void     CARD_GetCacheFlushFlag(BOOL *icache, BOOL *dcache);
257 
258 /*---------------------------------------------------------------------------*
259   Name:         CARD_SetCacheFlushFlag
260 
261   Description:  Configures cache invalidation to be automatic or manual.
262                 By default, this is FALSE for the instruction cache and TRUE for the data cache.
263 
264   Arguments:    icache: TRUE to enable automatic invalidation of the instruction cache.
265                 dcache: TRUE to enable automatic invalidation of the data cache.
266 
267   Returns:      None.
268  *---------------------------------------------------------------------------*/
269 void     CARD_SetCacheFlushFlag(BOOL icache, BOOL dcache);
270 
271 
272 /*---------------------------------------------------------------------------*
273  * Internal Functions
274  *---------------------------------------------------------------------------*/
275 
276 u32     CARDi_ReadRomID(void);
277 void    CARDi_RefreshRom(u32 warn_mask);
278 BOOL    CARDi_IsTwlRom(void);
279 
280 /*---------------------------------------------------------------------------*
281   Name:         CARDi_GetOwnSignature
282 
283   Description:  Gets this system's signature data for DS Download Play.
284 
285   Arguments:    None.
286 
287   Returns:      This system's signature data for DS Download Play.
288  *---------------------------------------------------------------------------*/
289 const u8* CARDi_GetOwnSignature(void);
290 
291 /*---------------------------------------------------------------------------*
292   Name:         CARDi_SetOwnSignature
293 
294   Description:  Sets this system's signature data for DS Download Play.
295                 Call this from a higher-level library when starting without a Game Card.
296 
297   Arguments:    Signature data for DS Download Play.
298 
299   Returns:      None.
300  *---------------------------------------------------------------------------*/
301 void CARDi_SetOwnSignature(const void *signature);
302 
303 
304 #ifdef __cplusplus
305 } /* extern "C" */
306 #endif
307 
308 
309 /* NITRO_CARD_ROM_H_ */
310 #endif
311