1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> 4<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css"> 5<base target="main"> 6<title>NAND API Introduction</title> 7</head> 8 9<body> 10 11<h1>NAND API Introduction</h1> 12 13<h2>Introduction</h2> 14<p> 15The NAND library provides an API to access the NAND flash memory built into the Revolution console. NAND flash memory has the following characteristics. 16<ul> 17<li>Nonvolatile memory. 18<li>Fast read, but slightly slow write. 19<li>Random access. 20<li>Concept of bit error. 21<li>Concept of bad blocks. 22<li>Concept of wear and tear because of writing. 23</ul> 24</p> 25 26<p> 27The built-in flash memory capacity of the Revolution console is 512 MB. However, because system files are written at the time of factory shipment, a portion of the 512 MB capacity is unavailable to the application program. 28</p> 29 30<p> 31The NAND library provides a file system with the following characteristics. 32<ul> 33<li>Similar architecture to the UNIX file system. 34<li>Hierarchical file system. 35<li>Access control with three permission levels (Owner/Group/Other). 36<li>Single-bit error correction is done in the file system. 37<li>Bad block processing is done in the file system. 38<li>Ability of the file system to withstand sudden power shutdown. (The entire file system will not be damaged even if power is shut down while writing data or updating the FAT.) 39<li>Up to twelve characters for the file name/directory name 40<li>Supports both absolute path specification and relative path specification. 41<li>Path delimiter text character is "<CODE>/</CODE>." 42<li>The maximum path length is 64 characters (including the NULL character). 43<li>A directory structure up to eight levels deep can be created. 44<li>File block size is 16 KB. 45<li>Maximum number of files/directories to be created is approximately 6000. 46</ul> 47</p> 48 49<p> 50We have prepared sample demo programs that demonstrate how to use the NAND library under the path <code>$REVOLUTION_SDK_ROOT/build/demos/nanddemo/</code>. API functions declarations are in the <code>$REVOLUTION_SDK_ROOT/include/revolution/nand.h</code> header file. 51</p> 52 53<h2>Process Flow</h2> 54<p> 55First call the <a href="./NANDInit.html"><CODE>NANDInit</CODE></a> function to initialize the NAND library and then start using NAND API functions. 56</p> 57 58<h2>Directory Structure</h2> 59<p> 60Although a number of directories are available for the file system used within the internal flash memory, the application programmer should be aware of the following: 61<table border="1"> 62 <tbody> 63 <tr> 64<td bgcolor="#C0C0C0">Path</td> 65<td bgcolor="#C0C0C0">Description</td> 66 </tr> 67 <tr> 68<td>/title/<title-id(Hi)>/<title-id(Low)>/data</td> 69<td>This directory is automatically provided by the system. Save application save data, etc., in this directory.</td> 70 </tr> 71 <tr> 72<td>/tmp</td> 73<td>Temporary directory. Files and directories stored under this directory are deleted when the system starts up.</td> 74 </tr> 75 <tr> 76<td>/tmp/sys</td> 77 <td>This directory is reserved for use by the system as a temporary directory. Avoid having application programs access this directory directly. Doing so can lead to system instability.</td> 78 </tr> 79 </tbody> 80</table> 81</p> 82 83<h2>Application Save Data</h2> 84<p> 85Use the NAND library to save application data. For programmers, the NAND flash memory is simpler to use than the CARD library, as it is built into the Revolution console. Refer to the gamesave sample demo program for more information on saving data. 86</p> 87<p> 88When the NAND library is initialized, the current directory is automatically set as the save data directory. This directory is by default in the development device environment and is common to all applications. However, unique save data directories are available on mass-produced devices for different applications. 89</p> 90 91<h2>Synchronous and Asynchronous Functions</h2> 92<p> 93NAND API functions provide both synchronous and asynchronous access to the internal flash memory. Synchronous functions block the current thread until the process completes and control is transferred to other executable threads. Asynchronous functions return immediately. If a request starts normally, a callback function is called at the completion of the process, and a result code and a command block is passed. The callback function and the command block are specified when the asynchronous function is called. Asynchronous functions contain the suffix <B><CODE>Async</CODE></B>. 94</p> 95 96<h2>inode</h2> 97<p> 98File management is done through inodes in the NAND library file system. To create a new file or a directory, one available inode is required for each file/directory. The number of available inodes can be checked using the <a href="./NANDFreeBlocks.html"><CODE>NANDFreeBlocks</CODE></a> function or the <a href="./NANDFreeBlocksAsync.html"><CODE>NANDFreeBlocksAsync</CODE></a> function. 99</p> 100 101<h2>Result Code List</h2> 102<table> 103 <tbody> 104 <tr> 105<td bgcolor="#C0C0C0">Return Values</td> 106<td bgcolor="#C0C0C0">Description</td> 107 </tr> 108 <tr> 109<td>NAND_RESULT_OK</td> 110<td>Function completes successfully.</td> 111 </tr> 112 <tr> 113<td>NAND_RESULT_ACCESS</td> 114<td>There are no permission/access privileges for accessing files or directories.</td> 115 </tr> 116 <tr> 117<td>NAND_RESULT_ALLOC_FAILED</td> 118<td>Failed to allocate memory within the NAND library.</td> 119 </tr> 120 <tr> 121 <td>NAND_RESULT_AUTHENTICATION</td> 122 <td>Data authentication failed</td> 123 </tr> 124 <tr> 125<td>NAND_RESULT_BUSY</td> 126<td>Busy state (queue of requests is full)</td> 127 </tr> 128 <tr> 129<td>NAND_RESULT_CORRUPT</td> 130<td>The internal flash memory is corrupted beyond repair</td> 131 </tr> 132 <tr> 133<td>NAND_RESULT_ECC_CRIT</td> 134<td>Fatal ECC error detected.</td> 135 </tr> 136 <tr> 137<td>NAND_RESULT_EXISTS</td> 138<td>File or directory with the same name already exists.</td> 139 </tr> 140 <tr> 141<td>NAND_RESULT_INVALID</td> 142<td>Input parameter or the function call itself is invalid.</td> 143 </tr> 144 <tr> 145<td>NAND_RESULT_MAXBLOCKS</td> 146<td>No free space in file system.</td> 147 </tr> 148 <tr> 149<td>NAND_RESULT_MAXFD</td> 150<td>No more files can be opened as the maximum number of file descriptor entries was used.</td> 151 </tr> 152 <tr> 153<td>NAND_RESULT_MAXFILES</td> 154<td>No more files/directories can be created as the file system's inodes are used up.</td> 155 </tr> 156 <tr> 157<td>NAND_RESULT_NOEXISTS</td> 158<td>The specified file or directory does not exist.</td> 159 </tr> 160 <tr> 161<td>NAND_RESULT_NOTEMPTY</td> 162<td>File is not empty.</td> 163 </tr> 164 <tr> 165<td>NAND_RESULT_OPENFD</td> 166<td>The file descriptor is open.</td> 167 </tr> 168 <tr> 169<td>NAND_RESULT_UNKNOWN</td> 170<td>Unknown error code.</td> 171 </tr> 172 <tr> 173<td>NAND_RESULT_FATAL_ERROR</td> 174<td>Program design error code.</td> 175 </tr> 176 </tbody> 177</table> 178 179<p> 180Of these, the following are result codes that might be returned by asynchronous function calls. Furthermore, the callback functions specified when asynchronous function is called cannot accept <CODE>NAND_RESULT_ALLOC_FAILED</CODE>or <CODE>NAND_RESULT_BUSY</CODE>. 181<ul> 182<CODE> 183<li>NAND_RESULT_OK 184<li>NAND_RESULT_ACCESS 185<li>NAND_RESULT_ALLOC_FAILED 186<li>NAND_RESULT_BUSY 187<li>NAND_RESULT_INVALID 188<li>NAND_RESULT_FATAL</CODE> 189</ul> 190</p> 191 192<h2>Notes</h2> 193<h3>Precautions when Writing Data</h3> 194<p> 195The file system used to manage built-in flash memory has been designed to withstand unexpected power shutdown. The entire file system will not crash even if power shuts down in the middle of updating the FAT located in built-in flash memory. Instead the system will restart using the FAT status in effect just before the FAT was to be updated. However, care must be taken regarding write timing. Assume that the following operations have been performed on a given file. 196</p> 197<ol> 198<li>Open() 199<li>Read() 200<li>Write() 201<li>Write() 202<li>Write() 203<li>Close() 204</ol> 205<p> 206Write() alone does not update the FAT in the built-in flash memory. (The FAT in memory is updated.) Even if power shuts down midway through the execution of Write(), file contents will start from the state in effect before Write() was invoked. However, if an operation that involves updating the FAT in built-in flash memory occurs between instances of Write(), the data written by Write() up to that point will be reflected in built-in flash memory. For example, if another thread or process executes Create() immediately after the Write() on line 3 has finished executing, the FAT in built-in flash memory will be updated. If the power goes out immediately after this Create() function has finished executing, only the data written due to the Write() in line 3 will be reflected in the file. Although even this behavior may not be a problem depending on the data structure recorded for the file, if any of the of Write() on lines 3, 4 or 5 are left out, problems will result if data consistency is lost. 207</p> 208<p> 209One method of avoiding inconsistency of data due to this type of FAT update timing is to use a temporary file. First, copy the target file to /tmp and then perform all subsequent reads and writes on the file copied to /tmp. Finally, after the copied file is closed, Move() can be used to overwrite the original file, thus avoiding inconsistency of data described previously. This algorithm is implemented by the functions NANDSafeOpen[Async] and NANDSafeClose[Async]. The sample demo "safe" is provided to demonstrate the atomic nature of updating files using these functions. 210</p> 211 212<h3>Disadvantages of NANDSafe Functions</h2> 213<p> 214Although <code>NANDSafeOpen[Async]</code> and <code>NANDSafeClose[Async]</code> guarantee the atomicity of file updates, they incur a higher cost than the ordinary <code>NANDOpen[Async]</code> and <code>NANDClose[Async]</code> in order to achieve it. Note the following when using these functions. 215<ul> 216<li>A buffer for copying files must be allocated. 217<li>The directory <code>/tmp/sys</code> is created when <code>NANDSafeOpen[Async]</code> is executed for the first time. 218<li>Because <code>NANDSafeOpen[Async]</code> internally copies original files below <code>/tmp/sys</code>, it consumes time and storage space under <code>/tmp</code> in accordance with file size. 219<li><code>NANDSafeOpen[Async]</code> consumes two i-nodes in order to create files and directories when copying. Furthermore, it generates two FAT updates. 220<li>When <code>NANDSafeClose[Async]</code> executes, it generates two file closes, a file move, and deletes a created directory. (However, <code>/tmp/sys</code> is not removed once created.) The function therefore generates four FAT updates. 221</ul> 222</p> 223 224<h3>Allowable Characters in File and Directory Names</h3> 225<p> 226The characters that can be used in file and directory names are limited to the alphanumeric characters <code>[0-9a-zA-Z]</code> and a few symbols <code>[-_.]</code>. 227</p> 228 229<h3>Buffer Alignment</h3> 230<p> 231The buffers used for reading and writing data and the buffers used for getting directory lists must be 32-byte aligned. In addition, the size of data write/read must also be a multiple of 32 bytes. 232</p> 233<p> 234Performance is slightly enhanced by using 64-byte alignment for the buffer used to read/write data. 235</p> 236 237<h3>File/Directory Properties</h3> 238<p> 239You can set properties for files/directories. However, as of 6/16/2006, no decision has been made regarding what type of properties to provide. Although arguments for specifying attributes are included with functions that create files/directories and functions that change properties, at present, do not specify any value other than zero for these arguments. 240</p> 241 242<h3>Internal Flash Memory Wear</h3> 243<p> 244Writing to the internal flash memory will wear it down, so avoid writing too frequently (do not use the flash memory as virtual memory). When performing auto-save, please limit its frequency to less than once per minute. However, limitations become even more severe when performing automatic saving using the NANDSafe line of functions. Because the NANDSafe functions perform six FAT updates during the process of opening and closing files, you need to increase the interval between automatic saves (less than once every six minutes on average) to avoid wear and tear on the FAT. 245</p> 246 247<h3>Fluctuations in Access Time</h3> 248<p> 249Due to the characteristics of the NAND flash device, the time required to access data may vary even though the amount of data being read/written is the same. For this reason, do not write game programs that depend on access time. 250</p> 251 252<h2>Limitations on Use</h2> 253<p> 254The following limitations are planned (although the values are yet to be confirmed) for the use of internal flash memory. They are included here for your reference. 255<table border="1"> 256 <tbody> 257 <tr> 258<td bgcolor="#C0C0C0">Coverage</td> 259<td bgcolor="#C0C0C0">Upper Limit</td> 260 </tr> 261 <tr> 262 <td>Maximum file storage capacity of the home directory</td> 263<td>16 MB</td> 264 </tr> 265 <tr> 266 <td>Number of files/directories that can be created in the home directory</td> 267 <td>32</td> 268 </tr> 269 <tr> 270 <td>Maximum storage capacity of file that can be created in <code>/tmp</code></td> 271<td>40 MB</td> 272 </tr> 273 <tr> 274 <td>Number of files/directories that can be created in <code>/tmp</code></td> 275 <td>64</td> 276 </tr> 277 </tbody> 278</table> 279</p> 280 281<H2>Revision History</H2> 282<p> 28306/16/2006 Initial version. <BR> 8/15/2006 Added a description of the NAND_RESULT_AUTHENTICATION result code.<br> 8/15/2006 Added precautions regarding writing data.<br> 8/15/2006 Revised description of maximum path length.<br> 8/15/2006 Revised description of /tmp/sys.<br> 8/15/2006 Added description of characters allowed in file/directory names.<br> 8/15/2006 Deleted the NAND_RESULT_INIT_FAILED result code.<br> 8/15/2006 Described the maximum allowable depth of the directory hierarchy.<br> 8/15/2006 Added a description of the NANDSafe line of functions.<br> 8/15/2006 Revised the table on operational limitations. 284</p> 285 286 287<hr> 288<P>CONFIDENTIAL</p> 289</BODY> 290</HTML> 291