X-Git-Url: https://git.carlh.net/gitweb/?a=blobdiff_plain;ds=sidebyside;f=README.md;h=a257e0e8d98f6069d8f543b41fe675788434b851;hb=48d955206bccfd6d4fe25ad0934765428fe7fda2;hp=72080a9eee9eb4611dda20d0775de0553a65a1b7;hpb=14c9ded75eb5ae8be70369effb7f946637de3843;p=lwext4.git diff --git a/README.md b/README.md index 72080a9..a257e0e 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,20 @@ +[![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 (3-Clause BSD)](https://img.shields.io/badge/license-BSD%203--Clause-blue.svg?style=flat-square)](http://opensource.org/licenses/BSD-3-Clause) [![Build Status](https://travis-ci.org/gkostka/lwext4.svg)](https://travis-ci.org/gkostka/lwext4) +![lwext4](https://cloud.githubusercontent.com/assets/8606098/11697327/68306d88-9eb9-11e5-8807-81a2887f077e.png) + About ===== -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). -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. +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 -Code is also available on github: -https://github.com/gkostka/lwext4 +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 @@ -18,15 +24,17 @@ 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 @@ -40,98 +48,85 @@ Features * only C standard library dependency * various CPU architectures supported (x86/64, cortex-mX, msp430 ...) * small memory footprint +* flexible configurations - -Memory footprint (for cortex-m4) +Memory footprint ------------ -* .text: 20KB - 40KB -* .data: 8KB (minimum 8 x 1KB block cache) -* .stack: 2KB + +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 ===== -Features incompatible: +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: +* filetype, recover, meta_bg, extents, 64bit, flex_bg: **yes** +* compression, journal_dev, mmp, ea_inode, dirdata, bg_meta_csum, largedir, inline_data: **no** + +compatible: ------------ -* 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 +* 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 +Dependencies ------------ -* CMake: http://www.cmake.org/cmake/resources/software.html -* MinGw: http://www.mingw.org/ -* GnuWin: http://gnuwin32.sourceforge.net/ +* Windows -Linux ------------- -* CMake, make, gcc +Download MSYS-2: https://sourceforge.net/projects/msys2/ -Generate makefiles ------------- +Install required packages is MSYS2 Shell package manager: ```bash - make - ``` + pacman -S make gcc cmake p7zip + ``` + +* Linux -Compile +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 +lwext4-generic demo application ===== -Simple lwext4 library presentation: +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 @@ -140,53 +135,68 @@ Simple lwext4 library presentation: How to use for images/blockdevices: ```bash - cd build_generic - lwext4_generic -i ext_images/ext2 - lwext4_generic -i ext_images/ext3 - lwext4_generic -i ext_images/ext4 + 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 +===== -Build and run automatic tests +Execute tests for 100MB unpacked images: +```bash + make test + ``` +Execute tests for autogenerated 1GB images (only on Linux targets) + fsck: +```bash + make test_all + ``` +Using lwext4-mkfs tool ===== -Build automatic test tools: +It is possible to create ext2/3/4 partition by internal library tool. + +Generate empty file (1GB): ```bash - make - cd build_generic - make - ``` -Uncompress ext/2/3/4 images: + dd if=/dev/zero of=ext_image bs=1M count=1024 + ``` +Create ext2 partition: ```bash - make unpack_images + lwext4-mkfs -i ext_image -e 2 ``` -Run server for one of the image file: +Create ext3 partition: ```bash - make server_ext2 - make server_ext3 - make server_ext4 - ``` -Execute tests: + lwext4-mkfs -i ext_image -e 3 + ``` +Create ext4 partition: ```bash - make test + 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 - -Build bf518 library: ------------- -```bash - make bf518 - cd build_bf518 - make lwext4 - ``` +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 + +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: ------------