Mistake on this page?
Report an issue in GitHub or email us
LittleFileSystem.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2017 ARM Limited
3  * SPDX-License-Identifier: Apache-2.0
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 
18 /** \addtogroup storage */
19 /** @{*/
20 
21 #ifndef MBED_LFSFILESYSTEM_H
22 #define MBED_LFSFILESYSTEM_H
23 
24 #include "filesystem/FileSystem.h"
25 #include "blockdevice/BlockDevice.h"
26 #include "platform/PlatformMutex.h"
27 #include "littlefs/lfs.h"
28 
29 namespace mbed {
30 
31 /**
32  * LittleFileSystem, a little file system
33  *
34  * Synchronization level: Thread safe
35  */
37 public:
38  /** Lifetime of the LittleFileSystem
39  *
40  * @param name Name of the file system in the tree.
41  * @param bd Block device to mount. Mounted immediately if not NULL.
42  * @param read_size
43  * Minimum size of a block read. This determines the size of read buffers.
44  * This may be larger than the physical read size to improve performance
45  * by caching more of the block device.
46  * @param prog_size
47  * Minimum size of a block program. This determines the size of program
48  * buffers. This may be larger than the physical program size to improve
49  * performance by caching more of the block device.
50  * @param block_size
51  * Size of an erasable block. This does not impact ram consumption and
52  * may be larger than the physical erase size. However, this should be
53  * kept small as each file currently takes up an entire block.
54  * @param lookahead
55  * Number of blocks to lookahead during block allocation. A larger
56  * lookahead reduces the number of passes required to allocate a block.
57  * The lookahead buffer requires only 1 bit per block so it can be quite
58  * large with little ram impact. Should be a multiple of 32.
59  */
60  LittleFileSystem(const char *name = NULL, mbed::BlockDevice *bd = NULL,
61  lfs_size_t read_size = MBED_LFS_READ_SIZE,
62  lfs_size_t prog_size = MBED_LFS_PROG_SIZE,
63  lfs_size_t block_size = MBED_LFS_BLOCK_SIZE,
64  lfs_size_t lookahead = MBED_LFS_LOOKAHEAD);
65 
66  virtual ~LittleFileSystem();
67 
68  /** Format a block device with the LittleFileSystem.
69  *
70  * The block device to format should be mounted when this function is called.
71  *
72  * @param bd This is the block device that will be formatted.
73  * @param read_size
74  * Minimum size of a block read. This determines the size of read buffers.
75  * This may be larger than the physical read size to improve performance
76  * by caching more of the block device.
77  * @param prog_size
78  * Minimum size of a block program. This determines the size of program
79  * buffers. This may be larger than the physical program size to improve
80  * performance by caching more of the block device.
81  * @param block_size
82  * Size of an erasable block. This does not impact ram consumption and
83  * may be larger than the physical erase size. However, this should be
84  * kept small as each file currently takes up an entire block.
85  * @param lookahead
86  * Number of blocks to lookahead during block allocation. A larger
87  * lookahead reduces the number of passes required to allocate a block.
88  * The lookahead buffer requires only 1 bit per block so it can be quite
89  * large with little ram impact. Should be a multiple of 32.
90  */
91  static int format(mbed::BlockDevice *bd,
92  lfs_size_t read_size = MBED_LFS_READ_SIZE,
93  lfs_size_t prog_size = MBED_LFS_PROG_SIZE,
94  lfs_size_t block_size = MBED_LFS_BLOCK_SIZE,
95  lfs_size_t lookahead = MBED_LFS_LOOKAHEAD);
96 
97  /** Mount a file system to a block device.
98  *
99  * @param bd Block device to mount to.
100  * @return 0 on success, negative error code on failure.
101  */
102  virtual int mount(mbed::BlockDevice *bd);
103 
104  /** Unmount a file system from the underlying block device.
105  *
106  * @return 0 on success, negative error code on failure
107  */
108  virtual int unmount();
109 
110  /** Reformat a file system. Results in an empty and mounted file system.
111  *
112  * @param bd
113  * Block device to reformat and mount. If NULL, the mounted
114  * Block device is used.
115  * Note: If mount fails, bd must be provided.
116  * Default: NULL
117  *
118  * @return 0 on success, negative error code on failure
119  */
120  virtual int reformat(mbed::BlockDevice *bd);
121 
122  /** Remove a file from the file system.
123  *
124  * @param path The name of the file to remove.
125  * @return 0 on success, negative error code on failure
126  */
127  virtual int remove(const char *path);
128 
129  /** Rename a file in the file system.
130  *
131  * @param path The name of the file to rename.
132  * @param newpath The name to rename it to.
133  * @return 0 on success, negative error code on failure
134  */
135  virtual int rename(const char *path, const char *newpath);
136 
137  /** Store information about the file in a stat structure
138  *
139  * @param path The name of the file to find information about.
140  * @param st The stat buffer to write to.
141  * @return 0 on success, negative error code on failure
142  */
143  virtual int stat(const char *path, struct stat *st);
144 
145  /** Create a directory in the file system.
146  *
147  * @param path The name of the directory to create.
148  * @param mode The permissions with which to create the directory.
149  * @return 0 on success, negative error code on failure
150  */
151  virtual int mkdir(const char *path, mode_t mode);
152 
153  /** Store information about the mounted file system in a statvfs structure.
154  *
155  * @param path The name of the file to find information about.
156  * @param buf The stat buffer to write to.
157  * @return 0 on success, negative error code on failure
158  */
159  virtual int statvfs(const char *path, struct statvfs *buf);
160 
161 protected:
162 #if !(DOXYGEN_ONLY)
163  /** Open a file on the file system.
164  *
165  * @param file Destination of the newly created handle to the referenced file.
166  * @param path The name of the file to open.
167  * @param flags The flags that trigger opening of the file. These flags are O_RDONLY, O_WRONLY, and O_RDWR,
168  * with an O_CREAT, O_TRUNC, or O_APPEND bitwise OR operator.
169  * @return 0 on success, negative error code on failure.
170  */
171  virtual int file_open(mbed::fs_file_t *file, const char *path, int flags);
172 
173  /** Close a file
174  *
175  * @param file File handle.
176  * return 0 on success, negative error code on failure
177  */
178  virtual int file_close(mbed::fs_file_t file);
179 
180  /** Read the contents of a file into a buffer
181  *
182  * @param file File handle.
183  * @param buffer The buffer to read in to.
184  * @param size The number of bytes to read.
185  * @return The number of bytes read, 0 at end of file, negative error on failure
186  */
187  virtual ssize_t file_read(mbed::fs_file_t file, void *buffer, size_t size);
188 
189  /** Write the contents of a buffer to a file
190  *
191  * @param file File handle.
192  * @param buffer The buffer to write from.
193  * @param size The number of bytes to write.
194  * @return The number of bytes written, negative error on failure
195  */
196  virtual ssize_t file_write(mbed::fs_file_t file, const void *buffer, size_t size);
197 
198  /** Flush any buffers associated with the file
199  *
200  * @param file File handle.
201  * @return 0 on success, negative error code on failure
202  */
203  virtual int file_sync(mbed::fs_file_t file);
204 
205  /** Move the file position to a given offset from a given location
206  *
207  * @param file File handle.
208  * @param offset The offset from whence to move to.
209  * @param whence The start of where to seek.
210  * SEEK_SET to start from beginning of file,
211  * SEEK_CUR to start from current position in file,
212  * SEEK_END to start from end of file.
213  * @return The new offset of the file
214  */
215  virtual off_t file_seek(mbed::fs_file_t file, off_t offset, int whence);
216 
217  /** Get the file position of the file
218  *
219  * @param file File handle.
220  * @return The current offset in the file
221  */
222  virtual off_t file_tell(mbed::fs_file_t file);
223 
224  /** Get the size of the file
225  *
226  * @param file File handle.
227  * @return Size of the file in bytes
228  */
229  virtual off_t file_size(mbed::fs_file_t file);
230 
231  /** Truncate or extend a file.
232  *
233  * The file's length is set to the specified value. The seek pointer is
234  * not changed. If the file is extended, the extended area appears as if
235  * it were zero-filled.
236  *
237  * @param file File handle.
238  * @param length The requested new length for the file
239  *
240  * @return Zero on success, negative error code on failure
241  */
242  virtual int file_truncate(mbed::fs_file_t file, off_t length);
243 
244  /** Open a directory on the file system.
245  *
246  * @param dir Destination for the handle to the directory.
247  * @param path Name of the directory to open.
248  * @return 0 on success, negative error code on failure
249  */
250  virtual int dir_open(mbed::fs_dir_t *dir, const char *path);
251 
252  /** Close a directory
253  *
254  * @param dir Dir handle.
255  * return 0 on success, negative error code on failure
256  */
257  virtual int dir_close(mbed::fs_dir_t dir);
258 
259  /** Read the next directory entry
260  *
261  * @param dir Dir handle.
262  * @param ent The directory entry to fill out.
263  * @return 1 on reading a filename, 0 at end of directory, negative error on failure
264  */
265  virtual ssize_t dir_read(mbed::fs_dir_t dir, struct dirent *ent);
266 
267  /** Set the current position of the directory
268  *
269  * @param dir Dir handle.
270  * @param offset Offset of the location to seek to,
271  * must be a value returned from dir_tell
272  */
273  virtual void dir_seek(mbed::fs_dir_t dir, off_t offset);
274 
275  /** Get the current position of the directory
276  *
277  * @param dir Dir handle.
278  * @return Position of the directory that can be passed to dir_rewind
279  */
280  virtual off_t dir_tell(mbed::fs_dir_t dir);
281 
282  /** Rewind the current position to the beginning of the directory
283  *
284  * @param dir Dir handle
285  */
286  virtual void dir_rewind(mbed::fs_dir_t dir);
287 #endif //!(DOXYGEN_ONLY)
288 
289 private:
290  lfs_t _lfs; // The actual file system
291  struct lfs_config _config;
292  mbed::BlockDevice *_bd; // The block device
293 
294  // default parameters
295  const lfs_size_t _read_size;
296  const lfs_size_t _prog_size;
297  const lfs_size_t _block_size;
298  const lfs_size_t _lookahead;
299 
300  // thread-safe locking
301  PlatformMutex _mutex;
302 };
303 
304 } // namespace mbed
305 
306 // Added "using" for backwards compatibility
307 #ifndef MBED_NO_GLOBAL_USING_DIRECTIVE
309 #endif
310 
311 #endif
312 
313 /** @}*/
virtual int reformat(mbed::BlockDevice *bd)
Reformat a file system.
virtual int mount(mbed::BlockDevice *bd)
Mount a file system to a block device.
A hardware device capable of writing and reading blocks.
Definition: BlockDevice.h:48
LittleFileSystem(const char *name=NULL, mbed::BlockDevice *bd=NULL, lfs_size_t read_size=MBED_LFS_READ_SIZE, lfs_size_t prog_size=MBED_LFS_PROG_SIZE, lfs_size_t block_size=MBED_LFS_BLOCK_SIZE, lfs_size_t lookahead=MBED_LFS_LOOKAHEAD)
Lifetime of the LittleFileSystem.
static int format(mbed::BlockDevice *bd, lfs_size_t read_size=MBED_LFS_READ_SIZE, lfs_size_t prog_size=MBED_LFS_PROG_SIZE, lfs_size_t block_size=MBED_LFS_BLOCK_SIZE, lfs_size_t lookahead=MBED_LFS_LOOKAHEAD)
Format a block device with the LittleFileSystem.
virtual int rename(const char *path, const char *newpath)
Rename a file in the file system.
The PlatformMutex class is used to synchronize the execution of threads.
Definition: PlatformMutex.h:47
virtual int unmount()
Unmount a file system from the underlying block device.
virtual int stat(const char *path, struct stat *st)
Store information about the file in a stat structure.
virtual int mkdir(const char *path, mode_t mode)
Create a directory in the file system.
A file system object.
Definition: FileSystem.h:50
Definition: lfs.h:277
LittleFileSystem, a little file system.
Definition: ATHandler.h:46
virtual int statvfs(const char *path, struct statvfs *buf)
Store information about the mounted file system in a statvfs structure.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.