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.40  08/12/2006 12:06:51  hiratsu
16   Added new member to command block.
17 
18   Revision 1.39  08/11/2006 12:03:21  hiratsu
19   Revised NANDCheck[Async] interface.
20 
21   Revision 1.38  2006/08/11 10:19:23  yasumoto_yoshitaka
22   suppress padding warning
23 
24   Revision 1.37  08/09/2006 01:56:16  hiratsu
25   Added NANDCheck().
26   But its implementation is not sufficient.
27 
28   Revision 1.36  07/31/2006 13:56:07  hiratsu
29   Fixed NANDSafeOpen/Close bug.
30 
31   Revision 1.35  07/27/2006 05:49:07  hiratsu
32   Removed outdated error code: NAND_RESULT_INIT_FAILED.
33 
34   Revision 1.34  07/24/2006 11:43:41  hiratsu
35   Added NANDGetHomeDir().
36 
37   Revision 1.33  07/03/2006 02:23:10  hiratsu
38   Added AUTHENTICATION result code.
39 
40   Revision 1.32  06/30/2006 08:52:34  hiratsu
41   Added NANDSafeOpen/Close() series.
42 
43   Revision 1.31  06/30/2006 04:13:27  hiratsu
44   Renamed macro.  NAND_TYPE_DIRECTORY -> NAND_TYPE_DIR
45 
46   Revision 1.30  06/27/2006 12:45:16  hiratsu
47   Removed NANDCheckInit().
48 
49   Revision 1.29  06/26/2006 11:41:35  hiratsu
50   Added NANDCheckInit(), and NANDGetType[Async]().
51 
52   Revision 1.28  06/17/2006 10:04:14  hiratsu
53   Added new error code: NAND_RESULT_ALLOC_FAILED because async function may fail to alloc memory.
54 
55   Revision 1.27  06/12/2006 08:14:07  hiratsu
56   NAND_MAX_FD -> 15.  Because system use one file descriptor.
57 
58   Revision 1.26  06/08/2006 11:09:17  hiratsu
59   Removed attribute macro.
60 
61   Revision 1.25  06/06/2006 08:45:35  hiratsu
62   Removed NANDFinalize().
63   New members are added to NANDCommandBlock.
64 
65   Revision 1.24  06/01/2006 12:38:25  hiratsu
66   Added new member to NANDCommandBlock.
67 
68   Revision 1.23  05/25/2006 09:27:28  hiratsu
69   Added new member to NANDFileInfo to implement safe file access.
70 
71   Revision 1.22  05/15/2006 09:34:28  hiratsu
72   Added NANDTellAsync(), NANDGetLengthAsync(), NANDChangeDirAsync().
73 
74   Revision 1.21  05/09/2006 09:10:25  hiratsu
75   Modified error code.
76 
77   Revision 1.20  05/04/2006 11:34:17  hiratsu
78   Implemented NANDGet/SetStatusAsync().
79 
80   Revision 1.19  05/04/2006 09:09:53  hiratsu
81   Renamed API.
82   NANDGetSize -> NANDGetLength
83   NANDGetOffset -> NANDTell
84 
85   Revision 1.18  05/04/2006 04:37:48  hiratsu
86   Added new APIs.  NANDSetUserData(), NANDGetUserData().
87   Renamed argument. cmdBlk -> block
88 
89   Revision 1.17  05/03/2006 08:50:20  hiratsu
90   NANDCommandBlock is installed for callback.
91 
92   Revision 1.16  2006/04/27 17:58:45  orest
93   Added NANDFinalize() api.
94 
95   Revision 1.15  04/25/2006 05:14:43  hiratsu
96   Added NANDSafeOpen/Close(). But these APIs wiil be changed soon.
97   Updated NANDFileInfo for above APIs.
98 
99   Revision 1.14  03/20/2006 10:55:35  hiratsu
100   Implemented NANDMove[Async] instead of NANDRename[Async].
101 
102   Revision 1.13  03/17/2006 04:41:56  hiratsu
103   Added NAND_MAX_NAME macro.
104   File and directory name length is limited by this value.
105 
106   Revision 1.12  03/16/2006 11:42:36  hiratsu
107   New error code is added.
108 
109   Revision 1.11  03/11/2006 09:45:13  hiratsu
110   Changed value of NAND_RESULT_UNKNOWN.
111 
112   Revision 1.10  03/02/2006 05:17:39  hiratsu
113   Added macro for maximum file descriptor.
114 
115   Revision 1.9  02/16/2006 13:03:35  hiratsu
116   Refined API names.
117 
118   Revision 1.8  02/13/2006 12:38:26  hiratsu
119   Some macro definitions are modified in order to match ISFS API.
120   Sorted APIs.
121   Misc APIs are added, but not implemented.
122 
123   Revision 1.7  02/11/2006 08:52:51  hiratsu
124   Renamed APIs.
125 
126   Revision 1.6  02/08/2006 12:57:47  hiratsu
127   Directory APIs are added.  But it is not tested very well.
128 
129   Revision 1.5  02/07/2006 06:56:50  hiratsu
130   Added directory API.
131 
132   Revision 1.4  02/06/2006 00:47:51  hiratsu
133   Added Async APIs and seek API.
134 
135  *---------------------------------------------------------------------------*/
136 
137 #ifndef __NAND_H__
138 #define __NAND_H__
139 
140 
141 #include <revolution/types.h>
142 
143 
144 #ifdef __cplusplus
145 extern "C" {
146 #endif
147 
148 
149 #define NAND_RESULT_OK                0
150 #define NAND_RESULT_ACCESS         ( -1)
151 #define NAND_RESULT_ALLOC_FAILED   ( -2)
152 #define NAND_RESULT_BUSY           ( -3)
153 #define NAND_RESULT_CORRUPT        ( -4)
154 #define NAND_RESULT_ECC_CRIT       ( -5)
155 #define NAND_RESULT_EXISTS         ( -6)
156 //#define NAND_RESULT_INIT_FAILED    ( -7)
157 #define NAND_RESULT_INVALID        ( -8)
158 #define NAND_RESULT_MAXBLOCKS      ( -9)
159 #define NAND_RESULT_MAXFD          (-10)
160 #define NAND_RESULT_MAXFILES       (-11)
161 #define NAND_RESULT_NOEXISTS       (-12)
162 #define NAND_RESULT_NOTEMPTY       (-13)
163 #define NAND_RESULT_OPENFD         (-14)
164 #define NAND_RESULT_AUTHENTICATION (-15)
165 #define NAND_RESULT_UNKNOWN        (-64)
166 #define NAND_RESULT_FATAL_ERROR   (-128)
167 
168 #define NAND_PERM_OTHER_READ   0x01
169 #define NAND_PERM_OTHER_WRITE  0x02
170 #define NAND_PERM_GROUP_READ   0x04
171 #define NAND_PERM_GROUP_WRITE  0x08
172 #define NAND_PERM_OWNER_READ   0x10
173 #define NAND_PERM_OWNER_WRITE  0x20
174 
175 #define NAND_PERM_OWNER_MASK   (NAND_PERM_OWNER_READ | NAND_PERM_OWNER_WRITE)
176 #define NAND_PERM_GROUP_MASK   (NAND_PERM_GROUP_READ | NAND_PERM_GROUP_WRITE)
177 #define NAND_PERM_OTHER_MASK   (NAND_PERM_OTHER_READ | NAND_PERM_OTHER_WRITE)
178 
179 #define NAND_ACCESS_READ       0x01
180 #define NAND_ACCESS_WRITE      0x02
181 #define NAND_ACCESS_RW         (NAND_ACCESS_READ | NAND_ACCESS_WRITE)
182 
183 #define NAND_SEEK_SET          0
184 #define NAND_SEEK_CUR          1
185 #define NAND_SEEK_END          2
186 
187 #define NAND_MAX_CAPACITY      (512*1024*1024)
188 #define NAND_MAX_INODES        6143
189 #define NAND_MAX_PATH          64
190 #define NAND_MAX_FD            15
191 #define NAND_MAX_NAME          12        // Not including the NULL character
192 
193 #define NAND_TYPE_FILE         0x01
194 #define NAND_TYPE_DIR          0x02
195 
196 #define NAND_CHECK_HOME_INSSPACE    0x00000001
197 #define NAND_CHECK_HOME_INSINODE    0x00000002
198 #define NAND_CHECK_SYS_INSSPACE     0x00000004
199 #define NAND_CHECK_SYS_INSINODE     0x00000008
200 
201 
202 #ifdef  __MWERKS__
203 #pragma warn_padding off
204 #endif
205 typedef struct NANDCommandBlock
206 {
207     void *userData;
208 
209     // Do not access below members.
210     void *callback;
211     void *fileInfo;
212     void *bytes;
213     void *inodes;
214     void *status;
215     u32 ownerId;
216     u16 groupId;
217     // 2 bytes padding
218     u32 attr;
219     u32 ownerAcc;
220     u32 groupAcc;
221     u32 othersAcc;
222     u32 num;
223     char absPath[NAND_MAX_PATH];
224     u32 *length;
225     u32 *pos;
226     int state;
227     void *copyBuf;
228     u32 bufLength;
229     u8 *type;
230     u32 uniqNo;
231     u32 reqBlocks;
232     u32 reqInodes;
233     u32 *answer;
234     u32 homeBlocks;
235     u32 homeInodes;
236 } NANDCommandBlock;
237 #ifdef  __MWERKS__
238 #pragma warn_padding reset
239 #endif
240 
241 typedef void (*NANDCallback)( s32 result, NANDCommandBlock *block );
242 
243 #ifdef  __MWERKS__
244 #pragma warn_padding off
245 #endif
246 typedef struct NANDFileInfo
247 {
248     // Do not access below members.
249     s32  fileDescriptor;
250     s32  origFd;
251     char origPath[NAND_MAX_PATH];
252     char tmpPath[NAND_MAX_PATH];
253     u8   accType;
254     // 3 bytes padding
255 } NANDFileInfo;
256 #ifdef  __MWERKS__
257 #pragma warn_padding reset
258 #endif
259 
260 
261 typedef struct NANDStatus
262 {
263     u32 ownerId;
264     u16 groupId;
265     u8  attribute;
266     u8  permission;
267 } NANDStatus;
268 
269 
270 s32   NANDInit           (void);
271 
272 //    File access API
273 s32   NANDCreate         (const char *path, u8 perm, u8 attr);
274 s32   NANDCreateAsync    (const char *path, u8 perm, u8 attr, NANDCallback cb, NANDCommandBlock *block);
275 s32   NANDOpen           (const char *path, NANDFileInfo *info, u8 accType);
276 s32   NANDOpenAsync      (const char *path, NANDFileInfo *info, u8 accType, NANDCallback cb, NANDCommandBlock *block);
277 s32   NANDClose          (NANDFileInfo *info);
278 s32   NANDCloseAsync     (NANDFileInfo *info, NANDCallback cb, NANDCommandBlock *block);
279 s32   NANDRead           (NANDFileInfo *info,       void *buf, u32 length);
280 s32   NANDReadAsync      (NANDFileInfo *info,       void *buf, u32 length, NANDCallback cb, NANDCommandBlock *block);
281 s32   NANDWrite          (NANDFileInfo *info, const void *buf, u32 length);
282 s32   NANDWriteAsync     (NANDFileInfo *info, const void *buf, u32 length, NANDCallback cb, NANDCommandBlock *block);
283 s32   NANDSeek           (NANDFileInfo *info, s32 offset, s32 whence);
284 s32   NANDSeekAsync      (NANDFileInfo *info, s32 offset, s32 whence, NANDCallback cb, NANDCommandBlock *block);
285 s32   NANDTell           (NANDFileInfo *info, u32 *pos);
286 s32   NANDTellAsync      (NANDFileInfo *info, u32 *pos, NANDCallback cb, NANDCommandBlock *block);
287 s32   NANDGetLength      (NANDFileInfo *info, u32 *length);
288 s32   NANDGetLengthAsync (NANDFileInfo *info, u32 *length, NANDCallback cb, NANDCommandBlock *block);
289 s32   NANDSafeOpen       (const char *path, NANDFileInfo *info, u8 accType, void *buf, u32 length);
290 s32   NANDSafeOpenAsync  (const char *path, NANDFileInfo *info, u8 accType, void *buf, u32 length, NANDCallback cb, NANDCommandBlock *block);
291 s32   NANDSafeClose      (NANDFileInfo *info);
292 s32   NANDSafeCloseAsync (NANDFileInfo *info, NANDCallback cb, NANDCommandBlock *block);
293 
294 //    Directory access API
295 s32   NANDReadDir        (const char *path, char *nameList, u32 *num);
296 s32   NANDReadDirAsync   (const char *path, char *nameList, u32 *num, NANDCallback cb, NANDCommandBlock *block);
297 s32   NANDCreateDir      (const char *path, u8 perm, u8 attr);
298 s32   NANDCreateDirAsync (const char *path, u8 perm, u8 attr, NANDCallback cb, NANDCommandBlock *block);
299 s32   NANDChangeDir      (const char *path);
300 s32   NANDChangeDirAsync (const char *path, NANDCallback cb, NANDCommandBlock *block);
301 s32   NANDGetCurrentDir  (      char  path[NAND_MAX_PATH]);
302 s32   NANDGetHomeDir     (      char  path[NAND_MAX_PATH]);
303 
304 //    File or Directory access API
305 s32   NANDDelete         (const char *path);
306 s32   NANDDeleteAsync    (const char *path, NANDCallback cb, NANDCommandBlock *block);
307 s32   NANDMove           (const char *path, const char *destDir);
308 s32   NANDMoveAsync      (const char *path, const char *destDir, NANDCallback cb, NANDCommandBlock *block);
309 s32   NANDGetStatus      (const char *path,       NANDStatus *stat);
310 s32   NANDGetStatusAsync (const char *path,       NANDStatus *stat, NANDCallback cb, NANDCommandBlock *block);
311 s32   NANDSetStatus      (const char *path, const NANDStatus *stat);
312 s32   NANDSetStatusAsync (const char *path, const NANDStatus *stat, NANDCallback cb, NANDCommandBlock *block);
313 s32   NANDGetType        (const char *path, u8 *type);
314 s32   NANDGetTypeAsync   (const char *path, u8 *type, NANDCallback cb, NANDCommandBlock *block);
315 
316 //    Misc APIs.
317 s32   NANDFreeBlocks     (u32 *bytes, u32 *inodes);
318 s32   NANDFreeBlocksAsync(u32 *bytes, u32 *inodes, NANDCallback cb, NANDCommandBlock *block);
319 
320 s32   NANDCheck          (u32 fsBlock, u32 inode, u32 *answer);
321 s32   NANDCheckAsync     (u32 fsBlock, u32 inode, u32 *answer, NANDCallback cb, NANDCommandBlock *block);
322 
323 void  NANDSetUserData   (      NANDCommandBlock *block, void *data);
324 void* NANDGetUserData   (const NANDCommandBlock *block);
325 
326 #ifdef __cplusplus
327 }
328 #endif
329 
330 
331 #endif // end of __NAND_H__
332