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.
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
To mount manually, first use
FSGetMountSource to obtain mountable devices and path information.
FSMount to mount the obtained information to the target path.
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.
There are 2 methods to mount a device; which one to use is determined by the file system to which the device
is formatted. A device which supports auto mounting should be mounted by the system automatically.
Also, media state of device that supports auto mounting is handled automatically. If a user calls the function to access the device and results in an error due to the device abnormality (e.g. disc ejection) is detected,
such an error will be handled automatically. It locks processing automatically within the function and then, waits for the device abnormality to be resolved by reattaching the device. If the same device is recognized properly again, the function processing will be unlocked and be retried. After function processing is completed, application processing can continue.
However, any of the media errors that cannot return to the application should be handled as a FATAL error without waiting for a resolution. For more information, see "Fig.1 Volume State Transition".
Conversely, a device that supports manual mounting (currently, FAT format only) must be manually mounted at first. Auto media state handling is disabled; therefore, device abnormality error must be handled within the developer's code.
An unspecified error is automatically handled as a FATAL error unexpected by the developer. If a FATAL error occurs, processing will be locked within the function and never return. The number of errors that need to be handled within the code can be minimized.
For some types of errors, applications can prevent the FS layer from handling it as fatal so that application can handle it manually. For information, see the Error Handling Flag section.
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
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.
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
When each media is detached while the application is running, the auto error processing handles each case as follows:
FSUnmountmust be called.
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.
Fig.2 Queue per FS Client
A set of demo programs can be found here.
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
2011/12/13 Initial version.