Nicolas Borla / Mbed OS BBR_1Ebene

BBR 1 Ebene

mbed-os/features/filesystem/littlefs/README.md@0:fbdae7e6d805, 2018-05-14 (annotated)

Committer:
borlanic
Date:
Mon May 14 11:29:06 2018 +0000
Revision:
0:fbdae7e6d805
BBR

Who changed what in which revision?

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