File System: Programming Tips

Debug Tips

How to Know the Reason When the Volume State Changed to FATAL

On the FS layer, when an unexpected error occurs, the volume state changes to FATAL state without completing the command (see Auto Error Handling). If the application uses APIs for Error Viewer (FSGetErrorCodeForViewer and FSGetLastErrorCodeForViewer), the error code 150-3XXX indicates the transition to the FATAL state. Especially, the code 150-303X is usually due to the application's implementation.

If the FS layer showed a fatal error, which is typically noticed because 150-303X is displayed, you can get the detailed error code in FSError type by either of following ways:

FS leaves the error code in the log when transitioning to FATAL state in following format:

Updated volume state of client 0xXXXXXXXX to FS_VOLSTATE_FATAL(10)
by error -1966XX

-1966XX is the error code. Refer FSError to see the description of the value.

Besides implementation errors, 150-303X error may also happen when the application attempted to create save data while the save data size was set to 0 (default value) by Application Configuration Tool.

Read/Write Performance Tips

Access to Different Devices

On the FS layer, commands are serialized on a FSClient structure basis. It is recommended to use a separate FSClient for each command which may access a different device.

Access to the Same Device/Volume

It is recommended to use the same FSClient structure when only a single device is being accessed. The reasons for this are as follows:

Behind the 2nd and 3rd reasons, Read/Write commands may be automatically divided into appropriate sizes within FS and then be processed sequentially. This is to support command cancellation in the middle of a read and to reduce the overhead associated with process switching. Because of this spec, if a Read/Write command for a different file in the same volume is registered into a separate FSClient structure queue at the same time, performance may degrade significantly. Because each command is internally divided and executed without synchronizing, switching to access a different request will frequently occur in the middle of processing. In such a situation, cache misses may increase and/or the specified address will be sought frequently, which should lead to performance degradation. This tendency is noticeable during accessing the optical disc.

Recommended Settings

Based on the above, the recommended simple usage policy for the FSClient structure is as follows:



Media error occurs after not coming back from an FS API for several tens of seconds.


When storage is experiencing a problem or not connected properly, it may take several tens of seconds to detect an error.

Revision History

2013-07-09 Added debug tips.
2013-05-08 Automated cleanup pass.
2013-03-15 Added troubleshooting.
2012-07-19 Readability cleanup.
2012-05-18 Initial version.