README.md

   1 [![Join the chat at https://gitter.im/gkostka/lwext4](https://badges.gitter.im/gkostka/lwext4.svg)](https://gitter.im/gkostka/lwext4?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
   2 [![License (GPL v2.0)](https://img.shields.io/badge/license-GPL%20(v2.0)-blue.svg?style=flat-square)](http://opensource.org/licenses/GPL-2.0)
   3 [![Build Status](https://travis-ci.org/gkostka/lwext4.svg)](https://travis-ci.org/gkostka/lwext4)
   4 [![](http://img.shields.io/gratipay/user/gkostka.svg)](https://gratipay.com/gkostka/)
   5
   6 ![lwext4](https://cloud.githubusercontent.com/assets/8606098/11697327/68306d88-9eb9-11e5-8807-81a2887f077e.png)
   7
   8 About
   9 =====
  10
  11
  12 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:
  13  - directory indexing - fast file find and list operations
  14  - extents - fast big file truncate
  15  - journaling transactions & recovery - power loss resistance
  16
  17 Lwext4 is an excellent choice for SD/MMC card, USB flash drive or any other wear
  18 leveled memory types. However it is not good for raw flash devices.
  19
  20 Feel free to contact me:
  21 kostka.grzegorz@gmail.com
  22
  23 Credits
  24 =====
  25
  26 The most of the source code of lwext4 was taken from HelenOS:
  27 * http://helenos.org/
  28
  29 Some features are based on FreeBSD and Linux implementations.
  30
  31 KaHo Ng (https://github.com/ngkaho1234):
  32 * advanced extents implementation
  33 * xattr support
  34 * metadata checksum support
  35 * journal recovery & transactions
  36 * many bugfixes & improvements
  37
  38 Lwext4 could be used also as fuse internals. Here is a nice project which uses lwext4 as a filesystem base:
  39 * https://github.com/ngkaho1234/fuse-lwext4
  40
  41 Some of the source files are licensed under GPLv2. It makes whole
  42 lwext4 GPLv2 licensed. To use library as a BSD3, GPLv2 licensed source
  43 files must be removed first. At this point there are two files
  44 licensed under GPLv2:
  45 * ext4_xattr.c
  46 * ext4_extents.c
  47
  48 All other modules and headers are BSD-3-Clause licensed code.
  49
  50
  51 Features
  52 =====
  53
  54 * filetypes: regular, directories, softlinks
  55 * support for hardlinks
  56 * multiple blocksize supported: 1KB, 2KB, 4KB ... 64KB
  57 * little/big endian architectures supported
  58 * multiple configurations (ext2/ext3/ext4)
  59 * only C standard library dependency
  60 * various CPU architectures supported (x86/64, cortex-mX, msp430 ...)
  61 * small memory footprint
  62 * flexible configurations
  63
  64 Memory footprint
  65 ------------
  66
  67 Advanced ext4 filesystem features, like extents or journaling require some memory.
  68 However most of the memory expensive features could be disabled at compile time.
  69 Here is a brief summary for cortex-m4 processor:
  70
  71 * .text:  20KB - only ext2 fs support , 50KB - full ext4 fs feature set
  72 * .data:  8KB - minimum 8 x 1KB  block cache, 12KB - when journaling and extents are enabled
  73 * .stack: 2KB - is enough (not measured precisely)
  74
  75 Blocks are allocated dynamically. Previous versions of library could work without
  76 malloc but from 1.0.0 dynamic memory allocation is required. However, block cache
  77 should not allocate more than CONFIG_BLOCK_DEV CACHE_SIZE.
  78
  79 Supported ext2/3/4 features
  80 =====
  81 incompatible:
  82 ------------
  83 *  filetype, recover, meta_bg, extents, 64bit, flex_bg: **yes**
  84 *  compression, journal_dev, mmp, ea_inode, dirdata, bg_meta_csum, largedir, inline_data: **no**
  85
  86 compatible:
  87 ------------
  88 *  has_journal, ext_attr, dir_index: **yes**
  89 *  dir_prealloc, imagic_inodes, resize_inode: **no**
  90
  91 read-only:
  92 ------------
  93 *  sparse_super, large_file, huge_file, gdt_csum, dir_nlink, extra_isize, metadata_csum: **yes**
  94 *  quota, bigalloc, btree_dir: **no**
  95
  96 Project tree
  97 =====
  98 *  blockdev         - block devices set, supported blockdev
  99 *  fs_test          - test suite, mkfs and demo application
 100 *  src              - source files
 101 *  include          - header files
 102 *  toolchain        - cmake toolchain files
 103 *  CMakeLists.txt   - CMake config file
 104 *  ext_images.7z    - compressed ext2/3/4 100MB images
 105 *  fs_test.mk       - automatic tests definitions
 106 *  Makefile         - helper makefile to generate cmake and run test suite
 107 *  README.md       - readme file
 108
 109 Compile
 110 =====
 111 Dependencies
 112 ------------
 113 * Windows
 114
 115 Download MSYS-2:  https://sourceforge.net/projects/msys2/
 116
 117 Install required packages is MSYS2 Shell package manager:
 118 ```bash
 119  pacman -S make gcc cmake p7zip
 120   ```
 121
 122 * Linux
 123
 124 Package installation (Debian):
 125 ```bash
 126  apt-get install make gcc cmake p7zip
 127   ```
 128
 129 Compile & install tools
 130 ------------
 131 ```bash
 132  make generic
 133  cd build_generic
 134  make
 135  sudo make install
 136  ```
 137
 138 lwext4-generic demo application
 139 =====
 140 Simple lwext4 library test application:
 141 * load ext2/3/4 images
 142 * load linux block device with ext2/3/4 part
 143 * load windows volume with ext2/3/4 filesystem
 144 * directory speed test
 145 * file write/read speed test
 146
 147 How to use for images/blockdevices:
 148 ```bash
 149  lwext4-generic -i ext_images/ext2
 150  lwext4-generic -i ext_images/ext3
 151  lwext4-generic -i ext_images/ext4
 152  ```
 153
 154 Show full option set:
 155 ```bash
 156  lwext4-generic --help
 157    ```
 158
 159 Run automatic tests
 160 =====
 161
 162 Execute tests for 100MB unpacked images:
 163 ```bash
 164  make test
 165    ```
 166 Execute tests for autogenerated 1GB images (only on Linux targets) + fsck:
 167 ```bash
 168  make test_all
 169    ```
 170 Using lwext4-mkfs tool
 171 =====
 172 It is possible to create ext2/3/4 partition by internal library tool.
 173
 174 Generate empty file (1GB):
 175 ```bash
 176  dd if=/dev/zero of=ext_image bs=1M count=1024
 177    ```
 178 Create ext2 partition:
 179 ```bash
 180  lwext4-mkfs -i ext_image -e 2
 181    ```
 182 Create ext3 partition:
 183 ```bash
 184  lwext4-mkfs -i ext_image -e 3
 185    ```
 186 Create ext4 partition:
 187 ```bash
 188  lwext4-mkfs -i ext_image -e 4
 189    ```
 190 Show full option set:
 191 ```bash
 192  lwext4-mkfs --help
 193    ```
 194
 195 Cross compile standalone library
 196 =====
 197 Toolchains needed:
 198 ------------
 199
 200 Lwext4 could be compiled for many targets. Here are an examples for 8/16/32/64 bit architectures.
 201 * generic for x86 or amd64
 202 * arm-none-eabi-gcc for ARM cortex-m0/m3/m4 microcontrollers
 203 * avr-gcc for AVR xmega microcontrollers
 204 * bfin-elf-gcc for blackfin processors
 205 * msp430-gcc for msp430 microcontrollers
 206
 207 Library has been tested only for generic (amd64) & ARM Cortex M architectures.
 208 For other targets compilation passes (with warnings somewhere) but tests are
 209 not done yet. Lwext4 code is written with endianes respect. Big endian
 210 behavior also hasn't been tested yet.
 211
 212 Build avrxmega7 library:
 213 ------------
 214 ```bash
 215  make avrxmega7
 216  cd build_avrxmega7
 217  make lwext4
 218  ```
 219
 220 Build cortex-m0 library:
 221 ------------
 222 ```bash
 223  make cortex-m0
 224  cd build_cortex-m0
 225  make lwext4
 226  ```
 227
 228 Build cortex-m3 library:
 229 ------------
 230 ```bash
 231  make cortex-m3
 232  cd build_cortex-m3
 233  make lwext4
 234  ```
 235
 236 Build cortex-m4 library:
 237 ------------
 238 ```bash
 239  make cortex-m4
 240  cd build_cortex-m4
 241  make lwext4
 242 ```
 243
 244