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     /** Store information about the mounted filesystem in a statvfs structure
00147      *
00148      *  @param path     The name of the file to find information about
00149      *  @param buf      The stat buffer to write to
00150      *  @return         0 on success, negative error code on failure
00151      */
00152     virtual int statvfs(const char *path, struct statvfs *buf);
00153 
00154 protected:
00155     /** Open a file on the filesystem
00156      *
00157      *  @param file     Destination for the handle to a newly created file
00158      *  @param path     The name of the file to open
00159      *  @param flags    The flags to open the file in, one of O_RDONLY, O_WRONLY, O_RDWR,
00160      *                  bitwise or'd with one of O_CREAT, O_TRUNC, O_APPEND
00161      *  @return         0 on success, negative error code on failure
00162      */
00163     virtual int file_open(mbed::fs_file_t *file, const char *path, int flags);
00164 
00165     /** Close a file
00166      *
00167      *  @param file     File handle
00168      *  return          0 on success, negative error code on failure
00169      */
00170     virtual int file_close(mbed::fs_file_t file);
00171 
00172     /** Read the contents of a file into a buffer
00173      *
00174      *  @param file     File handle
00175      *  @param buffer   The buffer to read in to
00176      *  @param size     The number of bytes to read
00177      *  @return         The number of bytes read, 0 at end of file, negative error on failure
00178      */
00179     virtual ssize_t file_read(mbed::fs_file_t file, void *buffer, size_t size);
00180 
00181     /** Write the contents of a buffer to a file
00182      *
00183      *  @param file     File handle
00184      *  @param buffer   The buffer to write from
00185      *  @param size     The number of bytes to write 
00186      *  @return         The number of bytes written, negative error on failure
00187      */
00188     virtual ssize_t file_write(mbed::fs_file_t file, const void *buffer, size_t size);
00189 
00190     /** Flush any buffers associated with the file
00191      *
00192      *  @param file     File handle
00193      *  @return         0 on success, negative error code on failure
00194      */
00195     virtual int file_sync(mbed::fs_file_t file);
00196 
00197     /** Move the file position to a given offset from from a given location
00198      *
00199      *  @param file     File handle
00200      *  @param offset   The offset from whence to move to
00201      *  @param whence   The start of where to seek
00202      *      SEEK_SET to start from beginning of file,
00203      *      SEEK_CUR to start from current position in file,
00204      *      SEEK_END to start from end of file
00205      *  @return         The new offset of the file
00206      */
00207     virtual off_t file_seek(mbed::fs_file_t file, off_t offset, int whence);
00208 
00209     /** Get the file position of the file
00210      *
00211      *  @param file     File handle
00212      *  @return         The current offset in the file
00213      */
00214     virtual off_t file_tell(mbed::fs_file_t file);
00215 
00216     /** Get the size of the file
00217      *
00218      *  @param file     File handle
00219      *  @return         Size of the file in bytes
00220      */
00221     virtual off_t file_size(mbed::fs_file_t file);
00222 
00223     /** Open a directory on the filesystem
00224      *
00225      *  @param dir      Destination for the handle to the directory
00226      *  @param path     Name of the directory to open
00227      *  @return         0 on success, negative error code on failure
00228      */
00229     virtual int dir_open(mbed::fs_dir_t *dir, const char *path);
00230 
00231     /** Close a directory
00232      *
00233      *  @param dir      Dir handle
00234      *  return          0 on success, negative error code on failure
00235      */
00236     virtual int dir_close(mbed::fs_dir_t dir);
00237 
00238     /** Read the next directory entry
00239      *
00240      *  @param dir      Dir handle
00241      *  @param ent      The directory entry to fill out
00242      *  @return         1 on reading a filename, 0 at end of directory, negative error on failure
00243      */
00244     virtual ssize_t dir_read(mbed::fs_dir_t dir, struct dirent *ent);
00245 
00246     /** Set the current position of the directory
00247      *
00248      *  @param dir      Dir handle
00249      *  @param offset   Offset of the location to seek to,
00250      *                  must be a value returned from dir_tell
00251      */
00252     virtual void dir_seek(mbed::fs_dir_t dir, off_t offset);
00253 
00254     /** Get the current position of the directory
00255      *
00256      *  @param dir      Dir handle
00257      *  @return         Position of the directory that can be passed to dir_rewind
00258      */
00259     virtual off_t dir_tell(mbed::fs_dir_t dir);
00260 
00261     /** Rewind the current position to the beginning of the directory
00262      *
00263      *  @param dir      Dir handle
00264      */
00265     virtual void dir_rewind(mbed::fs_dir_t dir);
00266     
00267 private:
00268     lfs_t _lfs; // _the actual filesystem
00269     struct lfs_config _config;
00270     BlockDevice *_bd; // the block device
00271 
00272     // default parameters
00273     const lfs_size_t _read_size;
00274     const lfs_size_t _prog_size;
00275     const lfs_size_t _block_size;
00276     const lfs_size_t _lookahead;
00277 
00278     // thread-safe locking
00279     PlatformMutex _mutex;
00280 };
00281 
00282 
00283 #endif