1 /*---------------------------------------------------------------------------*
2   Project:      NAND flash library
3   File:         nand.h
4   Programmer:   HIRATSU Daisuke
5 
6   Copyright (C) 2005-2006 Nintendo.  All rights reserved.
7 
8   These coded instructions, statements, and computer programs contain
9   proprietary information of Nintendo of America Inc. and/or Nintendo
10   Company Ltd., and are protected by Federal copyright law.  They may
11   not be disclosed to third parties or copied or duplicated in any form,
12   in whole or in part, without the prior written consent of Nintendo.
13 
14   $Log: nand.h,v $
15   Revision 1.57  2009/09/24 09:29:28  iwai_yuma
16   Added NANDSetAutoErrorMessaging() and NANDCountNumOpenableFiles(). Removed NANDSafe API series.
17 
18   Revision 1.56  2009/07/15 10:16:20  iwai_yuma
19   Removed NANDSafe* API series.
20 
21   Revision 1.55  2008/06/20 12:29:44  iwai_yuma
22   (none)
23 
24   Revision 1.54  2008/02/22 02:30:21  iwai_yuma
25   None.
26 
27   Revision 1.53  2007/04/20 08:30:37  hiratsu
28   Added NANDSimpleSafeCancel[Async]().
29 
30   Revision 1.52  2007/04/09 03:01:13  hiratsu
31   Added NANDSimpleSafe* and NANDGet*DirUsage API series.
32 
33   Revision 1.51  2007/02/21 11:55:24  hiratsu
34   Added new result code: NAND_RESULT_MAXDEPTH.
35 
36   Revision 1.50  2006/11/23 07:07:24  hiratsu
37   Renamed member variable.
38 
39   Revision 1.49  2006/11/20 08:25:04  hiratsu
40   Added new member to NANDFileInfo structure in order to detect
41   multiple NANDClose[Async]() calls for same NANDFileInfo.
42 
43   Revision 1.48  2006/10/23 10:50:44  hiratsu
44   Removed SafeCancel APIs becase they are not mature.
45 
46   Revision 1.47  2006/10/19 00:50:37  hiratsu
47   Prepared NANDSafeCancel[Async]().
48 
49   Revision 1.46  2006/10/07 09:29:55  hiratsu
50   Added new API, NANDGetAvailableArea[Async].
51 
52   Revision 1.45  2006/10/05 13:26:25  hiratsu
53   Icon animation speed macros were wrong.  Fixed.
54 
55   Revision 1.44  2006/09/15 14:00:22  hiratsu
56   Modified comment.
57 
58   Revision 1.43  2006/09/14 13:05:23  hiratsu
59   Added banner API.
60 
61   Revision 1.42  2006/09/05 12:50:47  hiratsu
62   Added NAND_FSBLOCK_SIZE macro.
63 
64   Revision 1.41  2006/08/22 23:59:24  hiratsu
65   Added new members for NANDCheckAsync().
66 
67   Revision 1.40  2006/08/12 12:06:51  hiratsu
68   Added new member to command block.
69 
70   Revision 1.39  2006/08/11 12:03:21  hiratsu
71   Revised NANDCheck[Async] interface.
72 
73   Revision 1.38  2006/08/11 10:19:23  yasumoto_yoshitaka
74   surpress padding warning
75 
76   Revision 1.37  2006/08/09 01:56:16  hiratsu
77   Added NANDCheck().
78   But its implementation is not sufficient.
79 
80   Revision 1.36  2006/07/31 13:56:07  hiratsu
81   Fixed NANDSafeOpen/Close bug.
82 
83   Revision 1.35  2006/07/27 05:49:07  hiratsu
84   Removed outdated error code: NAND_RESULT_INIT_FAILED.
85 
86   Revision 1.34  2006/07/24 11:43:41  hiratsu
87   Added NANDGetHomeDir().
88 
89   Revision 1.33  2006/07/03 02:23:10  hiratsu
90   Added AUTHENTICATION result code.
91 
92   Revision 1.32  2006/06/30 08:52:34  hiratsu
93   Added NANDSafeOpen/Close() series.
94 
95   Revision 1.31  2006/06/30 04:13:27  hiratsu
96   Renamed macro.  NAND_TYPE_DIRECTORY -> NAND_TYPE_DIR
97 
98   Revision 1.30  2006/06/27 12:45:16  hiratsu
99   Removed NANDCheckInit().
100 
101   Revision 1.29  2006/06/26 11:41:35  hiratsu
102   Added NANDCheckInit(), and NANDGetType[Async]().
103 
104   Revision 1.28  2006/06/17 10:04:14  hiratsu
105   Added new error code: NAND_RESULT_ALLOC_FAILED because async function may fail to alloc memory.
106 
107   Revision 1.27  2006/06/12 08:14:07  hiratsu
108   NAND_MAX_FD -> 15.  Because system use one file descriptor.
109 
110   Revision 1.26  2006/06/08 11:09:17  hiratsu
111   Removed attribute macro.
112 
113   Revision 1.25  2006/06/06 08:45:35  hiratsu
114   Removed NANDFinalize().
115   New members are added to NANDCommandBlock.
116 
117   Revision 1.24  2006/06/01 12:38:25  hiratsu
118   Added new member to NANDCommandBlock.
119 
120   Revision 1.23  2006/05/25 09:27:28  hiratsu
121   Added new member to NANDFileInfo to implement safe file access.
122 
123   Revision 1.22  2006/05/15 09:34:28  hiratsu
124   Added NANDTellAsync(), NANDGetLengthAsync(), NANDChangeDirAsync().
125 
126   Revision 1.21  2006/05/09 09:10:25  hiratsu
127   Modified error code.
128 
129   Revision 1.20  2006/05/04 11:34:17  hiratsu
130   Implemented NANDGet/SetStatusAsync().
131 
132   Revision 1.19  2006/05/04 09:09:53  hiratsu
133   Renamed API.
134   NANDGetSize -> NANDGetLength
135   NANDGetOffset -> NANDTell
136 
137   Revision 1.18  2006/05/04 04:37:48  hiratsu
138   Added new APIs.  NANDSetUserData(), NANDGetUserData().
139   Renamed argument. cmdBlk -> block
140 
141   Revision 1.17  2006/05/03 08:50:20  hiratsu
142   NANDCommandBlock is installed for callback.
143 
144   Revision 1.16  2006/04/27 17:58:45  orest
145   Added NANDFinalize() api.
146 
147   Revision 1.15  2006/04/25 05:14:43  hiratsu
148   Added NANDSafeOpen/Close(). But these APIs wiil be changed soon.
149   Updated NANDFileInfo for above APIs.
150 
151   Revision 1.14  2006/03/20 10:55:35  hiratsu
152   Implemented NANDMove[Async] instead of NANDRename[Async].
153 
154   Revision 1.13  2006/03/17 04:41:56  hiratsu
155   Added NAND_MAX_NAME macro.
156   File and directory name length is limited by this value.
157 
158   Revision 1.12  2006/03/16 11:42:36  hiratsu
159   New error code is added.
160 
161   Revision 1.11  2006/03/11 09:45:13  hiratsu
162   Changed value of NAND_RESULT_UNKNOWN.
163 
164   Revision 1.10  2006/03/02 05:17:39  hiratsu
165   Added macro for maximum file descriptor.
166 
167   Revision 1.9  2006/02/16 13:03:35  hiratsu
168   Refined API names.
169 
170   Revision 1.8  2006/02/13 12:38:26  hiratsu
171   Some macro definitions are modified in order to match ISFS API.
172   Sorted APIs.
173   Misc APIs are added, but not implemented.
174 
175   Revision 1.7  2006/02/11 08:52:51  hiratsu
176   Renamed APIs.
177 
178   Revision 1.6  2006/02/08 12:57:47  hiratsu
179   Directory APIs are added.  But it is not tested very well.
180 
181   Revision 1.5  2006/02/07 06:56:50  hiratsu
182   Added directory API.
183 
184   Revision 1.4  2006/02/06 00:47:51  hiratsu
185   Added Async APIs and seek API.
186 
187  *---------------------------------------------------------------------------*/
188 
189 #ifndef __NAND_H__
190 #define __NAND_H__
191 
192 
193 #include <revolution/types.h>
194 
195 
196 #ifdef __cplusplus
197 extern "C" {
198 #endif
199 
200 
201 #define NAND_RESULT_OK                0
202 #define NAND_RESULT_ACCESS         ( -1)
203 #define NAND_RESULT_ALLOC_FAILED   ( -2)
204 #define NAND_RESULT_BUSY           ( -3)
205 #define NAND_RESULT_CORRUPT        ( -4)
206 #define NAND_RESULT_ECC_CRIT       ( -5)
207 #define NAND_RESULT_EXISTS         ( -6)
208 //#define NAND_RESULT_INIT_FAILED    ( -7)
209 #define NAND_RESULT_INVALID        ( -8)
210 #define NAND_RESULT_MAXBLOCKS      ( -9)
211 #define NAND_RESULT_MAXFD          (-10)
212 #define NAND_RESULT_MAXFILES       (-11)
213 #define NAND_RESULT_NOEXISTS       (-12)
214 #define NAND_RESULT_NOTEMPTY       (-13)
215 #define NAND_RESULT_OPENFD         (-14)
216 #define NAND_RESULT_AUTHENTICATION (-15)
217 #define NAND_RESULT_MAXDEPTH       (-16)
218 #define NAND_RESULT_UNKNOWN        (-64)
219 #define NAND_RESULT_FATAL_ERROR   (-128)
220 
221 #define NAND_PERM_OTHER_READ   0x01
222 #define NAND_PERM_OTHER_WRITE  0x02
223 #define NAND_PERM_GROUP_READ   0x04
224 #define NAND_PERM_GROUP_WRITE  0x08
225 #define NAND_PERM_OWNER_READ   0x10
226 #define NAND_PERM_OWNER_WRITE  0x20
227 
228 #define NAND_PERM_OWNER_MASK   (NAND_PERM_OWNER_READ | NAND_PERM_OWNER_WRITE)
229 #define NAND_PERM_GROUP_MASK   (NAND_PERM_GROUP_READ | NAND_PERM_GROUP_WRITE)
230 #define NAND_PERM_OTHER_MASK   (NAND_PERM_OTHER_READ | NAND_PERM_OTHER_WRITE)
231 
232 #define NAND_ACCESS_READ       0x01
233 #define NAND_ACCESS_WRITE      0x02
234 #define NAND_ACCESS_RW         (NAND_ACCESS_READ | NAND_ACCESS_WRITE)
235 
236 #define NAND_SEEK_SET          0
237 #define NAND_SEEK_CUR          1
238 #define NAND_SEEK_END          2
239 
240 #define NAND_MAX_CAPACITY      (512*1024*1024)
241 #define NAND_MAX_INODES        6143
242 #define NAND_MAX_PATH          64
243 #define NAND_MAX_FD            15
244 #define NAND_MAX_NAME          12        // Not including the NULL character
245 
246 #define NAND_FSBLOCK_SIZE      (16*1024) // 16KB
247 
248 #define NAND_TYPE_FILE         0x01
249 #define NAND_TYPE_DIR          0x02
250 
251 #define NAND_CHECK_HOME_INSSPACE    0x00000001
252 #define NAND_CHECK_HOME_INSINODE    0x00000002
253 #define NAND_CHECK_SYS_INSSPACE     0x00000004
254 #define NAND_CHECK_SYS_INSINODE     0x00000008
255 
256 
257 
258 #ifdef  __MWERKS__
259 #pragma warn_padding off
260 #endif
261 typedef struct NANDCommandBlock
262 {
263     void *userData;
264 
265     // Do not access below members.
266     void *callback;
267     void *fileInfo;
268     void *bytes;
269     void *inodes;
270     void *status;
271     u32 ownerId;
272     u16 groupId;
273     u8  nextStage;
274     // 1 bytes padding
275     u32 attr;
276     u32 ownerAcc;
277     u32 groupAcc;
278     u32 othersAcc;
279     u32 num;
280     char absPath[NAND_MAX_PATH];
281     u32 *length;
282     u32 *pos;
283     int state;
284     void *copyBuf;
285     u32 bufLength;
286     u8 *type;
287     u32 uniqNo;
288     u32 reqBlocks;
289     u32 reqInodes;
290     u32 *answer;
291     u32 homeBlocks;
292     u32 homeInodes;
293     u32 userBlocks;
294     u32 userInodes;
295     u32 workBlocks;
296     u32 workInodes;
297     const char **dir;
298     BOOL simpleFlag;
299 } NANDCommandBlock;
300 #ifdef  __MWERKS__
301 #pragma warn_padding reset
302 #endif
303 
304 typedef void (*NANDCallback)( s32 result, NANDCommandBlock *block );
305 
306 #ifdef  __MWERKS__
307 #pragma warn_padding off
308 #endif
309 typedef struct NANDFileInfo
310 {
311     // Do not access below members.
312     s32  fileDescriptor;
313     s32  origFd;
314     char origPath[NAND_MAX_PATH];
315     char tmpPath[NAND_MAX_PATH];
316     u8   accType;
317     u8   stage;
318     u8   mark;
319     // 2 bytes padding
320 } NANDFileInfo;
321 #ifdef  __MWERKS__
322 #pragma warn_padding reset
323 #endif
324 
325 
326 typedef struct NANDStatus
327 {
328     u32 ownerId;
329     u16 groupId;
330     u8  attribute;
331     u8  permission;
332 } NANDStatus;
333 
334 
335 s32   NANDInit           (void);
336 
337 //    File access API
338 s32   NANDCreate         (const char *path, u8 perm, u8 attr);
339 s32   NANDCreateAsync    (const char *path, u8 perm, u8 attr, NANDCallback cb, NANDCommandBlock *block);
340 s32   NANDOpen           (const char *path, NANDFileInfo *info, u8 accType);
341 s32   NANDOpenAsync      (const char *path, NANDFileInfo *info, u8 accType, NANDCallback cb, NANDCommandBlock *block);
342 s32   NANDClose          (NANDFileInfo *info);
343 s32   NANDCloseAsync     (NANDFileInfo *info, NANDCallback cb, NANDCommandBlock *block);
344 s32   NANDRead           (NANDFileInfo *info,       void *buf, u32 length);
345 s32   NANDReadAsync      (NANDFileInfo *info,       void *buf, u32 length, NANDCallback cb, NANDCommandBlock *block);
346 s32   NANDWrite          (NANDFileInfo *info, const void *buf, u32 length);
347 s32   NANDWriteAsync     (NANDFileInfo *info, const void *buf, u32 length, NANDCallback cb, NANDCommandBlock *block);
348 s32   NANDSeek           (NANDFileInfo *info, s32 offset, s32 whence);
349 s32   NANDSeekAsync      (NANDFileInfo *info, s32 offset, s32 whence, NANDCallback cb, NANDCommandBlock *block);
350 s32   NANDTell           (NANDFileInfo *info, u32 *pos);
351 s32   NANDTellAsync      (NANDFileInfo *info, u32 *pos, NANDCallback cb, NANDCommandBlock *block);
352 s32   NANDGetLength      (NANDFileInfo *info, u32 *length);
353 s32   NANDGetLengthAsync (NANDFileInfo *info, u32 *length, NANDCallback cb, NANDCommandBlock *block);
354 
355 s32   NANDSimpleSafeOpen       (const char *path, NANDFileInfo *info, const u8 accType, void *buf, const u32 length);
356 s32   NANDSimpleSafeOpenAsync  (const char *path, NANDFileInfo *info, const u8 accType, void *buf, const u32 length, NANDCallback cb, NANDCommandBlock *block);
357 s32   NANDSimpleSafeClose      (NANDFileInfo *info);
358 s32   NANDSimpleSafeCloseAsync (NANDFileInfo *info, NANDCallback cb, NANDCommandBlock *block);
359 s32   NANDSimpleSafeCancel     (NANDFileInfo *info);
360 s32   NANDSimpleSafeCancelAsync(NANDFileInfo *info, NANDCallback cb, NANDCommandBlock *block);
361 
362 
363 //    Directory access API
364 s32   NANDReadDir        (const char *path, char *nameList, u32 *num);
365 s32   NANDReadDirAsync   (const char *path, char *nameList, u32 *num, NANDCallback cb, NANDCommandBlock *block);
366 s32   NANDCreateDir      (const char *path, u8 perm, u8 attr);
367 s32   NANDCreateDirAsync (const char *path, u8 perm, u8 attr, NANDCallback cb, NANDCommandBlock *block);
368 s32   NANDChangeDir      (const char *path);
369 s32   NANDChangeDirAsync (const char *path, NANDCallback cb, NANDCommandBlock *block);
370 s32   NANDGetCurrentDir  (      char  path[NAND_MAX_PATH]);
371 s32   NANDGetHomeDir     (      char  path[NAND_MAX_PATH]);
372 
373 //    File or Directory access API
374 s32   NANDDelete         (const char *path);
375 s32   NANDDeleteAsync    (const char *path, NANDCallback cb, NANDCommandBlock *block);
376 s32   NANDMove           (const char *path, const char *destDir);
377 s32   NANDMoveAsync      (const char *path, const char *destDir, NANDCallback cb, NANDCommandBlock *block);
378 s32   NANDGetStatus      (const char *path,       NANDStatus *stat);
379 s32   NANDGetStatusAsync (const char *path,       NANDStatus *stat, NANDCallback cb, NANDCommandBlock *block);
380 s32   NANDSetStatus      (const char *path, const NANDStatus *stat);
381 s32   NANDSetStatusAsync (const char *path, const NANDStatus *stat, NANDCallback cb, NANDCommandBlock *block);
382 s32   NANDGetType        (const char *path, u8 *type);
383 s32   NANDGetTypeAsync   (const char *path, u8 *type, NANDCallback cb, NANDCommandBlock *block);
384 
385 //    Misc APIs.
386 s32   NANDFreeBlocks     (u32 *bytes, u32 *inodes);
387 s32   NANDFreeBlocksAsync(u32 *bytes, u32 *inodes, NANDCallback cb, NANDCommandBlock *block);
388 
389 s32   NANDCheck          (u32 fsBlock, u32 inode, u32 *answer);
390 s32   NANDCheckAsync     (u32 fsBlock, u32 inode, u32 *answer, NANDCallback cb, NANDCommandBlock *block);
391 s32   NANDGetAvailableArea     (u32 *fsBlock, u32 *inode);
392 s32   NANDGetAvailableAreaAsync(u32 *fsBlock, u32 *inode, NANDCallback cb, NANDCommandBlock *block);
393 
394 void  NANDSetUserData   (      NANDCommandBlock *block, void *data);
395 void* NANDGetUserData   (const NANDCommandBlock *block);
396 
397 s32   NANDGetTmpDirUsage      (u32 *fsBlock, u32 *inode);
398 s32   NANDGetTmpDirUsageAsync (u32 *fsBlock, u32 *inode, NANDCallback cb, NANDCommandBlock *block);
399 s32   NANDGetHomeDirUsage     (u32 *fsBlock, u32 *inode);
400 s32   NANDGetHomeDirUsageAsync(u32 *fsBlock, u32 *inode, NANDCallback cb, NANDCommandBlock *block);
401 
402 //    Error API
403 BOOL  NANDSetAutoErrorMessaging(BOOL enable);
404 
405 //    Debug API
406 s32   NANDCountNumOpenableFiles(u8 *number, BOOL *cleaning);
407 
408 /********************** Banner ***********************/
409 
410 #define NAND_BANNER_TEXTURE_SIZE (192 * 64 * 2)
411 #define NAND_BANNER_ICON_SIZE    ( 48 * 48 * 2)
412 #define NAND_BANNER_COMMENT_SIZE 32
413 
414 #define NAND_BANNER_ICON_ANIM_SPEED_END    0
415 #define NAND_BANNER_ICON_ANIM_SPEED_FAST   1
416 #define NAND_BANNER_ICON_ANIM_SPEED_NORMAL 2
417 #define NAND_BANNER_ICON_ANIM_SPEED_SLOW   3
418 #define NAND_BANNER_ICON_ANIM_SPEED_MASK   3
419 
420 #define NAND_BANNER_FLAG_NOTCOPY 0x00000001
421 
422 #define NAND_BANNER_FLAG_ANIM_BOUNCE 0x00000010
423 #define NAND_BANNER_FLAG_ANIM_LOOP   0x00000000
424 #define NAND_BANNER_FLAG_ANIM_MASK   0x00000010
425 
426 #define NAND_BANNER_SIGNATURE 0x5749424E
427 
428 #define NANDGetIconSpeed(stat, n)          (((stat)->iconSpeed  >> (2 * (n))) & NAND_BANNER_ICON_ANIM_SPEED_MASK)
429 #define NANDSetIconSpeed(stat, n, f)       ((stat)->iconSpeed  = (u16) (((stat)->iconSpeed  & ~(NAND_BANNER_ICON_ANIM_SPEED_MASK << (2 * (n)))) | ((f) << (2 * (n)))))
430 
431 #define NAND_BANNER_SIZE( i ) ( 32 + NAND_BANNER_COMMENT_SIZE * sizeof(u16) * 2 + NAND_BANNER_TEXTURE_SIZE + NAND_BANNER_ICON_SIZE * (i) )
432 
433 typedef struct
434 {
435     u32 signature;            // Signature: 0x5749424E
436 
437     u32 flag;                 // Flags
438     u16 iconSpeed;            // Icon animation speed
439     u8  reserved[22];         // for 32B align
440 
441     u16 comment[2][NAND_BANNER_COMMENT_SIZE];    // title and comment
442     u8  bannerTexture[NAND_BANNER_TEXTURE_SIZE]; // Banner texture
443     u8  iconTexture[8][NAND_BANNER_ICON_SIZE];   // Icon texture 0-7
444 } NANDBanner;
445 
446 
447 void NANDInitBanner( NANDBanner *bnr, u32 flag, const u16 *title, const u16 *comment );
448 
449 
450 #ifdef __cplusplus
451 }
452 #endif
453 
454 
455 #endif // end of __NAND_H__
456