NAND API Introduction

Introduction

The NAND library provides an API to access the NAND flash memory built into the Revolution console. NAND flash memory has the following characteristics.

• Nonvolatile memory.
• Fast read, but slightly slow write.
• Random access.
• Concept of bit error.
• Concept of bad blocks.
• Concept of wear and tear because of writing.

The 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.

The NAND library provides a file system with the following characteristics.

• Similar architecture to the UNIX file system.
• Hierarchical file system.
• Access control with three permission levels (Owner/Group/Other).
• Single-bit error correction is done in the file system.
• Bad block processing is done in the file system.
• 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.)
• Up to twelve characters for the file name/directory name
• Supports both absolute path specification and relative path specification.
• Path delimiter text character is "/."
• The maximum path length is 64 characters (including the NULL character).
• A directory structure up to eight levels deep can be created.
• File block size is 16 KB.
• Maximum number of files/directories to be created is approximately 6000.

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

Process Flow

First call the NANDInit function to initialize the NAND library and then start using NAND API functions.

Directory Structure

Although 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:

Path	Description
/title/<title-id(Hi)>/<title-id(Low)>/data	This directory is automatically provided by the system. Save application save data, etc., in this directory.
/tmp	Temporary directory. Files and directories stored under this directory are deleted when the system starts up.
/tmp/sys	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.

Application Save Data

Use 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.

When 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.

Synchronous and Asynchronous Functions

NAND 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 Async.

inode

File 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 NANDFreeBlocks function or the NANDFreeBlocksAsync function.

Result Code List

Of 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 NAND_RESULT_ALLOC_FAILEDor NAND_RESULT_BUSY.

• NAND_RESULT_OK
• NAND_RESULT_ACCESS
• NAND_RESULT_ALLOC_FAILED
• NAND_RESULT_BUSY
• NAND_RESULT_INVALID
• NAND_RESULT_FATAL

Notes

Precautions when Writing Data

The 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.

1. Open()
2. Read()
3. Write()
4. Write()
5. Write()
6. Close()

Write() 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.

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 /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.

Disadvantages of NANDSafe Functions

Although NANDSafeOpen[Async] and NANDSafeClose[Async] guarantee the atomicity of file updates, they incur a higher cost than the ordinary NANDOpen[Async] and NANDClose[Async] in order to achieve it. Note the following when using these functions.

• A buffer for copying files must be allocated.
• The directory /tmp/sys is created when NANDSafeOpen[Async] is executed for the first time.
• Because NANDSafeOpen[Async] internally copies original files below /tmp/sys, it consumes time and storage space under /tmp in accordance with file size.
• NANDSafeOpen[Async] consumes two i-nodes in order to create files and directories when copying. Furthermore, it generates two FAT updates.
• When NANDSafeClose[Async] executes, it generates two file closes, a file move, and deletes a created directory. (However, /tmp/sys is not removed once created.) The function therefore generates four FAT updates.

Allowable Characters in File and Directory Names

The characters that can be used in file and directory names are limited to the alphanumeric characters [0-9a-zA-Z] and a few symbols [-_.].

Buffer Alignment

The 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.

Performance is slightly enhanced by using 64-byte alignment for the buffer used to read/write data.

File/Directory Properties

You 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.

Internal Flash Memory Wear

Writing 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.

Fluctuations in Access Time

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.

Limitations on Use

The 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.

Coverage	Upper Limit
Maximum file storage capacity of the home directory	16 MB
Number of files/directories that can be created in the home directory	32
Maximum storage capacity of file that can be created in /tmp	40 MB
Number of files/directories that can be created in /tmp	64

Revision History

06/16/2006 Initial version.
8/15/2006 Added a description of the NAND_RESULT_AUTHENTICATION result code.
8/15/2006 Added precautions regarding writing data.
8/15/2006 Revised description of maximum path length.
8/15/2006 Revised description of /tmp/sys.
8/15/2006 Added description of characters allowed in file/directory names.
8/15/2006 Deleted the NAND_RESULT_INIT_FAILED result code.
8/15/2006 Described the maximum allowable depth of the directory hierarchy.
8/15/2006 Added a description of the NANDSafe line of functions.
8/15/2006 Revised the table on operational limitations.

CONFIDENTIAL