intro.html - OpenGrok cross reference for /RvlSDK-3.3/man/en_US/nand/intro.html

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css">
<base target="main">
<title>NAND Function Introduction</title>
</head>

<body>

<h1>NAND API</h1>

<h2>Introduction</h2>
<p>
The NAND library provides functions to access the NAND flash memory built into the Wii console. NAND flash memory has the following characteristics:
<ul>
<li>Nonvolatile memory.
<li>Fast read, but slightly slow write.
<li>Random access.
<li>Concept of bit error.
<li>Concept of bad blocks.
<li>Concept of wear and tear because of writing.
</ul>
</p>

<p>
The NAND memory capacity of the Wii console is 512 MB. However, not all of the 512 MB space can be used by the application program, as some of the space will be taken by the system files written at the factory or for permanently reserved system needs.
</p>

<p>
The NAND library provides a file system with the following characteristics.
<ul>
<li>Similar architecture to UNIX file systems.
<li>Hierarchical file system.
<li>Access control with three permission levels (Owner/Group/Other). (Group is a permission that corresponds to a company. The Group permission can be used when you want to allow access for titles from the same company.)
<li>Single-bit error correction is done in the file system.
<li>Bad block processing is done in the file system.
<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.)
<li>Up to twelve characters for file or directory names.
<li>Supports both absolute path specification and relative path specification.
<li>Path delimiter text character is &quot;<CODE>/</CODE>&quot;.
<li>The maximum path length is 64 characters, including the NULL character.
<li>A directory structure up to eight levels deep can be created.
<li>The size of the file system block (FS block) is 16 KB. (In other words, even a 1-byte file takes a region of 16 KB.)
<li>Maximum number of files/directories that can be created is approximately 6000.
</ul>
</p>

<p>
We have prepared sample demo programs that demonstrate how to use the NAND library under the path <code>$REVOLUTION_SDK_ROOT/build/demos/nanddemo/</code>. Function declarations are in the <code>$REVOLUTION_SDK_ROOT/include/revolution/nand.h</code> header file.
</p>


<h2>Banners</h2>
<p>
You must create a banner file in order to create an application save file in Wii console NAND memory. In the Wii Menu, home directories without a banner file are deleted. <font color="#ff0000">If creating multiple files that include a banner file, be sure to create the banner file last. </font>If the banner file is created first, and then an accident such as a power interruption occurs, the home directory would have a banner file, but some of the save files might not be there. This could confuse players because it would appear from the save data screen in the Wii Menu that the application had no problem creating the save files, when in fact there was a problem. See the <I><a href="../../../docs/ja_JP/Programmer's_Guide/Wii_SaveData.jp.pdf">Wii Save Data Specifications</a></I> for more information.<br>
</p>
<p>
The <a href="./NANDBanner.html"><CODE>NANDBanner</CODE></a> structure and the <a href="./NANDInitBanner.html"><CODE>NANDInitBanner</CODE></a>, <a href="./NANDGetIconSpeed.html"><CODE>NANDGetIconSpeed</CODE></a> and <a href="./NANDSetIconSpeed.html"><CODE>NANDSetIconSpeed</CODE></a> functions have been prepared to simplify the process of creating banners. Also, reference the <CODE>banner</CODE> sample demo program.
</p>

<h2>Functions That Determine Whether a File or Directory Can Be Newly Created</h2>
<p>
As mentioned before, Wii console NAND memory has a capacity of 512MB, but not all of it can be used by the application program. The memory includes system programs represented by console feature applications, a reserved region for bad blocks, and a free region which must be allocated for system use. Do not conclude whether a new file/directory can be created solely based on available space in the file system; use of <CODE>NANDFreeBlocks[Async]</CODE> is not recommended.<br>When the application attempts to create files or directories in the home directory, determine whether to go ahead and create the new files/directories or to perform some process such as displaying a message indicating insufficient memory space based on responses from the functions below.
</p>

<h3>NANDCheck[Async]</h3>
<p>
The <a href="./NANDCheck.html"><CODE>NANDCheck</CODE></a> and <a href="./NANDCheckAsync.html"><CODE>NANDCheckAsync</CODE></a> functions report the number of file system blocks and inodes that the application is about to consume. If the application is creating a new file or directory under the home directory, call the <a href="./NANDCheck.html"><CODE>NANDCheck</CODE></a> or <a href="./NANDCheckAsync.html"><CODE>NANDCheckAsync</CODE></a> function first. The total number of file system blocks and inodes for the file or directory that the application will create is passed to the <a href="./NANDCheckAsync.html"><CODE>NANDCheck</CODE></a> and <a href="./NANDCheckAsync.html"><CODE>NANDCheckAsync</CODE></a> functions. The system will calculate whether a sufficient space to fulfill that request is available in the file system, and will give the verdict to the application program. Using <a href="../tools/ncheck_tool.html">Ncheck tool</A> to confirm that <CODE>NANDCheck</CODE> or <CODE>NANDCheckAsync</CODE> has been implemented correctly may reduce the amount of available space in Wii console NAND memory.
</p>

<h3>Determining Whether Multiple Files or Directories Can Be Created</h3>
<p>
If the application requires multiple files or directories to proceed, sum the total number of file system blocks and inodes consumed by each, and then branch to either &quot;Create file/directory group&quot; or &quot;Create no files/directories,&quot; based on the result of a single call to the <CODE>NANDCheck[Async]</CODE> function. Do not call the <CODE>NANDCheck[Async]</CODE> function every time a file or directory is created. If you call the <CODE>NANDCheck[Async]</CODE> function multiple times to create multiple files and directories, depending on the available space in Wii console NAND memory you may not be able to create all of the required files and directories.
</p>

<dl><dd><pre><code>
// Correct sequence (pseudo-code)
NANDCheck(FileA+FileB+FileC);    // Check A & B & C at once.
if(success){
    createFileA();
    createFileB();
    createFileC();
}
</code></pre></dd></dl>

<dl><dd><pre><code>
// Incorrect sequence (pseudo-code)
NANDCheck(FileA);   // Check A
if(success){
    createFileA();
}

NANDCheck(FileB);   // Check B
if(success){
    createFileB();
}

NANDCheck(FileC)    // Check C
if(success){
    createFileC()
}
</code></pre></dd></dl>

<p>
The number of file system blocks (FS blocks) consumed by a given file is rounded up to be an integer value of the file size divided by 16 KB. Thus, an 8 KB file consumes one FS block, and a 40 KB consumes three FS blocks. Accordingly, if an application needs to create two files, one 8 KB and one 40 KB, that file group consumes four FS blocks (1 + 3 = 4). Do not calculate this as <CODE>(40+8)/16 = 3</CODE> and call the <CODE>NANDCheck[Async]</CODE> function under the assumption that three FS blocks will be consumed.
</p>

<h2>Functions That Get the Available Space for an Application</h2>
<p>
The <a href="./NANDCheck.html"><CODE>NANDCheck</CODE></a> and the <a href="./NANDCheckAsync.html"><CODE>NANDCheckAsync</CODE></a> functions determine whether files/directories can be created, but they are not suited to determine exactly how much free space is available. If you want to inform the player how much free space is available for the application to use in Wii console NAND memory, use the <a href="./NANDGetAvailableArea.html"><CODE>NANDGetAvailableArea</CODE></a> or the <a href="./NANDGetAvailableAreaAsync.html"><CODE>NANDGetAvailableAreaAsync</CODE></a> function. These functions get the number of file system blocks and inodes that the application can consume.
</p>

<h2>Process Flow</h2>
<p>
First, call the <a href="./NANDInit.html"><CODE>NANDInit</CODE></a> function to initialize the NAND library before using NAND functions. <font color="ff0000">(<B>Note:</B> Starting with RevolutionSDK 2.1, patch 1, the <CODE>NANDInit</CODE> function is automatically called by the system.)</font>If the application is creating a new file or directory in a directory other than <CODE>/tmp</CODE>, first call the <a href="./NANDCheck.html"><CODE>NANDCheck</CODE></a> or <a href="./NANDCheckAsync.html"><CODE>NANDCheckAsync</CODE></a> function to verify that the file system has sufficient free space and inodes for the application before calling the <a href="./NANDCreate.html"><CODE>NANDCreate</CODE></a> function.
</p>
<p>
Refer to <a href="./sequence.html">NAND Processing Sequence</a> for an example of process flow including the error processing.
</p>

<h2>Directory Structure</h2>
<p>
Although a number of directories are available for the file system in Wii console NAND memory, the application programmer should be aware of the following.
<table class="api_list" border="1">
  <tbody>
    <tr>
<td bgcolor="#C0C0C0">Path</td>
<td bgcolor="#C0C0C0">Description</td>
    </tr>
    <tr>
<th nowrap>/title/&lt;title-id(Hi)&gt;/&lt;title-id(Low)&gt;/data</th>
<td>This is the application home directory. The home directory is provided automatically by the system. Save the application's save data and other application-related data in this directory.</td>
    </tr>
    <tr>
<th>/tmp</th>
<td>Temporary directory. Files and directories stored under this directory are deleted when the system starts up.</td>
    </tr>
    <tr>
<th>/tmp/sys</th>
<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>
    </tr>
  </tbody>
</table>
<br> <I>&lt;title-id (Hi)&gt;</I> is a 32-bit value determined according to the application type. It is assigned by the system and displayed as a string in hexadecimal notation. The value is 00010000 for disc applications and 00010001 and higher for NAND applications. At the present time, the value 00010001 is assigned to &lt;title-id (Hi)&gt; for WiiWare (but this might change in the future).<br><EM>&lt;title-id (Low)&gt;</EM> is equivalent to the four-character game code unique to each application, after conversion to a hexadecimal-notation string based on the ASCII character code table. For example, if the initial code is &quot;RABJ&quot;, it is converted to <CODE>5241424a</CODE>. The <EM>&lt;title-id (Low)&gt;</EM> string is not automatically updated with the DDF file's <CODE>GameName</CODE> when an ELF file is executed on NDEV, so it must be directly specified separately using <CODE>setinitialcode</CODE>.

</p>

<h2>Directory and File Access</h2>
<p>
The Wii console NAND memory file system controls access using three levels of permissions: <STRONG>Owner</STRONG>, <STRONG>Group</STRONG>, and <STRONG>Other</STRONG>. <STRONG>Owner</STRONG> and <STRONG>Group</STRONG> permissions are managed by the application, using access control IDs called the <I>Owner ID</I> and <I>Group ID</I>, respectively. <STRONG>Other</STRONG> permissions apply to titles whose Owner ID and Group ID both differ.<br><br>The Owner ID is a unique ID given to titles imported into Wii console NAND memory, and is assigned automatically by the system. A Wii console can hold multiple imported titles, but they will never be assigned duplicate Owner IDs.<br>The Group ID is a characteristic ID assigned to individual companies. In the case of a disc application, when creating master data using the <CODE>makemaster</CODE> command, the two-byte string set for the <CODE>Company</CODE> variable in the DDF file's <CODE>[DiskID]</CODE> is converted into hexadecimal notation based on the ASCII character code table, and this value is used as the Group ID. For example, if the <CODE><EM>Company</EM></CODE> variable is <CODE>[00]</CODE>, the Group ID is <CODE>[0x3030]</CODE>.
</h2>
</p>

<h2>Application Save Data</h2>
<p>
Use the NAND library to save application data. Refer to the <CODE>gamesave</CODE> sample demo program for more information on saving data.
</p>
<p>
When the NAND library is initialized, the current directory is automatically set as the home directory. This directory is hardwired in software in the development device environment and is common to all applications. However, a unique home directory is provided for each application on the production units.
</p>

<h2>Synchronous and Asynchronous Functions</h2>
<p>
Certain NAND functions provide both synchronous and asynchronous access to Wii console NAND memory.<br>Synchronous functions block the current thread until the process is completed and control is transferred to other executable threads. Asynchronous functions return immediately. If an asynchronous function request starts normally, a callback function is called at the completion of the process, and a result code and command block are passed to it. This callback function and command block are specified when the asynchronous function is called. If the asynchronous function call ends in an error (that is, if the result code is other than a normal exit), the specified callback function will not be called. Asynchronous functions contain the suffix <B><CODE>Async</CODE></B>.
</p>

<h2>Inodes</h2>
<p>
File management is done through inodes in the NAND library file system. One available inode is required for each file or directory that is created. The number of available i-nodes can be checked using the <a href="./NANDFreeBlocks.html"><CODE>NANDFreeBlocks</CODE></a> or <a href="./NANDFreeBlocksAsync.html"><CODE>NANDFreeBlocksAsync</CODE></a> function.<br>However, the values obtained by these functions are the available inode counts for the entire file system. In actuality, some free inodes must always be reserved for the system, so please do not determine whether a new file/directory can be created solely based on the value obtained by these functions. When creating a new file or directory in a location other than <CODE>/tmp</CODE>, please use the <a href="./NANDCheck.html"><CODE>NANDCheck</CODE></a> or <a href="./NANDCheckAsync.html"><CODE>NANDCheckAsync</CODE></a> function to make your determination.
</p>

<h2>Result Code List</h2>
<table class="arguments" border="1">
  <tbody>
    <tr>
<td bgcolor="#C0C0C0">Return Values</td>
<td bgcolor="#C0C0C0">Description</td>
    </tr>
    <tr>
<th>NAND_RESULT_OK</th>
<td>Completed successfully.</td>
    </tr>
    <tr>
<th>NAND_RESULT_ACCESS</th>
<td>The are no permission/access privileges for accessing files or directories.</td>
    </tr>
    <tr>
<th>NAND_RESULT_ALLOC_FAILED</th>
<td>The library failed internally to secure the memory needed for receiving a large volume of requests at one time.</td>
    </tr>
    <tr>
<th>NAND_RESULT_AUTHENTICATION</th>
<td>Data authentication failed. Data may have been damaged due to faulty hardware, or data in Wii console NAND memory may have been altered illegally. (See Note 1)</td>
    </tr>
    <tr>
<th>NAND_RESULT_BUSY</th>
<td>Busy state (the queue holding requests is full).</td>
    </tr>
    <tr>
<th>NAND_RESULT_CORRUPT</th>
<td>Wear in the FAT region has caused irreparable damage to Wii console NAND memory.</td>
    </tr>
    <tr>
<th>NAND_RESULT_ECC_CRIT</th>
<td>Indicates that a fatal ECC error has been detected (that is, data error correction is not possible). This code might be returned when Wii console NAND memory is severely worn because the number of write/delete cycles has exceeded the device guaranteed performance.</td>
    </tr>
    <tr>
<th>NAND_RESULT_EXISTS</th>
<td>File or directory with the same name already exists.</td>
    </tr>
    <tr>
<th>NAND_RESULT_INVALID</th>
<td>An input parameter, or the function call itself, is invalid. This code is returned when an incorrect argument is passed to a NAND function, an attempt is made to close a file twice, or an attempt is made to use the <CODE>NANDSimpleSafe[Close]</CODE> functions to close a file that was opened by the <CODE>NANDOpen[Async]</CODE> functions (or vice versa).</td>
    </tr>
    <tr>
<th>NAND_RESULT_MAXBLOCKS</th>
<td>All of the FS blocks in the file system have been used, so there is no free space. This code is also returned when, due to device wear, the number of bad blocks has reached the upper limit. (See Note 2)</td>
    </tr>
    <tr>
<th>NAND_RESULT_MAXDEPTH</th>
<td>A directory structure deeper than this cannot be created (8 levels maximum).</td>
    </tr>
    <tr>
<th>NAND_RESULT_MAXFD</th>
<td>No more files can be opened because all of the file descriptor entries have been used. Reduce the number of files you open at one time.</td>
    </tr>
    <tr>
<th>NAND_RESULT_MAXFILES</th>
<td>No more files/directories can be created because the file system's inodes have been used up. (See notes)</td>
    </tr>
    <tr>
<th>NAND_RESULT_NOEXISTS</th>
<td>The specified file or directory does not exist.</td>
    </tr>
    <tr>
<th><S>NAND_RESULT_NOTEMPTY</S></th>
<td><S>File is not empty.</S></td>
    </tr>
    <tr>
<th>NAND_RESULT_OPENFD</th>
<td>The file descriptor has been left open. This code is returned when an attempt is made to delete a file that has not yet been closed. (The <CODE>NANDSimpleSafeClose[Async]</CODE> functions may potentially return this code because they perform delete operations internally).</td>
    </tr>
    <tr>
<th>NAND_RESULT_UNKNOWN</th>
<td>Unknown error. Represents an error unexpected by the Revolution SDK. Application operations cannot be guaranteed. When this code is returned, there is a high probability that there is some problem with the SDK.  Report the issue to Nintendo.</td>
    </tr>
    <tr>
<th>NAND_RESULT_FATAL_ERROR</th>
<td>The error code for problems resulting from flawed program design (for example, the library is not initialized, or the like).</td>
    </tr>
  </tbody>
</table>
<br>
<p>
Note 1: The <CODE>NAND_RESULT_AUTHENTICATION</CODE> error can also occur if the application programmer has made a coding mistake. If, during data writing by <CODE>NANDWrite[Async]</CODE>, the buffer specified by the argument is rewritten, the write process itself may succeed but a <CODE>NAND_RESULT_AUTHENTICATION</CODE> error might occur when <CODE>NANDRead[Async]</CODE> attempts to read the data. The same can happen when the specified buffer is rewritten while <CODE>NANDSimpleSafeOpen[Async]</CODE> is processing. When this is the case, <CODE>NANDSimpleSafeOpen[Async]</CODE> returns a <CODE>NAND_RESULT_AUTHENTICATION</CODE> error as its execution result.<br><br>Note 2: The <CODE>NAND_RESULT_MAXBLOCKS</CODE> and <CODE>NAND_RESULT_MAXFILES</CODE> error are not generated as long as the procedure described in section 8.9 Checking the Number of Free inodes and Amount of Free Memory Using <CODE>NANDCheck[Async]</CODE> Function in the <I>Wii Programming Guidelines</I> is followed. As long as the application adheres to NAND-related restrictions (for example, on home and <CODE>/tmp</CODE> directory usage), the appearance of these error codes suggests that a bug may exist in the application or system program. Note that if the implementation of <CODE>NANDCheck[Async]</CODE> is not carried out correctly, there is a risk that the system may not restart due to a <CODE>NAND_RESULT_MAXBLOCKS</CODE> or <CODE>NAND_RESULT_MAXFILES</CODE> error.
</p>

<p>
Of these, the following are result codes that might be returned by asynchronous function calls. Also, with the exception of certain asynchronous functions (<a href="./NANDSimpleSafeOpenAsync.html"><CODE>NANDSimpleSafeOpenAsync</CODE></a>, <a href="./NANDSimpleSafeCloseAsync.html"><CODE>NANDSimpleSafeCloseAsync</CODE></a>, <a href="./NANDSimpleSafeCancelAsync.html"><CODE>NANDSimpleSafeCancelAsync</CODE></a>), the specified callback function does not receive <CODE>NAND_RESULT_ALLOC_FAILED</CODE> or <CODE>NAND_RESULT_BUSY</CODE>.
<ul>
<li><CODE>NAND_RESULT_OK</CODE></li>
<li><CODE>NAND_RESULT_ACCESS</CODE></li>
<li><CODE>NAND_RESULT_ALLOC_FAILED</CODE></li>
<li><CODE>NAND_RESULT_BUSY</CODE></CODE></li>
<li><CODE>NAND_RESULT_INVALID</CODE></li>
<li><CODE>NAND_RESULT_FATAL_ERROR</CODE></li>
</ul>
</p>

<p>
<font color="#ff0000">Starting from SDK Version 2.3 (firmware Version 12.0.2), most synchronous NAND functions can return <CODE>NAND_RESULT_ALLOC_FAILED</CODE> and <CODE>NAND_RESULT_BUSY</CODE>. These result codes may be returned when a synchronous NAND API is called while the queue for receiving requests is full (for example, due to a succession of calls to asynchronous NAND functions over a short period of time).</font>
</p>

<h2>Result Code Handling</h2>
<p>
The following table indicates the guidelines for handling result codes. Also refer to the <a href="./sequence.html">NAND Processing Sequence</a> page.
</p>
<table class="arguments" border="1">
  <tr>
<td ROWSPAN="3"><B>A. Items that applications must support</B></td>
<th>NAND_RESULT_AUTHENTICATION</th>
  </tr>
  <tr>
<th>NAND_RESULT_CORRUPT</th>
  </tr>
  <tr>
<th>NAND_RESULT_ECC_CRIT</th>
  </tr>
  <tr>
<td ROWSPAN="5"><B>B. Items that applications must support for which a bug report to Nintendo is expected (if possible)</B></td>
<th>NAND_RESULT_ALLOC_FAILED</th>
  </tr>
  <tr>
<th>NAND_RESULT_BUSY</th>
  </tr>
  <tr>
<th>NAND_RESULT_MAXBLOCKS</th>
  </tr>
  <tr>
<th>NAND_RESULT_MAXFILES</th>
  </tr>
  <tr>
<th>NAND_RESULT_UNKNOWN</th>
  </tr>
  <tr>
<td ROWSPAN="9"><B>C. Must be removed during the development or hidden from the player</B></td>
<th>NAND_RESULT_ACCESS</th>
  </tr>
  <tr>
<th>NAND_RESULT_EXISTS</th>
  </tr>
  <tr>
<th>NAND_RESULT_INVALID</th>
  </tr>
  <tr>
<th>NAND_RESULT_MAXDEPTH</th>
  </tr>
  <tr>
<th>NAND_RESULT_MAXFD</th>
  </tr>
  <tr>
<th>NAND_RESULT_NOEXISTS</th>
  </tr>
  <tr>
<th>NAND_RESULT_NOTEMPTY</th>
  </tr>
  <tr>
<th>NAND_RESULT_OPENFD</th>
  </tr>
  <tr>
<th>NAND_RESULT_FATAL_ERROR</th>
  </tr>
</table>
<p>
Result codes that are classified as (A) are the codes that may be caused by issues such as wear to Wii console NAND memory. For <CODE>NAND_RESULT_AUTHENTICATION</CODE>, it might also be the case that the application programmer has made a coding mistake. <br>Result codes that are classified as (B) are the codes that should not appear as long as the Wii system is running normally. For <CODE>NAND_RESULT_MAXBLOCKS</CODE> and <CODE>NAND_RESULT_MAXFILES</CODE>, these do not occur as long as <CODE>NANDCheck[Async]</CODE> has been implemented correctly. When the correct implementation is achieved, there is no need to perform error handling. If result codes in this category appear, please send a bug report to Nintendo if possible, as there is a chance of a defect in either RevolutionSDK or the Wii console/Wii development console.<br>Result codes that are classified as (C) are the codes that mainly suggest coding errors by the application programmers.<br>
</p>

<h2>Notes</h2>
<h3>Precautions When Writing Data</h3>
<p>
The file system used to manage Wii console NAND memory has been designed to survive unexpected power shutdowns. There is no worry of the entire file system crashing even if the power shuts down in the middle of FAT update in the internal NAND memory. The system will instead restart from a FAT state immediately before the update. However, care must be taken regarding write timing. Assume that the following operations have been performed on a given file.
</p>
<ol>
<li><CODE>Open()</CODE>
<li><CODE>Read()</CODE>
<li><CODE>Write()</CODE>
<li><CODE>Write()</CODE>
<li><CODE>Write()</CODE>
<li><CODE>Close()</CODE>
</ol>
<p>
The <CODE>Write</CODE> function alone does not update the FAT in the built-in flash memory (the FAT in memory is updated). Therefore, even if the power is disconnected midway through the execution of the <CODE>Write</CODE> function, file content will start from the state in effect before the <CODE>Write</CODE> function was invoked. However, if an operation that involves updating the FAT in built-in flash memory occurs as an interrupt between instances of the <CODE>Write</CODE> function, the data written by the <CODE>Write</CODE> function up to that point will be applied to built-in flash memory. For example, if another thread or process executes the <CODE>Create</CODE> function immediately after the <CODE>Write</CODE> function on line three has finished executing, the FAT in built-in flash memory will be updated. If the power is disconnected immediately after this <CODE>Create</CODE> function has finished executing, only the data written by the <CODE>Write</CODE> function on line three will be applied to the file. Although this behavior may not pose a problem depending on the data structure recorded for the file, when any of the of <CODE>Write</CODE> invocations on lines three, four, or five are left out, problems will result if this causes data inconsistency.
</p>
<p>
One 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 <CODE>/tmp</CODE> and then perform all subsequent reads and writes on the file copied to <CODE>/tmp</CODE>. Finally, after the copied file is closed, the <CODE>Move</CODE> function can be used to overwrite the original file, thus avoiding the aforementioned data inconsistency. This algorithm is implemented by the <a href="./NANDSimpleSafeOpen.html"><CODE>NANDSimpleSafeOpen</CODE></a>, <a href="./NANDSimpleSafeOpenAsync.html"><CODE>NANDSimpleSafeOpenAsync</CODE></a>, <a href="./NANDSimpleSafeClose.html"><CODE>NANDSimpleSafeClose</CODE></a> and <a href="./NANDSimpleSafeCloseAsync.html"><CODE>NANDSimpleSafeCloseAsync</CODE></a> functions. The <CODE>safe</CODE> sample demo is provided to demonstrate the atomic nature of updating files using these functions.
</p>

<h3>NAND API Functions to Update the FAT in Wii Console NAND Memory</h3>
<p>
The following functions in the NAND API update the FAT in Wii console NAND memory. For details, see the manual page for each function.
</p>

<ul>
<li><a href="./NANDCreate.html">NANDCreate[Async]</a>
<li><a href="./NANDCreateDir.html">NANDCreateDir[Async]</a>
<li><a href="./NANDDelete.html">NANDDelete[Async]</a>
<li><a href="./NANDMove.html">NANDMove[Async]</a>
<li><a href="./NANDClose.html">NANDClose[Async]</a>
<li><a href="./NANDSimpleSafeOpen.html">NANDSimpleSafeOpen[Async]</a>
<li><a href="./NANDSimpleSafeClose.html">NANDSimpleSafeClose[Async]</a>
<li><a href="./NANDSimpleSafeCancel.html">NANDSimpleSafeCancel[Async]</a>
</ul>

<h3>About the NANDSimpleSafe Functions</h3>
<p>
If a <CODE>NANDSimpleSafe</CODE> function ends on an error, call <CODE>NANDSimpleSafeCancel[Async]</CODE>. These functions will try to release resources used by <CODE>NANDSimpleSafe</CODE>-type functions.
</p>
<p>
Although the <code>NANDSimpleSafeOpen[Async]</CODE> and <CODE>NANDSimpleSafeClose[Async]</code> functions guarantee the atomicity of file updates, to achieve it they incur a higher cost than the ordinary <code>NANDOpen[Async]</CODE> and <CODE>NANDClose[Async]</code> functions. When using these functions, note the following points.
<ul>
<li><font color="ff0000">The <CODE>NANDSimpleSafe</CODE> functions cannot simultaneously open multiple files that have the same filename.</font><CODE>NAND_RESULT_FATAL_ERROR</CODE> is returned. Careful attention is required when an application manages save files by creating a directory hierarchy such as <CODE>~/userA/save.dat</CODE> and <CODE>~/userB/save.dat</CODE>.
<li><font color="ff0000">There are restrictions on the size of the buffer needed for file copying. Be sure to specify a size that is a multiple of <code>NAND_FSBLOCK_SIZE</code> (16KB).</font>
<li>A buffer for copying files must be allocated.
<li>The <code>/tmp/sys</code> directory is created when <code>NANDSimpleSafeOpen[Async]</code> is executed for the first time.
<li>Because <code>NANDSimpleSafeOpen[Async]</code> copies the original files, the amount of time it takes and region under the <code>/tmp</code> directory that it consumes will vary corresponding to file size.
<li>When copying, the <code>NANDSimpleSafeOpen[Async]</code> function will use one inode in <code>/tmp</code> to create a copy of the original file under <code>/tmp/sys</code>. Furthermore, it generates one FAT update.
<li>When the <code>NANDSafeClose[Async]</code> functions are run, they perform two file closes and a file move (however, <code>/tmp/sys</code> is not removed once created). The function thus generates three FAT updates.
</ul>
</p>

<h3><a name="NAND RW NOTICE">Notes Regarding Wii Console NAND Memory Reading and Writing</a></h3>
<h4>Overview</h4>
<p>
With respect to the Revolution SDK firmware specifications, problems can occur when performing certain processes during Wii console NAND memory reading and writing. This section describes the conditions for and symptoms of these problems, and ways to handle the problems.
</p>

<h4>Occurrence Conditions and Symptoms</h4>
<p>
If, during the processing of <CODE>NANDRead[Async]</CODE> or <CODE>NANDWrite[Async]</CODE>, a certain function or combination of functions is called from a different thread, the processing of other functions may be delayed or even fail.(This can also occur with <code>CNTRead</code> or any other function that acts internally to generate read/write access to Wii console NAND memory.)
</p>

<p>These are the functions (and combinations of functions) to which this applies: (See note)</p>
<ul>
<li><code>CNTInit, DVDInit, HIDOpen[Async]</code></li>
<li>WD library functions</li>
<li>NCD library functions</li>
<li>NWC24 library functions</li>
<li><code>NETGetWirelessMacAddress</code></li>
<li><code>NETLockCrypto</code></li>
<li>RVL DWC (DL)  library functions</li>
</ul>

<p>
Note: This may also apply to other functions included in private packages. Inquire for details.
</p>

<p>
When the processing of <CODE>NANDRead[Async]</CODE> and <CODE>NANDWrite[Async]</CODE> overlaps with any of these functions, the processing load on the firmware can increase. The following reported cases are representative of how this can affect other functions.
</p>

<ul>
<li><CODE>KPADRead</CODE> and <CODE>KPADReadEx</CODE> return 0 for a period of time, indicating that data could not be obtained.
<li>Despite this condition, the callback function registered by <CODE>OSSetPowerCallback</CODE> and <CODE>OSSetResetCallback</CODE> is not called.</li>
</ul>

<p>
In addition to these, there might also be other functions that do not operate normally. It is unknown which functions will be affected in which ways.
</p>

<h4>Workaround</h4>
<p>
Avoid using <CODE>NANDRead[Async]</CODE> and <CODE>NANDWrite[Async]</CODE> at the same time as the above-mentioned functions. If it proves difficult to avoid large-sized reads and writes, divide the tasks by making multiple calls to <CODE>NANDRead[Async]</CODE> and <CODE>NANDWrite[Async]</CODE>. Make calls to the above-mentioned functions during the time between the end of <CODE>NANDRead[Async]</CODE> and <CODE>NANDWrite[Async]</CODE> and the next call. Wait for the processing of these other functions to end before making calls to <CODE>NANDRead[Async]</CODE> and <CODE>NANDWrite[Async]</CODE>.
</p>

<h3>Allowable Characters in File and Directory Names</h3>
<p>
The 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>.
</p>

<h3>Buffer Alignment</h3>
<p>
The buffers used for reading and writing data and the buffers used for getting directory lists must be 32-byte aligned. Furthermore, the buffer for data read/directory list retrieval must be a multiple of 32 bytes.
</p>
<p>
<font color="#ff0000">Performance is slightly enhanced by using 64-byte alignment for the buffer used to read/write data.</font>
</p>

<h3>File/Directory Properties</h3>
<p>
You can set properties for files/directories. However, as of 2006/06/16, 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.
</p>

<h3>Prohibition on Frequent Read Access</h3>
<p>
As a characteristic of NAND flash devices, <font color="#ff0000">if read access is repeated frequently several hundred thousand times or more on a given region without performing an erase or write operation, data may become corrupted in the periphery of that region.</font>If it is necessary to read data saved in Wii console NAND memory repeatedly, first load a sizeable chunk of data in MEM1 or MEM2, and then read data from MEM1 or MEM2 to reduce the number of read access operations on Wii console NAND memory.<br>For example, the following types of Read access are prohibited.
<ul>
<li>Performing a Read access to Wii console NAND memory every time data for a single character of a font is required
<li>Periodically performing a Read access to Wii console NAND memory at an interval of every frame or every second
<li>Performing Read access to Wii console NAND memory every time a character moves
</ul>
</p>

<h3>Wear on Wii Console NAND Memory</h3>
<p>
Write operations will wear out Wii console NAND memory, so please avoid frequent writing. (Use as virtual memory is prohibited.) When performing auto-save, please limit its average frequency to less than once per minute. When saves are automatically performed using <CODE>NANDSimpleSafe</CODE>-related functions, the process of opening and closing files causes the FAT to be updated four times. Therefore, to avoid wear and tear on the FAT, you need to increase the interval between automatic saves (to less than once every four minutes on average).

<h3>Fluctuations in Access Time</h3>
<p>
Due 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.
</p>

<h3>Reset/Shutdown Processes</h3>
<p>
We recommend not calling the reset/shutdown functions until all Wii console NAND memory operations issued by the application program are completed.<br>The reset/shutdown functions will execute without waiting for the NAND functions issued by the application to end. The file system managing Wii console NAND memory will guarantee the integrity of the entire file system against accidents such as power outages which may occur at any time, but will not guarantee integrity of the data that was in the middle of a write operation. Also refer to <a href="../os/Reset/intro.html">Reset Function/Shutdown Function</a> regarding reset/shutdown operations.
</p>

<h3>Regarding Data Tampering</h3>
<p>
The file system managing Wii console NAND memory is strong by design against data tampering or prying. In general, there is no need to implement any tampering protection for save data saved to Wii console NAND memory from the application side. However, security is not guaranteed for the future, so data tampering processing can also be implemented by the application in order to ensure better security.
</p>

<h3>Periodic Access from the System</h3>
<p>
<font color="ff0000">Starting with SDK 2.1 patch 1 (2006/08/30), the system now periodically accesses Wii console NAND memory. </font>There will be a file write once per minute, and a file open/close once every five minutes (FAT will also be updated at the close). For this reason, a single file descriptor will always be consumed. Also, when the timing of an access by the system and an access by the application happen to overlap, it may take longer than normal for the process to complete.
</p>

<h2>Limitations on Use</h2>
<p>
The following restrictions apply regarding the use of Wii console NAND memory. Note that the files and/or directories created under <code>/tmp/sys</code> will also be subject to these restrictions. If the application is using <CODE>NANDSimpleSafe</CODE>-type functions to update 1 MB save files, then the upper limit on the capacity of files that can be freely created in <CODE>/tmp</CODE> by the application is 39 MB less than it would be otherwise.
<table border="1" width="95%">
  <tbody>
    <tr>
<td bgcolor="#C0C0C0">Coverage</td>
<td bgcolor="#C0C0C0">Upper Limit</td>
    </tr>
    <tr>
<td>Maximum capacity of files that can be created in the home directory</td>
<td>16 MB</td>
    </tr>
    <tr>
<td>Number of files/directories that can be created in the home directory</td>
      <td>32</td>
    </tr>
    <tr>
<td>Maximum capacity of files that can be created in <code>/tmp</code></td>
<td>40 MB</td>
    </tr>
    <tr>
<td>Number of files/directories that can be created in <code>/tmp</code></td>
      <td>64</td>
    </tr>
  </tbody>
</table>
</p>

<H2>Revision History</H2>
<p>
2009/12/02 Added notes regarding Wii console NAND memory reading and writing.<br>2009/11/02 Explained <CODE>NAND_RESULT_AUTHENTICATION</CODE>.<br>2009/10/13 Added links to the <CODE>Ncheck</CODE> tool and the <I>Save Data Specifications</I>.<br>2009/07/17 Deleted text about the <CODE>NANDSafe</CODE> functions because they are no longer public functions.<br>2009/02/03 Added a description of <CODE>NAND_RESULT_MAXBLOCKS</CODE> and <CODE>NAND_RESULT_MAXFILES</CODE> to Result Code Handling.<br>2009/02/02 Revised the descriptions of <CODE>NAND_RESULT_MAXBLOCKS</CODE>, <CODE>NAND_RESULT_MAXFILES</CODE>, <CODE>NAND_RESULT_ALLOC_FAILED</CODE> and <CODE>NAND_RESULT_BUSY</CODE> in Result Code Handling.<br>2008/10/29 Made revisions and additions to the descriptions of <CODE>NAND_RESULT_MAXBLOCKS</CODE>, <CODE>NAND_RESULT_MAXFD</CODE>, <CODE>NAND_RESULT_MAXFILES</CODE> and <CODE>NAND_RESULT_UNKNOWN</CODE><br>2008/09/26 Added an explanation about WiiWare title-id(Hi).<br>2008/08/28 Revised the descriptions of <I>title-id(Hi)</I> and <I>title-id(Low)</I>.<br>2008/08/01 Revised the functions in the NAND API for updating the FAT in Wii console NAND memory. Revised the description regarding data tampering.<br>2008/07/29 Added text about result codes.<br>2008/05/16 Deleted explanations for the CARD library.<br>2008/05/13 Added NAND API functions to update the FAT in Wii console NAND memory.<br>2008/05/13 Added explanations for <I>title-id(Hi)</I> and <I>title-id(Low)</I>.<br>2007/05/ E Added guidelines for handling result codes.<br>2007/05/ M Added a simple explanation concerning group permissions.<br>2007/05/ M Added a note about the frequency of <CODE>NANDSimpleSafe</CODE>-type function calls.<br>2007/05/09 Added a note stating that callback functions are not invoked when an asynchronous function call exits with an error.<br>2007/05/09 Added descriptions for <CODE>NANDSimpleSafe</CODE>-type functions. Added a note recommending against the use of <CODE>NANDSafe</CODE>-type functions.<br>2007/02/xx Added the <CODE>NAND_RESULT_MAXDEPTH</CODE> result code.<br>2007/02/xx Added a supplementary note about the <CODE>NAND_RESULT_OPENFD</CODE> result code.<br>2006/12/18 Added a description of the prohibition on frequent Read access.<br>2006/11/30 Added text about result codes.<br>2006/11/30 Added text noting that many synchronous functions can return <CODE>NAND_RESULT_ALLOC_FAILED</CODE> and <CODE>NAND_RESULT_BUSY</CODE>.<br>2006/11/30 Deleted text about <CODE>NANDGetAvailableArea[Async]</CODE> as an alternative to <CODE>NANDCheck[Async]</CODE>.<br>2006/11/10 Added supplemental information about banner files and <CODE>NANDCheck[Async]</CODE>.<br>2006/10/25 Added an explanation of <CODE>NANDGetAvailableArea[Async]</CODE>.<br>2006/10/25 Standardized the terminology.<br>2006/10/25 Added information regarding periodic access from the system.<br>2006/09/28 Explained the implementation details regarding <CODE>NANDSafe</CODE>-type functions. Clarified the limitations on use.<br>2006/09/25 Specified the home directory location.<br>2006/09/19 Added details regarding the result codes that the <CODE>NANDSafeOpenAsync</CODE> and <CODE>NANDSafeCloseAsync</CODE> function callbacks may receive.<br>2006/09/19 Added information about banner files.<br>2006/08/30 Added a note that <CODE>NANDInit</CODE> is now automatically called by the system.<br>2006/08/30 Added information regarding <CODE>NANDCheck</CODE>.<br>2006/08/30 Fixed spelling errors in the result code.<br>2006/08/15 Revised the table of limitations on use.<br>2006/08/15 Added a description of the <CODE>NANDSafe</CODE>-type functions.<br>2006/08/15 Described the maximum allowable depth of the directory hierarchy.<br>2006/08/15 Deleted the <CODE>NAND_RESULT_INIT_FAILED</CODE> result code.<br>2006/08/15 Added description of characters allowed in file/directory names.<br>2006/08/15 Revised the description of <CODE>/tmp/sys</CODE>.<br>2006/08/15 Revised description of maximum path length.<br>2006/08/15 Added precautions regarding writing data.<br>2006/08/15 Added a description of the <CODE>NAND_RESULT_AUTHENTICATION</CODE> result code.<br>2006/06/16 Initial version.<br>
</p>


<hr><p>CONFIDENTIAL</p></body>
</html>