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