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 #ifndef MBED_LFSFILESYSTEM_H
00017 #define MBED_LFSFILESYSTEM_H
00018 
00019 #include "FileSystem.h"
00020 #include "BlockDevice.h"
00021 #include "PlatformMutex.h"
00022 extern "C" {
00023 #include "lfs.h"
00024 }
00025 
00026 
00027 /**
00028  * LittleFileSystem, a little filesystem
00029  */
00030 class LittleFileSystem : public mbed::FileSystem {
00031 public:
00032     /** Lifetime of the LittleFileSystem
00033      *
00034      *  @param name         Name to add filesystem to tree as
00035      *  @param bd           BlockDevice to mount, may be passed instead to mount call
00036      *  @param read_size
00037      *      Minimum size of a block read. This determines the size of read buffers.
00038      *      This may be larger than the physical read size to improve performance
00039      *      by caching more of the block device.
00040      *  @param prog_size
00041      *      Minimum size of a block program. This determines the size of program
00042      *      buffers. This may be larger than the physical program size to improve
00043      *      performance by caching more of the block device.
00044      *  @param block_size
00045      *      Size of an erasable block. This does not impact ram consumption and
00046      *      may be larger than the physical erase size. However, this should be
00047      *      kept small as each file currently takes up an entire block.
00048      *  @param lookahead
00049      *      Number of blocks to lookahead during block allocation. A larger
00050      *      lookahead reduces the number of passes required to allocate a block.
00051      *      The lookahead buffer requires only 1 bit per block so it can be quite
00052      *      large with little ram impact. Should be a multiple of 32.
00053      */
00054     LittleFileSystem(const char *name=NULL, BlockDevice *bd=NULL,
00055             lfs_size_t read_size=MBED_LFS_READ_SIZE,
00056             lfs_size_t prog_size=MBED_LFS_PROG_SIZE,
00057             lfs_size_t block_size=MBED_LFS_BLOCK_SIZE,
00058             lfs_size_t lookahead=MBED_LFS_LOOKAHEAD);
00059     virtual ~LittleFileSystem();
00060     
00061     /** Formats a block device with the LittleFileSystem
00062      *
00063      *  The block device to format should be mounted when this function is called.
00064      *
00065      *  @param bd       This is the block device that will be formated.
00066      *  @param read_size
00067      *      Minimum size of a block read. This determines the size of read buffers.
00068      *      This may be larger than the physical read size to improve performance
00069      *      by caching more of the block device.
00070      *  @param prog_size
00071      *      Minimum size of a block program. This determines the size of program
00072      *      buffers. This may be larger than the physical program size to improve
00073      *      performance by caching more of the block device.
00074      *  @param block_size
00075      *      Size of an erasable block. This does not impact ram consumption and
00076      *      may be larger than the physical erase size. However, this should be
00077      *      kept small as each file currently takes up an entire block.
00078      *  @param lookahead
00079      *      Number of blocks to lookahead during block allocation. A larger
00080      *      lookahead reduces the number of passes required to allocate a block.
00081      *      The lookahead buffer requires only 1 bit per block so it can be quite
00082      *      large with little ram impact. Should be a multiple of 32.
00083      */
00084     static int format(BlockDevice *bd,
00085         lfs_size_t read_size=MBED_LFS_READ_SIZE,
00086         lfs_size_t prog_size=MBED_LFS_PROG_SIZE,
00087         lfs_size_t block_size=MBED_LFS_BLOCK_SIZE,
00088         lfs_size_t lookahead=MBED_LFS_LOOKAHEAD);
00089 
00090     /** Mounts a filesystem to a block device
00091      *
00092      *  @param bd       BlockDevice to mount to
00093      *  @return         0 on success, negative error code on failure
00094      */
00095     virtual int mount(BlockDevice *bd);
00096 
00097     /** Unmounts a filesystem from the underlying block device
00098      *
00099      *  @return         0 on success, negative error code on failure
00100      */
00101     virtual int unmount();
00102 
00103     /** Reformats a filesystem, results in an empty and mounted filesystem
00104      *
00105      *  @param bd
00106      *      BlockDevice to reformat and mount. If NULL, the mounted
00107      *      block device will be used.
00108      *      Note: if mount fails, bd must be provided.
00109      *      Default: NULL
00110      *
00111      *  @return         0 on success, negative error code on failure
00112      */
00113     virtual int reformat(BlockDevice *bd);
00114 
00115     /** Remove a file from the filesystem.
00116      *
00117      *  @param path     The name of the file to remove.
00118      *  @return         0 on success, negative error code on failure
00119      */
00120     virtual int remove(const char *path);
00121 
00122     /** Rename a file in the filesystem.
00123      *
00124      *  @param path     The name of the file to rename.
00125      *  @param newpath  The name to rename it to
00126      *  @return         0 on success, negative error code on failure
00127      */
00128     virtual int rename(const char *path, const char *newpath);
00129 
00130     /** Store information about the file in a stat structure
00131      *
00132      *  @param path     The name of the file to find information about
00133      *  @param st       The stat buffer to write to
00134      *  @return         0 on success, negative error code on failure
00135      */
00136     virtual int stat(const char *path, struct stat *st);
00137 
00138     /** Create a directory in the filesystem.
00139      *
00140      *  @param path     The name of the directory to create.
00141      *  @param mode     The permissions with which to create the directory
00142      *  @return         0 on success, negative error code on failure
00143      */
00144     virtual int mkdir(const char *path, mode_t mode);
00145 
00146 protected:
00147     /** Open a file on the filesystem
00148      *
00149      *  @param file     Destination for the handle to a newly created file
00150      *  @param path     The name of the file to open
00151      *  @param flags    The flags to open the file in, one of O_RDONLY, O_WRONLY, O_RDWR,
00152      *                  bitwise or'd with one of O_CREAT, O_TRUNC, O_APPEND
00153      *  @return         0 on success, negative error code on failure
00154      */
00155     virtual int file_open(mbed::fs_file_t *file, const char *path, int flags);
00156 
00157     /** Close a file
00158      *
00159      *  @param file     File handle
00160      *  return          0 on success, negative error code on failure
00161      */
00162     virtual int file_close(mbed::fs_file_t file);
00163 
00164     /** Read the contents of a file into a buffer
00165      *
00166      *  @param file     File handle
00167      *  @param buffer   The buffer to read in to
00168      *  @param size     The number of bytes to read
00169      *  @return         The number of bytes read, 0 at end of file, negative error on failure
00170      */
00171     virtual ssize_t file_read(mbed::fs_file_t file, void *buffer, size_t size);
00172 
00173     /** Write the contents of a buffer to a file
00174      *
00175      *  @param file     File handle
00176      *  @param buffer   The buffer to write from
00177      *  @param size     The number of bytes to write 
00178      *  @return         The number of bytes written, negative error on failure
00179      */
00180     virtual ssize_t file_write(mbed::fs_file_t file, const void *buffer, size_t size);
00181 
00182     /** Flush any buffers associated with the file
00183      *
00184      *  @param file     File handle
00185      *  @return         0 on success, negative error code on failure
00186      */
00187     virtual int file_sync(mbed::fs_file_t file);
00188 
00189     /** Move the file position to a given offset from from a given location
00190      *
00191      *  @param file     File handle
00192      *  @param offset   The offset from whence to move to
00193      *  @param whence   The start of where to seek
00194      *      SEEK_SET to start from beginning of file,
00195      *      SEEK_CUR to start from current position in file,
00196      *      SEEK_END to start from end of file
00197      *  @return         The new offset of the file
00198      */
00199     virtual off_t file_seek(mbed::fs_file_t file, off_t offset, int whence);
00200 
00201     /** Get the file position of the file
00202      *
00203      *  @param file     File handle
00204      *  @return         The current offset in the file
00205      */
00206     virtual off_t file_tell(mbed::fs_file_t file);
00207 
00208     /** Get the size of the file
00209      *
00210      *  @param file     File handle
00211      *  @return         Size of the file in bytes
00212      */
00213     virtual off_t file_size(mbed::fs_file_t file);
00214 
00215     /** Open a directory on the filesystem
00216      *
00217      *  @param dir      Destination for the handle to the directory
00218      *  @param path     Name of the directory to open
00219      *  @return         0 on success, negative error code on failure
00220      */
00221     virtual int dir_open(mbed::fs_dir_t *dir, const char *path);
00222 
00223     /** Close a directory
00224      *
00225      *  @param dir      Dir handle
00226      *  return          0 on success, negative error code on failure
00227      */
00228     virtual int dir_close(mbed::fs_dir_t dir);
00229 
00230     /** Read the next directory entry
00231      *
00232      *  @param dir      Dir handle
00233      *  @param ent      The directory entry to fill out
00234      *  @return         1 on reading a filename, 0 at end of directory, negative error on failure
00235      */
00236     virtual ssize_t dir_read(mbed::fs_dir_t dir, struct dirent *ent);
00237 
00238     /** Set the current position of the directory
00239      *
00240      *  @param dir      Dir handle
00241      *  @param offset   Offset of the location to seek to,
00242      *                  must be a value returned from dir_tell
00243      */
00244     virtual void dir_seek(mbed::fs_dir_t dir, off_t offset);
00245 
00246     /** Get the current position of the directory
00247      *
00248      *  @param dir      Dir handle
00249      *  @return         Position of the directory that can be passed to dir_rewind
00250      */
00251     virtual off_t dir_tell(mbed::fs_dir_t dir);
00252 
00253     /** Rewind the current position to the beginning of the directory
00254      *
00255      *  @param dir      Dir handle
00256      */
00257     virtual void dir_rewind(mbed::fs_dir_t dir);
00258     
00259 private:
00260     lfs_t _lfs; // _the actual filesystem
00261     struct lfs_config _config;
00262     BlockDevice *_bd; // the block device
00263 
00264     // default parameters
00265     const lfs_size_t _read_size;
00266     const lfs_size_t _prog_size;
00267     const lfs_size_t _block_size;
00268     const lfs_size_t _lookahead;
00269 
00270     // thread-safe locking
00271     PlatformMutex _mutex;
00272 };
00273 
00274 
00275 #endif