1 /*---------------------------------------------------------------------------*
2   Project:  TwlSDK - FS - libraries
3   File:     rfat.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 #ifndef NITRO_FS_RFAT_H_
19 #define NITRO_FS_RFAT_H_
20 
21 
22 #include <nitro/fs/types.h>
23 
24 
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28 
29 
30 /*---------------------------------------------------------------------------*/
31 /* Constants */
32 
33 //#define FS_DISABLE_OLDPROTOTYPES
34 
35 #define FS_COMMAND_ASYNC_BEGIN  (FSCommandType)(FS_COMMAND_READFILE)
36 #define FS_COMMAND_ASYNC_END    (FSCommandType)(FS_COMMAND_WRITEFILE + 1)
37 #define FS_COMMAND_SYNC_BEGIN   (FSCommandType)(FS_COMMAND_SEEKDIR)
38 #define FS_COMMAND_SYNC_END     (FSCommandType)(FS_COMMAND_CLOSEFILE + 1)
39 #define FS_COMMAND_STATUS_BEGIN (FSCommandType)(FS_COMMAND_ACTIVATE)
40 #define FS_COMMAND_STATUS_END   (FSCommandType)(FS_COMMAND_RESUME + 1)
41 
42 // Numbers omitted for compatibility
43 #define FS_ARCHIVE_FLAG_IS_SYNC     0x00000100
44 #define FS_ARCHIVE_FLAG_TABLE_LOAD  0x00000004
45 #define FS_ARCHIVE_FLAG_OBSOLETE    0x00000104
46 
47 // User procedure setting flag.
48 // This is specified as the 'flags' argument for FS_SetArchiveProc().
49 // Enable bits only for items that request callbacks.
50 
51 // Asynchronous commands
52 #define	FS_ARCHIVE_PROC_READFILE		(1 << FS_COMMAND_READFILE)
53 #define	FS_ARCHIVE_PROC_WRITEFILE		(1 << FS_COMMAND_WRITEFILE)
54 // All asynchronous commands
55 #define	FS_ARCHIVE_PROC_ASYNC	\
56 	(FS_ARCHIVE_PROC_READFILE | FS_ARCHIVE_PROC_WRITEFILE)
57 
58 // Synchronous commands
59 #define	FS_ARCHIVE_PROC_SEEKDIR			(1 << FS_COMMAND_SEEKDIR)
60 #define	FS_ARCHIVE_PROC_READDIR			(1 << FS_COMMAND_READDIR)
61 #define	FS_ARCHIVE_PROC_FINDPATH		(1 << FS_COMMAND_FINDPATH)
62 #define	FS_ARCHIVE_PROC_GETPATH			(1 << FS_COMMAND_GETPATH)
63 #define	FS_ARCHIVE_PROC_OPENFILEFAST	(1 << FS_COMMAND_OPENFILEFAST)
64 #define	FS_ARCHIVE_PROC_OPENFILEDIRECT	(1 << FS_COMMAND_OPENFILEDIRECT)
65 #define	FS_ARCHIVE_PROC_CLOSEFILE		(1 << FS_COMMAND_CLOSEFILE)
66 // All synchronous commands
67 #define	FS_ARCHIVE_PROC_SYNC	\
68 	(FS_ARCHIVE_PROC_SEEKDIR | FS_ARCHIVE_PROC_READDIR |	\
69 	 FS_ARCHIVE_PROC_FINDPATH | FS_ARCHIVE_PROC_GETPATH |	\
70 	FS_ARCHIVE_PROC_OPENFILEFAST | FS_ARCHIVE_PROC_OPENFILEDIRECT | FS_ARCHIVE_PROC_CLOSEFILE)
71 
72 // Messages when status changes
73 #define	FS_ARCHIVE_PROC_ACTIVATE		(1 << FS_COMMAND_ACTIVATE)
74 #define	FS_ARCHIVE_PROC_IDLE			(1 << FS_COMMAND_IDLE)
75 #define	FS_ARCHIVE_PROC_SUSPENDING		(1 << FS_COMMAND_SUSPEND)
76 #define	FS_ARCHIVE_PROC_RESUME			(1 << FS_COMMAND_RESUME)
77 // All messages when status changes
78 #define	FS_ARCHIVE_PROC_STATUS	\
79 	(FS_ARCHIVE_PROC_ACTIVATE | FS_ARCHIVE_PROC_IDLE |	\
80 	 FS_ARCHIVE_PROC_SUSPENDING | FS_ARCHIVE_PROC_RESUME)
81 
82 // All messages
83 #define	FS_ARCHIVE_PROC_ALL	(~0)
84 
85 
86 /*---------------------------------------------------------------------------*/
87 /* Declarations */
88 
89 typedef FSResult (*FS_ARCHIVE_PROC_FUNC) (struct FSFile *, FSCommandType);
90 typedef FSResult (*FS_ARCHIVE_READ_FUNC) (struct FSArchive *p, void *dst, u32 pos, u32 size);
91 typedef FSResult (*FS_ARCHIVE_WRITE_FUNC) (struct FSArchive *p, const void *src, u32 pos, u32 size);
92 
93 typedef struct FSArchiveFAT
94 {
95     u32     top;
96     u32     bottom;
97 }
98 FSArchiveFAT;
99 
100 typedef struct FSArchiveFNT
101 {
102     u32     start;
103     u16     index;
104     u16     parent;
105 }
106 FSArchiveFNT;
107 
108 #define FS_ROMFAT_CONTEXT_DEFINITION()      \
109 {                                           \
110     u32                     base;           \
111     u32                     fat;            \
112     u32                     fat_size;       \
113     u32                     fnt;            \
114     u32                     fnt_size;       \
115     u32                     fat_bak;        \
116     u32                     fnt_bak;        \
117     void                   *load_mem;       \
118     FS_ARCHIVE_READ_FUNC    read_func;      \
119     FS_ARCHIVE_WRITE_FUNC   write_func;     \
120     u8                      reserved3[4];   \
121     FS_ARCHIVE_PROC_FUNC    proc;           \
122     u32                     proc_flag;      \
123 }
124 
125 typedef struct FSROMFATArchiveContext
126 FS_ROMFAT_CONTEXT_DEFINITION()
127 FSROMFATArchiveContext;
128 
129 #ifdef FS_DISABLE_OLDPROTOTYPES
130 #undef FS_ROMFAT_CONTEXT_DEFINITION
131 #define FS_ROMFAT_CONTEXT_DEFINITION() { u8 reserved[52]; } obsolete
132 #endif // FS_DISABLE_OLDPROTOTYPES
133 
134 // for FS_COMMAND_SEEKDIR
135 typedef struct
136 {
137     FSDirPos pos;
138 }
139 FSSeekDirInfo;
140 
141 // for FS_COMMAND_READDIR
142 typedef struct
143 {
144     FSDirEntry *p_entry;
145     BOOL    skip_string;
146 }
147 FSReadDirInfo;
148 
149 // for FS_COMMAND_FINDPATH
150 typedef struct
151 {
152     FSDirPos pos;
153     const char *path;
154     BOOL    find_directory;
155     union
156     {
157         FSFileID *file;
158         FSDirPos *dir;
159     }
160     result;
161 }
162 FSFindPathInfo;
163 
164 // for FS_COMMAND_GETPATH
165 typedef struct
166 {
167     u8     *buf;
168     u32     buf_len;
169     u16     total_len;
170     u16     dir_id;
171 }
172 FSGetPathInfo;
173 
174 // for FS_COMMAND_OPENFILEFAST
175 typedef struct
176 {
177     FSFileID id;
178 }
179 FSOpenFileFastInfo;
180 
181 // for FS_COMMAND_OPENFILEDIRECT
182 typedef struct
183 {
184     u32     top;
185     u32     bottom;
186     u32     index;
187 }
188 FSOpenFileDirectInfo;
189 
190 // for FS_COMMAND_CLOSEFILE
191 typedef struct
192 {
193     u32     reserved;
194 }
195 FSCloseFileInfo;
196 
197 // for FS_COMMAND_READFILE
198 typedef struct
199 {
200     void   *dst;
201     u32     len_org;
202     u32     len;
203 }
204 FSReadFileInfo;
205 
206 // for FS_COMMAND_WRITEFILE
207 typedef struct
208 {
209     const void *src;
210     u32     len_org;
211     u32     len;
212 }
213 FSWriteFileInfo;
214 
215 typedef union FSROMFATCommandInfo
216 {
217     FSReadFileInfo          readfile;
218     FSWriteFileInfo         writefile;
219     FSSeekDirInfo           seekdir;
220     FSReadDirInfo           readdir;
221     FSFindPathInfo          findpath;
222     FSGetPathInfo           getpath;
223     FSOpenFileFastInfo      openfilefast;
224     FSOpenFileDirectInfo    openfiledirect;
225     FSCloseFileInfo         closefile;
226 }
227 FSROMFATCommandInfo;
228 
229 typedef struct FSROMFATFileProperty
230 {
231     u32                 own_id;
232     u32                 top;
233     u32                 bottom;
234     u32                 pos;
235 }
236 FSROMFATFileProperty;
237 
238 typedef struct FSROMFATDirProperty
239 {
240     FSDirPos            pos;
241     u32                 parent;
242 }
243 FSROMFATDirProperty;
244 
245 typedef union FSROMFATProperty
246 {
247     FSROMFATFileProperty    file;
248     FSROMFATDirProperty     dir;
249 }
250 FSROMFATProperty;
251 
252 
253 /*---------------------------------------------------------------------------*/
254 /* Functions */
255 
256 /*---------------------------------------------------------------------------*
257   Name:         FS_GetArchiveBase
258 
259   Description:  Gets the base offset for a ROMFAT archive.
260 
261   Arguments:    arc: ROMFAT archive
262 
263   Returns:      Base offset for the ROMFAT archive.
264  *---------------------------------------------------------------------------*/
265 u32     FS_GetArchiveBase(const struct FSArchive *arc);
266 
267 /*---------------------------------------------------------------------------*
268   Name:         FS_GetArchiveFAT
269 
270   Description:  Gets the FAT offset for a ROMFAT archive.
271 
272   Arguments:    arc: ROMFAT archive
273 
274   Returns:      FAT offset for the ROMFAT archive.
275  *---------------------------------------------------------------------------*/
276 u32     FS_GetArchiveFAT(const struct FSArchive *arc);
277 
278 /*---------------------------------------------------------------------------*
279   Name:         FS_GetArchiveFNT
280 
281   Description:  Gets the FNT offset for a ROMFAT archive.
282 
283   Arguments:    arc: ROMFAT archive
284 
285   Returns:      FNT offset for the ROMFAT archive.
286  *---------------------------------------------------------------------------*/
287 u32     FS_GetArchiveFNT(const struct FSArchive *arc);
288 
289 /* Obtain specified position offset from the archive's base */
290 /*---------------------------------------------------------------------------*
291   Name:         FS_GetArchiveOffset
292 
293   Description:  Gets the offset for the specified position from a ROMFAT archive's base.
294 
295   Arguments:    arc: ROMFAT archive
296 
297   Returns:      Offset to the specified position with the base added.
298  *---------------------------------------------------------------------------*/
299 u32     FS_GetArchiveOffset(const struct FSArchive *arc, u32 pos);
300 
301 /*---------------------------------------------------------------------------*
302   Name:         FS_IsArchiveTableLoaded
303 
304   Description:  Determines whether a ROMFAT archive has finished preloading the table.
305 
306   Arguments:    arc: ROMFAT archive
307 
308   Returns:      TRUE if the table has been preloaded.
309  *---------------------------------------------------------------------------*/
310 BOOL    FS_IsArchiveTableLoaded(volatile const struct FSArchive *arc);
311 
312 /*---------------------------------------------------------------------------*
313   Name:         FS_LoadArchive
314 
315   Description:  Loads the ROMFAT archive into the file system.
316 
317   Arguments:    arc: ROMFAT archive
318                 base: An arbitrary u32 value that can be used independently
319                 fat: Starting offset of the FAT table
320                 fat_size: Size of the FAT table
321                 fnt: Starting offset of the FNT table
322                 fnt_size: Size of the FNT table
323                 read_func: Read access callback
324                 write_func: Write access callback
325 
326   Returns:      TRUE if the ROMFAT archive is loaded correctly.
327  *---------------------------------------------------------------------------*/
328 BOOL    FS_LoadArchive(struct FSArchive *arc, u32 base,
329                        u32 fat, u32 fat_size, u32 fnt, u32 fnt_size,
330                        FS_ARCHIVE_READ_FUNC read_func, FS_ARCHIVE_WRITE_FUNC write_func);
331 
332 /*---------------------------------------------------------------------------*
333   Name:         FS_UnloadArchive
334 
335   Description:  Unloads a ROMFAT archive from the file system.
336 
337   Arguments:    arc: ROMFAT archive
338 
339   Returns:      TRUE if the ROMFAT archive is unloaded correctly.
340  *---------------------------------------------------------------------------*/
341 BOOL    FS_UnloadArchive(struct FSArchive *arc);
342 
343 /*---------------------------------------------------------------------------*
344   Name:         FS_LoadArchiveTables
345 
346   Description:  Preloads the FAT and FNT of an FS_UnloadArchive archive in memory.
347                 This will load the data and return the required size only when it is less than the specified size.
348 
349   Arguments:    arc: ROMFAT archive
350                 mem: Buffer to store the table data
351                 size: The size of mem
352 
353   Returns:      Always returns the total table size.
354  *---------------------------------------------------------------------------*/
355 u32     FS_LoadArchiveTables(struct FSArchive *arc, void *mem, u32 size);
356 
357 /*---------------------------------------------------------------------------*
358   Name:         FS_UnloadArchiveTables
359 
360   Description:  Releases preloaded memory for a ROMFAT archive.
361 
362   Arguments:    arc: ROMFAT archive
363 
364   Returns:      The buffer provided by the user to serve as preloaded memory.
365  *---------------------------------------------------------------------------*/
366 void   *FS_UnloadArchiveTables(struct FSArchive *arc);
367 
368 /*---------------------------------------------------------------------------*
369   Name:         FS_SetArchiveProc
370 
371   Description:  Sets the user procedure for a ROMFAT archive.
372                 If proc is NULL or flags is 0, this will simply disable the user procedure.
373 
374 
375   Arguments:    arc: ROMFAT archive
376                 proc: User procedure
377                 flags: Bitset of commands with procedure hooks
378 
379   Returns:      None.
380  *---------------------------------------------------------------------------*/
381 void    FS_SetArchiveProc(struct FSArchive *arc, FS_ARCHIVE_PROC_FUNC proc, u32 flags);
382 
383 /*---------------------------------------------------------------------------*
384   Name:         FS_GetFileImageTop
385 
386   Description:  Gets the offset to the start of a file opened from a ROMFAT archive.
387 
388 
389   Arguments:    file: File handle
390 
391   Returns:      The offset to the start of the file in the archive.
392  *---------------------------------------------------------------------------*/
393 u32     FS_GetFileImageTop(const struct FSFile *file);
394 
395 /*---------------------------------------------------------------------------*
396   Name:         FS_GetFileImageBottom
397 
398   Description:  Gets the offset to the end of a file opened from a ROMFAT archive.
399 
400 
401   Arguments:    file: File handle
402 
403   Returns:      The offset to the end of the file in the archive.
404  *---------------------------------------------------------------------------*/
405 u32     FS_GetFileImageBottom(const struct FSFile *file);
406 
407 
408 /*---------------------------------------------------------------------------*/
409 
410 
411 #ifdef __cplusplus
412 } /* extern "C" */
413 #endif
414 
415 
416 #endif /* NITRO_FS_RFAT_H_ */
417