FATFileSystem.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2012 ARM Limited
00003  *
00004  * Permission is hereby granted, free of charge, to any person obtaining a copy
00005  * of this software and associated documentation files (the "Software"), to deal
00006  * in the Software without restriction, including without limitation the rights
00007  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00008  * copies of the Software, and to permit persons to whom the Software is
00009  * furnished to do so, subject to the following conditions:
00010  *
00011  * The above copyright notice and this permission notice shall be included in
00012  * all copies or substantial portions of the Software.
00013  *
00014  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00015  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00016  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00017  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00018  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00019  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
00020  * SOFTWARE.
00021  */
00022 
00023 /** \addtogroup storage */
00024 /** @{*/
00025 
00026 #ifndef MBED_FATFILESYSTEM_H
00027 #define MBED_FATFILESYSTEM_H
00028 
00029 #include "features/storage/filesystem/FileSystem.h"
00030 #include "features/storage/blockdevice/BlockDevice.h"
00031 #include "FileHandle.h"
00032 #include <stdint.h>
00033 #include "PlatformMutex.h"
00034 #include "features/storage/filesystem/fat/ChaN/ff.h"
00035 
00036 namespace mbed {
00037 
00038 /**
00039  * FAT file system based on ChaN's FAT file system library v0.8
00040  *
00041  * Synchronization level: Thread safe
00042  */
00043 class FATFileSystem : public FileSystem {
00044 public:
00045     /** Lifetime of the FAT file system.
00046      *
00047      *  @param name     Name of the file system in the tree.
00048      *  @param bd       Block device to mount. Mounted immediately if not NULL.
00049      */
00050     FATFileSystem(const char *name = NULL, BlockDevice *bd = NULL);
00051     virtual ~FATFileSystem();
00052 
00053     /** Format a logical drive, FDISK partitioning rule.
00054      *
00055      *  The block device to format should be mounted when this function is called.
00056      *
00057      *  @param bd
00058      *    This is the block device that will be formatted.
00059      *
00060      *  @param cluster_size
00061      *    This is the number of bytes per cluster. A larger cluster size decreases
00062      *    the overhead of the FAT table, but also increases the minimum file size. The
00063      *    cluster size must be a multiple of the underlying device's allocation unit
00064      *    and is currently limited to a max of 32,768 bytes. If the cluster size is set to zero, a cluster size
00065      *    is determined from the device's allocation unit. Defaults to zero.
00066      *
00067      *  @return         0 on success, negative error code on failure.
00068      */
00069     static int format(BlockDevice *bd, bd_size_t cluster_size = 0);
00070 
00071     /** Mount a file system to a block device.
00072      *
00073      *  @param bd       Block device to mount to.
00074      *  @return         0 on success, negative error code on failure.
00075      */
00076     virtual int mount(BlockDevice *bd);
00077 
00078     /** Unmount a file system from the underlying block device.
00079      *
00080      *  @return         0 on success, negative error code on failure.
00081      */
00082     virtual int unmount();
00083 
00084     /** Reformat a file system, results in an empty and mounted file system.
00085      *
00086      *  @param bd
00087      *      Block device to reformat and mount. If NULL, the mounted
00088      *      Block device is used.
00089      *      Note: If mount fails, bd must be provided.
00090      *      Default: NULL
00091      *
00092      *  @param allocation_unit
00093      *      This is the number of bytes per cluster size. The valid value is N
00094      *      times the sector size. N is a power of 2, from 1 to 128, for the FAT
00095      *      volume, and up to 16MiB for the exFAT volume. If zero is given,
00096      *      the default allocation unit size is selected by the underlying
00097      *      file system, which depends on the volume size.
00098      *
00099      *  @return         0 on success, negative error code on failure.
00100      */
00101     virtual int reformat(BlockDevice *bd, int allocation_unit);
00102 
00103     /** Reformat a file system, results in an empty and mounted file system.
00104      *
00105      *  @param bd       Block device to reformat and mount. If NULL, the mounted
00106      *                  Block device is used.
00107      *                  Note: If mount fails, bd must be provided.
00108      *                  Default: NULL
00109      *  @return         0 on success, negative error code on failure.
00110      */
00111     virtual int reformat(BlockDevice *bd = NULL)
00112     {
00113         // Required for virtual inheritance shenanigans.
00114         return reformat(bd, 0);
00115     }
00116 
00117     /** Remove a file from the file system.
00118      *
00119      *  @param path     The name of the file to remove.
00120      *  @return         0 on success, negative error code on failure.
00121      */
00122     virtual int remove(const char *path);
00123 
00124     /** Rename a file in the file system.
00125      *
00126      *  @param path     The current name of the file to rename.
00127      *  @param newpath  The new name of the file.
00128      *  @return         0 on success, negative error code on failure.
00129      */
00130     virtual int rename(const char *path, const char *newpath);
00131 
00132     /** Store information about the file in a stat structure.
00133      *
00134      *  @param path     The name of the file to store information about.
00135      *  @param st       The stat buffer to write to.
00136      *  @return         0 on success, negative error code on failure.
00137      */
00138     virtual int stat(const char *path, struct stat *st);
00139 
00140     /** Create a directory in the file system.
00141      *
00142      *  @param path     The name of the directory to create.
00143      *  @param mode     The permissions with which to create the directory.
00144      *  @return         0 on success, negative error code on failure.
00145      */
00146     virtual int mkdir(const char *path, mode_t mode);
00147 
00148     /** Store information about the mounted file system in a statvfs structure.
00149      *
00150      *  @param path     The name of the file to store information about.
00151      *  @param buf      The stat buffer to write to.
00152      *  @return         0 on success, negative error code on failure.
00153      */
00154     virtual int statvfs(const char *path, struct statvfs *buf);
00155 
00156 protected:
00157 #if !(DOXYGEN_ONLY)
00158     /** Open a file on the file system.
00159      *
00160      *  @param file     Destination for the handle to a newly created file.
00161      *  @param path     The name of the file to open.
00162      *  @param flags    The flags that trigger opening of the file. These flags are O_RDONLY, O_WRONLY, and O_RDWR,
00163      *                  with an O_CREAT, O_TRUNC, or O_APPEND bitwise OR operator.
00164      *  @return         0 on success, negative error code on failure.
00165      */
00166     virtual int file_open(fs_file_t *file, const char *path, int flags);
00167 
00168     /** Close a file
00169      *
00170      *  @param file     File handle.
00171      *  @return         0 on success, negative error code on failure.
00172      */
00173     virtual int file_close(fs_file_t file);
00174 
00175     /** Read the contents of a file into a buffer.
00176      *
00177      *  @param file     File handle.
00178      *  @param buffer   The buffer to read into.
00179      *  @param len      The number of bytes to read.
00180      *  @return         The number of bytes read; 0 at the end of the file, negative error on failure.
00181      */
00182     virtual ssize_t file_read(fs_file_t file, void *buffer, size_t len);
00183 
00184     /** Write the contents of a buffer to a file.
00185      *
00186      *  @param file     File handle.
00187      *  @param buffer   The buffer to write from.
00188      *  @param len      The number of bytes to write.
00189      *  @return         The number of bytes written, negative error on failure.
00190      */
00191     virtual ssize_t file_write(fs_file_t file, const void *buffer, size_t len);
00192 
00193     /** Flush any buffers associated with the file.
00194      *
00195      *  @param file     File handle.
00196      *  @return         0 on success, negative error code on failure.
00197      */
00198     virtual int file_sync(fs_file_t file);
00199 
00200     /** Move the file position to a given offset from a given location
00201      *
00202      *  @param file     File handle.
00203      *  @param offset   The offset from whence to move to.
00204      *  @param whence   The start of where to seek.
00205      *      SEEK_SET to start from the beginning of the file,
00206      *      SEEK_CUR to start from the current position in the file,
00207      *      SEEK_END to start from the end of the file.
00208      *  @return         The new offset of the file.
00209      */
00210     virtual off_t file_seek(fs_file_t file, off_t offset, int whence);
00211 
00212     /** Get the file position of the file.
00213      *
00214      *  @param file     File handle.
00215      *  @return         The current offset in the file.
00216      */
00217     virtual off_t file_tell(fs_file_t file);
00218 
00219     /** Get the size of the file.
00220      *
00221      *  @param file     File handle.
00222      *  @return         Size of the file in bytes.
00223      */
00224     virtual off_t file_size(fs_file_t file);
00225 
00226     /** Truncate or extend a file.
00227      *
00228      * The file's length is set to the specified value. The seek pointer is
00229      * not changed. If the file is extended, the extended area appears as if
00230      * it were zero-filled.
00231      *
00232      *  @param file     File handle.
00233      *  @param length   The requested new length for the file.
00234      *
00235      *  @return         0 on success, negative error code on failure.
00236      */
00237     virtual int file_truncate(mbed::fs_file_t file, off_t length);
00238 
00239     /** Open a directory on the file system.
00240      *
00241      *  @param dir      Destination for the handle to the directory.
00242      *  @param path     Name of the directory to open.
00243      *  @return         0 on success, negative error code on failure.
00244      */
00245     virtual int dir_open(fs_dir_t *dir, const char *path);
00246 
00247     /** Close a directory
00248      *
00249      *  @param dir      Dir handle.
00250      *  @return         0 on success, negative error code on failure.
00251      */
00252     virtual int dir_close(fs_dir_t dir);
00253 
00254     /** Read the next directory entry
00255      *
00256      *  @param dir      Dir handle.
00257      *  @param ent      The directory entry to fill out.
00258      *  @return         1 on reading a filename, 0 at the end of the directory, negative error on failure.
00259      */
00260     virtual ssize_t dir_read(fs_dir_t dir, struct dirent *ent);
00261 
00262     /** Set the current position of the directory.
00263      *
00264      *  @param dir      Dir handle.
00265      *  @param offset   Offset of the location to seek to.
00266      *                  Must be a value returned by dir_tell.
00267      */
00268     virtual void dir_seek(fs_dir_t dir, off_t offset);
00269 
00270     /** Get the current position of the directory.
00271      *
00272      *  @param dir      Dir handle.
00273      *  @return         Directory position, which can be passed to dir_rewind.
00274      */
00275     virtual off_t dir_tell(fs_dir_t dir);
00276 
00277     /** Rewind the current position to the beginning of the directory.
00278      *
00279      *  @param dir      Dir handle.
00280      */
00281     virtual void dir_rewind(fs_dir_t dir);
00282 #endif //!(DOXYGEN_ONLY)
00283 
00284 private:
00285     FATFS _fs; // Work area (file system object) for logical drive.
00286     char _fsid[sizeof("0:")];
00287     int _id;
00288 
00289 protected:
00290     virtual void lock();
00291     virtual void unlock();
00292     virtual int mount(BlockDevice *bd, bool mount);
00293 };
00294 
00295 } // namespace mbed
00296 
00297 // Added "using" for backwards compatibility.
00298 #ifndef MBED_NO_GLOBAL_USING_DIRECTIVE
00299 using mbed::FATFileSystem;
00300 #endif
00301 
00302 #endif
00303 
00304 /** @}*/