VF API Description

Introduction

The VF library constructs a virtual file system in a specified region.

The VF library has the following characteristics:

Similar architecture to a UNIX file system
Hierarchical file system
Both "/" and "¥" can be used as path delimiters
Although the number of drives mounted simultaneously will depend on the number of files that can be opened with the particular device, only 26 drives can be mounted simultaneously
A maximum of five files can simultaneously be manipulated on each drive
The update time, etc. is retrieved from the RTC (OSGetTime())
For the vff file, specify a size of 20 KB or larger
Searching file names or directory names is case-insensitive
However, drive names are case-sensitive
Functions that specify paths, such as VFOpenFile(), consume stack space of about 3 KB

To learn how to use the VF library, see ./build/demos/vfdemo/.
Sample demo programs for NAND drives are provided.
Functions declarations are in the ./include/revolution/vf.h header file.

Process Flow

After the necessary device initialization, initialize the VF library by calling VFInit.
VFFinalize must be called when finished.

(drive) mount
?
file operations
?
(drive) unmount

Handling Error Codes

Performing operations on a drive mounted in the VF library is the same as directly reading and writing to the vff file that was used for mounting the drive.
If the VF library returns the VF_ERR_EIO error, it means there has been a failure in reading or writing to the vff file, and more specifically, that the process has failed because of an error by a device function. If this error is returned, call the VFGetLastDeviceError function to get the specific device library error and then perform the same error-handling procedure in the guideline that you would follow if a direct call to the device function failed. Below is a list of drive types and their corresponding device-control libraries.

Drive type	Device functions used inside the VF library.
Drive type	VFCreateSystemFile*	VFMount, VFUnmount	All other file system operations
NANDFlash	NANDCreate	NANDOpen, NANDClose	NANDRead, NANDWrite
DVD	(None)	DVDOpen, DVDClose	DVDRead
RAM	(None)	(None)	(None)

Note: 'None' is written to indicate there is no device access; thus, an VF_ERR_EIO error will not be generated.

All other errors besides VF_ERR_EIO indicate errors due to a processing failure by the VF library itself, so you will need to review the VFErr function reference and take the appropriate response.

Revision History

2006/06/01      Fixed a bug that caused an infinite loop when using VFDeleteFile(W).
2006/06/09      Added an argument to VFReadFile to get the size of the loaded file.
2006/06/16      Because there was a bug when the file system type was set to FAT32,
 reverted to the original format in which the FAT type is automatically set according to the volume size.
2006/06/27      Revised code when NAND is used. Every time VFWriteFile() is called, it flushes.
 Eliminated the alignment restriction for buffers passed by VFWriteFile() and VFReadFile( ).
2006/07/14      Added VFMove{File, Dir}(W) and VFRename{File, Dir}(W).
2006/08/09      Added VFCutFileSize(W).
2006/08/24      Added VFFormatDrive(W).
(From now on, after mounting a vff file for the first time, please format it. See the demo for criteria.)
2006/09/12      Added VFInitEx() and VFFinalize().
2006/09/13      Added VFIsAvailable().
2006/09/14      Fixed a bug that prevented mounting after mounting and unmounting 31 times, using a different drive name.
2006/09/15      Fixed a critical section bug.
2006/09/21      Fixed a bug related to the log name.
 Fixed the problem when attaching (mounting) with the same drive name twice.
 (An error is now returned VFErr.)
2006/09/26      Increased the speed of VFFormatDrive() when mounting NAND.
 Added VFSync and VFFileSync.
2006/09/27      Changed code so that the cache can be set when mounting.
 VFMountDrive, VFAttachDrive
2006/09/29      Corrected the VF_ERR_ENOEXEC that was returned when there was no space on the drive during VFWriteFile to VF_ERR_ENOSPC.
 Added VFBuffering (default is VF_WRITE_BACK_ON_SIGNIF_API).
2006/10/02      Corrected problems with various APIs when handling drive names.
 Included a caution regarding the use of uppercase and lowercase in drive names in the Introduction.
2006/10/11      Changed behavior so that VF_ERR_VFF_FILE_FORMAT is returned when an illegal file is specified during mount.
 When the above error is detected, create the .vff file again after deleting it.
2006/10/12      Corrected such that VF_ERR_NOT_ALLOCATED_DRV is returned if activate is called before attach succeeds.

2006/10/13      Added VFDeleteSystemFileNANDFlash.
2006/10/17      Fixed a bug that prevented errors in VFGetFileSizeByFd( ), VFGetOffsetByFd( ), and VFGetDriveFreeSizeW( ) from being reflected in VFGetLastError( ).
                
2006/10/18      Corrected a problem that prevented -1 from being returned when an internal error occurred with the 2006/10/17 version of VFGetFileSizeByFd( ).

2006/10/25      Added NANDCheck to the sample demos.
2006/10/27      Added the VF_DTA_GET_FILE_SECONDS(vta) macro to get the file update time from the file search information (VFDta).
2006/10/30      Added a caution regarding stacks in the Introduction and Notes.
2006/11/09      Added VFUnmountDriveForce to unmount a drive even if a file is open.
 Added VFInactivateDriveForce to invalidate a drive even if a file is open.
2006/11/14      Added detailed description to the VFErr document.
2007/04/27      Added VFSetTimeStampCallback.
2007/05/08      Revisions to the Manuals. Added the VFGetApiErrorString manual.
2007/06/26      Fixed region corruption that occurred when the same drive was repeatedly mounted and unmounted.
2007/09/10      Added a note about VF_ERR_EIO.
2007/10/11      Added the Introduction.

Notes

If the error returned by a VF function is VF_ERR_EIO, use the VFGetLastDeviceError function to get the value of the device error and then perform processing that complies with the guidelines for that device.
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 written/read must also be a multiple of 32 bytes.
The above restriction has been eliminated. Please be aware, though, that the 32 byte alignment restriction remains for .vff files. (2006/06/23)
Please do not include hidden characters in the path string passed to the API.
Executing VFCreateFile() or VFOpenFile() in directories that contain many files consumes processing time.
To improve the processing time, set the cache to match the maximum number of files allowed to exist.
After mounting a vff file for the first time, be sure to format it with VFFormatDrive().
Uppercase and lowercase are not differentiated when searching file names or directory names.
However, uppercase and lowercase are strictly differentiated for drive names.
Changed so that VF_ERR_VFF_FILE_FORMAT is returned when an illegal file is specified during mount. When the above error is detected, create the .vff file again after deleting it.
Run NANDCheck within the application when creating files in NAND memory.
Functions that specify paths, such as VFOpenFile(), consume stack space of about 3 KB.

CONFIDENTIAL