+[](https://gitter.im/gkostka/lwext4?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[-blue.svg?style=flat-square)](http://opensource.org/licenses/GPL-2.0)
[](https://travis-ci.org/gkostka/lwext4)
+[](https://gratipay.com/gkostka/)
+
+
About
=====
-The main goal of the lwext4 project is to provide ext2/3/4 filesystem for microcontrollers. It may be an interesting alternative for traditional MCU filesystem libraries (mostly based on FAT32).
-Lwext4 may be used with SD/MMC card, USB flash drive or other block based memory device. However it is not good for flash memory–based storage devices.
+The main goal of the lwext4 project is to provide ext2/3/4 filesystem for microcontrollers. It may be an interesting alternative for traditional MCU filesystem libraries (mostly based on FAT32). Library has some cool and unique features in microcontrollers world:
+ - directory indexing - fast file find and list operations
+ - extents - fast big file truncate
+ - journaling transactions & recovery - power loss resistance
-Code is also available on github:
-https://github.com/gkostka/lwext4
+Lwext4 is an excellent choice for SD/MMC card, USB flash drive or any other wear
+leveled memory types. However it is not good for raw flash devices.
Feel free to contact me:
kostka.grzegorz@gmail.com
The most of the source code of lwext4 was taken from HelenOS:
* http://helenos.org/
+
Some features are based on FreeBSD and Linux implementations.
KaHo Ng (https://github.com/ngkaho1234):
* advanced extents implementation
* xattr support
-* metadata checksum suport
+* metadata checksum support
+* journal recovery & transactions
* many bugfixes & improvements
-fuse-lwext4 project:
+Lwext4 could be used also as fuse internals. Here is a nice project which uses lwext4 as a filesystem base:
* https://github.com/ngkaho1234/fuse-lwext4
+Some of the source files are licensed under GPLv2. It makes whole
+lwext4 GPLv2 licensed. To use library as a BSD3, GPLv2 licensed source
+files must be removed first. At this point there are two files
+licensed under GPLv2:
+* ext4_xattr.c
+* ext4_extents.c
+
+All other modules and headers are BSD-3-Clause licensed code.
+
+
Features
=====
* only C standard library dependency
* various CPU architectures supported (x86/64, cortex-mX, msp430 ...)
* small memory footprint
+* flexible configurations
-
-Memory footprint (for cortex-m4)
+Memory footprint
------------
-* .text: 20KB - 40KB
-* .data: 8KB (minimum 8 x 1KB block cache)
-* .stack: 2KB
+
+Advanced ext4 filesystem features, like extents or journaling require some memory.
+However most of the memory expensive features could be disabled at compile time.
+Here is a brief summary for cortex-m4 processor:
+
+* .text: 20KB - only ext2 fs support , 50KB - full ext4 fs feature set
+* .data: 8KB - minimum 8 x 1KB block cache, 12KB - when journaling and extents are enabled
+* .stack: 2KB - is enough (not measured precisely)
+
+Blocks are allocated dynamically. Previous versions of library could work without
+malloc but from 1.0.0 dynamic memory allocation is required. However, block cache
+should not allocate more than CONFIG_BLOCK_DEV CACHE_SIZE.
Supported ext2/3/4 features
=====
-Features incompatible:
+incompatible:
------------
-* compression: no
-* filetype: yes
-* recover: no
-* journal_dev: no
-* meta_bg: yes
-* extents: yes
-* 64bit: yes
-* mmp: no
-* flex_bg: yes
-* ea_inode: no
-* dirdata: no
-* bg_meta_csum: no
-* largedir: no
-* inline_data: no
-
-Features compatible:
-------------
-* dir_prealloc: no
-* imagic_inodes: no
-* has_journal: no
-* ext_attr: yes
-* resize_inode: no
-* dir_index: yes
-
-Features read-only:
+* filetype, recover, meta_bg, extents, 64bit, flex_bg: **yes**
+* compression, journal_dev, mmp, ea_inode, dirdata, bg_meta_csum, largedir, inline_data: **no**
+
+compatible:
------------
-* sparse_super: yes
-* large_file: yes
-* btree_dir: yes
-* huge_file: yes
-* gdt_csum: yes
-* dir_nlink: yes
-* extra_isize: yes
-* quota: no
-* bigalloc: no
-* metadata_csum: yes
+* has_journal, ext_attr, dir_index: **yes**
+* dir_prealloc, imagic_inodes, resize_inode: **no**
+read-only:
+------------
+* sparse_super, large_file, huge_file, gdt_csum, dir_nlink, extra_isize, metadata_csum: **yes**
+* quota, bigalloc, btree_dir: **no**
Project tree
=====
* blockdev - block devices set, supported blockdev
-* demos - demo directory sources
-* fs_test - test suite
-* lwext4 - internals of the lwext4 library
-* toolchain - specific toolchain cmake files
+* fs_test - test suite, mkfs and demo application
+* src - source files
+* include - header files
+* toolchain - cmake toolchain files
* CMakeLists.txt - CMake config file
* ext_images.7z - compressed ext2/3/4 100MB images
* fs_test.mk - automatic tests definitions
* Makefile - helper makefile to generate cmake and run test suite
-* readme.mediawiki - readme file
+* README.md - readme file
Compile
=====
-Windows
+Dependencies
------------
-* CMake: http://www.cmake.org/cmake/resources/software.html
-* MinGw: http://www.mingw.org/
-* GnuWin: http://gnuwin32.sourceforge.net/
+* Windows
-Linux
-------------
-* CMake, make, gcc
+Download MSYS-2: https://sourceforge.net/projects/msys2/
-Generate makefiles
-------------
+Install required packages is MSYS2 Shell package manager:
```bash
- make
- ```
+ pacman -S make gcc cmake p7zip
+ ```
+
+* Linux
-Compile
+Package installation (Debian):
+```bash
+ apt-get install make gcc cmake p7zip
+ ```
+
+Compile & install tools
------------
```bash
+ make generic
cd build_generic
make
+ sudo make install
```
-
-Generic demo application
+lwext4-generic demo application
=====
-Simple lwext4 library presentation:
+Simple lwext4 library test application:
* load ext2/3/4 images
* load linux block device with ext2/3/4 part
* load windows volume with ext2/3/4 filesystem
How to use for images/blockdevices:
```bash
- cd build_generic
- lwext4_generic -i ext_images/ext2
- lwext4_generic -i ext_images/ext3
- lwext4_generic -i ext_images/ext4
+ lwext4-generic -i ext_images/ext2
+ lwext4-generic -i ext_images/ext3
+ lwext4-generic -i ext_images/ext4
```
+
+Show full option set:
+```bash
+ lwext4-generic --help
+ ```
+Run automatic tests
+=====
-Build and run automatic tests
+Execute tests for 100MB unpacked images:
+```bash
+ make test
+ ```
+Execute tests for autogenerated 1GB images (only on Linux targets) + fsck:
+```bash
+ make test_all
+ ```
+Using lwext4-mkfs tool
=====
-Build automatic test tools:
+It is possible to create ext2/3/4 partition by internal library tool.
+
+Generate empty file (1GB):
```bash
- make
- cd build_generic
- make
- ```
-Uncompress ext/2/3/4 images:
+ dd if=/dev/zero of=ext_image bs=1M count=1024
+ ```
+Create ext2 partition:
```bash
- make unpack_images
+ lwext4-mkfs -i ext_image -e 2
```
-Run server for one of the image file:
+Create ext3 partition:
```bash
- make server_ext2
- make server_ext3
- make server_ext4
- ```
-Execute tests:
+ lwext4-mkfs -i ext_image -e 3
+ ```
+Create ext4 partition:
```bash
- make test
+ lwext4-mkfs -i ext_image -e 4
+ ```
+Show full option set:
+```bash
+ lwext4-mkfs --help
```
Cross compile standalone library
=====
Toolchains needed:
------------
-* arm-none-eabi-gcc for cortex-mX
-* avr-gcc for avr
-* bfin-elf-gcc for bfin
-* msp430-gcc for msp430
-
-Build bf518 library:
-------------
-```bash
- make bf518
- cd build_bf518
- make lwext4
- ```
+Lwext4 could be compiled for many targets. Here are an examples for 8/16/32/64 bit architectures.
+* generic for x86 or amd64
+* arm-none-eabi-gcc for ARM cortex-m0/m3/m4 microcontrollers
+* avr-gcc for AVR xmega microcontrollers
+* bfin-elf-gcc for blackfin processors
+* msp430-gcc for msp430 microcontrollers
+
+Library has been tested only for generic (amd64) & ARM Cortex M architectures.
+For other targets compilation passes (with warnings somewhere) but tests are
+not done yet. Lwext4 code is written with endianes respect. Big endian
+behavior also hasn't been tested yet.
Build avrxmega7 library:
------------
projects / lwext4.git / blobdiff