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 (3-Clause BSD)](https://img.shields.io/badge/license-BSD%203--Clause-blue.svg?style=flat-square)](http://opensource.org/licenses/BSD-3-Clause)
   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 Features
  42 =====
  43
  44 * filetypes: regular, directories, softlinks
  45 * support for hardlinks
  46 * multiple blocksize supported: 1KB, 2KB, 4KB ... 64KB
  47 * little/big endian architectures supported
  48 * multiple configurations (ext2/ext3/ext4)
  49 * only C standard library dependency
  50 * various CPU architectures supported (x86/64, cortex-mX, msp430 ...)
  51 * small memory footprint
  52 * flexible configurations
  53
  54 Memory footprint
  55 ------------
  56
  57 Advanced ext4 filesystem features, like extents or journaling require some memory.
  58 However most of the memory expensive features could be disabled at compile time.
  59 Here is a brief summary for cortex-m4 processor:
  60
  61 * .text:  20KB - only ext2 fs support , 50KB - full ext4 fs feature set
  62 * .data:  8KB - minimum 8 x 1KB  block cache, 12KB - when journaling and extents are enabled
  63 * .stack: 2KB - is enough (not measured precisely)
  64
  65 Blocks are allocated dynamically. Previous versions of library could work without
  66 malloc but from 1.0.0 dynamic memory allocation is required. However, block cache
  67 should not allocate more than CONFIG_BLOCK_DEV CACHE_SIZE.
  68
  69 Supported ext2/3/4 features
  70 =====
  71 incompatible:
  72 ------------
  73 *  filetype, recover, meta_bg, extents, 64bit, flex_bg: **yes**
  74 *  compression, journal_dev, mmp, ea_inode, dirdata, bg_meta_csum, largedir, inline_data: **no**
  75
  76 compatible:
  77 ------------
  78 *  has_journal, ext_attr, dir_index: **yes**
  79 *  dir_prealloc, imagic_inodes, resize_inode: **no**
  80
  81 read-only:
  82 ------------
  83 *  sparse_super, large_file, huge_file, gdt_csum, dir_nlink, extra_isize, metadata_csum: **yes**
  84 *  quota, bigalloc, btree_dir: **no**
  85
  86 Project tree
  87 =====
  88 *  blockdev         - block devices set, supported blockdev
  89 *  fs_test          - test suite, mkfs and demo application
  90 *  src              - source files
  91 *  include          - header files
  92 *  toolchain        - cmake toolchain files
  93 *  CMakeLists.txt   - CMake config file
  94 *  ext_images.7z    - compressed ext2/3/4 100MB images
  95 *  fs_test.mk       - automatic tests definitions
  96 *  Makefile         - helper makefile to generate cmake and run test suite
  97 *  README.md       - readme file
  98
  99 Compile
 100 =====
 101 Dependencies
 102 ------------
 103 * Windows
 104
 105 Download MSYS-2:  https://sourceforge.net/projects/msys2/
 106
 107 Install required packages is MSYS2 Shell package manager:
 108 ```bash
 109  pacman -S make gcc cmake p7zip
 110   ```
 111
 112 * Linux
 113
 114 Package installation (Debian):
 115 ```bash
 116  apt-get install make gcc cmake p7zip
 117   ```
 118
 119 Compile & install tools
 120 ------------
 121 ```bash
 122  make generic
 123  cd build_generic
 124  make
 125  sudo make install
 126  ```
 127
 128 lwext4-generic demo application
 129 =====
 130 Simple lwext4 library test application:
 131 * load ext2/3/4 images
 132 * load linux block device with ext2/3/4 part
 133 * load windows volume with ext2/3/4 filesystem
 134 * directory speed test
 135 * file write/read speed test
 136
 137 How to use for images/blockdevices:
 138 ```bash
 139  lwext4-generic -i ext_images/ext2
 140  lwext4-generic -i ext_images/ext3
 141  lwext4-generic -i ext_images/ext4
 142  ```
 143
 144 Show full option set:
 145 ```bash
 146  lwext4-generic --help
 147    ```
 148
 149 Run automatic tests
 150 =====
 151
 152 Execute tests for 100MB unpacked images:
 153 ```bash
 154  make test
 155    ```
 156 Execute tests for autogenerated 1GB images (only on Linux targets) + fsck:
 157 ```bash
 158  make test_all
 159    ```
 160 Using lwext4-mkfs tool
 161 =====
 162 It is possible to create ext2/3/4 partition by internal library tool.
 163
 164 Generate empty file (1GB):
 165 ```bash
 166  dd if=/dev/zero of=ext_image bs=1M count=1024
 167    ```
 168 Create ext2 partition:
 169 ```bash
 170  lwext4-mkfs -i ext_image -e 2
 171    ```
 172 Create ext3 partition:
 173 ```bash
 174  lwext4-mkfs -i ext_image -e 3
 175    ```
 176 Create ext4 partition:
 177 ```bash
 178  lwext4-mkfs -i ext_image -e 4
 179    ```
 180 Show full option set:
 181 ```bash
 182  lwext4-mkfs --help
 183    ```
 184
 185 Cross compile standalone library
 186 =====
 187 Toolchains needed:
 188 ------------
 189
 190 Lwext4 could be compiled for many targets. Here are an examples for 8/16/32/64 bit architectures.
 191 * generic for x86 or amd64
 192 * arm-none-eabi-gcc for ARM cortex-m0/m3/m4 microcontrollers
 193 * avr-gcc for AVR xmega microcontrollers
 194 * bfin-elf-gcc for blackfin processors
 195 * msp430-gcc for msp430 microcontrollers
 196
 197 Library has been tested only for generic (amd64) & ARM Cortex M architectures.
 198 For other targets compilation passes (with warnings somewhere) but tests are
 199 not done yet. Lwext4 code is written with endianes respect. Big endian
 200 behavior also hasn't been tested yet.
 201
 202 Build avrxmega7 library:
 203 ------------
 204 ```bash
 205  make avrxmega7
 206  cd build_avrxmega7
 207  make lwext4
 208  ```
 209
 210 Build cortex-m0 library:
 211 ------------
 212 ```bash
 213  make cortex-m0
 214  cd build_cortex-m0
 215  make lwext4
 216  ```
 217
 218 Build cortex-m3 library:
 219 ------------
 220 ```bash
 221  make cortex-m3
 222  cd build_cortex-m3
 223  make lwext4
 224  ```
 225
 226 Build cortex-m4 library:
 227 ------------
 228 ```bash
 229  make cortex-m4
 230  cd build_cortex-m4
 231  make lwext4
 232 ```
 233
 234