README.md

   1 [![Build Status](https://travis-ci.org/gkostka/lwext4.svg)](https://travis-ci.org/gkostka/lwext4)
   2
   3 About
   4 =====
   5
   6 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).
   7
   8 Lwext4 may be used with SD/MMC card, USB flash drive or other block based memory device. However it is not good for flash memory–based storage devices.
   9
  10 Code is also available on github:
  11 https://github.com/gkostka/lwext4
  12
  13 Feel free to contact me:
  14 kostka.grzegorz@gmail.com
  15
  16 Credits
  17 =====
  18
  19 The most of the source code of lwext4 was taken from HelenOS:
  20 * http://helenos.org/
  21 Some features are based on FreeBSD and Linux implementations.
  22
  23 KaHo Ng (https://github.com/ngkaho1234):
  24 * advanced extents implementation
  25 * xattr support
  26 * metadata checksum support
  27 * journal recovery
  28 * many bugfixes & improvements
  29
  30 fuse-lwext4 project:
  31 * https://github.com/ngkaho1234/fuse-lwext4
  32
  33 Features
  34 =====
  35
  36 * filetypes: regular, directories, softlinks
  37 * support for hardlinks
  38 * multiple blocksize supported: 1KB, 2KB, 4KB ... 64KB
  39 * little/big endian architectures supported
  40 * multiple configurations (ext2/ext3/ext4)
  41 * only C standard library dependency
  42 * various CPU architectures supported (x86/64, cortex-mX, msp430 ...)
  43 * small memory footprint
  44
  45
  46 Memory footprint (for cortex-m4)
  47 ------------
  48 * .text:  20KB - 40KB
  49 * .data:  8KB         (minimum 8 x 1KB  block cache)
  50 * .stack: 2KB
  51
  52 Supported ext2/3/4 features
  53 =====
  54 Features incompatible:
  55 ------------
  56 *  compression: no
  57 *  filetype: yes
  58 *  recover: no
  59 *  journal_dev: no
  60 *  meta_bg: yes
  61 *  extents: yes
  62 *  64bit: yes
  63 *  mmp: no
  64 *  flex_bg: yes
  65 *  ea_inode: no
  66 *  dirdata: no
  67 *  bg_meta_csum: no
  68 *  largedir: no
  69 *  inline_data: no
  70
  71 Features compatible:
  72 ------------
  73 *  dir_prealloc: no
  74 *  imagic_inodes: no
  75 *  has_journal: yes (in progress)
  76 *  ext_attr: yes
  77 *  resize_inode: no
  78 *  dir_index: yes
  79
  80 Features read-only:
  81 ------------
  82 *  sparse_super: yes
  83 *  large_file: yes
  84 *  btree_dir: yes
  85 *  huge_file: yes
  86 *  gdt_csum: yes
  87 *  dir_nlink: yes
  88 *  extra_isize: yes
  89 *  quota: no
  90 *  bigalloc: no
  91 *  metadata_csum: yes
  92
  93
  94 Project tree
  95 =====
  96 *  blockdev         - block devices set, supported blockdev
  97 *  fs_test          - test suite, mkfs and demo application
  98 *  lwext4           - internals of the lwext4 library
  99 *  toolchain        - specific toolchain cmake files
 100 *  CMakeLists.txt   - CMake config file
 101 *  ext_images.7z    - compressed ext2/3/4 100MB images
 102 *  fs_test.mk       - automatic tests definitions
 103 *  Makefile         - helper makefile to generate cmake and run test suite
 104 *  readme.mediawiki - readme file
 105
 106 Compile
 107 =====
 108 Windows
 109 ------------
 110 * CMake:  http://www.cmake.org/cmake/resources/software.html
 111 * MinGw:  http://www.mingw.org/
 112 * GnuWin: http://gnuwin32.sourceforge.net/
 113
 114 Linux
 115 ------------
 116 * CMake, make, gcc
 117
 118 Generate makefiles
 119 ------------
 120 ```bash
 121  make
 122  ```
 123
 124 Compile
 125 ------------
 126 ```bash
 127  cd build_generic
 128  make
 129  ```
 130
 131
 132 Generic demo application
 133 =====
 134 Simple lwext4 library presentation:
 135 * load ext2/3/4 images
 136 * load linux block device with ext2/3/4 part
 137 * load windows volume with ext2/3/4 filesystem
 138 * directory speed test
 139 * file write/read speed test
 140
 141 How to use for images/blockdevices:
 142 ```bash
 143  cd build_generic
 144  lwext4_generic -i ext_images/ext2
 145  lwext4_generic -i ext_images/ext3
 146  lwext4_generic -i ext_images/ext4
 147  ```
 148
 149
 150 Build and run automatic tests
 151 =====
 152 Build automatic test tools:
 153 ```bash
 154  make
 155  cd build_generic
 156  make
 157   ```
 158 Uncompress ext/2/3/4 images:
 159 ```bash
 160  make unpack_images
 161    ```
 162 Run server for one of the image file:
 163 ```bash
 164  make server_ext2
 165  make server_ext3
 166  make server_ext4
 167   ```
 168 Execute tests:
 169 ```bash
 170  make test
 171    ```
 172
 173 Cross compile standalone library
 174 =====
 175 Toolchains needed:
 176 ------------
 177 * arm-none-eabi-gcc for cortex-mX
 178 * avr-gcc for avr
 179 * bfin-elf-gcc for bfin
 180 * msp430-gcc for msp430
 181
 182
 183 Build bf518 library:
 184 ------------
 185 ```bash
 186  make bf518
 187  cd build_bf518
 188  make lwext4
 189  ```
 190
 191 Build avrxmega7 library:
 192 ------------
 193 ```bash
 194  make avrxmega7
 195  cd build_avrxmega7
 196  make lwext4
 197  ```
 198
 199 Build cortex-m0 library:
 200 ------------
 201 ```bash
 202  make cortex-m0
 203  cd build_cortex-m0
 204  make lwext4
 205  ```
 206
 207 Build cortex-m3 library:
 208 ------------
 209 ```bash
 210  make cortex-m3
 211  cd build_cortex-m3
 212  make lwext4
 213  ```
 214
 215 Build cortex-m4 library:
 216 ------------
 217 ```bash
 218  make cortex-m4
 219  cd build_cortex-m4
 220  make lwext4
 221 ```
 222
 223