Kev Mann / mbed-dev-OS5_10_4

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

features/storage/filesystem/littlefs/README.md@2:7aab896b1a3b, 2019-03-13 (annotated)

Committer:
kevman
Date:
Wed Mar 13 11:03:24 2019 +0000
Revision:
2:7aab896b1a3b
Parent:
0:38ceb79fef03 
2019-03-13

Who changed what in which revision?

UserRevisionLine numberNew contents of line
kevman 0:38ceb79fef03 1 ## Mbed OS API for the little filesystem
kevman 0:38ceb79fef03 2
kevman 0:38ceb79fef03 3 This is the Mbed OS API for littlefs, a little fail-safe filesystem
kevman 0:38ceb79fef03 4 designed for embedded systems.
kevman 0:38ceb79fef03 5
kevman 0:38ceb79fef03 6 ```
kevman 0:38ceb79fef03 7 | | | .---._____
kevman 0:38ceb79fef03 8 .-----. | |
kevman 0:38ceb79fef03 9 --|o |---| littlefs |
kevman 0:38ceb79fef03 10 --| |---| |
kevman 0:38ceb79fef03 11 '-----' '----------'
kevman 0:38ceb79fef03 12 | | |
kevman 0:38ceb79fef03 13 ```
kevman 0:38ceb79fef03 14
kevman 0:38ceb79fef03 15 **Bounded RAM/ROM** - The littlefs is designed to work with a limited amount
kevman 0:38ceb79fef03 16 of memory. Recursion is avoided, and dynamic memory is limited to configurable
kevman 0:38ceb79fef03 17 buffers that can be provided statically.
kevman 0:38ceb79fef03 18
kevman 0:38ceb79fef03 19 **Power-loss resilient** - The littlefs is designed for systems that may have
kevman 0:38ceb79fef03 20 random power failures. The littlefs has strong copy-on-write guarantees, and
kevman 0:38ceb79fef03 21 storage on disk is always kept in a valid state.
kevman 0:38ceb79fef03 22
kevman 0:38ceb79fef03 23 **Wear leveling** - Because the most common form of embedded storage is erodible
kevman 0:38ceb79fef03 24 flash memories, littlefs provides a form of dynamic wear leveling for systems
kevman 0:38ceb79fef03 25 that cannot fit a full flash translation layer.
kevman 0:38ceb79fef03 26
kevman 0:38ceb79fef03 27 ## Usage
kevman 0:38ceb79fef03 28
kevman 0:38ceb79fef03 29 If you are already using a filesystem in Mbed, adopting the littlefs should
kevman 0:38ceb79fef03 30 just require a name change to use the [LittleFileSystem](LittleFileSystem.h)
kevman 0:38ceb79fef03 31 class.
kevman 0:38ceb79fef03 32
kevman 0:38ceb79fef03 33 Here is a simple example that updates a file named "boot_count" every time
kevman 0:38ceb79fef03 34 the application runs:
kevman 0:38ceb79fef03 35 ``` c++
kevman 0:38ceb79fef03 36 #include "LittleFileSystem.h"
kevman 0:38ceb79fef03 37 #include "SPIFBlockDevice.h"
kevman 0:38ceb79fef03 38
kevman 0:38ceb79fef03 39 // Physical block device, can be any device that supports the BlockDevice API
kevman 0:38ceb79fef03 40 SPIFBlockDevice bd(PTE2, PTE4, PTE1, PTE5);
kevman 0:38ceb79fef03 41
kevman 0:38ceb79fef03 42 // Storage for the littlefs
kevman 0:38ceb79fef03 43 LittleFileSystem fs("fs");
kevman 0:38ceb79fef03 44
kevman 0:38ceb79fef03 45 // Entry point
kevman 0:38ceb79fef03 46 int main() {
kevman 0:38ceb79fef03 47 // Mount the filesystem
kevman 0:38ceb79fef03 48 int err = fs.mount(&bd);
kevman 0:38ceb79fef03 49 if (err) {
kevman 0:38ceb79fef03 50 // Reformat if we can't mount the filesystem,
kevman 0:38ceb79fef03 51 // this should only happen on the first boot
kevman 0:38ceb79fef03 52 LittleFileSystem::format(&bd);
kevman 0:38ceb79fef03 53 fs.mount(&bd);
kevman 0:38ceb79fef03 54 }
kevman 0:38ceb79fef03 55
kevman 0:38ceb79fef03 56 // Read the boot count
kevman 0:38ceb79fef03 57 uint32_t boot_count = 0;
kevman 0:38ceb79fef03 58 FILE *f = fopen("/fs/boot_count", "r+");
kevman 0:38ceb79fef03 59 if (!f) {
kevman 0:38ceb79fef03 60 // Create the file if it doesn't exist
kevman 0:38ceb79fef03 61 f = fopen("/fs/boot_count", "w+");
kevman 0:38ceb79fef03 62 }
kevman 0:38ceb79fef03 63 fread(&boot_count, sizeof(boot_count), 1, f);
kevman 0:38ceb79fef03 64
kevman 0:38ceb79fef03 65 // Update the boot count
kevman 0:38ceb79fef03 66 boot_count += 1;
kevman 0:38ceb79fef03 67 rewind(f);
kevman 0:38ceb79fef03 68 fwrite(&boot_count, sizeof(boot_count), 1, f);
kevman 0:38ceb79fef03 69
kevman 0:38ceb79fef03 70 // Remember that storage may not be updated until the file
kevman 0:38ceb79fef03 71 // is closed successfully
kevman 0:38ceb79fef03 72 fclose(f);
kevman 0:38ceb79fef03 73
kevman 0:38ceb79fef03 74 // Release any resources we were using
kevman 0:38ceb79fef03 75 fs.unmount();
kevman 0:38ceb79fef03 76
kevman 0:38ceb79fef03 77 // Print the boot count
kevman 0:38ceb79fef03 78 printf("boot_count: %ld\n", boot_count);
kevman 0:38ceb79fef03 79 }
kevman 0:38ceb79fef03 80 ```
kevman 0:38ceb79fef03 81
kevman 0:38ceb79fef03 82 ## Reference material
kevman 0:38ceb79fef03 83
kevman 0:38ceb79fef03 84 [DESIGN.md](littlefs/DESIGN.md) - DESIGN.md contains a fully detailed dive into
kevman 0:38ceb79fef03 85 how littlefs actually works. We encourage you to read it because the
kevman 0:38ceb79fef03 86 solutions and tradeoffs at work here are quite interesting.
kevman 0:38ceb79fef03 87
kevman 0:38ceb79fef03 88 [SPEC.md](littlefs/SPEC.md) - SPEC.md contains the on-disk specification of
kevman 0:38ceb79fef03 89 littlefs with all the nitty-gritty details. This can be useful for developing
kevman 0:38ceb79fef03 90 tooling.
kevman 0:38ceb79fef03 91
kevman 0:38ceb79fef03 92 ## Related projects
kevman 0:38ceb79fef03 93
kevman 0:38ceb79fef03 94 [littlefs](https://github.com/geky/littlefs) - Where the core of littlefs
kevman 0:38ceb79fef03 95 currently lives.
kevman 0:38ceb79fef03 96
kevman 0:38ceb79fef03 97 [littlefs-fuse](https://github.com/geky/littlefs-fuse) - A [FUSE](https://github.com/libfuse/libfuse)
kevman 0:38ceb79fef03 98 wrapper for littlefs. The project allows you to mount littlefs directly in a
kevman 0:38ceb79fef03 99 Linux machine. This can be useful for debugging littlefs if you have an SD card
kevman 0:38ceb79fef03 100 handy.
kevman 0:38ceb79fef03 101
kevman 0:38ceb79fef03 102 [littlefs-js](https://github.com/geky/littlefs-js) - A JavaScript wrapper for
kevman 0:38ceb79fef03 103 littlefs. I'm not sure why you would want this, but it is handy for demos.
kevman 0:38ceb79fef03 104 You can see it in action [here](http://littlefs.geky.net/demo.html).