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 Features incompatible:
  67 ------------
  68 *  compression: no
  69 *  filetype: yes
  70 *  recover: no
  71 *  journal_dev: no
  72 *  meta_bg: yes
  73 *  extents: yes
  74 *  64bit: yes
  75 *  mmp: no
  76 *  flex_bg: yes
  77 *  ea_inode: no
  78 *  dirdata: no
  79 *  bg_meta_csum: no
  80 *  largedir: no
  81 *  inline_data: no
  82
  83 Features compatible:
  84 ------------
  85 *  dir_prealloc: no
  86 *  imagic_inodes: no
  87 *  has_journal: yes (in progress)
  88 *  ext_attr: yes
  89 *  resize_inode: no
  90 *  dir_index: yes
  91
  92 Features read-only:
  93 ------------
  94 *  sparse_super: yes
  95 *  large_file: yes
  96 *  btree_dir: yes
  97 *  huge_file: yes
  98 *  gdt_csum: yes
  99 *  dir_nlink: yes
 100 *  extra_isize: yes
 101 *  quota: no
 102 *  bigalloc: no
 103 *  metadata_csum: yes
 104
 105
 106 Project tree
 107 =====
 108 *  blockdev         - block devices set, supported blockdev
 109 *  fs_test          - test suite, mkfs and demo application
 110 *  src              - source files
 111 *  include          - header files
 112 *  toolchain        - cmake toolchain files
 113 *  CMakeLists.txt   - CMake config file
 114 *  ext_images.7z    - compressed ext2/3/4 100MB images
 115 *  fs_test.mk       - automatic tests definitions
 116 *  Makefile         - helper makefile to generate cmake and run test suite
 117 *  README.md       - readme file
 118
 119 Compile
 120 =====
 121 Dependencies
 122 ------------
 123 * Windows
 124
 125 Download MSYS-2:  https://sourceforge.net/projects/msys2/
 126
 127 Install required packages is MSYS2 Shell package manager:
 128 ```bash
 129  pacman -S make gcc cmake p7zip
 130   ```
 131
 132 * Linux
 133
 134 Package installation (Debian):
 135 ```bash
 136  apt-get install make gcc cmake p7zip
 137   ```
 138
 139 Compile & install tools
 140 ------------
 141 ```bash
 142  make generic
 143  cd build_generic
 144  make
 145  sudo make install
 146  ```
 147
 148 lwext4-generic demo application
 149 =====
 150 Simple lwext4 library test application:
 151 * load ext2/3/4 images
 152 * load linux block device with ext2/3/4 part
 153 * load windows volume with ext2/3/4 filesystem
 154 * directory speed test
 155 * file write/read speed test
 156
 157 How to use for images/blockdevices:
 158 ```bash
 159  lwext4-generic -i ext_images/ext2
 160  lwext4-generic -i ext_images/ext3
 161  lwext4-generic -i ext_images/ext4
 162  ```
 163
 164 Show full option set:
 165 ```bash
 166  lwext4-generic --help
 167    ```
 168
 169 Run automatic tests
 170 =====
 171
 172 Execute tests for 100MB unpacked images:
 173 ```bash
 174  make test
 175    ```
 176 Execute tests for autogenerated 1GB images (only on Linux targets) + fsck:
 177 ```bash
 178  make test_all
 179    ```
 180 Using lwext4-mkfs tool
 181 =====
 182 It is possible to create ext2/3/4 partition by internal library tool.
 183
 184 Generate empty file (1GB):
 185 ```bash
 186  dd if=/dev/zero of=ext_image bs=1M count=1024
 187    ```
 188 Create ext2 partition:
 189 ```bash
 190  lwext4-mkfs -i ext_image -e 2
 191    ```
 192 Create ext3 partition:
 193 ```bash
 194  lwext4-mkfs -i ext_image -e 3
 195    ```
 196 Create ext4 partition:
 197 ```bash
 198  lwext4-mkfs -i ext_image -e 4
 199    ```
 200 Show full option set:
 201 ```bash
 202  lwext4-mkfs --help
 203    ```
 204
 205 Cross compile standalone library
 206 =====
 207 Toolchains needed:
 208 ------------
 209
 210 Lwext4 could be compiled for many targets. Here are an examples for 8/16/32/64 bit architectures.
 211 * generic for x86 or amd64
 212 * arm-none-eabi-gcc for ARM cortex-m0/m3/m4 microcontrollers
 213 * avr-gcc for AVR xmega microcontrollers
 214 * bfin-elf-gcc for blockfin processors
 215 * msp430-gcc for msp430 microcontrollers
 216
 217 Library has been tested only for generic (amd64) & ARM Cortex M architectures.
 218 For other targets compilation passes (with warnings somewhere) but tests are
 219 not done yet. Lwext4 code is written with endianes respect. Big endian
 220 behavior also hasn't been tested yet.
 221
 222 Build bf518 library:
 223 ------------
 224 ```bash
 225  make bf518
 226  cd build_bf518
 227  make lwext4
 228  ```
 229
 230 Build avrxmega7 library:
 231 ------------
 232 ```bash
 233  make avrxmega7
 234  cd build_avrxmega7
 235  make lwext4
 236  ```
 237
 238 Build cortex-m0 library:
 239 ------------
 240 ```bash
 241  make cortex-m0
 242  cd build_cortex-m0
 243  make lwext4
 244  ```
 245
 246 Build cortex-m3 library:
 247 ------------
 248 ```bash
 249  make cortex-m3
 250  cd build_cortex-m3
 251  make lwext4
 252  ```
 253
 254 Build cortex-m4 library:
 255 ------------
 256 ```bash
 257  make cortex-m4
 258  cd build_cortex-m4
 259  make lwext4
 260 ```
 261
 262