LittleFileSystem.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2017 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 /** \addtogroup storage */
00018 /** @{*/
00019 
00020 #ifndef MBED_LFSFILESYSTEM_H
00021 #define MBED_LFSFILESYSTEM_H
00022 
00023 #include "features/storage/filesystem/FileSystem.h"
00024 #include "features/storage/blockdevice/BlockDevice.h"
00025 #include "platform/PlatformMutex.h"
00026 #include "features/storage/filesystem/littlefs/littlefs/lfs.h"
00027 
00028 namespace mbed {
00029 
00030 /**
00031  * LittleFileSystem, a little file system
00032  *
00033  * Synchronization level: Thread safe
00034  */
00035 class LittleFileSystem : public mbed::FileSystem {
00036 public:
00037     /** Lifetime of the LittleFileSystem
00038      *
00039      *  @param name     Name of the file system in the tree.
00040      *  @param bd       Block device to mount. Mounted immediately if not NULL.
00041      *  @param read_size
00042      *      Minimum size of a block read. This determines the size of read buffers.
00043      *      This may be larger than the physical read size to improve performance
00044      *      by caching more of the block device.
00045      *  @param prog_size
00046      *      Minimum size of a block program. This determines the size of program
00047      *      buffers. This may be larger than the physical program size to improve
00048      *      performance by caching more of the block device.
00049      *  @param block_size
00050      *      Size of an erasable block. This does not impact ram consumption and
00051      *      may be larger than the physical erase size. However, this should be
00052      *      kept small as each file currently takes up an entire block.
00053      *  @param lookahead
00054      *      Number of blocks to lookahead during block allocation. A larger
00055      *      lookahead reduces the number of passes required to allocate a block.
00056      *      The lookahead buffer requires only 1 bit per block so it can be quite
00057      *      large with little ram impact. Should be a multiple of 32.
00058      */
00059     LittleFileSystem(const char *name = NULL, mbed::BlockDevice *bd = NULL,
00060                      lfs_size_t read_size = MBED_LFS_READ_SIZE,
00061                      lfs_size_t prog_size = MBED_LFS_PROG_SIZE,
00062                      lfs_size_t block_size = MBED_LFS_BLOCK_SIZE,
00063                      lfs_size_t lookahead = MBED_LFS_LOOKAHEAD);
00064 
00065     virtual ~LittleFileSystem();
00066 
00067     /** Format a block device with the LittleFileSystem.
00068      *
00069      *  The block device to format should be mounted when this function is called.
00070      *
00071      *  @param bd       This is the block device that will be formatted.
00072      *  @param read_size
00073      *      Minimum size of a block read. This determines the size of read buffers.
00074      *      This may be larger than the physical read size to improve performance
00075      *      by caching more of the block device.
00076      *  @param prog_size
00077      *      Minimum size of a block program. This determines the size of program
00078      *      buffers. This may be larger than the physical program size to improve
00079      *      performance by caching more of the block device.
00080      *  @param block_size
00081      *      Size of an erasable block. This does not impact ram consumption and
00082      *      may be larger than the physical erase size. However, this should be
00083      *      kept small as each file currently takes up an entire block.
00084      *  @param lookahead
00085      *      Number of blocks to lookahead during block allocation. A larger
00086      *      lookahead reduces the number of passes required to allocate a block.
00087      *      The lookahead buffer requires only 1 bit per block so it can be quite
00088      *      large with little ram impact. Should be a multiple of 32.
00089      */
00090     static int format(mbed::BlockDevice *bd,
00091                       lfs_size_t read_size = MBED_LFS_READ_SIZE,
00092                       lfs_size_t prog_size = MBED_LFS_PROG_SIZE,
00093                       lfs_size_t block_size = MBED_LFS_BLOCK_SIZE,
00094                       lfs_size_t lookahead = MBED_LFS_LOOKAHEAD);
00095 
00096     /** Mount a file system to a block device.
00097      *
00098      *  @param bd       Block device to mount to.
00099      *  @return         0 on success, negative error code on failure.
00100      */
00101     virtual int mount(mbed::BlockDevice *bd);
00102 
00103     /** Unmount a file system from the underlying block device.
00104      *
00105      *  @return         0 on success, negative error code on failure
00106      */
00107     virtual int unmount();
00108 
00109     /** Reformat a file system. Results in an empty and mounted file system.
00110      *
00111      *  @param bd
00112      *      Block device to reformat and mount. If NULL, the mounted
00113      *      Block device is used.
00114      *      Note: If mount fails, bd must be provided.
00115      *      Default: NULL
00116      *
00117      *  @return         0 on success, negative error code on failure
00118      */
00119     virtual int reformat(mbed::BlockDevice *bd);
00120 
00121     /** Remove a file from the file system.
00122      *
00123      *  @param path     The name of the file to remove.
00124      *  @return         0 on success, negative error code on failure
00125      */
00126     virtual int remove(const char *path);
00127 
00128     /** Rename a file in the file system.
00129      *
00130      *  @param path     The name of the file to rename.
00131      *  @param newpath  The name to rename it to.
00132      *  @return         0 on success, negative error code on failure
00133      */
00134     virtual int rename(const char *path, const char *newpath);
00135 
00136     /** Store information about the file in a stat structure
00137      *
00138      *  @param path     The name of the file to find information about.
00139      *  @param st       The stat buffer to write to.
00140      *  @return         0 on success, negative error code on failure
00141      */
00142     virtual int stat(const char *path, struct stat *st);
00143 
00144     /** Create a directory in the file system.
00145      *
00146      *  @param path     The name of the directory to create.
00147      *  @param mode     The permissions with which to create the directory.
00148      *  @return         0 on success, negative error code on failure
00149      */
00150     virtual int mkdir(const char *path, mode_t mode);
00151 
00152     /** Store information about the mounted file system in a statvfs structure.
00153      *
00154      *  @param path     The name of the file to find information about.
00155      *  @param buf      The stat buffer to write to.
00156      *  @return         0 on success, negative error code on failure
00157      */
00158     virtual int statvfs(const char *path, struct statvfs *buf);
00159 
00160 protected:
00161 #if !(DOXYGEN_ONLY)
00162     /** Open a file on the file system.
00163      *
00164      *  @param file     Destination of the newly created handle to the referenced file.
00165      *  @param path     The name of the file to open.
00166      *  @param flags    The flags that trigger opening of the file. These flags are O_RDONLY, O_WRONLY, and O_RDWR,
00167      *                  with an O_CREAT, O_TRUNC, or O_APPEND bitwise OR operator.
00168      *  @return         0 on success, negative error code on failure.
00169      */
00170     virtual int file_open(mbed::fs_file_t *file, const char *path, int flags);
00171 
00172     /** Close a file
00173      *
00174      *  @param file     File handle.
00175      *  return          0 on success, negative error code on failure
00176      */
00177     virtual int file_close(mbed::fs_file_t file);
00178 
00179     /** Read the contents of a file into a buffer
00180      *
00181      *  @param file     File handle.
00182      *  @param buffer   The buffer to read in to.
00183      *  @param size     The number of bytes to read.
00184      *  @return         The number of bytes read, 0 at end of file, negative error on failure
00185      */
00186     virtual ssize_t file_read(mbed::fs_file_t file, void *buffer, size_t size);
00187 
00188     /** Write the contents of a buffer to a file
00189      *
00190      *  @param file     File handle.
00191      *  @param buffer   The buffer to write from.
00192      *  @param size     The number of bytes to write.
00193      *  @return         The number of bytes written, negative error on failure
00194      */
00195     virtual ssize_t file_write(mbed::fs_file_t file, const void *buffer, size_t size);
00196 
00197     /** Flush any buffers associated with the file
00198      *
00199      *  @param file     File handle.
00200      *  @return         0 on success, negative error code on failure
00201      */
00202     virtual int file_sync(mbed::fs_file_t file);
00203 
00204     /** Move the file position to a given offset from a given location
00205      *
00206      *  @param file     File handle.
00207      *  @param offset   The offset from whence to move to.
00208      *  @param whence   The start of where to seek.
00209      *      SEEK_SET to start from beginning of file,
00210      *      SEEK_CUR to start from current position in file,
00211      *      SEEK_END to start from end of file.
00212      *  @return         The new offset of the file
00213      */
00214     virtual off_t file_seek(mbed::fs_file_t file, off_t offset, int whence);
00215 
00216     /** Get the file position of the file
00217      *
00218      *  @param file     File handle.
00219      *  @return         The current offset in the file
00220      */
00221     virtual off_t file_tell(mbed::fs_file_t file);
00222 
00223     /** Get the size of the file
00224      *
00225      *  @param file     File handle.
00226      *  @return         Size of the file in bytes
00227      */
00228     virtual off_t file_size(mbed::fs_file_t file);
00229 
00230     /** Truncate or extend a file.
00231      *
00232      * The file's length is set to the specified value. The seek pointer is
00233      * not changed. If the file is extended, the extended area appears as if
00234      * it were zero-filled.
00235      *
00236      *  @param file     File handle.
00237      *  @param length   The requested new length for the file
00238      *
00239      *  @return         Zero on success, negative error code on failure
00240      */
00241     virtual int file_truncate(mbed::fs_file_t file, off_t length);
00242 
00243     /** Open a directory on the file system.
00244      *
00245      *  @param dir      Destination for the handle to the directory.
00246      *  @param path     Name of the directory to open.
00247      *  @return         0 on success, negative error code on failure
00248      */
00249     virtual int dir_open(mbed::fs_dir_t *dir, const char *path);
00250 
00251     /** Close a directory
00252      *
00253      *  @param dir      Dir handle.
00254      *  return          0 on success, negative error code on failure
00255      */
00256     virtual int dir_close(mbed::fs_dir_t dir);
00257 
00258     /** Read the next directory entry
00259      *
00260      *  @param dir      Dir handle.
00261      *  @param ent      The directory entry to fill out.
00262      *  @return         1 on reading a filename, 0 at end of directory, negative error on failure
00263      */
00264     virtual ssize_t dir_read(mbed::fs_dir_t dir, struct dirent *ent);
00265 
00266     /** Set the current position of the directory
00267      *
00268      *  @param dir      Dir handle.
00269      *  @param offset   Offset of the location to seek to,
00270      *                  must be a value returned from dir_tell
00271      */
00272     virtual void dir_seek(mbed::fs_dir_t dir, off_t offset);
00273 
00274     /** Get the current position of the directory
00275      *
00276      *  @param dir      Dir handle.
00277      *  @return         Position of the directory that can be passed to dir_rewind
00278      */
00279     virtual off_t dir_tell(mbed::fs_dir_t dir);
00280 
00281     /** Rewind the current position to the beginning of the directory
00282      *
00283      *  @param dir      Dir handle
00284      */
00285     virtual void dir_rewind(mbed::fs_dir_t dir);
00286 #endif //!(DOXYGEN_ONLY)
00287 
00288 private:
00289     lfs_t _lfs; // The actual file system
00290     struct lfs_config _config;
00291     mbed::BlockDevice *_bd; // The block device
00292 
00293     // default parameters
00294     const lfs_size_t _read_size;
00295     const lfs_size_t _prog_size;
00296     const lfs_size_t _block_size;
00297     const lfs_size_t _lookahead;
00298 
00299     // thread-safe locking
00300     PlatformMutex _mutex;
00301 };
00302 
00303 } // namespace mbed
00304 
00305 // Added "using" for backwards compatibility
00306 #ifndef MBED_NO_GLOBAL_USING_DIRECTIVE
00307 using mbed::LittleFileSystem;
00308 #endif
00309 
00310 #endif
00311 
00312 /** @}*/