X-Git-Url: https://git.carlh.net/gitweb/?a=blobdiff_plain;f=README.md;h=3abd86066a6dc43e69c07ebc88cf520bdf38f6bf;hb=HEAD;hp=5bdc906cdbdf5083f174c2c97eb70a9f2801c821;hpb=f0082d0d8b0b69a2d8c6a04690b7258cfb80c022;p=lwext4.git diff --git a/README.md b/README.md index 5bdc906..3abd860 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,55 @@ +[![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) +[![License (GPL v2.0)](https://img.shields.io/badge/license-GPL%20(v2.0)-blue.svg?style=flat-square)](http://opensource.org/licenses/GPL-2.0) [![Build Status](https://travis-ci.org/gkostka/lwext4.svg)](https://travis-ci.org/gkostka/lwext4) +[![](http://img.shields.io/gratipay/user/gkostka.svg)](https://gratipay.com/gkostka/) -==About== +![lwext4](https://cloud.githubusercontent.com/assets/8606098/11697327/68306d88-9eb9-11e5-8807-81a2887f077e.png) -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). +About +===== -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. -Code is also available on github: -https://github.com/gkostka/lwext4 +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: + - directory indexing - fast file find and list operations + - extents - fast big file truncate + - journaling transactions & recovery - power loss resistance + +Lwext4 is an excellent choice for SD/MMC card, USB flash drive or any other wear +leveled memory types. However it is not good for raw flash devices. Feel free to contact me: kostka.grzegorz@gmail.com -==Credits== +Credits +===== The most of the source code of lwext4 was taken from HelenOS: * http://helenos.org/ + Some features are based on FreeBSD and Linux implementations. KaHo Ng (https://github.com/ngkaho1234): * advanced extents implementation * xattr support -* metadata checksum suport +* metadata checksum support +* journal recovery & transactions * many bugfixes & improvements -fuse-lwext4 project: +Lwext4 could be used also as fuse internals. Here is a nice project which uses lwext4 as a filesystem base: * https://github.com/ngkaho1234/fuse-lwext4 -==Features== +Some of the source files are licensed under GPLv2. It makes whole +lwext4 GPLv2 licensed. To use library as a BSD3, GPLv2 licensed source +files must be removed first. At this point there are two files +licensed under GPLv2: +* ext4_xattr.c +* ext4_extents.c + +All other modules and headers are BSD-3-Clause licensed code. + + +Features +===== * filetypes: regular, directories, softlinks * support for hardlinks @@ -37,80 +59,85 @@ fuse-lwext4 project: * only C standard library dependency * various CPU architectures supported (x86/64, cortex-mX, msp430 ...) * small memory footprint - - -;Memory footprint (for cortex-m4): -* .text: 20KB - 40KB -* .data: 8KB (minimum 8 x 1KB block cache) -* .stack: 2KB - -==Supported ext2/3/4 features== -;Features incompatible: -* compression: no -* filetype: yes -* recover: no -* journal_dev: no -* meta_bg: yes -* extents: yes -* 64bit: yes -* mmp: no -* flex_bg: yes -* ea_inode: no -* dirdata: no -* bg_meta_csum: no -* largedir: no -* inline_data: no -;Features compatible: -* dir_prealloc: no -* imagic_inodes: no -* has_journal: no -* ext_attr: yes -* resize_inode: no -* dir_index: yes -;Features read-only: -* sparse_super: yes -* large_file: yes -* btree_dir: yes -* huge_file: yes -* gdt_csum: yes -* dir_nlink: yes -* extra_isize: yes -* quota: no -* bigalloc: no -* metadata_csum: yes - - -==Project tree== +* flexible configurations + +Memory footprint +------------ + +Advanced ext4 filesystem features, like extents or journaling require some memory. +However most of the memory expensive features could be disabled at compile time. +Here is a brief summary for cortex-m4 processor: + +* .text: 20KB - only ext2 fs support , 50KB - full ext4 fs feature set +* .data: 8KB - minimum 8 x 1KB block cache, 12KB - when journaling and extents are enabled +* .stack: 2KB - is enough (not measured precisely) + +Blocks are allocated dynamically. Previous versions of library could work without +malloc but from 1.0.0 dynamic memory allocation is required. However, block cache +should not allocate more than CONFIG_BLOCK_DEV CACHE_SIZE. + +Supported ext2/3/4 features +===== +incompatible: +------------ +* filetype, recover, meta_bg, extents, 64bit, flex_bg: **yes** +* compression, journal_dev, mmp, ea_inode, dirdata, bg_meta_csum, largedir, inline_data: **no** + +compatible: +------------ +* has_journal, ext_attr, dir_index: **yes** +* dir_prealloc, imagic_inodes, resize_inode: **no** + +read-only: +------------ +* sparse_super, large_file, huge_file, gdt_csum, dir_nlink, extra_isize, metadata_csum: **yes** +* quota, bigalloc, btree_dir: **no** + +Project tree +===== * blockdev - block devices set, supported blockdev -* demos - demo directory sources -* fs_test - test suite -* lwext4 - internals of the lwext4 library -* toolchain - specific toolchain cmake files +* fs_test - test suite, mkfs and demo application +* src - source files +* include - header files +* toolchain - cmake toolchain files * CMakeLists.txt - CMake config file * ext_images.7z - compressed ext2/3/4 100MB images * fs_test.mk - automatic tests definitions * Makefile - helper makefile to generate cmake and run test suite -* readme.mediawiki - readme file +* README.md - readme file -==Compile== -Windows: -* CMake: http://www.cmake.org/cmake/resources/software.html -* MinGw: http://www.mingw.org/ -* GnuWin: http://gnuwin32.sourceforge.net/ - -Linux: -* CMake, make, gcc - -;Generate makefiles: - make - -;Compile +Compile +===== +Dependencies +------------ +* Windows + +Download MSYS-2: https://sourceforge.net/projects/msys2/ + +Install required packages is MSYS2 Shell package manager: +```bash + pacman -S make gcc cmake p7zip + ``` + +* Linux + +Package installation (Debian): +```bash + apt-get install make gcc cmake p7zip + ``` + +Compile & install tools +------------ +```bash + make generic cd build_generic make + sudo make install + ``` - -==Generic demo application== -Simple lwext4 library presentation: +lwext4-generic demo application +===== +Simple lwext4 library test application: * load ext2/3/4 images * load linux block device with ext2/3/4 part * load windows volume with ext2/3/4 filesystem @@ -118,57 +145,100 @@ Simple lwext4 library presentation: * file write/read speed test How to use for images/blockdevices: - cd build_generic - generic -i ext_images/ext2 - generic -i ext_images/ext3 - generic -i ext_images/ext4 - - -==Build and run automatic tests== -Build and run automatic tests -Build automatic test tools: - make - cd build_generic - make -Uncompress ext/2/3/4 images: - make unpack_images -Run server for one of the image file: - make server_ext2 - make server_ext3 - make server_ext4 -Execute tests: +```bash + lwext4-generic -i ext_images/ext2 + lwext4-generic -i ext_images/ext3 + lwext4-generic -i ext_images/ext4 + ``` + +Show full option set: +```bash + lwext4-generic --help + ``` + +Run automatic tests +===== + +Execute tests for 100MB unpacked images: +```bash make test - -==Cross compile standalone library== + ``` +Execute tests for autogenerated 1GB images (only on Linux targets) + fsck: +```bash + make test_all + ``` +Using lwext4-mkfs tool +===== +It is possible to create ext2/3/4 partition by internal library tool. + +Generate empty file (1GB): +```bash + dd if=/dev/zero of=ext_image bs=1M count=1024 + ``` +Create ext2 partition: +```bash + lwext4-mkfs -i ext_image -e 2 + ``` +Create ext3 partition: +```bash + lwext4-mkfs -i ext_image -e 3 + ``` +Create ext4 partition: +```bash + lwext4-mkfs -i ext_image -e 4 + ``` +Show full option set: +```bash + lwext4-mkfs --help + ``` + +Cross compile standalone library +===== Toolchains needed: -* arm-none-eabi-gcc for cortex-mX -* avr-gcc for avr -* bfin-elf-gcc for bfin -* msp430-gcc for msp430 +------------ +Lwext4 could be compiled for many targets. Here are an examples for 8/16/32/64 bit architectures. +* generic for x86 or amd64 +* arm-none-eabi-gcc for ARM cortex-m0/m3/m4 microcontrollers +* avr-gcc for AVR xmega microcontrollers +* bfin-elf-gcc for blackfin processors +* msp430-gcc for msp430 microcontrollers -Build bf518 library: - make bf518 - cd build_bf518 - make lwext4 +Library has been tested only for generic (amd64) & ARM Cortex M architectures. +For other targets compilation passes (with warnings somewhere) but tests are +not done yet. Lwext4 code is written with endianes respect. Big endian +behavior also hasn't been tested yet. Build avrxmega7 library: +------------ +```bash make avrxmega7 cd build_avrxmega7 make lwext4 + ``` Build cortex-m0 library: +------------ +```bash make cortex-m0 cd build_cortex-m0 make lwext4 + ``` Build cortex-m3 library: +------------ +```bash make cortex-m3 cd build_cortex-m3 make lwext4 + ``` Build cortex-m4 library: +------------ +```bash make cortex-m4 cd build_cortex-m4 make lwext4 +``` +