1UFFS: Ultra-low-cost Flash File System 2 3Project: http://uffs.sf.net/ 4Blog: http://all-about-uffs.blogspot.com/ 5Q/A: http://groups.google.com/group/uffs/ 6 7Author: Ricky Zheng <[email protected]> 8 9INTRODUCTION 10------------ 11 12UFFS is a nand flash file system designed for embedded system. 13 14UFFS have some unique and advanced features: 15 * Low cost: e.g. it needs only 41K bytes RAM for 64MB NAND flash (page size 2048). 16 17 * Fast booting: it reads only a few spares from each block, typically 18 mounting a fully filled file system (Gbits) within one second. 19 20 * Superb Reliability: 21 - The file system is designed for the embedded system which may 22 frequently lost power/reset without care. 23 - Journal file system, the file system will automatically rollback 24 to the last state when lost power on the middle of flash programing. 25 - When 'write' return without error, the data is guarenteed been 26 saved on flash. 27 28 * Fast file create/read/write/seek. 29 * Bad-block tolerant, ECC enable and good ware-leveling. 30 * There is no garbage collection needed for UFFS. 31 * Support multiple NAND flash class in one system. 32 * Support bare flash hardware, no operating system needed. 33 * Support static memory allocation (works without 'malloc'). 34 * Fully simulated on PC (Windows/Linux) platform. 35 36Disadvantage: 37 * space inefficency for small files: UFFS use at least one 38 'block'(the minial erase unit for NAND flash, e.g. 16K ) for a file. 39 * maximum supported blocks: 2^16 = 65535 40 41Memory consuming example: 42 For page size = 512: 43 [VARY]Tree nodes: 16 * total_blocks 44 [CONST]Page Bufs: MAX_CACHED_BUFFERS(10) * (40 + pageSize(512)) = 5.4K 45 [CONST]Block Info caches: (24 + 14 * pages_per_block (32)) * MAX_CACHED_BLOCK_INFO (10) = 4.6K 46 47 Example 1: 128M bytes NAND, 8192 blocks, total memory cost: 48 (16 * 8192)128K + 5.4K + 4.6K = 138K bytes. 49 50 Example 2: 32M Bytes NAND, 2048 blocks, total memory cost: 51 (16 * 2048)32K + 5.4K + 4.6K = 42K bytes. 52 53 Example 3: 16M bytes NAND, 1024 blocks, total memory cost: 54 (16 * 1024)16K + 5.4K + 4.6K = 26K bytes. 55 56 For page size = 2048: 57 [VARY]Tree nodes: 16 * total_blocks 58 [CONST]Page Bufs: MAX_CACHED_BUFFERS(10) * (40 + pageSize(2048)) = 20.4K 59 [CONST]Block Info caches: (24 + 14 * pages_per_block (32)) * MAX_CACHED_BLOCK_INFO (10) = 4.6K 60 61 Example 1: 512M bytes NAND, 8192 blocks, total memory cost: 62 (16 * 8192)128K + 20.4K + 4.6K = 153K bytes. 63 64 Example 2: 128M Bytes NAND, 2048 blocks, total memory cost: 65 (16 * 2048)32K + 20.4K + 4.6K = 57K bytes. 66 67 Example 3: 64M bytes NAND, 1024 blocks, total memory cost: 68 (16 * 1024)16K + 20.4K + 4.6K = 41K bytes. 69 70 71BUILD SIMULATOR REQUIREMENT 72--------------------------- 73From V1.2.0, build uffs simulator requires 'cmake'. 74'cmake' can be downloaded from: http://www.cmake.org/ 75 76or, under Debian/Ubuntu: 77 sudo apt-get install cmake 78 79BUILD SIMULATOR ON LINUX 80------------------------ 811) create a 'build' dir: 82 83mkdir -p ~/build/uffs 84 852) create Makefiles and build: 86 cd ~/build/uffs 87 cmake <path_to_uffs> 88 make 89 905) run simulator (interactive mode): 91 src/utils/mkuffs 92 93 94BUILD SIMULATOR ON WINDOWS 95-------------------------- 96 971) create a 'build' dir along with uffs source dir, 98 d:\build\uffs 99 1002) Create VC project files: 101 cd build\uffs 102 cmake <path_to_uffs> 103 1043) Open uffs.dsw (or uffs.sln for VC > 6 ), compile & run. 105 106 107LATEST SOURCE CODE 108------------------ 109You can get the latest source code from git repository: 110 git clone git://uffs.git.sourceforge.net/gitroot/uffs/uffs 111 112 113CURRENT STATUS 114-------------- 115UFFS 0.1.x is a working version on PC simulator, also has been ported to 116uBase embedded OS as a 'real world' product for thousands of copies, 117it works fine so far. 118 119UFFS 0.2.0 implementes full directory. 120 121UFFS 1.0.0 is the first stable release at sf.net. 122 123UFFS 1.1.0: support NAND flash with large page size (up to 2K). 124 125UFFS 1.1.1: bug fixes. a tool for making uffs disk image. 126 127UFFS 1.1.2: bug fixes. add more Flash Class. change Licence from GNU GPLv2 to GNU LGPLv2 128 129UFFS 1.2.0: 130 - eliminate 'current path' and relatives. Now you should use absolute path in all 131 uffs APIs. For dir, the fullname should end with '/'. 132 - allow using static memory allocation, 'malloc' is no longer needed. 133 - using cmake for building simulator. 134 - bug fixes & minor changes. 135 136UFFS 1.2.1: 137 - improve bad block management 138 - bug fixes 139 - change Licence to modified GNU GPLv2. 140 141UFFS 1.3.0: 142 - improved flash interface 143 - support hardware ECC 144 - support user defined spare layout (for customized NAND flash controller) 145 - support 4K page size 146 - no partial page program required, support MLC NAND flash 147 - reduced buffer flushes by grouping buffers 148 - structual improvments and bug fixes 149 150UFFS v1.3.1: 151 - Tidy up three memory allocators: static, native and system. 152 - Fix bugs in flash interface example. 153 - Fix memory allocation bugs when using static memory allocator. 154 - Add flash driver interface 'WriteFullPage()'. 155 - Fix compilation errors for BlackFin DSP compiler. 156 157UFFS v1.3.2: 158 - Add POSIX like file system APIs. 159 - Bug fixes. 160 161UFFS v1.3.3: 162 - Change Flash Interface, simplify interface. 163 - Improved bad block handling. 164 - Better support for MLC NAND flash. 165 - Added hardware ECC and RS-ECC controller emulator. 166 - Bug fixes. 167 168UFFS v1.3.4 169 - New UO_NOECC option for skipping ECC (fast reading). 170 - POSIX compliance uffs_seek(). 171 - Improved unclean page detection (add new 'seal' byte in spare area). 172 - Optional page data CRC. 173 - Bug fixes. 174 - Other improvements. 175 176LICENCE 177------- 178 From v1.2.1, UFFS is released under a modified GNU GPLv2. (the same as eCos Licence) 179 The full licence text can be found in the header of source files: 180 181 UFFS is free software; you can redistribute it and/or modify it under 182 the GNU Library General Public License as published by the Free Software 183 Foundation; either version 2 of the License, or (at your option) any 184 later version. 185 186 UFFS is distributed in the hope that it will be useful, but WITHOUT 187 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 188 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 189 or GNU Library General Public License, as applicable, for more details. 190 191 You should have received a copy of the GNU General Public License 192 and GNU Library General Public License along with UFFS; if not, write 193 to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 194 Boston, MA 02110-1301, USA. 195 196 As a special exception, if other files instantiate templates or use 197 macros or inline functions from this file, or you compile this file 198 and link it with other works to produce a work based on this file, 199 this file does not by itself cause the resulting work to be covered 200 by the GNU General Public License. However the source code for this 201 file must still be made available in accordance with section (3) of 202 the GNU General Public License v2. 203 204 This exception does not invalidate any other reasons why a work based 205 on this file might be covered by the GNU General Public License. 206 207 208TESTING UFFS WITH SQLITE3 REGRESSION TEST CASES 209----------------------------------------------- 210UFFS can be tested with sqlite3 regression test cases (on Linux). 211 2121) install tcl8.5-dev on host PC: 213 apt-get install tcl8.5 tcl8.5-dev 214 215 # make sure your Linux is using tcl8.5 as the default tclsh: 216 sudo update-alternatives --config tclsh 217 (select "tclsh8.5" from the list.) 218 2192) build uffs: 220 mkdir -p ~/build/uffs 221 cd ~/build/uffs 222 cmake <path_to_uffs> 223 2243) build sqlite3: 225 cd <path_to_uffs>/src/test/sqlite3/sqlite-src-3070900 226 ./configure # create some build support files 227 git checkout -f Makefile config.h # restore modified Makefile and config.h 228 make test # start build 'testfixture' program. 229 230 # now you'll see something like: 231 Connect: Connection refused 232 Assert (uffs_ret == ret && ret == bak_ret) fail at /home/.../src/test/api_test/os_uffs.c:os_unlink:329: unlink("/home/.../src/test/sqlite3/sqlite-src-3070900/./test.db-journal"), unix return 0, uffs return -1, bak return -1 233 make: *** [test] Error 1 234 2354) run test cases: 236 Open two terminals. 237 on termional A: 238 cd ~/build/uffs 239 src/utils/mkuffs -t 1024 240 241 #on uffs simulator command line, enter: 242 format / 243 apisrv 244 245 on terminal B: 246 cd <path_to_uffs>/src/test/sqlite3/sqlite-src-3070900 247 ./test-uffs.sh 248 249 Note: if you want to run mkuffs on another PC, for example, a Windows PC, you need to specify the IP address in test-uffs.sh. 250 251 The test will take 1~4 hours, depends on how fast your Linux box is. 252 253 254ACKNOWLEDGMENT 255--------------- 256Special thanks for your contributions to: 257(list in no particular order) 258 259* Chen Jun <[email protected]> 260* Michail <[email protected]> 261* Sjpu <[email protected]> 262* RobertGray <[email protected]> 263* Dongbo <[email protected]> 264* Cag <[email protected]> 265* Sergey <[email protected]> 266* Chris Conrad <[email protected]> 267* Vladimir <[email protected]> 268* Thien Pham <[email protected]> 269* Emmanuel Blot <[email protected]> 270* Michael <[email protected]> 271* Mick D <[email protected]> 272* Paul <[email protected]> 273* Rogerz <[email protected]> 274 275 276