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, among other items, 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. Return of the VF_ERR_EIO error by the VF library means that reading or writing to the VFF file has failed; more specifically, 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. For a list of mountable drive types and their corresponding device control libraries, see below.

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 that there is no device access; thus, no VF_ERR_EIO errors can be generated.

All errors other than VF_ERR_EIO indicate processing failure by the VF library itself. For these errors, you must consult 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 preceding error is detected, create the .vff file again after deleting it.
2006/10/12      Revised to return VF_ERR_NOT_ALLOCATED_DRV before attach is successful, and when activate is called. 
                
2006/10/13      Added VFDeleteSystemFileNANDFlash.
2006/10/17      Fixed a bug where errors of the VFGetFileSizeByFd, VFGetOffsetByFd, and VFGetDriveFreeSizeW functions were not reflected in the VFGetLastError function.  
                               
2006/10/18      Corrected a problem that prevented -1 from being returned when an internal error occurred with the 2006/10/17 version of the VFGetFileSizeByFd function.
                
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 preceding 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