File System Overview

Introduction

FS supports a series of standard file systems. Also, it provides new features in file directory operations necessary for application development in general. Specifically, the following new features should be provided:

Refer to the header file fs.h in include directory for more information on the FS specification.

Cafe FS Characteristics

Every function that needs to access each volume has the following 2 types of arguments:

The format of asynchronous functions that can return values must match that of synchronous functions. As with synchronous functions, pointer values passed to the arguments should be saved.

Also, the system automatically mounts each volume on the disc, system save memory, and USB storage. However, removable devices, such as SD cards, and HFIO devices for development should be mounted manually. To mount manually, first use FSGetMountSource to obtain mountable devices and path information. Next, use FSMount to mount the obtained information to the target path.

Auto Error Handling

Auto error handling can help minimize the number of errors that need to be handled in the application code and reduce developers' burden. The following 2 types of auto error handling should be available.
However, the media state handling is not available for manually mounting devices, such as an SD card.

In case of auto error handling due to a device abnormality error or FATAL error, the volume state will change. The volume state change can be detected by 3 methods: a callback function, a message, and polling. Using these methods, at the time of auto error handling the application can perform any given processing. For more information on volume states, see FSVolumeState.

fs volume state transitions

Fig.1 Volume State Transition

Auto error handling usage examples are explained next. Assume an FS thread and a graphic display thread are running. The graphic display thread polls a volume state change. The polling of volume states requires state information which is stored in the FS client. If auto error handling occurs, the graphics display thread will detect a volume state change and automatically display an error dialog box on the screen containing the encountered error. For detailed auto error handling usage examples, refer to the FS demos.

WARNING:
Synchronous FS functions may block indefinitely if the volume state is changed by a user operation, such as a disc eject, or by a fatal error caused by a programming error. An application must be able to display graphics or handle system messages without waiting for blocked FS function returns, so as to display an error message for FS error and handle the system events such as process switching or shutdown.

Error Handling Flag

Most functions take an "error handling flag" as an argument. For some types of errors, the application can toggle the FS layer's behavior to either "internally handle it as fatal" or "return status code without auto handling". Typically, the application specifies error types that are expected to happen or that the application wants to handle manually. For more information, see FSRetFlag.

Media Detachment

When each media is detached while the application is running, the auto error processing handles each case as follows:

NOTE:
Abnormality of auto-mounted devices are notified with a latency of approximately 1 second. This is due to an internal timer required to determine the media state correctly.

Infinite Command Queue

Almost all FS functions have a command block argument. Infinite command queues are implemented for a function which uses this command block to create an FS queue.

The top pointer of a queue is managed per FS client. Therefore, functions invoked for the same client should always be processed in the order of invocation. As long as it is going through the same client even when the target device is different, the processing starts after the previous one is completed. To access multiple devices in parallel, clients should be separated by device.

You can cancel a function before processing by specifying a client and/or command block.

You can also set a priority to each command block. Priority is used to sort commands in the waiting queue of each FSClient. Large file read/write command will be automatically paused when a command with higher priority is queued to the same client.

command queue

Fig.2 Queue per FS Client

Demos

A set of demo programs can be found here.

Revision History

2014/09/16 Added warning about calling synchronous FS functions.
2013/12/11 Modified "Auto Error Handling" to clarify when error is detected automatically and the device reinsertion is needed to be recovered from media error state.
2013/06/11 Added precaution at SD Card detachment in "Media Detachment".
2013/05/13 Added information about SD Card detachment in "Media Detachment".
2013/05/08 Automated cleanup pass.
2013/05/07 Fixed "Fig.1 Volume State Transition".
2013/04/15 Added note about auto error handling.
2012/11/20 Replaced "FAT32" to "FAT".
2012/09/10 Added descriptions about media detachment.
2012/07/31 Added descriptions about command priority.
2012/07/27 Removed information about FSA.
2012/07/18 Readability cleanup.
2012/05/18 Revised descriptions in Auto Error Handling. Added link to FSRetFlag.
2011/12/13 Initial version.


CONFIDENTIAL