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).
   9
  10 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.
  11
  12 Code is also available on github:
  13 https://github.com/gkostka/lwext4
  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 Some features are based on FreeBSD and Linux implementations.
  24
  25 KaHo Ng (https://github.com/ngkaho1234):
  26 * advanced extents implementation
  27 * xattr support
  28 * metadata checksum support
  29 * journal recovery
  30 * many bugfixes & improvements
  31
  32 fuse-lwext4 project:
  33 * https://github.com/ngkaho1234/fuse-lwext4
  34
  35 Features
  36 =====
  37
  38 * filetypes: regular, directories, softlinks
  39 * support for hardlinks
  40 * multiple blocksize supported: 1KB, 2KB, 4KB ... 64KB
  41 * little/big endian architectures supported
  42 * multiple configurations (ext2/ext3/ext4)
  43 * only C standard library dependency
  44 * various CPU architectures supported (x86/64, cortex-mX, msp430 ...)
  45 * small memory footprint
  46
  47
  48 Memory footprint (for cortex-m4)
  49 ------------
  50 * .text:  20KB - 40KB
  51 * .data:  8KB         (minimum 8 x 1KB  block cache)
  52 * .stack: 2KB
  53
  54 Supported ext2/3/4 features
  55 =====
  56 Features incompatible:
  57 ------------
  58 *  compression: no
  59 *  filetype: yes
  60 *  recover: no
  61 *  journal_dev: no
  62 *  meta_bg: yes
  63 *  extents: yes
  64 *  64bit: yes
  65 *  mmp: no
  66 *  flex_bg: yes
  67 *  ea_inode: no
  68 *  dirdata: no
  69 *  bg_meta_csum: no
  70 *  largedir: no
  71 *  inline_data: no
  72
  73 Features compatible:
  74 ------------
  75 *  dir_prealloc: no
  76 *  imagic_inodes: no
  77 *  has_journal: yes (in progress)
  78 *  ext_attr: yes
  79 *  resize_inode: no
  80 *  dir_index: yes
  81
  82 Features read-only:
  83 ------------
  84 *  sparse_super: yes
  85 *  large_file: yes
  86 *  btree_dir: yes
  87 *  huge_file: yes
  88 *  gdt_csum: yes
  89 *  dir_nlink: yes
  90 *  extra_isize: yes
  91 *  quota: no
  92 *  bigalloc: no
  93 *  metadata_csum: yes
  94
  95
  96 Project tree
  97 =====
  98 *  blockdev         - block devices set, supported blockdev
  99 *  fs_test          - test suite, mkfs and demo application
 100 *  lwext4           - internals of the lwext4 library
 101 *  toolchain        - specific toolchain cmake files
 102 *  CMakeLists.txt   - CMake config file
 103 *  ext_images.7z    - compressed ext2/3/4 100MB images
 104 *  fs_test.mk       - automatic tests definitions
 105 *  Makefile         - helper makefile to generate cmake and run test suite
 106 *  readme.mediawiki - readme file
 107
 108 Compile
 109 =====
 110 Dependencies
 111 ------------
 112 * Windows
 113
 114 Download MSYS-2:  https://sourceforge.net/projects/msys2/
 115
 116 Install required packages is MSYS2 Shell package manager:
 117 ```bash
 118  pacman -S make gcc cmake p7zip
 119   ```
 120
 121 * Linux
 122
 123 Package installation (Debian):
 124 ```bash
 125  apt-get install make gcc cmake p7zip
 126   ```
 127
 128 Compile & install tools
 129 ------------
 130 ```bash
 131  make generic
 132  cd build_generic
 133  make
 134  sudo make install
 135  ```
 136
 137 lwext4-generic demo application
 138 =====
 139 Simple lwext4 library test applicatin:
 140 * load ext2/3/4 images
 141 * load linux block device with ext2/3/4 part
 142 * load windows volume with ext2/3/4 filesystem
 143 * directory speed test
 144 * file write/read speed test
 145
 146 How to use for images/blockdevices:
 147 ```bash
 148  lwext4-generic -i ext_images/ext2
 149  lwext4-generic -i ext_images/ext3
 150  lwext4-generic -i ext_images/ext4
 151  ```
 152
 153 Show full option set:
 154 ```bash
 155  lwext4-generic --help
 156    ```
 157
 158 Run automatic tests
 159 =====
 160
 161 Execute tests for 100MB unpacked images:
 162 ```bash
 163  make test
 164    ```
 165 Execute tests for autogenerated 1GB images (only on Linux targets) + fsck:
 166 ```bash
 167  make test_all
 168    ```
 169 Using lwext4-mkfs tool
 170 =====
 171 It is possible to create ext2/3/4 partition by internal library tool.
 172
 173 Generate empty file (1GB):
 174 ```bash
 175  dd if=/dev/zero of=ext_image bs=1M count=1024
 176    ```
 177 Create ext2 partition:
 178 ```bash
 179  lwext4-mkfs -i ext_image -e 2
 180    ```
 181 Create ext3 partition:
 182 ```bash
 183  lwext4-mkfs -i ext_image -e 3
 184    ```
 185 Create ext4 partition:
 186 ```bash
 187  lwext4-mkfs -i ext_image -e 4
 188    ```
 189 Show full option set:
 190 ```bash
 191  lwext4-mkfs --help
 192    ```
 193
 194 Cross compile standalone library
 195 =====
 196 Toolchains needed:
 197 ------------
 198 * arm-none-eabi-gcc for cortex-mX
 199 * avr-gcc for avr
 200 * bfin-elf-gcc for bfin
 201 * msp430-gcc for msp430
 202
 203
 204 Build bf518 library:
 205 ------------
 206 ```bash
 207  make bf518
 208  cd build_bf518
 209  make lwext4
 210  ```
 211
 212 Build avrxmega7 library:
 213 ------------
 214 ```bash
 215  make avrxmega7
 216  cd build_avrxmega7
 217  make lwext4
 218  ```
 219
 220 Build cortex-m0 library:
 221 ------------
 222 ```bash
 223  make cortex-m0
 224  cd build_cortex-m0
 225  make lwext4
 226  ```
 227
 228 Build cortex-m3 library:
 229 ------------
 230 ```bash
 231  make cortex-m3
 232  cd build_cortex-m3
 233  make lwext4
 234  ```
 235
 236 Build cortex-m4 library:
 237 ------------
 238 ```bash
 239  make cortex-m4
 240  cd build_cortex-m4
 241  make lwext4
 242 ```
 243
 244