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