Mistake on this page?
Report an issue in GitHub or email us
LittleFileSystem2.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_LFS2FILESYSTEM_H
21 #define MBED_LFS2FILESYSTEM_H
22 
23 #include "FileSystem.h"
24 #include "BlockDevice.h"
25 #include "PlatformMutex.h"
26 #include "lfs2.h"
27 
28 namespace mbed {
29 
30 /**
31  * LittleFileSystem2, a little file system
32  *
33  * Synchronization level: Thread safe
34  */
36 public:
37  /** Lifetime of the LittleFileSystem2
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 block_size
42  * Size of a logical block. This does not impact ram consumption and
43  * may be larger than the physical erase block. If the physical erase
44  * block is larger, littlefs will use that instead. Larger values will
45  * be faster but waste more storage when files are not aligned to a
46  * block size.
47  * @param block_cycles
48  * Number of erase cycles before a block is forcefully evicted. Larger
49  * values are more efficient but cause less even wear distribution. 0
50  * disables dynamic wear-leveling.
51  * @param cache_size
52  * Size of read/program caches. Each file uses 1 cache, and littlefs
53  * allocates 2 caches for internal operations. Larger values should be
54  * faster but uses more RAM.
55  * @param lookahead_size
56  * Size of the lookahead buffer. A larger lookahead reduces the
57  * allocation scans and results in a faster filesystem but uses
58  * more RAM.
59  */
60  LittleFileSystem2(const char *name = NULL, mbed::BlockDevice *bd = NULL,
61  lfs2_size_t block_size = MBED_LFS2_BLOCK_SIZE,
62  uint32_t block_cycles = MBED_LFS2_BLOCK_CYCLES,
63  lfs2_size_t cache_size = MBED_LFS2_CACHE_SIZE,
64  lfs2_size_t lookahead = MBED_LFS2_LOOKAHEAD_SIZE);
65 
66  virtual ~LittleFileSystem2();
67 
68  /** Format a block device with the LittleFileSystem2.
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 block_size
74  * Size of a logical block. This does not impact ram consumption and
75  * may be larger than the physical erase block. If the physical erase
76  * block is larger, littlefs will use that instead. Larger values will
77  * be faster but waste more storage when files are not aligned to a
78  * block size.
79  * @param block_cycles
80  * Number of erase cycles before a block is forcefully evicted. Larger
81  * values are more efficient but cause less even wear distribution. 0
82  * disables dynamic wear-leveling.
83  * @param cache_size
84  * Size of read/program caches. Each file uses 1 cache, and littlefs
85  * allocates 2 caches for internal operations. Larger values should be
86  * faster but uses more RAM.
87  * @param lookahead_size
88  * Size of the lookahead buffer. A larger lookahead reduces the
89  * allocation scans and results in a faster filesystem but uses
90  * more RAM.
91  */
92  static int format(mbed::BlockDevice *bd,
93  lfs2_size_t block_size = MBED_LFS2_BLOCK_SIZE,
94  uint32_t block_cycles = MBED_LFS2_BLOCK_CYCLES,
95  lfs2_size_t cache_size = MBED_LFS2_CACHE_SIZE,
96  lfs2_size_t lookahead_size = MBED_LFS2_LOOKAHEAD_SIZE);
97 
98  /** Mount a file system to a block device.
99  *
100  * @param bd Block device to mount to.
101  * @return 0 on success, negative error code on failure.
102  */
103  virtual int mount(mbed::BlockDevice *bd);
104 
105  /** Unmount a file system from the underlying block device.
106  *
107  * @return 0 on success, negative error code on failure
108  */
109  virtual int unmount();
110 
111  /** Reformat a file system. Results in an empty and mounted file system.
112  *
113  * @param bd
114  * Block device to reformat and mount. If NULL, the mounted
115  * Block device is used.
116  * Note: If mount fails, bd must be provided.
117  * Default: NULL
118  *
119  * @return 0 on success, negative error code on failure
120  */
121  virtual int reformat(mbed::BlockDevice *bd);
122 
123  /** Remove a file from the file system.
124  *
125  * @param path The name of the file to remove.
126  * @return 0 on success, negative error code on failure
127  */
128  virtual int remove(const char *path);
129 
130  /** Rename a file in the file system.
131  *
132  * @param path The name of the file to rename.
133  * @param newpath The name to rename it to.
134  * @return 0 on success, negative error code on failure
135  */
136  virtual int rename(const char *path, const char *newpath);
137 
138  /** Store information about the file in a stat structure
139  *
140  * @param path The name of the file to find information about.
141  * @param st The stat buffer to write to.
142  * @return 0 on success, negative error code on failure
143  */
144  virtual int stat(const char *path, struct stat *st);
145 
146  /** Create a directory in the file system.
147  *
148  * @param path The name of the directory to create.
149  * @param mode The permissions with which to create the directory.
150  * @return 0 on success, negative error code on failure
151  */
152  virtual int mkdir(const char *path, mode_t mode);
153 
154  /** Store information about the mounted file system in a statvfs structure.
155  *
156  * @param path The name of the file to find information about.
157  * @param buf The stat buffer to write to.
158  * @return 0 on success, negative error code on failure
159  */
160  virtual int statvfs(const char *path, struct statvfs *buf);
161 
162 protected:
163 #if !(DOXYGEN_ONLY)
164  /** Open a file on the file system.
165  *
166  * @param file Destination of the newly created handle to the referenced file.
167  * @param path The name of the file to open.
168  * @param flags The flags that trigger opening of the file. These flags are O_RDONLY, O_WRONLY, and O_RDWR,
169  * with an O_CREAT, O_TRUNC, or O_APPEND bitwise OR operator.
170  * @return 0 on success, negative error code on failure.
171  */
172  virtual int file_open(mbed::fs_file_t *file, const char *path, int flags);
173 
174  /** Close a file
175  *
176  * @param file File handle.
177  * return 0 on success, negative error code on failure
178  */
179  virtual int file_close(mbed::fs_file_t file);
180 
181  /** Read the contents of a file into a buffer
182  *
183  * @param file File handle.
184  * @param buffer The buffer to read in to.
185  * @param size The number of bytes to read.
186  * @return The number of bytes read, 0 at end of file, negative error on failure
187  */
188  virtual ssize_t file_read(mbed::fs_file_t file, void *buffer, size_t size);
189 
190  /** Write the contents of a buffer to a file
191  *
192  * @param file File handle.
193  * @param buffer The buffer to write from.
194  * @param size The number of bytes to write.
195  * @return The number of bytes written, negative error on failure
196  */
197  virtual ssize_t file_write(mbed::fs_file_t file, const void *buffer, size_t size);
198 
199  /** Flush any buffers associated with the file
200  *
201  * @param file File handle.
202  * @return 0 on success, negative error code on failure
203  */
204  virtual int file_sync(mbed::fs_file_t file);
205 
206  /** Move the file position to a given offset from a given location
207  *
208  * @param file File handle.
209  * @param offset The offset from whence to move to.
210  * @param whence The start of where to seek.
211  * SEEK_SET to start from beginning of file,
212  * SEEK_CUR to start from current position in file,
213  * SEEK_END to start from end of file.
214  * @return The new offset of the file
215  */
216  virtual off_t file_seek(mbed::fs_file_t file, off_t offset, int whence);
217 
218  /** Get the file position of the file
219  *
220  * @param file File handle.
221  * @return The current offset in the file
222  */
223  virtual off_t file_tell(mbed::fs_file_t file);
224 
225  /** Get the size of the file
226  *
227  * @param file File handle.
228  * @return Size of the file in bytes
229  */
230  virtual off_t file_size(mbed::fs_file_t file);
231 
232  /** Truncate or extend a file.
233  *
234  * The file's length is set to the specified value. The seek pointer is
235  * not changed. If the file is extended, the extended area appears as if
236  * it were zero-filled.
237  *
238  * @param file File handle.
239  * @param length The requested new length for the file
240  *
241  * @return Zero on success, negative error code on failure
242  */
243  virtual int file_truncate(mbed::fs_file_t file, off_t length);
244 
245  /** Open a directory on the file system.
246  *
247  * @param dir Destination for the handle to the directory.
248  * @param path Name of the directory to open.
249  * @return 0 on success, negative error code on failure
250  */
251  virtual int dir_open(mbed::fs_dir_t *dir, const char *path);
252 
253  /** Close a directory
254  *
255  * @param dir Dir handle.
256  * return 0 on success, negative error code on failure
257  */
258  virtual int dir_close(mbed::fs_dir_t dir);
259 
260  /** Read the next directory entry
261  *
262  * @param dir Dir handle.
263  * @param ent The directory entry to fill out.
264  * @return 1 on reading a filename, 0 at end of directory, negative error on failure
265  */
266  virtual ssize_t dir_read(mbed::fs_dir_t dir, struct dirent *ent);
267 
268  /** Set the current position of the directory
269  *
270  * @param dir Dir handle.
271  * @param offset Offset of the location to seek to,
272  * must be a value returned from dir_tell
273  */
274  virtual void dir_seek(mbed::fs_dir_t dir, off_t offset);
275 
276  /** Get the current position of the directory
277  *
278  * @param dir Dir handle.
279  * @return Position of the directory that can be passed to dir_rewind
280  */
281  virtual off_t dir_tell(mbed::fs_dir_t dir);
282 
283  /** Rewind the current position to the beginning of the directory
284  *
285  * @param dir Dir handle
286  */
287  virtual void dir_rewind(mbed::fs_dir_t dir);
288 #endif //!(DOXYGEN_ONLY)
289 
290 private:
291  lfs2_t _lfs; // The actual file system
292  struct lfs2_config _config;
293  mbed::BlockDevice *_bd; // The block device
294 
295  // thread-safe locking
296  PlatformMutex _mutex;
297 };
298 
299 } // namespace mbed
300 
301 // Added "using" for backwards compatibility
302 #ifndef MBED_NO_GLOBAL_USING_DIRECTIVE
304 #endif
305 
306 #endif
307 
308 /** @}*/
Definition: lfs2.h:364
LittleFileSystem2(const char *name=NULL, mbed::BlockDevice *bd=NULL, lfs2_size_t block_size=MBED_LFS2_BLOCK_SIZE, uint32_t block_cycles=MBED_LFS2_BLOCK_CYCLES, lfs2_size_t cache_size=MBED_LFS2_CACHE_SIZE, lfs2_size_t lookahead=MBED_LFS2_LOOKAHEAD_SIZE)
Lifetime of the LittleFileSystem2.
A hardware device capable of writing and reading blocks.
Definition: BlockDevice.h:47
virtual int mount(mbed::BlockDevice *bd)
Mount a file system to a block device.
virtual int stat(const char *path, struct stat *st)
Store information about the file in a stat structure.
virtual int reformat(mbed::BlockDevice *bd)
Reformat a file system.
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 mkdir(const char *path, mode_t mode)
Create a directory in the file system.
static int format(mbed::BlockDevice *bd, lfs2_size_t block_size=MBED_LFS2_BLOCK_SIZE, uint32_t block_cycles=MBED_LFS2_BLOCK_CYCLES, lfs2_size_t cache_size=MBED_LFS2_CACHE_SIZE, lfs2_size_t lookahead_size=MBED_LFS2_LOOKAHEAD_SIZE)
Format a block device with the LittleFileSystem2.
A file system object.
Definition: FileSystem.h:49
virtual int statvfs(const char *path, struct statvfs *buf)
Store information about the mounted file system in a statvfs structure.
LittleFileSystem2, a little file system.
Definition: ATHandler.h:46
virtual int unmount()
Unmount a file system from the underlying block device.
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.