X-Git-Url: https://git.carlh.net/gitweb/?a=blobdiff_plain;f=README.md;h=3abd86066a6dc43e69c07ebc88cf520bdf38f6bf;hb=HEAD;hp=f9853ae30cdb0f2c88e199648262dee9da4be08a;hpb=4253692dd49156b401ad347568469bbcb0e006e0;p=lwext4.git diff --git a/README.md b/README.md index f9853ae..3abd860 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,21 @@ +[![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/) ![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 @@ -20,18 +25,29 @@ 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 support -* journal recovery +* 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 +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 ===== @@ -43,67 +59,52 @@ 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: yes (in progress) -* 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 * fs_test - test suite, mkfs and demo application -* lwext4 - internals of the lwext4 library -* toolchain - specific toolchain cmake files +* 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 ===== @@ -136,7 +137,7 @@ Compile & install tools lwext4-generic demo application ===== -Simple lwext4 library test applicatin: +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 @@ -195,19 +196,18 @@ 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: ------------