1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> 4<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css"> 5<base target="main"> 6<title>VF API Introduction</title> 7</head> 8 9<body> 10 11<h1>VF API Description</h1> 12 13<h2>Introduction</h2> 14<p> 15The VF library constructs a virtual file system in a specified region.<BR><BR>The VF library has the following characteristics: 16<ul> 17<li>Similar architecture to a UNIX file system 18<li>Hierarchical file system 19<li>Both "/" and "¥" can be used as path delimiters 20<li>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 21<li>A maximum of five files can simultaneously be manipulated on each drive 22<li>The update time, etc. is retrieved from the RTC (<CODE>OSGetTime()</CODE>) 23<li>For the vff file, specify a size of 20 KB or larger 24<li>Searching file names or directory names is case-insensitive<br>However, drive names are case-sensitive 25<li>Functions that specify paths, such as <CODE>VFOpenFile()</CODE>, consume stack space of about 3 KB 26</ul> 27</p> 28 29<p> 30To learn how to use the VF library, see <code>./build/demos/vfdemo/</code>.<br>Sample demo programs for NAND drives are provided.<BR>Functions declarations are in the <code>./include/revolution/vf.h</code> header file. 31</p> 32 33<h2>Process Flow</h2> 34<p> 35After the necessary device initialization, initialize the VF library by calling <CODE><a href="./VFInit.html">VFInit</a></CODE>.<br><CODE>VFFinalize</CODE> must be called when finished.<br><br>(drive) mount<BR> ?<BR>file operations<BR> ?<BR>(drive) unmount<BR> 36</p> 37 38<h2>Handling Error Codes</h2> 39<p> 40Performing operations on a drive mounted in the VF library is the same as directly reading and writing to the <CODE>vff</CODE> file that was used for mounting the drive.<BR>If the VF library returns the <CODE>VF_ERR_EIO</CODE> error, it means there has been a failure in reading or writing to the <CODE>vff</CODE> file, and more specifically, that the process has failed because of an error by a device function. If this error is returned, call the <a href="VFGetLastDeviceError.html">VFGetLastDeviceError</a> 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. 41</p> 42<table style="border:solid 1px Black"> 43<tr><td rowspan="2" style="background-color:#F0F0FF">Drive type</td><td colspan="3" align="center" style="background-color:#F0F0FF">Device functions used inside the VF library.</td></tr> 44<tr><td style="background-color:#F0F0FF">VFCreateSystemFile*</td><td style="background-color:#F0F0FF">VFMount*, VFUnmount*</td><td style="background-color:#F0F0FF">All other file system operations</td></tr> 45<tr><td style="background-color:#FFF0F0">NANDFlash</td><td style="background-color:#FFFFF0">NANDCreate</td><td style="background-color:#FFFFF0">NANDOpen, NANDClose</td><td style="background-color:#FFFFF0">NANDRead, NANDWrite</td></tr> 46<tr><td style="background-color:#FFF0F0">DVD</td><td style="background-color:#C0C0C0">(None)</td><td style="background-color:#FFFFF0">DVDOpen, DVDClose</td><td style="background-color:#FFFFF0">DVDRead</td></tr> 47<tr><td style="background-color:#FFF0F0">RAM</td><td style="background-color:#C0C0C0">(None)</td><td style="background-color:#C0C0C0">(None)</td><td style="background-color:#C0C0C0">(None)</td></tr> 48</table> 49<p> 50<B>Note:</B> 'None' is written to indicate there is no device access; thus, an VF_ERR_EIO error will not be generated. 51</p> 52All other errors besides <CODE>VF_ERR_EIO</CODE> indicate errors due to a processing failure by the VF library itself, so you will need to review the <a href="VFErr.html">VFErr</a> function reference and take the appropriate response. 53</p> 54 55<h2>Revision History</h2> 56<pre> 572006/06/01 Fixed a bug that caused an infinite loop when using <CODE>VFDeleteFile(W)</CODE>. 582006/06/09 Added an argument to <CODE>VFReadFile</CODE> to get the size of the loaded file. 592006/06/16 Because there was a bug when the file system type was set to FAT32, 60 reverted to the original format in which the FAT type is automatically set according to the volume size. 612006/06/27 Revised code when NAND is used. Every time <CODE>VFWriteFile()</CODE> is called, it flushes. 62 Eliminated the alignment restriction for buffers passed by <CODE>VFWriteFile()</CODE> and <CODE>VFReadFile( )</CODE>. 632006/07/14 Added <CODE>VFMove{File, Dir}(W)</CODE> and <CODE>VFRename{File, Dir}(W)</CODE>. 642006/08/09 Added <CODE>VFCutFileSize(W)</CODE>. 652006/08/24 Added <CODE>VFFormatDrive(W)</CODE>. 66(From now on, after mounting a vff file for the first time, please format it. See the demo for criteria.) 672006/09/12 Added <CODE>VFInitEx()</CODE> and <CODE>VFFinalize()</CODE>. 682006/09/13 Added <CODE>VFIsAvailable()</CODE>. 692006/09/14 Fixed a bug that prevented mounting after mounting and unmounting 31 times, using a different drive name. 702006/09/15 Fixed a critical section bug. 712006/09/21 Fixed a bug related to the log name. 72 Fixed the problem when attaching (mounting) with the same drive name twice. 73 (An error is now returned <code><a href="./VFErr.html">VFErr</a></code>.) 742006/09/26 Increased the speed of <CODE>VFFormatDrive()</CODE> when mounting NAND. 75 Added <code><a href="./VFSync.html">VFSync</a></code> and <code><a href="./VFFileSync.html">VFFileSync</a></code>. 762006/09/27 Changed code so that the cache can be set when mounting. 77 <code><a href="./VFMountDrive.html">VFMountDrive</a></code>, <code><a href="./VFAttachDrive.html">VFAttachDrive</a></code> 782006/09/29 Corrected the <CODE>VF_ERR_ENOEXEC</CODE> that was returned when there was no space on the drive during <CODE>VFWriteFile</CODE> to <CODE>VF_ERR_ENOSPC</CODE>. 79 Added <code><a href="./VFBuffering.html">VFBuffering</a></code> (default is <CODE>VF_WRITE_BACK_ON_SIGNIF_API</CODE>). 802006/10/02 Corrected problems with various APIs when handling drive names. 81 Included a caution regarding the use of uppercase and lowercase in drive names in the Introduction. 822006/10/11 Changed behavior so that <CODE>VF_ERR_VFF_FILE_FORMAT</CODE> is returned when an illegal file is specified during mount. 83 When the above error is detected, create the .vff file again after deleting it. 842006/10/12 Corrected such that <CODE>VF_ERR_NOT_ALLOCATED_DRV</CODE> is returned if <CODE>activate</CODE> is called before <CODE>attach</CODE> succeeds. 85 862006/10/13 Added <code><a href="./VFDeleteSystemFile.html">VFDeleteSystemFileNANDFlash</a></code>. 872006/10/17 Fixed a bug that prevented errors in <CODE>VFGetFileSizeByFd( )</CODE>, <CODE>VFGetOffsetByFd( )</CODE>, and <CODE>VFGetDriveFreeSizeW( )</CODE> from being reflected in <CODE>VFGetLastError( )</CODE>. 88 892006/10/18 Corrected a problem that prevented -1 from being returned when an internal error occurred with the 2006/10/17 version of <CODE>VFGetFileSizeByFd( )</CODE>. 90 912006/10/25 Added <CODE>NANDCheck</CODE> to the sample demos. 922006/10/27 Added the <CODE>VF_DTA_GET_FILE_SECONDS(vta)</CODE> macro to get the file update time from the file search information (<CODE>VFDta</CODE>). 932006/10/30 Added a caution regarding stacks in the Introduction and Notes. 942006/11/09 Added <code><a href="./VFUnmountDrive.html">VFUnmountDriveForce</a></code> to unmount a drive even if a file is open. 95 Added <code><a href="./VFInactivateDrive.html">VFInactivateDriveForce</a></code> to invalidate a drive even if a file is open. 962006/11/14 Added detailed description to the <a href="./VFErr.html">VFErr</a> document. 972007/04/27 Added <a href="./VFSetTimeStampCallback.html">VFSetTimeStampCallback</a>. 982007/05/08 Revisions to the Manuals. Added the <CODE>VFGetApiErrorString</CODE> manual. 992007/06/26 Fixed region corruption that occurred when the same drive was repeatedly mounted and unmounted. 1002007/09/10 Added a note about <CODE>VF_ERR_EIO</CODE>. 1012007/10/11 Added the Introduction. 102 103</pre> 104 105<h2>Notes</h2> 106<p> 107 108<ul> 109<li><FONT COLOR="#ff0000">If the error returned by a VF function is <CODE>VF_ERR_EIO</CODE>, use the <CODE>VFGetLastDeviceError</CODE> function to get the value of the device error and then perform processing that complies with the guidelines for that device.</FONT> 110 111<li><s>The buffers used for reading and writing data and the buffers used for getting directory lists must be 32-byte aligned.<br> In addition, the size of data written/read must also be a multiple of 32 bytes.</s><br> The above restriction has been eliminated. Please be aware, though, that the 32 byte alignment restriction remains for .vff files. (2006/06/23)<br> 112<li>Please do not include hidden characters in the path string passed to the API.<br> 113<li>Executing <CODE>VFCreateFile()</CODE> or <CODE>VFOpenFile()</CODE> in directories that contain many files consumes processing time.<br>To improve the processing time, set the cache to match the maximum number of files allowed to exist.<br> 114<li>After mounting a vff file for the first time, be sure to format it with <CODE>VFFormatDrive()</CODE>.<br> 115<li>Uppercase and lowercase are not differentiated when searching file names or directory names.<br>However, uppercase and lowercase are strictly differentiated for drive names. 116<li>Changed so that <CODE>VF_ERR_VFF_FILE_FORMAT</CODE> is returned when an illegal file is specified during mount. When the above error is detected, create the .vff file again after deleting it. 117 118<li>Run <CODE>NANDCheck</CODE> within the application when creating files in NAND memory. 119<li>Functions that specify paths, such as <CODE>VFOpenFile()</CODE>, consume stack space of about 3 KB. 120</ul> 121</p> 122 123 124<hr><p>CONFIDENTIAL</p></body> 125</html> 126