1 /*---------------------------------------------------------------------------*
2 Project: TwlSDK - FS - include
3 File: api.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:: 2009-01-30#$
14 $Rev: 9941 $
15 $Author: yosizaki $
16
17 *---------------------------------------------------------------------------*/
18 #if !defined(NITRO_FS_API_H_)
19 #define NITRO_FS_API_H_
20
21
22 #include <nitro/fs/archive.h>
23 #include <nitro/fs/file.h>
24 #include <nitro/fs/romfat.h>
25 #include <nitro/fs/overlay.h>
26 #include <nitro/std.h>
27
28 #ifdef SDK_TWL
29 #include <twl/fatfs.h>
30 #endif // SDK_TWL
31
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35
36
37 /*---------------------------------------------------------------------------*/
38 /* Functions */
39
40 /*---------------------------------------------------------------------------*
41 Name: FS_Init
42
43 Description: Initializes the FS library.
44
45 Arguments: default_dma_no: The DMA number to use internally, as necessary. (0-3)
46 Add MI_DMA_USING_NEW when using the new DMA, and specify MI_DMA_NOT_USE when not using DMA.
47
48
49 Returns: None.
50 *---------------------------------------------------------------------------*/
51 void FS_Init(u32 default_dma_no);
52
53 /*---------------------------------------------------------------------------*
54 Name: FS_InitFatDriver
55
56 Description: Initializes the FAT driver.
57
58 Arguments: None.
59
60 Returns: None.
61 *---------------------------------------------------------------------------*/
62 #if defined(SDK_TWL)
63 void FS_InitFatDriver(void);
64 #endif
65
66 /*---------------------------------------------------------------------------*
67 Name: FS_IsAvailable
68
69 Description: Determines if the FS library has already been initialized.
70
71 Arguments: None.
72
73 Returns: TRUE if the FS_Init function has already been called.
74 *---------------------------------------------------------------------------*/
75 BOOL FS_IsAvailable(void);
76
77 /*---------------------------------------------------------------------------*
78 Name: FS_End
79
80 Description: Unmounts all archives and shuts down the FS library.
81
82 Arguments: None.
83
84 Returns: None.
85 *---------------------------------------------------------------------------*/
86 void FS_End(void);
87
88 /*---------------------------------------------------------------------------*
89 Name: FS_GetDefaultDMA
90
91 Description: Gets the DMA channel currently configured for FS library use.
92
93 Arguments: None.
94
95 Returns: current DMA channel
96 *---------------------------------------------------------------------------*/
97 u32 FS_GetDefaultDMA(void);
98
99 /*---------------------------------------------------------------------------*
100 Name: FS_SetDefaultDMA
101
102 Description: Sets the DMA channel for the FS library to use.
103
104 Arguments: dma_no: The DMA number to use internally, as necessary. (0-3)
105 Add MI_DMA_USING_NEW when using the new DMA, and specify MI_DMA_NOT_USE when not using DMA.
106
107
108 Returns: The DMA channel that had previously been set.
109 *---------------------------------------------------------------------------*/
110 u32 FS_SetDefaultDMA(u32 dma_no);
111
112 /*---------------------------------------------------------------------------*
113 Name: FS_SetCurrentDirectory
114
115 Description: Changes the current directory
116
117 Arguments: path: Path name
118
119 Returns: If successful, TRUE.
120 *---------------------------------------------------------------------------*/
121 BOOL FS_SetCurrentDirectory(const char *path);
122
123 /*---------------------------------------------------------------------------*
124 Name: FS_CreateFileFromMemory
125
126 Description: Temporarily generates file that maps memory region.
127
128 Arguments: file: FSFile structure that stores a file handle
129 buf: Memory that is target of READ and WRITE
130 size: Byte size of buf
131
132 Returns: If successful, TRUE.
133 *---------------------------------------------------------------------------*/
134 BOOL FS_CreateFileFromMemory(FSFile *file, void *buf, u32 size);
135
136 /*---------------------------------------------------------------------------*
137 Name: FS_CreateFileFromRom
138
139 Description: Temporarily generates a file that maps a specified CARD-ROM region.
140
141 Arguments: file: FSFile structure that stores a file handle
142 offset: Offset from the start of the CARD-ROM region to be read
143 size: Size in bytes from the offset in the target region
144
145 Returns: If successful, TRUE.
146 *---------------------------------------------------------------------------*/
147 BOOL FS_CreateFileFromRom(FSFile *file, u32 offset, u32 size);
148
149 /*---------------------------------------------------------------------------*
150 Name: FS_OpenTopLevelDirectory
151
152 Description: Opens the special high-level directory that can enumerate the archive name
153
154 Arguments: dir: FSFile structure that stores directory handle
155
156 Returns: If successful, TRUE.
157 *---------------------------------------------------------------------------*/
158 BOOL FS_OpenTopLevelDirectory(FSFile *dir);
159
160 /*---------------------------------------------------------------------------*
161 Name: FS_TryLoadTable
162
163 Description: Preloads a "rom" archive's table data.
164
165 Arguments: mem: Buffer to store the table data
166 If NULL, simply calculate and return the size.
167 size: The size of mem
168
169 Returns: The number of bytes required to preload a "rom" archive's FAT and FNT data.
170 *---------------------------------------------------------------------------*/
171 u32 FS_TryLoadTable(void *mem, u32 size);
172
173 /*---------------------------------------------------------------------------*
174 Name: FS_GetTableSize
175
176 Description: Gets a "ROM" archive's table size.
177
178 Arguments: None.
179
180 Returns: The number of bytes required to preload a "rom" archive's FAT and FNT data.
181 *---------------------------------------------------------------------------*/
FS_GetTableSize(void)182 SDK_INLINE u32 FS_GetTableSize(void)
183 {
184 return FS_TryLoadTable(NULL, 0);
185 }
186
187 /*---------------------------------------------------------------------------*
188 Name: FS_LoadTable
189
190 Description: Preloads a "rom" archive's table data.
191
192 Arguments: mem: Buffer to store the table data
193 size: The size of mem
194
195 Returns: TRUE if data was preloaded successfully.
196 *---------------------------------------------------------------------------*/
FS_LoadTable(void * mem,u32 size)197 SDK_INLINE BOOL FS_LoadTable(void *mem, u32 size)
198 {
199 return (FS_TryLoadTable(mem, size) <= size);
200 }
201
202 /*---------------------------------------------------------------------------*
203 Name: FS_UnloadTable
204
205 Description: Releases the table preloaded for a "rom" archive.
206
207 Arguments: None.
208
209 Returns: Pointer to the buffer assigned for the table.
210 *---------------------------------------------------------------------------*/
FS_UnloadTable(void)211 SDK_INLINE void *FS_UnloadTable(void)
212 {
213 return FS_UnloadArchiveTables(FS_FindArchive("rom", 3));
214 }
215
216 /*---------------------------------------------------------------------------*
217 Name: FS_ForceToEnableLatencyEmulation
218
219 Description: Uses a driver to emulate the random wait times that occur when accessing a degraded NAND device.
220
221
222 Arguments: None.
223
224 Returns: None.
225 *---------------------------------------------------------------------------*/
226 void FS_ForceToEnableLatencyEmulation(void);
227
228
229 /*---------------------------------------------------------------------------*
230 * Internal functions
231 *---------------------------------------------------------------------------*/
232
233 #define FS_TMPBUF_LENGTH 2048
234 #define FS_MOUNTDRIVE_MAX OS_MOUNT_INFO_MAX
235 #define FS_TEMPORARY_BUFFER_MAX (FS_TMPBUF_LENGTH * FS_MOUNTDRIVE_MAX)
236
237 #ifdef SDK_TWL
238 typedef struct FSFATFSArchiveContext
239 {
240 FSArchive arc[1];
241 char fullpath[2][FATFS_PATH_MAX];
242 u8 *tmpbuf;
243 FATFSDriveResource resource[1];
244 }
245 FSFATFSArchiveContext;
246
247 typedef struct FSFATFSArchiveWork
248 {
249 u8 tmpbuf[FS_TMPBUF_LENGTH];
250 FSFATFSArchiveContext context;
251 int slot;
252 }
253 FSFATFSArchiveWork;
254
255
256 /*---------------------------------------------------------------------------*
257 Name: FSiFATFSDrive
258
259 Description: Context array that manages the archive of a FAT base
260 Ordinarily, an array size for the quantity of FS_MOUNTDRIVE_MAX is required, and in default, static variables in the LTDMAIN segment are used.
261 With applications built using a special memory arrangment, it is possible to set the proper buffer by changing this variable internally by calling the FSi_SetupFATBuffers function that was over-ridden.
262
263
264
265
266 Arguments: None.
267
268 Returns: Buffer for the amount of the FS_MOUNTDRIVE_MAX of the FSFATFSArchiveContext structure
269 *---------------------------------------------------------------------------*/
270 extern FSFATFSArchiveContext *FSiFATFSDrive;
271
272 /*---------------------------------------------------------------------------*
273 Name: FSiFATFSAsyncRequest
274
275 Description: Command buffer that is used in asynchronous processing by the FAT base archive.
276 Ordinarily, an array size for the quantity of FS_MOUNTDRIVE_MAX is required, and in default, static variables in the LTDMAIN segment are used.
277 With applications built using a special memory arrangment, it is possible to set the proper buffer by changing this variable internally by calling the FSi_SetupFATBuffers function that was over-ridden.
278
279
280
281
282 Arguments: None.
283
284 Returns: Static command buffer of FS_TEMPORARY_BUFFER_MAX bytes.
285 *---------------------------------------------------------------------------*/
286 extern FATFSRequestBuffer *FSiFATFSAsyncRequest;
287
288 /*---------------------------------------------------------------------------*
289 Name: FSi_MountSpecialArchive
290
291 Description: Directly mounts a special archive
292
293 Arguments: param: Parameter that specifies the mounting target
294 arcname: Archive name to mount
295 "otherPub" or "otherPrv" can be specified; when NULL is specified, unmount the previous archive
296
297 pWork: Work region that is used for mounting
298 It is necessary to retain while mounted
299
300 Returns: FS_RESULT_SUCCESS if processing was successful.
301 *---------------------------------------------------------------------------*/
302 FSResult FSi_MountSpecialArchive(u64 param, const char *arcname, FSFATFSArchiveWork* pWork);
303
304 /*---------------------------------------------------------------------------*
305 Name: FSi_FormatSpecialArchive
306
307 Description: Formats content of special archive that satisfies the following conditions
308 - Currently mounted
309 - Hold your own ownership rights (dataPub, dataPrv, share*)
310
311 Arguments: path: Path name that includes the archive name
312
313 Returns: FS_RESULT_SUCCESS if processing was successful.
314 *---------------------------------------------------------------------------*/
315 FSResult FSi_FormatSpecialArchive(const char *path);
316
317 #endif // SDK_TWL
318
319 /*---------------------------------------------------------------------------*
320 Name: FSiTemporaryBuffer
321
322 Description: Pointer to the static temporary buffer for issuing read/write commands.
323 It must be memory that can be referenced by both ARM9/ARM7, and by default a static variable in the LTDMAIN segment is used.
324 For applications constructed using a special memory layout, you can change these variables to set the appropriate buffer before calling the FS_Init function.
325
326
327
328
329 Arguments: None.
330
331 Returns: Static command buffer of FS_TEMPORARY_BUFFER_MAX bytes.
332 *---------------------------------------------------------------------------*/
333 extern u8 *FSiTemporaryBuffer/* [FS_TEMPORARY_BUFFER_MAX] ATTRIBUTE_ALIGN(32)*/;
334
335 /*---------------------------------------------------------------------------*
336 Name: FSi_SetupFATBuffers
337
338 Description: Initializes various buffers needed by the FAT base archive.
339 With applications built using a special memory arrangment, it is possible to independently set the various buffers by over-riding this variable and suppressing the required memory size.
340
341
342
343 Arguments: None.
344
345 Returns: None.
346 *---------------------------------------------------------------------------*/
347 void FSi_SetupFATBuffers(void);
348
349 /*---------------------------------------------------------------------------*
350 Name: FSi_OverrideRomArchive
351
352 Description: Replaces the ROM archive content as necessary.
353
354 Arguments: arc ROM archive structure that should be mounted.
355
356 Returns: It is necessary to return TRUE if replacing with a different implementation without using the standard ROM archive on the card.
357
358 *---------------------------------------------------------------------------*/
359 BOOL FSi_OverrideRomArchive(FSArchive *arc);
360
361 /*---------------------------------------------------------------------------*
362 Name: FSi_IsValidAddressForARM7
363
364 Description: Determines whether this is a buffer accessible from ARM7.
365 With applications built using a special memory layout, it is possible to redefine the proper determination routine by overriding this function.
366
367
368
369 Arguments: buffer Buffer to be determined
370 length: Buffer length
371
372 Returns: TRUE if it is a buffer accessible from ARM7.
373 *---------------------------------------------------------------------------*/
374 BOOL FSi_IsValidAddressForARM7(const void *buffer, u32 length);
375
376 /*---------------------------------------------------------------------------*
377 Name: FSi_SetSwitchableWramSlots
378
379 Description: Specifies WRAM slot that the FS library can switch to ARM7 depending on the circumstances.
380
381 Arguments: bitsB: WRAM-B slot bit collection
382 bitsC: Bitset of WRAM-C slots
383
384 Returns: None.
385 *---------------------------------------------------------------------------*/
386 void FSi_SetSwitchableWramSlots(int bitsB, int bitsC);
387
388 /*---------------------------------------------------------------------------*
389 Name: FSi_UnmountRomAndCloseNANDSRL
390
391 Description: Disables the ROM archive for a NAND application and closes the SRL file.
392
393 Arguments: None.
394
395 Returns: None.
396 *---------------------------------------------------------------------------*/
397 void FSi_UnmountRomAndCloseNANDSRL(void);
398
399 /*---------------------------------------------------------------------------*
400 Name: FSi_ConvertStringSjisToUnicode
401
402 Description: Converts a Shift JIS string into a Unicode string.
403 When the path name being handled is clearly only in ASCII code, and the mutual conversion of Unicode and ShiftJIS can be simplified, it is possible to prevent the standard processes of the STD library from linking by overwriting this function.
404
405
406
407
408 Arguments: dst: Conversion destination buffer
409 The storage process is ignored if NULL is specified.
410 dst_len: Pointer which stores and passes the maximum number of characters for the conversion destination buffer, then receives the number of characters that were actually stored.
411 Ignored when NULL is given.
412
413 src: Conversion source buffer
414 src_len Pointer which stores and passes the maximum number of characters to be converted, then receives the number actually converted.
415 The end-of-string position takes priority over this specification.
416 When either a negative value is stored and passed, or NULL is given, the character count is revised to be the number of characters to the end of the string.
417
418
419 callback: The callback to be called if there are any characters that can't be converted.
420 When NULL is specified, the conversion process ends at the position of the character that cannot be converted.
421
422
423 Returns: Result of the conversion process.
424 *---------------------------------------------------------------------------*/
425 STDResult FSi_ConvertStringSjisToUnicode(u16 *dst, int *dst_len,
426 const char *src, int *src_len,
427 STDConvertUnicodeCallback callback);
428
429 /*---------------------------------------------------------------------------*
430 Name: FSi_ConvertStringUnicodeToSjis
431
432 Description: Converts a Unicode character string into a ShiftJIS character string.
433 When the path name being handled is clearly only in ASCII code, and the mutual conversion of Unicode and ShiftJIS can be simplified, it is possible to prevent the standard processes of the STD library from linking by overwriting this function.
434
435
436
437
438 Arguments: dst: Conversion destination buffer
439 The storage process is ignored if NULL is specified.
440 dst_len: Pointer which stores and passes the maximum number of characters for the conversion destination buffer, then receives the number of characters that were actually stored.
441 Ignored when NULL is given.
442
443 src: Conversion source buffer
444 src_len Pointer which stores and passes the maximum number of characters to be converted, then receives the number actually converted.
445 The end-of-string position takes priority over this specification.
446 When either a negative value is stored and passed, or NULL is given, the character count is revised to be the number of characters to the end of the string.
447
448
449 callback: The callback to be called if there are any characters that can't be converted.
450 When NULL is specified, the conversion process ends at the position of the character that cannot be converted.
451
452
453 Returns: Result of the conversion process.
454 *---------------------------------------------------------------------------*/
455 STDResult FSi_ConvertStringUnicodeToSjis(char *dst, int *dst_len,
456 const u16 *src, int *src_len,
457 STDConvertSjisCallback callback);
458
459 /*---------------------------------------------------------------------------*
460 Name: FSi_GetUnicodeBuffer
461
462 Description: Gets temporary buffer for Unicode conversion.
463 The FS library is used for conversion of Shift_JIS.
464
465 Arguments: src: Shift_JIS string needed in Unicode conversion or NULL
466
467 Returns: String buffer converted to UTF16-LE if necessary
468 *---------------------------------------------------------------------------*/
469 u16* FSi_GetUnicodeBuffer(const char *src);
470
471 /*---------------------------------------------------------------------------*
472 Name: FSi_ReleaseUnicodeBuffer
473
474 Description: Deallocates the temporary buffer for Unicode conversion
475
476 Arguments: buf: Buffer allocated by the FSi_GetUnicodeBuffer function
477
478 Returns: None.
479 *---------------------------------------------------------------------------*/
480 void FSi_ReleaseUnicodeBuffer(const void *buf);
481
482
483 /*---------------------------------------------------------------------------*
484 * Deprecated Functions
485 *---------------------------------------------------------------------------*/
486
487 #define FS_DMA_NOT_USE MI_DMA_NOT_USE
488
489 /*---------------------------------------------------------------------------*
490 Name: FS_ChangeDir
491
492 Description: Changes the current directory
493
494 Arguments: path: Path name
495
496 Returns: If successful, TRUE.
497 *---------------------------------------------------------------------------*/
498 BOOL FS_ChangeDir(const char *path);
499
500
501 #ifdef SDK_ARM7
502 #define FS_CreateReadServerThread(priority) (void)CARD_SetThreadPriority(priority)
503 #endif // SDK_ARM7
504
505
506 #ifdef __cplusplus
507 } /* extern "C" */
508 #endif
509
510
511 #endif /* NITRO_FS_API_H_ */
512