{"id":26400079,"url":"https://github.com/ARMmbed/littlefs","last_synced_at":"2025-03-17T14:01:15.617Z","repository":{"id":37676421,"uuid":"83160811","full_name":"littlefs-project/littlefs","owner":"littlefs-project","description":"A little fail-safe filesystem designed for microcontrollers","archived":false,"fork":false,"pushed_at":"2024-10-04T18:46:06.000Z","size":7495,"stargazers_count":5175,"open_issues_count":536,"forks_count":794,"subscribers_count":149,"default_branch":"master","last_synced_at":"2024-10-29T15:04:16.447Z","etag":null,"topics":["embedded","filesystem","microcontroller"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/littlefs-project.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-02-25T20:33:13.000Z","updated_at":"2024-10-27T20:17:54.000Z","dependencies_parsed_at":"2023-10-25T20:32:04.592Z","dependency_job_id":"93abc187-87e9-482c-a9cc-8d77052cfebd","html_url":"https://github.com/littlefs-project/littlefs","commit_stats":{"total_commits":716,"total_committers":70,"mean_commits":"10.228571428571428","dds":0.38268156424581,"last_synced_commit":"d01280e64934a09ba16cac60cf9d3a37e228bb66"},"previous_names":["armmbed/littlefs"],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/littlefs-project%2Flittlefs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/littlefs-project%2Flittlefs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/littlefs-project%2Flittlefs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/littlefs-project%2Flittlefs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/littlefs-project","download_url":"https://codeload.github.com/littlefs-project/littlefs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244047608,"owners_count":20389205,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["embedded","filesystem","microcontroller"],"created_at":"2025-03-17T14:00:39.230Z","updated_at":"2025-03-17T14:01:15.553Z","avatar_url":"https://github.com/littlefs-project.png","language":"C","readme":"## littlefs\n\nA little fail-safe filesystem designed for microcontrollers.\n\n```\n   | | |     .---._____\n  .-----.   |          |\n--|o    |---| littlefs |\n--|     |---|          |\n  '-----'   '----------'\n   | | |\n```\n\n**Power-loss resilience** - littlefs is designed to handle random power\nfailures. All file operations have strong copy-on-write guarantees and if\npower is lost the filesystem will fall back to the last known good state.\n\n**Dynamic wear leveling** - littlefs is designed with flash in mind, and\nprovides wear leveling over dynamic blocks. Additionally, littlefs can\ndetect bad blocks and work around them.\n\n**Bounded RAM/ROM** - littlefs is designed to work with a small amount of\nmemory. RAM usage is strictly bounded, which means RAM consumption does not\nchange as the filesystem grows. The filesystem contains no unbounded\nrecursion and dynamic memory is limited to configurable buffers that can be\nprovided statically.\n\n## Example\n\nHere's a simple example that updates a file named `boot_count` every time\nmain runs. The program can be interrupted at any time without losing track\nof how many times it has been booted and without corrupting the filesystem:\n\n``` c\n#include \"lfs.h\"\n\n// variables used by the filesystem\nlfs_t lfs;\nlfs_file_t file;\n\n// configuration of the filesystem is provided by this struct\nconst struct lfs_config cfg = {\n    // block device operations\n    .read  = user_provided_block_device_read,\n    .prog  = user_provided_block_device_prog,\n    .erase = user_provided_block_device_erase,\n    .sync  = user_provided_block_device_sync,\n\n    // block device configuration\n    .read_size = 16,\n    .prog_size = 16,\n    .block_size = 4096,\n    .block_count = 128,\n    .cache_size = 16,\n    .lookahead_size = 16,\n    .block_cycles = 500,\n};\n\n// entry point\nint main(void) {\n    // mount the filesystem\n    int err = lfs_mount(\u0026lfs, \u0026cfg);\n\n    // reformat if we can't mount the filesystem\n    // this should only happen on the first boot\n    if (err) {\n        lfs_format(\u0026lfs, \u0026cfg);\n        lfs_mount(\u0026lfs, \u0026cfg);\n    }\n\n    // read current count\n    uint32_t boot_count = 0;\n    lfs_file_open(\u0026lfs, \u0026file, \"boot_count\", LFS_O_RDWR | LFS_O_CREAT);\n    lfs_file_read(\u0026lfs, \u0026file, \u0026boot_count, sizeof(boot_count));\n\n    // update boot count\n    boot_count += 1;\n    lfs_file_rewind(\u0026lfs, \u0026file);\n    lfs_file_write(\u0026lfs, \u0026file, \u0026boot_count, sizeof(boot_count));\n\n    // remember the storage is not updated until the file is closed successfully\n    lfs_file_close(\u0026lfs, \u0026file);\n\n    // release any resources we were using\n    lfs_unmount(\u0026lfs);\n\n    // print the boot count\n    printf(\"boot_count: %d\\n\", boot_count);\n}\n```\n\n## Usage\n\nDetailed documentation (or at least as much detail as is currently available)\ncan be found in the comments in [lfs.h](lfs.h).\n\nlittlefs takes in a configuration structure that defines how the filesystem\noperates. The configuration struct provides the filesystem with the block\ndevice operations and dimensions, tweakable parameters that tradeoff memory\nusage for performance, and optional static buffers if the user wants to avoid\ndynamic memory.\n\nThe state of the littlefs is stored in the `lfs_t` type which is left up\nto the user to allocate, allowing multiple filesystems to be in use\nsimultaneously. With the `lfs_t` and configuration struct, a user can\nformat a block device or mount the filesystem.\n\nOnce mounted, the littlefs provides a full set of POSIX-like file and\ndirectory functions, with the deviation that the allocation of filesystem\nstructures must be provided by the user.\n\nAll POSIX operations, such as remove and rename, are atomic, even in event\nof power-loss. Additionally, file updates are not actually committed to\nthe filesystem until sync or close is called on the file.\n\n## Other notes\n\nLittlefs is written in C, and specifically should compile with any compiler\nthat conforms to the `C99` standard.\n\nAll littlefs calls have the potential to return a negative error code. The\nerrors can be either one of those found in the `enum lfs_error` in\n[lfs.h](lfs.h), or an error returned by the user's block device operations.\n\nIn the configuration struct, the `prog` and `erase` function provided by the\nuser may return a `LFS_ERR_CORRUPT` error if the implementation already can\ndetect corrupt blocks. However, the wear leveling does not depend on the return\ncode of these functions, instead all data is read back and checked for\nintegrity.\n\nIf your storage caches writes, make sure that the provided `sync` function\nflushes all the data to memory and ensures that the next read fetches the data\nfrom memory, otherwise data integrity can not be guaranteed. If the `write`\nfunction does not perform caching, and therefore each `read` or `write` call\nhits the memory, the `sync` function can simply return 0.\n\n## Design\n\nAt a high level, littlefs is a block based filesystem that uses small logs to\nstore metadata and larger copy-on-write (COW) structures to store file data.\n\nIn littlefs, these ingredients form a sort of two-layered cake, with the small\nlogs (called metadata pairs) providing fast updates to metadata anywhere on\nstorage, while the COW structures store file data compactly and without any\nwear amplification cost.\n\nBoth of these data structures are built out of blocks, which are fed by a\ncommon block allocator. By limiting the number of erases allowed on a block\nper allocation, the allocator provides dynamic wear leveling over the entire\nfilesystem.\n\n```\n                    root\n                   .--------.--------.\n                   | A'| B'|         |\n                   |   |   |-\u003e       |\n                   |   |   |         |\n                   '--------'--------'\n                .----'   '--------------.\n       A       v                 B       v\n      .--------.--------.       .--------.--------.\n      | C'| D'|         |       | E'|new|         |\n      |   |   |-\u003e       |       |   | E'|-\u003e       |\n      |   |   |         |       |   |   |         |\n      '--------'--------'       '--------'--------'\n      .-'   '--.                  |   '------------------.\n     v          v              .-'                        v\n.--------.  .--------.        v                       .--------.\n|   C    |  |   D    |   .--------.       write       | new E  |\n|        |  |        |   |   E    |        ==\u003e        |        |\n|        |  |        |   |        |                   |        |\n'--------'  '--------'   |        |                   '--------'\n                         '--------'                   .-'    |\n                         .-'    '-.    .-------------|------'\n                        v          v  v              v\n                   .--------.  .--------.       .--------.\n                   |   F    |  |   G    |       | new F  |\n                   |        |  |        |       |        |\n                   |        |  |        |       |        |\n                   '--------'  '--------'       '--------'\n```\n\nMore details on how littlefs works can be found in [DESIGN.md](DESIGN.md) and\n[SPEC.md](SPEC.md).\n\n- [DESIGN.md](DESIGN.md) - A fully detailed dive into how littlefs works.\n  I would suggest reading it as the tradeoffs at work are quite interesting.\n\n- [SPEC.md](SPEC.md) - The on-disk specification of littlefs with all the\n  nitty-gritty details. May be useful for tooling development.\n\n## Testing\n\nThe littlefs comes with a test suite designed to run on a PC using the\n[emulated block device](bd/lfs_testbd.h) found in the `bd` directory.\nThe tests assume a Linux environment and can be started with make:\n\n``` bash\nmake test\n```\n\n## License\n\nThe littlefs is provided under the [BSD-3-Clause] license. See\n[LICENSE.md](LICENSE.md) for more information. Contributions to this project\nare accepted under the same license.\n\nIndividual files contain the following tag instead of the full license text.\n\n    SPDX-License-Identifier:    BSD-3-Clause\n\nThis enables machine processing of license information based on the SPDX\nLicense Identifiers that are here available: http://spdx.org/licenses/\n\n## Related projects\n\n- [littlefs-fuse] - A [FUSE] wrapper for littlefs. The project allows you to\n  mount littlefs directly on a Linux machine. Can be useful for debugging\n  littlefs if you have an SD card handy.\n\n- [littlefs-js] - A javascript wrapper for littlefs. I'm not sure why you would\n  want this, but it is handy for demos.  You can see it in action\n  [here][littlefs-js-demo].\n  \n- [littlefs-python] - A Python wrapper for littlefs. The project allows you\n  to create images of the filesystem on your PC. Check if littlefs will fit\n  your needs, create images for a later download to the target memory or\n  inspect the content of a binary image of the target memory.\n  \n- [littlefs2-rust] - A Rust wrapper for littlefs. This project allows you\n  to use littlefs in a Rust-friendly API, reaping the benefits of Rust's memory\n  safety and other guarantees.\n\n- [nim-littlefs] - A Nim wrapper and API for littlefs. Includes a fuse\n  implementation based on [littlefs-fuse]\n\n- [chamelon] - A pure-OCaml implementation of (most of) littlefs, designed for\n  use with the MirageOS library operating system project. It is interoperable\n  with the reference implementation, with some caveats.\n\n- [littlefs-disk-img-viewer] - A memory-efficient web application for viewing\n  littlefs disk images in your web browser.\n\n- [mklfs] - A command line tool for creating littlefs images. Used in the Lua\n  RTOS ecosystem.\n\n- [mklittlefs] - A command line tool for creating littlefs images. Used in the\n  ESP8266 and RP2040 ecosystem.\n\n- [pico-littlefs-usb] - An interface for littlefs that emulates a FAT12\n  filesystem over USB. Allows mounting littlefs on a host PC without additional\n  drivers.\n\n- [ramcrc32bd] - An example block device using littlefs's 32-bit CRC for\n  error-correction.\n\n- [ramrsbd] - An example block device using Reed-Solomon codes for\n  error-correction.\n\n- [Mbed OS] - The easiest way to get started with littlefs is to jump into Mbed\n  which already has block device drivers for most forms of embedded storage.\n  littlefs is available in Mbed OS as the [LittleFileSystem] class.\n\n- [SPIFFS] - Another excellent embedded filesystem for NOR flash. As a more\n  traditional logging filesystem with full static wear-leveling, SPIFFS will\n  likely outperform littlefs on small memories such as the internal flash on\n  microcontrollers.\n\n- [Dhara] - An interesting NAND flash translation layer designed for small\n  MCUs. It offers static wear-leveling and power-resilience with only a fixed\n  _O(|address|)_ pointer structure stored on each block and in RAM.\n\n- [ChaN's FatFs] - A lightweight reimplementation of the infamous FAT filesystem\n  for microcontroller-scale devices. Due to limitations of FAT it can't provide\n  power-loss resilience, but it does allow easy interop with PCs.\n\n[BSD-3-Clause]: https://spdx.org/licenses/BSD-3-Clause.html\n[littlefs-fuse]: https://github.com/geky/littlefs-fuse\n[FUSE]: https://github.com/libfuse/libfuse\n[littlefs-js]: https://github.com/geky/littlefs-js\n[littlefs-js-demo]:http://littlefs.geky.net/demo.html\n[littlefs-python]: https://pypi.org/project/littlefs-python/\n[littlefs2-rust]: https://crates.io/crates/littlefs2\n[nim-littlefs]: https://github.com/Graveflo/nim-littlefs\n[chamelon]: https://github.com/yomimono/chamelon\n[littlefs-disk-img-viewer]: https://github.com/tniessen/littlefs-disk-img-viewer\n[mklfs]: https://github.com/whitecatboard/Lua-RTOS-ESP32/tree/master/components/mklfs/src\n[mklittlefs]: https://github.com/earlephilhower/mklittlefs\n[pico-littlefs-usb]: https://github.com/oyama/pico-littlefs-usb\n[ramcrc32bd]: https://github.com/geky/ramcrc32bd\n[ramrsbd]: https://github.com/geky/ramrsbd\n[Mbed OS]: https://github.com/armmbed/mbed-os\n[LittleFileSystem]: https://os.mbed.com/docs/mbed-os/latest/apis/littlefilesystem.html\n[SPIFFS]: https://github.com/pellepl/spiffs\n[Dhara]: https://github.com/dlbeer/dhara\n[ChaN's FatFs]: http://elm-chan.org/fsw/ff/00index_e.html\n","funding_links":[],"categories":["C Libraries","C++"],"sub_categories":["Filesystems (Or Similar)"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FARMmbed%2Flittlefs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FARMmbed%2Flittlefs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FARMmbed%2Flittlefs/lists"}