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. 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, among other items, 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>. <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>Revision History</h2> 39<pre> 402006/06/01 Fixed a bug that caused an infinite loop when using <CODE>VFDeleteFile(W)</CODE>. 412006/06/09 Added an argument to <CODE>VFReadFile()</CODE> to get the size of the loaded file. 422006/06/16 Because there was a bug when the file system type was set to FAT32, 43 reverted to the original format in which the FAT type is automatically set according to the volume size. 442006/06/27 Revised code when NAND is used. Every time <CODE>VFWriteFile()</CODE> is called, it flushes. 45 Eliminated the alignment restriction for buffers passed by <CODE>VFWriteFile()</CODE> and <CODE>VFReadFile()</CODE>. 462006/07/14 Added <CODE>VFMove{File, Dir}(W)</CODE> and <CODE>VFRename{File, Dir}(W)</CODE>. 472006/08/09 Added <CODE>VFCutFileSize(W)</CODE>. 482006/08/24 Added <CODE>VFFormatDrive(W)</CODE>. 49 (From now on, after mounting a vff file for the first time, please format it. See the demo for criteria.) 502006/09/12 Added <CODE>VFInitEx()</CODE> and <CODE>VFFinalize()</CODE>. 512006/09/13 Added <CODE>VFIsAvailable()</CODE>. 522006/09/14 Fixed a bug that prevented mounting after mounting and unmounting 31 times, using a different drive name. 532006/09/15 Fixed a critical section bug. 542006/09/21 Fixed a bug related to the log name. 55 Fixed the problem when attaching (mounting) with the same drive name twice. 56 (An error is now returned <code><a href="./VFErr.html">VFErr</a></code>.) 572006/09/26 Increased the speed of <CODE>VFFormatDrive()</CODE> when mounting NAND. 58 Added <code><a href="./VFSync.html">VFSync</a></code> and <code><a href="./VFFileSync.html">VFFileSync</a></code>. 592006/09/27 Changed code so that the cache can be set when mounting. 60 <code><a href="./VFMountDrive.html">VFMountDrive</a></code>, <code><a href="./VFAttachDrive.html">VFAttachDrive</a></code> 612006/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>. 62 Added <code><a href="./VFBuffering.html">VFBuffering</a></code> (default is <CODE>VF_WRITE_BACK_ON_SIGNIF_API</CODE>). 632006/10/02 Corrected problems with various APIs when handling drive names. 64 Included a caution regarding the use of uppercase and lowercase in drive names in the Introduction. 652006/10/11 Changed behavior so that <CODE>VF_ERR_VFF_FILE_FORMAT</CODE> is returned when an illegal file is specified during mount. 66 When the preceding error is detected, create the <CODE>.vff</CODE> file again after deleting it. 672006/10/12 Revised specifications so that <CODE>VF_ERR_NOT_ALLOCATED_DRV</CODE> is returned when <CODE>activate</CODE> is called before <CODE>attach</CODE> has succeeded. 682006/10/13 Added <code><a href="./VFDeleteSystemFile.html">VFDeleteSystemFileNANDFlash</a></code>. 692006/10/17 Corrected a problem where errors from the <CODE>VFGetFileSizeByFd</CODE>, <CODE>VFGetOffsetByFd</CODE>, and <CODE>VFGetDriveFreeSizeW</CODE> functions were not being shown by the <CODE>VFGetLastError</CODE> function. 702006/10/18 Corrected a problem that prevented -1 from being returned when an internal error occurred with the 2006/10/17 version of the <CODE>VFGetFileSizeByFd</CODE> function.<BR> 712006/10/25 Added <CODE>NANDCheck</CODE> to the sample demos. 722006/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>). 732006/10/30 Added a caution regarding stacks in the Introduction and Notes. 742006/11/09 Added <code><a href="./VFUnmountDrive.html">VFUnmountDriveForce</a></code> to unmount a drive even if a file is open. 75 Added <code><a href="./VFInactivateDrive.html">VFInactivateDriveForce</a></code> to invalidate a drive even if a file is open. 762006/11/14 Added detailed description to the <a href="./VFErr.html">VFErr</a> document. 772007/04/27 Added <a href="./VFSetTimeStampCallback.html">VFSetTimeStampCallback</a>. 782007/05/08 Made revisions to the manual. Added <CODE>VFGetApiErrorString</CODE> to the manual. 792007/06/26 Fixed region corruption that occurred when the same drive was repeatedly mounted and unmounted. 80 81</pre> 82 83<h2>Notes</h2> 84<p> 85 86<ul> 87<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 <CODE>.vff</CODE> files. (2006/06/23)<br> 88<li>Please do not include hidden characters in the path string passed to the API.<br> 89<li>Executing <CODE>VFCreateFile()</CODE> or <CODE>VFOpenFile()</CODE> 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.<br> 90<li>After mounting a vff file for the first time, be sure to format it with <CODE>VFFormatDrive()</CODE>.<br> 91<li>Uppercase and lowercase are not differentiated when searching file names or directory names. However, uppercase and lowercase are strictly differentiated for drive names. 92<li>Changed so that <CODE>VF_ERR_VFF_FILE_FORMAT</CODE> is returned when an illegal file is specified during mount. When the preceding error is detected, create the <CODE>.vff</CODE> file again after deleting it. 93 94<li>Run <CODE>NANDCheck</CODE> within the application when creating files in NAND memory. 95<li>Functions that specify paths, such as <CODE>VFOpenFile()</CODE>, consume stack space of about 3 KB. 96</ul> 97</p> 98 99 100<hr><p>CONFIDENTIAL</p></body> 101</html> 102