README.md

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