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