1 /*---------------------------------------------------------------------------*
2   Project:  TwlSDK - FS - include
3   File:     overlay.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-09-18#$
14   $Rev: 8573 $
15   $Author: okubata_ryoma $
16 
17  *---------------------------------------------------------------------------*/
18 
19 
20 #if	!defined(NITRO_FS_OVERLAY_H_)
21 #define NITRO_FS_OVERLAY_H_
22 
23 
24 #include <nitro/fs/file.h>
25 #include <nitro/mi.h>
26 #include <nitro/card/rom.h>
27 
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 
34 /*---------------------------------------------------------------------------*/
35 /* Declarations */
36 
37 // Overlay ID
38 typedef u32 FSOverlayID;
39 #define	FS_EXTERN_OVERLAY(name)     extern u32 SDK_OVERLAY_ ## name ## _ID[1]
40 #define	FS_OVERLAY_ID(name)         ((u32)&(SDK_OVERLAY_ ## name ## _ID))
41 #define	FS_EXTERN_LTDOVERLAY(name)  extern u32 SDK_LTDOVERLAY_ ## name ## _ID[1]
42 #define	FS_LTDOVERLAY_ID(name)      ((u32)&(SDK_LTDOVERLAY_ ## name ## _ID))
43 
44 typedef void (*FSOverlayInitFunc) (void);
45 
46 // Structure with overlay header information
47 typedef struct FSOverlayInfoHeader
48 {
49 // Protected:
50     u32     id;
51     u8     *ram_address;
52     u32     ram_size;
53     u32     bss_size;
54     FSOverlayInitFunc *sinit_init;
55     FSOverlayInitFunc *sinit_init_end;
56     u32     file_id;
57     u32     compressed:24;
58     u32     flag:8;
59 }
60 FSOverlayInfoHeader;
61 
62 // Structure with overlay information
63 typedef struct FSOverlayInfo
64 {
65 // Private:
66     FSOverlayInfoHeader header;
67     MIProcessor         target;
68     CARDRomRegion       file_pos;
69 }
70 FSOverlayInfo;
71 
72 
73 /*---------------------------------------------------------------------------*/
74 /* Functions */
75 
76 /*---------------------------------------------------------------------------*
77   Name:         FSi_InitOverlay
78 
79   Description:  Initializes overlay management information.
80 
81   Arguments:    None.
82 
83   Returns:      None.
84  *---------------------------------------------------------------------------*/
85 void FSi_InitOverlay(void);
86 
87 /*---------------------------------------------------------------------------*
88   Name:         FS_LoadOverlayInfo
89 
90   Description:  Load the information of specified overlay module.
91 
92   Arguments:    p_ovi:       pointer to destination FSOverlayInfo
93                 target:      ARM9 or ARM7
94                 id:          overlay-id (FS_OVERLAY_ID(overlay-name))
95 
96   Returns:      If succeeded, TRUE.
97  *---------------------------------------------------------------------------*/
98 BOOL    FS_LoadOverlayInfo(FSOverlayInfo *p_ovi, MIProcessor target, FSOverlayID id);
99 
100 /*---------------------------------------------------------------------------*
101   Name:         FS_GetOverlayTotalSize
102 
103   Description:  Get total size of overlay module from FSOverlayInfo.
104                 (text section + data section + bss section)
105 
106   Arguments:    p_ovi:       pointer to FSOverlayInfo
107 
108   Returns:      total size of overlay module
109  *---------------------------------------------------------------------------*/
FS_GetOverlayTotalSize(const FSOverlayInfo * p_ovi)110 SDK_INLINE u32 FS_GetOverlayTotalSize(const FSOverlayInfo *p_ovi)
111 {
112     return (u32)(p_ovi->header.ram_size + p_ovi->header.bss_size);
113 }
114 
115 /*---------------------------------------------------------------------------*
116   Name:         FS_GetOverlayImageSize
117 
118   Description:  Get image size of overlay module from FSOverlayInfo.
119                 (text section + data section)
120 
121   Arguments:    p_ovi:       pointer to FSOverlayInfo
122 
123   Returns:      Image size of overlay module.
124  *---------------------------------------------------------------------------*/
FS_GetOverlayImageSize(const FSOverlayInfo * p_ovi)125 SDK_INLINE u32 FS_GetOverlayImageSize(const FSOverlayInfo *p_ovi)
126 {
127     return (u32)(p_ovi->header.ram_size);
128 }
129 
130 /*---------------------------------------------------------------------------*
131   Name:         FS_GetOverlayAddress
132 
133   Description:  Get start-address of overlay module from FSOverlayInfo.
134 
135   Arguments:    p_ovi:       pointer to FSOverlayInfo
136 
137   Returns:      Start-address of overlay module.
138  *---------------------------------------------------------------------------*/
FS_GetOverlayAddress(const FSOverlayInfo * p_ovi)139 SDK_INLINE void *FS_GetOverlayAddress(const FSOverlayInfo *p_ovi)
140 {
141     return p_ovi->header.ram_address;
142 }
143 
144 /*---------------------------------------------------------------------------*
145   Name:         FS_GetOverlayFileID
146 
147   Description:  Get file-id which contains an image of overlay module.
148 
149   Arguments:    p_ovi:       pointer to FSOverlayInfo
150 
151   Returns:      File-id of overlay.
152  *---------------------------------------------------------------------------*/
153 FSFileID FS_GetOverlayFileID(const FSOverlayInfo *p_ovi);
154 
155 /*---------------------------------------------------------------------------*
156   Name:         FS_ClearOverlayImage
157 
158   Description:  Zero out the memory where FS_GetOverlayAddress() points,
159                 and invalidate its region of cache.
160                 This function is called in FS_LoadOverlayImage().
161 
162   Arguments:    p_ovi:       pointer to FSOverlayInfo
163 
164   Returns:      None.
165  *---------------------------------------------------------------------------*/
166 void    FS_ClearOverlayImage(FSOverlayInfo *p_ovi);
167 
168 /*---------------------------------------------------------------------------*
169   Name:         FS_LoadOverlayImage
170 
171   Description:  Load the image of overlay module without 'static initializer'.
172                 By this call, the memory where FS_GetOverlayAddress() points
173                 is set to rare initial status.
174 
175   Arguments:    p_ovi:       pointer to FSOverlayInfo
176 
177   Returns:      If succeeded, TRUE.
178  *---------------------------------------------------------------------------*/
179 BOOL    FS_LoadOverlayImage(FSOverlayInfo *p_ovi);
180 
181 /*---------------------------------------------------------------------------*
182   Name:         FS_LoadOverlayImageAsync
183 
184   Description:  Load the image of overlay module without 'static initializer'.
185                 By this call, the memory where FS_GetOverlayAddress() points
186                 is set to rare initial status.
187 
188   Arguments:    p_ovi:       pointer to FSOverlayInfo
189                 p_file:      pointer to FSFile for asynchronous reading
190 
191   Returns:      If succeeded, TRUE.
192  *---------------------------------------------------------------------------*/
193 BOOL    FS_LoadOverlayImageAsync(FSOverlayInfo *p_ovi, FSFile *p_file);
194 
195 /*---------------------------------------------------------------------------*
196   Name:         FS_StartOverlay
197 
198   Description:  Execute 'static initializer'.
199                 This function needs:
200                     the memory where FS_GetOverlayAddress() points is
201                     set by data which FS_LoadOverlayImage() makes.
202 
203   Arguments:    p_ovi:       pointer to FSOverlayInfo
204 
205   Returns:      None.
206  *---------------------------------------------------------------------------*/
207 void    FS_StartOverlay(FSOverlayInfo *p_ovi);
208 
209 /*---------------------------------------------------------------------------*
210   Name:         FS_EndOverlay
211 
212   Description:  Execute 'static unintinalizer'.
213                 By this function:
214                     all the destructors in specified overlay module
215                     are removed from global destructor chain and executed.
216 
217   Arguments:    p_ovi:       pointer to FSOverlayInfo
218 
219   Returns:      None.
220  *---------------------------------------------------------------------------*/
221 void    FS_EndOverlay(FSOverlayInfo *p_ovi);
222 
223 /*---------------------------------------------------------------------------*
224   Name:         FS_UnloadOverlayImage
225 
226   Description:  Unload overlay module.
227 
228   Arguments:    p_ovi:       pointer to FSOverlayInfo
229 
230   Returns:      If succeeded, TRUE.
231  *---------------------------------------------------------------------------*/
232 BOOL    FS_UnloadOverlayImage(FSOverlayInfo *p_ovi);
233 
234 /*---------------------------------------------------------------------------*
235   Name:         FS_LoadOverlay
236 
237   Description:  Load overlay module and initialize.
238 
239   Arguments:    target:      ARM9 or ARM7
240                 id:          overlay-id (FS_OVERLAY_ID(overlay-name))
241 
242   Returns:      If succeeded, TRUE.
243  *---------------------------------------------------------------------------*/
244 BOOL    FS_LoadOverlay(MIProcessor target, FSOverlayID id);
245 
246 /*---------------------------------------------------------------------------*
247   Name:         FS_UnloadOverlay
248 
249   Description:  Unload overlay module and clean up.
250 
251   Arguments:    target:      ARM9 or ARM7
252                 id:          overlay-id (FS_OVERLAY_ID(overlay-name))
253 
254   Returns:      If succeeded, TRUE.
255  *---------------------------------------------------------------------------*/
256 BOOL    FS_UnloadOverlay(MIProcessor target, FSOverlayID id);
257 
258 /*---------------------------------------------------------------------------*
259   Name:         FS_AttachOverlayTable
260 
261   Description:  Attach the overlayinfo-table (OVT) to file-system.
262                 After setting, FS_LoadOverlayInfo()
263                 loads overlay-info from specified memory.
264 
265   Arguments:    target:      ARM9 or ARM7
266                 ptr:         pointer to buffer which contains OVT.
267                             If ptr is NULL, reset to default(from CARD).
268                 len:         length of OVT.
269 
270   Returns:      None.
271  *---------------------------------------------------------------------------*/
272 void    FS_AttachOverlayTable(MIProcessor target, const void *ptr, u32 len);
273 
274 
275 /* Obsolete */
276 
277 /*---------------------------------------------------------------------------*
278   Name:         FS_RegisterOverlayToDebugger
279 
280   Description:  Register specified overlay to debugger so that the debugger can trace
281                 its runtime information.
282                 (obsolete)
283 
284   Arguments:    p_ovi:       ignored
285                 p_file:      ignored
286 
287   Returns:      None.
288  *---------------------------------------------------------------------------*/
FS_RegisterOverlayToDebugger(const FSOverlayInfo * p_ovi,const FSFile * p_file)289 SDK_INLINE void FS_RegisterOverlayToDebugger(const FSOverlayInfo *p_ovi, const FSFile *p_file)
290 {
291     (void)p_ovi;
292     (void)p_file;
293 }
294 
295 
296 #ifdef __cplusplus
297 } /* extern "C" */
298 #endif
299 
300 
301 #endif /* NITRO_FS_OVERLAY_H_ */
302