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