|
428
|
1 <!-- {{{ Banner --> |
|
|
2 |
|
|
3 <!-- =============================================================== --> |
|
|
4 <!-- --> |
|
|
5 <!-- yaffs.sgml --> |
|
|
6 <!-- --> |
|
|
7 <!-- Documentation for the eCos port of the YAFFS filesystem. --> |
|
|
8 <!-- --> |
|
|
9 <!-- =============================================================== --> |
|
|
10 <!-- ####ECOSDOCCOPYRIGHTBEGIN#### --> |
|
|
11 <!-- =============================================================== --> |
|
|
12 <!-- Copyright (C) 2009 eCosCentric Ltd. --> |
|
|
13 <!-- This material may be distributed only subject to the terms --> |
|
|
14 <!-- and conditions set forth in the Open Publication License, v1.0 --> |
|
|
15 <!-- or later (the latest version is presently available at --> |
|
|
16 <!-- http://www.opencontent.org/openpub/) --> |
|
|
17 <!-- Distribution of the work or derivative of the work in any --> |
|
|
18 <!-- standard (paper) book form is prohibited unless prior --> |
|
|
19 <!-- permission obtained from the copyright holder --> |
|
|
20 <!-- =============================================================== --> |
|
|
21 <!-- ####ECOSDOCCOPYRIGHTEND#### --> |
|
|
22 <!-- =============================================================== --> |
|
|
23 <!-- #####DESCRIPTIONBEGIN#### --> |
|
|
24 <!-- --> |
|
|
25 <!-- Author(s): wry --> |
|
|
26 <!-- Date: 2009-05-28 --> |
|
|
27 <!-- --> |
|
|
28 <!-- ####DESCRIPTIONEND#### --> |
|
|
29 <!-- =============================================================== --> |
|
|
30 |
|
|
31 <!-- }}} --> |
|
|
32 |
|
|
33 <!-- ### Uncomment to make a standalone book: |
|
|
34 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> |
|
|
35 <book id="fs-yaffs-book"> |
|
|
36 <bookinfo> |
|
|
37 <title>The YAFFS filesystem for eCos</title> |
|
|
38 <copyright><year>2009</year><holder>eCosCentric Limited</holder></copyright> |
|
|
39 <legalnotice> |
|
|
40 <title>Documentation licensing terms</title> |
|
|
41 <para>This material may be distributed only subject to the terms |
|
|
42 and conditions set forth in the Open Publication License, v1.0 |
|
|
43 or later (the latest version is presently available at |
|
|
44 <ulink url="http://www.opencontent.org/openpub/">http://www.opencontent.org/openpub/</ulink>). |
|
|
45 </para> |
|
|
46 <para> |
|
|
47 Distribution of the work or derivative of the work in any |
|
|
48 standard (paper) book form is prohibited unless prior |
|
|
49 permission is obtained from the copyright holder. |
|
|
50 </para> |
|
|
51 </legalnotice> |
|
|
52 </bookinfo> |
|
|
53 ! /### --> |
|
|
54 |
|
|
55 <part id="fs-yaffs"> |
|
|
56 <title>The YAFFS filesystem</title> |
|
|
57 |
|
|
58 <chapter id="yaffs-overview-c"> |
|
|
59 <title>What is YAFFS?</title> |
|
|
60 |
|
|
61 <para> |
|
|
62 YAFFS is a filesystem for NAND flash chips. |
|
|
63 </para> |
|
|
64 |
|
|
65 <para> |
|
|
66 YAFFS is accessed through the FILEIO package which presents a standard |
|
|
67 POSIX compatible IO interface through which applications use standard |
|
|
68 open(), read(), write() and close() calls. |
|
|
69 </para> |
|
|
70 |
|
|
71 <para> |
|
|
72 YAFFS is a <emphasis>journalling</emphasis> filesystem |
|
|
73 with <emphasis>wear-levelling</emphasis>. It is |
|
|
74 particularly suited to NAND flash parts, having been |
|
|
75 designed with their unique properties in mind. |
|
|
76 The use of traditional filesystems (FAT, ext2, etc) which do not have |
|
|
77 these features is not recommended on such chips because their design |
|
|
78 requires the use of fixed address on the underlying hardware. |
|
|
79 Such behaviour causes flash sectors to wear out, the consequence of |
|
|
80 which would typically be to cause the whole device to become unbootable. |
|
|
81 </para> |
|
|
82 |
|
|
83 <para> |
|
|
84 YAFFS also provides a high degree of robustness, which is usually |
|
|
85 a requirement of embedded devices. |
|
|
86 A power failure or other crash can leave a traditional filesystem |
|
|
87 in an inconsistent state which is often difficult to repair, |
|
|
88 especially in the field. |
|
|
89 </para> |
|
|
90 |
|
|
91 <para> |
|
|
92 YAFFS can also be built into RedBoot, which allows you to store |
|
|
93 application images on NAND flash and boot them with |
|
|
94 RedBoot's usual flexible scripting system. |
|
|
95 </para> |
|
|
96 |
|
|
97 <para> |
|
|
98 For more information about NAND flash chips, |
|
|
99 how they differ from NOR flash parts |
|
|
100 and other ways to access them, refer to the documentation for the |
|
|
101 <xref linkend="io-nand-overview" endterm="io-nand-short">. |
|
|
102 </para> |
|
|
103 |
|
|
104 <para> |
|
|
105 For more information about YAFFS itself, refer to |
|
|
106 <ulink url="http://www.yaffs.net/">yaffs.net</ulink>. |
|
|
107 </para> |
|
|
108 </chapter> |
|
|
109 |
|
|
110 <chapter id="yaffs-getstarted"><title>Getting started with YAFFS</title> |
|
|
111 |
|
|
112 <sect1 id="yaffs-licensing"><title>Licensing considerations</title> |
|
|
113 <para> |
|
|
114 Before you can use YAFFS, you must accept its license. |
|
|
115 <emphasis>YAFFS is not covered by the standard eCos license.</emphasis> |
|
|
116 You will be reminded of your license to use YAFFS when you install it. |
|
|
117 </para> |
|
|
118 |
|
|
119 <para> |
|
|
120 Most users will only have access to YAFFS under the GNU GPL. |
|
|
121 This costs nothing to license. However this usually means that if you ever |
|
|
122 distribute your application, |
|
|
123 you must do so under the GPL. |
|
|
124 This requires you to publish or otherwise make all of your application, |
|
|
125 eCos and everything else you link with it available as source code. |
|
|
126 For full details refer to the text of the |
|
|
127 <ulink url="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GPL |
|
|
128 (v2)</ulink>. |
|
|
129 </para> |
|
|
130 |
|
|
131 <para> |
|
|
132 If you cannot accept the restrictions and obligations of the GPL, |
|
|
133 YAFFS for eCos is available under a proprietary license, for a fee. |
|
|
134 Details are available on request from |
|
|
135 <ulink url="http://www.ecoscentric.com/">eCosCentric</ulink> or |
|
|
136 <ulink url="http://www.yaffs.net/yaffs-licences">Aleph One</ulink>. |
|
|
137 </para> |
|
|
138 </sect1> |
|
|
139 |
|
|
140 <sect1 id="yaffs-install"><title>Installation</title> |
|
|
141 <para> |
|
|
142 YAFFS is supplied as an EPK (eCos Package) file. |
|
|
143 </para> |
|
|
144 |
|
|
145 <sect2 id="yaffs-install-configtool"><title>Installation via the eCos |
|
|
146 Configuration Tool</title> |
|
|
147 <para> |
|
|
148 <orderedlist> |
|
|
149 <listitem><para>Open up the eCos Configuration Tool.</para></listitem> |
|
|
150 <listitem><para>Open up the <emphasis>Administration</emphasis> dialog, |
|
|
151 from the <emphasis>Tools</emphasis> menu.</para></listitem> |
|
|
152 <listitem><para>Press the <emphasis>Add</emphasis> button.</para></listitem> |
|
|
153 <listitem><para>A file browser windows opens. Navigate to the YAFFS EPK file.</para></listitem> |
|
|
154 <listitem><para>The License screen shows. You must accept the license |
|
|
155 in order to install the package. Press Yes if you do.</para></listitem> |
|
|
156 </orderedlist> |
|
|
157 </para> |
|
|
158 </sect2> |
|
|
159 |
|
|
160 <sect2 id="yaffs-install-commandline"><title>Installing from the |
|
|
161 command-line</title> |
|
|
162 <para> Advanced users may alternatively use the |
|
|
163 <filename>ecosadmin.tcl</filename> tool from the command line. You |
|
|
164 will be prompted to accept the license at the appropriate time during |
|
|
165 the procedure. |
|
|
166 </para> |
|
|
167 |
|
|
168 <programlisting> |
|
|
169 tclsh $ECOS_REPOSITORY/ecosadmin.tcl add yaffs-v1_2_3.epk |
|
|
170 </programlisting> |
|
|
171 </sect2> |
|
|
172 </sect1> |
|
|
173 |
|
|
174 <sect1 id="yaffs-config-build"><title>Configuration and Building</title> |
|
|
175 <para> |
|
|
176 After installing the EPK, YAFFS is added to your eCos repository |
|
|
177 and is configured and built in the normal way. |
|
|
178 </para> |
|
|
179 |
|
|
180 <sect2 id="yaffs-pkg-deps"><title>Package dependencies</title> |
|
|
181 <para> |
|
|
182 To link YAFFS into your application, |
|
|
183 add <filename>CYGPKG_FS_YAFFS</filename> to your eCos |
|
|
184 configuration in the normal way, either using the eCos Configuration Tool |
|
|
185 (<emphasis>Packages</emphasis> dialog on the <emphasis>Build</emphasis> |
|
|
186 menu), or the <filename>ecosconfig</filename> command-line tool.</para> |
|
|
187 |
|
|
188 <para> |
|
|
189 You will also need to add <filename>CYGPKG_IO_NAND</filename> and |
|
|
190 <filename>CYGPKG_IO_FILEIO</filename> to your configuration if they |
|
|
191 are not already present. |
|
|
192 Your platform HAL should supply packages for all NAND device(s) present. |
|
|
193 </para> |
|
|
194 |
|
|
195 <para> |
|
|
196 If you started with a smaller template than <emphasis>default</emphasis>, |
|
|
197 you may also need to add some of the following:</para> |
|
|
198 <itemizedlist> |
|
|
199 <listitem><para><filename>CYGPKG_LIBC_STDLIB</filename></para></listitem> |
|
|
200 <listitem><para><filename>CYGPKG_LIBC_STRING</filename> </para></listitem> |
|
|
201 <listitem><para><filename>CYGPKG_MEMALLOC</filename> or something else |
|
|
202 which provides <filename>CYGINT_ISO_MALLOC</filename></para></listitem> |
|
|
203 <listitem><para><filename>CYGPKG_LIBC_I18N</filename> or something else |
|
|
204 which provides <filename>CYGINT_ISO_CTYPE</filename></para></listitem> |
|
|
205 </itemizedlist> |
|
|
206 </sect2> |
|
|
207 |
|
|
208 <sect2 id="yaffs-pkg-options"><title>Configuration options</title> |
|
|
209 <para> |
|
|
210 YAFFS provides a number of package options, including tuning parameters. |
|
|
211 </para> |
|
|
212 |
|
|
213 <variablelist> |
|
|
214 <varlistentry><term><constant>CYGPKG_FS_YAFFS_CFLAGS_ADD</constant></term> |
|
|
215 <term><constant>CYGPKG_FS_YAFFS_CFLAGS_REMOVE</constant></term><listitem><para> |
|
|
216 These settings allow specific build options to be added to or removed from the CFLAGS |
|
|
217 list when building YAFFS.</para></listitem></varlistentry> |
|
|
218 <varlistentry><term><constant>CYGSEM_FS_YAFFS_CACHE_SHORT_NAMES</constant></term><listitem><para>If |
|
|
219 set, caches files' short names in RAM. This consumes more RAM but |
|
|
220 improves performance.</para></listitem></varlistentry> |
|
|
221 <varlistentry><term><constant>CYGPKG_FS_YAFFS_RET_DIRENT_DTYPE</constant></term><listitem><para>Controls |
|
|
222 whether YAFFS supports setting the <structfield>d_type</structfield> |
|
|
223 field in a <structname>struct dirent</structname>. If you don't need |
|
|
224 this, leave it switched off to save a little code size.</para></listitem></varlistentry> |
|
|
225 <varlistentry><term><constant>CYGNUM_FS_YAFFS_RESERVED_BLOCKS</constant></term><listitem><para> |
|
|
226 The number of blocks to keep in reserve to allow for garbage collection |
|
|
227 and block failures. The recommended value is 5, but you can tune it |
|
|
228 for performance. <emphasis>This setting is a global default and may be |
|
|
229 changed by a mount-time option.</emphasis></para></listitem></varlistentry> |
|
|
230 <varlistentry><term><constant>CYGNUM_FS_YAFFS_SHORTOP_CACHES</constant></term><listitem><para> |
|
|
231 The number of page cache entries to use. Values of 10 to 20 are |
|
|
232 recommended; increasing the number consumes more RAM, and 0 disables |
|
|
233 it altogether. <emphasis>This setting is a global default and may be |
|
|
234 changed by a mount-time option.</emphasis></para></listitem></varlistentry> |
|
|
235 <varlistentry><term><constant>CYGNUM_FS_YAFFS_TRACEMASK</constant></term><listitem><para>This |
|
|
236 is a 32-bit bitfield which controls diagnostic output. The bit definitions |
|
|
237 are found in <filename>yportenv.h</filename>; they are only useful if |
|
|
238 you are debugging YAFFS itself.</para></listitem></varlistentry> |
|
|
239 <varlistentry><term><constant>CYGNUM_FS_YAFFS_TEMP_BUFFERS</constant></term> |
|
|
240 <listitem><para> |
|
|
241 YAFFS requires temporary buffers in many places throughout the code. |
|
|
242 To avoid the overhead of a dynamic malloc every time, a number of |
|
|
243 buffers are preallocated at mount time. This setting controls how many; |
|
|
244 should it not prove enough, YAFFS will call malloc on demand as required. |
|
|
245 The default setting is 6; most users will not need to change it. |
|
|
246 </para></listitem></varlistentry> |
|
|
247 <varlistentry><term><constant>CYGSEM_FS_YAFFS_SMALLPAGE_MODE</constant></term> |
|
|
248 <listitem><para>This option only affects behaviour on so-called "small page" NAND devices |
|
|
249 (those whose pages are 512 bytes long). |
|
|
250 Such devices do not have enough space in their Out Of Band area to |
|
|
251 store a full set of YAFFS metadata tags. There are two ways to work |
|
|
252 around this: <itemizedlist><listitem><para><constant>YAFFS2</constant> mode - |
|
|
253 the default - uses regular tags, but at |
|
|
254 a price: it steals 16 bytes from the available space per page to store |
|
|
255 them. <emphasis>This reduces the apparent available |
|
|
256 size of your filesystem by 1/32!</emphasis></para></listitem> |
|
|
257 <listitem><para><constant>YAFFS1</constant> mode places a smaller tagset |
|
|
258 in the OOB area, but with a different side-effect: whenever a page is |
|
|
259 deleted, one byte of the tags area has to be rewritten. Some devices |
|
|
260 forbid rewrite-without-erase in this way, so it may not be safe for you |
|
|
261 to use this option. <emphasis>You must refer to the spec sheet for the chip on |
|
|
262 your board before selecting this option!</emphasis></para></listitem></itemizedlist> |
|
|
263 </para></listitem></varlistentry> |
|
|
264 <varlistentry><term><constant>CYGSEM_FS_YAFFS_OMIT_YAFFS2_CODE</constant></term><listitem><para> |
|
|
265 This causes all YAFFS2 code to be omitted from the build. This option only makes sense when |
|
|
266 all the devices on which YAFFS is to be used are small-page and operating in YAFFS1 mode. |
|
|
267 <note><para>There is no corresponding option to omit YAFFS1 code, because that code is only |
|
|
268 compiled when <constant>CYGSEM_FS_YAFFS_SMALLPAGE_MODE</constant> is set to YAFFS1. </para></note> |
|
|
269 </para></listitem></varlistentry> |
|
|
270 </variablelist> |
|
|
271 </sect2> |
|
|
272 </sect1> |
|
|
273 |
|
|
274 <sect1 id="yaffs-using"><title>Using YAFFS</title> |
|
|
275 <para> |
|
|
276 YAFFS appears in the eCos filesystem table. |
|
|
277 This means that you can mount a filesystem in the standard Unix-like way, |
|
|
278 then interact with it with calls to open, read, etc. |
|
|
279 </para> |
|
|
280 |
|
|
281 <sect2 id="yaffs-mounting"><title>Mounting a filesystem</title> |
|
|
282 |
|
|
283 <para> |
|
|
284 Before you can use a filesystem, it must be <emphasis>mounted</emphasis>. |
|
|
285 </para> |
|
|
286 |
|
|
287 <para> |
|
|
288 A NAND device is logically organised as one or more |
|
|
289 <emphasis>partitions</emphasis>, which are |
|
|
290 usually set up by the relevant platform HAL. |
|
|
291 You need to tell the mount command |
|
|
292 which device and partition you wish to access. In the following example, |
|
|
293 we are mounting partition 0 of the <emphasis>onboard</emphasis> NAND device. |
|
|
294 </para> |
|
|
295 <!-- FIXME: Update if partition naming is changed. --> |
|
|
296 |
|
|
297 <programlisting> |
|
|
298 rv = mount("onboard/0", "/nand", "yaffs"); |
|
|
299 </programlisting> |
|
|
300 |
|
|
301 <note><para>The <emphasis>device</emphasis> argument to the |
|
|
302 <function>mount</function> call is a NAND-specific device name, not |
|
|
303 an entry in /dev. |
|
|
304 Refer to the documentation for your platform HAL for details of how |
|
|
305 the NAND device(s) are named, and to the NAND library documentation |
|
|
306 for details of how partitions are addressed. |
|
|
307 </para></note> |
|
|
308 |
|
|
309 <para> |
|
|
310 You can, if you wish, make the filesystem mounting automatic at |
|
|
311 static constructor time with the MTAB_ENTRY macro. (Your platform |
|
|
312 HAL may already do this; check it carefully.) |
|
|
313 </para> |
|
|
314 |
|
|
315 <programlisting> |
|
|
316 MTAB_ENTRY(my_nand, "/nand", "yaffs", "onboard/0", "", 0); |
|
|
317 </programlisting> |
|
|
318 |
|
|
319 <note><para>This example is for eCosPro. In eCos, the MTAB_ENTRY macro |
|
|
320 takes only four arguments.</para></note> |
|
|
321 |
|
|
322 <sect3 id="yaffs-mount-options"><title>Mount-time options</title> |
|
|
323 <para> |
|
|
324 eCosPro allows various options to be passed to a filesystem at mount time, |
|
|
325 by combining them with the filesystem argument in a particular format. |
|
|
326 YAFFS understands the following options: |
|
|
327 </para> |
|
|
328 |
|
|
329 <itemizedlist> |
|
|
330 <listitem><para><constant>reserved</constant>=<int> The number of |
|
|
331 physical NAND blocks to reserve for garbage collection and block failures |
|
|
332 (minimum 2). The default is set in CDL as |
|
|
333 <constant>CYGNUM_FS_YAFFS_RESERVED_BLOCKS</constant>.</para></listitem> |
|
|
334 <listitem><para><constant>caches</constant>=<int> The number of |
|
|
335 page cache entries to use. |
|
|
336 Values of 10 to 20 are recommended. |
|
|
337 The default is set in CDL as |
|
|
338 <constant>CYGNUM_FS_YAFFS_SHORTOP_CACHES</constant>.</para></listitem> |
|
|
339 <listitem><para><constant>skip-checkpoint-read</constant> Instructs YAFFS |
|
|
340 to not attempt to reload the filesystem from a checkpoint, if one exists. |
|
|
341 In other words, this option forces a full filesystem scan whether or not |
|
|
342 one is necessary.</para></listitem> |
|
|
343 </itemizedlist> |
|
|
344 </sect3> |
|
|
345 </sect2> |
|
|
346 |
|
|
347 <sect2 id="yaffs-sync"><title>Data flushing</title> |
|
|
348 <para> |
|
|
349 YAFFS operates a cacheing layer in order to save undue wear on the |
|
|
350 NAND chip if many small writes are performed. Because of this, |
|
|
351 if you wish to ensure that any data written to a still-open file has |
|
|
352 been fully flushed, you must make a synchronisation request. This is |
|
|
353 done with the <function>fsync</function> function, which takes as its |
|
|
354 argument the file descriptor of the file you wish to synchronise.</para> |
|
|
355 </sect2> |
|
|
356 |
|
|
357 <sect2 id="yaffs-checkpointing"><title>Checkpointing</title> |
|
|
358 <para> |
|
|
359 When mounting a filesystem, YAFFS has to scan the NAND chip to recreate |
|
|
360 its internal state. This can be a slow process, but is made much |
|
|
361 faster if there is a valid <emphasis>checkpoint</emphasis>. |
|
|
362 </para> |
|
|
363 |
|
|
364 <para> |
|
|
365 A checkpoint is written out automatically when you unmount the filesystem. |
|
|
366 At any other time, you can manually force a checkpoint to be written |
|
|
367 with one of the following functions: |
|
|
368 </para> |
|
|
369 |
|
|
370 <itemizedlist> |
|
|
371 <listitem><para><function>cyg_fs_fssync(mountpoint)</function> |
|
|
372 synchronises a filesystem (automatically called on umount)</para></listitem> |
|
|
373 <listitem><para><function>sync</function> synchronises all mounted |
|
|
374 filesystems.</para></listitem> |
|
|
375 </itemizedlist> |
|
|
376 |
|
|
377 <note><para> |
|
|
378 A checkpoint becomes invalid as soon as there have been any other writes |
|
|
379 to the filesystem. Finding a good place to sync is necessarily dependent |
|
|
380 on your application logic.</para> |
|
|
381 </note> |
|
|
382 </sect2> |
|
|
383 |
|
|
384 <sect2 id="yaffs-limitations"><title>Limitations</title> |
|
|
385 <para> |
|
|
386 Although YAFFS is a Unix-compatible filesystem, the eCos port does not |
|
|
387 provide support for the full range of Unix attributes. |
|
|
388 </para> |
|
|
389 <itemizedlist> |
|
|
390 <listitem><para> eCos does not check file or directory permissions; |
|
|
391 everything it creates is given fixed user and group IDs of zero and |
|
|
392 standard permissions (files rw-r--r--, directories rwxr-xr-x).</para></listitem> |
|
|
393 <listitem><para> It is not currently possible to change file ownership |
|
|
394 or permissions.</para></listitem> |
|
|
395 <listitem><para> It is not currently possible to create symbolic links, |
|
|
396 FIFOs (named pipes), sockets or device nodes.</para></listitem> |
|
|
397 <listitem><para> Hard links to files work in the expected way. Hard |
|
|
398 links to directories are forbidden.</para></listitem> |
|
|
399 <listitem><para> It is not possible to unlink the '.', '..' or |
|
|
400 'lost+found' special directories.</para></listitem> |
|
|
401 </itemizedlist> |
|
|
402 |
|
|
403 <note><para> |
|
|
404 If you will be sharing a YAFFS filesystem between eCos and some other |
|
|
405 operating system, you are advised to carefully check the other system's |
|
|
406 definitions of mode (permission) bits and whether any translation may be |
|
|
407 required.</para> |
|
|
408 </note> |
|
|
409 </sect2> |
|
|
410 </sect1> |
|
|
411 |
|
|
412 <sect1 id="yaffs-mem-reqs"><title>Memory requirements</title> |
|
|
413 <para> |
|
|
414 The amount of RAM required by YAFFS to hold its in-memory data structures |
|
|
415 grows with the number of objects (files and directories) in your |
|
|
416 filesystem. |
|
|
417 You are recommended to test your application thoroughly to ensure |
|
|
418 that sufficient memory exists for YAFFS to operate with the |
|
|
419 most complicated filesystem it is likely to encounter.</para> |
|
|
420 |
|
|
421 <para> |
|
|
422 If you wish to estimate your RAM usage, the YAFFS author provides the |
|
|
423 following calculation:</para> |
|
|
424 |
|
|
425 <itemizedlist> |
|
|
426 <listitem><para> The partition itself requires a yaffs_DeviceStruct of 3608 |
|
|
427 bytes.</para></listitem> |
|
|
428 <listitem><para> If CYGNUM_FS_YAFFS_SHORTOP_CACHES is enabled, each |
|
|
429 is the size of a NAND page plus 28 bytes.</para></listitem> |
|
|
430 <listitem><para> Every object (file, directory or hardlink) in the |
|
|
431 filesystem takes a yaffs_Object struct, which is 124 bytes.</para></listitem> |
|
|
432 <listitem><para> Every page of every file requires a Tnode entry, but |
|
|
433 they are always allocated in groups of 16 at a time.</para> |
|
|
434 <itemizedlist> |
|
|
435 <listitem><para>The size of a single Tnode entry is the |
|
|
436 number of <emphasis>bits</emphasis> required to number all the |
|
|
437 pages in the NAND partition YAFFS is using, numbering from |
|
|
438 <emphasis>one</emphasis>; this is rounded up to a multiple of 2, |
|
|
439 and has an absolute minimum of sixteen bits.</para></listitem> |
|
|
440 <listitem><para>For example: on a partition with 65536 pages, |
|
|
441 seventeen bits are required for the numbering, which round up to |
|
|
442 18. Therefore each file takes 288 bits (36 bytes) per group of Tnodes, |
|
|
443 and one group of Tnodes will cover up to sixteen pages of data.</para></listitem> |
|
|
444 </itemizedlist> |
|
|
445 </listitem> |
|
|
446 </itemizedlist> |
|
|
447 |
|
|
448 <note><para><emphasis>Actual memory consumption will be slightly |
|
|
449 higher than suggested by the above.</emphasis> This arises from the |
|
|
450 tree structure holding the Tnodes, overheads from the heap itself, |
|
|
451 and so on.</para></note> |
|
|
452 |
|
|
453 <para> |
|
|
454 YAFFS calls the standard <function>malloc</function> function to allocate |
|
|
455 memory and <function>free</function> to release it. Normally, the eCos |
|
|
456 heap occupies all spare RAM not needed for the program, its static |
|
|
457 data or the stacks. Therefore, most applications will not need to do |
|
|
458 anything special beyond ensuring there is enough spare RAM available on |
|
|
459 the platform.</para> |
|
|
460 |
|
|
461 <tip><para> |
|
|
462 If you wish to experiment with restricted-size heaps to determine |
|
|
463 much memory your application actually uses under YAFFS, |
|
|
464 you may find the option |
|
|
465 <constant>CYGSEM_MEMALLOC_INVOKE_OUT_OF_MEMORY</constant> of use. |
|
|
466 </para></tip> |
|
|
467 |
|
|
468 <sect2 id="yaffs-mem-reqs-example"><title>Worked example</title> |
|
|
469 <para> |
|
|
470 Consider a YAFFS filesystem hosted by a NAND partition with 65536 pages, |
|
|
471 each of size 2k, using the default setting of ten short-op caches. |
|
|
472 On this filesystem we shall store 10000 files each of |
|
|
473 size 10240 bytes, hence each requires a single group of Tnodes. |
|
|
474 </para> |
|
|
475 |
|
|
476 <table frame=all pgwide=0><title>YAFFS RAM use worked example</title> |
|
|
477 <tgroup cols=2> |
|
|
478 <colspec colname=c1> |
|
|
479 <colspec colname=c2> |
|
|
480 <thead><row> |
|
|
481 <entry>Consumer</entry> |
|
|
482 <entry>RAM used (bytes)</entry> |
|
|
483 </row></thead> |
|
|
484 <tfoot><row> |
|
|
485 <entry>Total</entry> |
|
|
486 <entry align=right> 1,624,368 </entry> |
|
|
487 </row></tfoot> |
|
|
488 <tbody> |
|
|
489 <row> |
|
|
490 <entry> yaffs_DeviceStruct </entry> |
|
|
491 <entry align=right> 3,608 </entry> |
|
|
492 </row> |
|
|
493 <row> |
|
|
494 <entry> Short-op caches @ 10 x (2048+28)</entry> |
|
|
495 <entry align=right> 20,760 </entry> |
|
|
496 </row> |
|
|
497 <row> |
|
|
498 <entry> yaffs_Objects @ 10,000 x 124 </entry> |
|
|
499 <entry align=right> 1,240,000 </entry> |
|
|
500 </row> |
|
|
501 <row> |
|
|
502 <entry> Tnode groups @ 10,000 x 36 <emphasis>(see above)</emphasis></entry> |
|
|
503 <entry align=right> 360,000 </entry> |
|
|
504 </row> |
|
|
505 </tbody> |
|
|
506 </tgroup> |
|
|
507 </table> |
|
|
508 |
|
|
509 <para> |
|
|
510 This example is a close match to the actual consumption measured by |
|
|
511 eCosCentric during testing. (The measured consumption as reported |
|
|
512 by <function>mallinfo</function> was 1,681,112 bytes, which includes |
|
|
513 the heap's own overheads.) |
|
|
514 </para> |
|
|
515 </sect2> |
|
|
516 </sect1> |
|
|
517 |
|
|
518 <sect1 id="yaffs-testing"><title>Testing</title> |
|
|
519 <para> |
|
|
520 YAFFS is supplied with a number of test programs, some of which are have been |
|
|
521 adapted from tests for other filesystems in eCos. |
|
|
522 </para> |
|
|
523 |
|
|
524 <glosslist> |
|
|
525 <glossentry><glossterm>fops</glossterm><glossdef><para> |
|
|
526 This was the first basic test created for the port of the filesystem. |
|
|
527 It is believed to exercise all of the code paths (filesystem operations, |
|
|
528 file operations and directory operations) within the eCos-YAFFS |
|
|
529 adaptation layer. </para> <para> |
|
|
530 This test was originally intended to run on a synthetic NAND filesystem. |
|
|
531 On real NAND chips, it deliberately omits the more stressful routines to |
|
|
532 avoid undue wear on the hardware. |
|
|
533 </para></glossdef></glossentry> |
|
|
534 <glossentry><glossterm>yaffs1</glossterm><glossdef><para> |
|
|
535 A number of filesystem edge-case semantic tests, including |
|
|
536 file and directory creation and deletion, |
|
|
537 invalid open and rename operations, and |
|
|
538 removing nonexistent files and directories. |
|
|
539 </para></glossdef></glossentry> |
|
|
540 <glossentry><glossterm>yaffs2</glossterm><glossdef><para> |
|
|
541 Concurrent multi-threaded filesystem access and consistency checks. |
|
|
542 </para></glossdef></glossentry> |
|
|
543 <glossentry><glossterm>yaffs4</glossterm><glossdef><para> |
|
|
544 Semantic and edge-case testing - like yaffs1 - but with long file names. |
|
|
545 </para></glossdef></glossentry> |
|
|
546 <glossentry><glossterm>yaffs5</glossterm><glossdef><para> |
|
|
547 Tests that file reading and writing works over reasonably large files |
|
|
548 (up to 1Mbyte) with different I/O chunk sizes. Some operation timings |
|
|
549 are collected and reported, as is the data rate on large files. |
|
|
550 </para></glossdef></glossentry> |
|
|
551 <glossentry><glossterm>yaffs6</glossterm><glossdef><para> |
|
|
552 Semantic and edge-case testing - like yaffs1 - but with Cyrillic filenames |
|
|
553 in order to test UTF-8 correctness. |
|
|
554 </para></glossdef></glossentry> |
|
|
555 <glossentry><glossterm>mounttime</glossterm><glossdef><para> |
|
|
556 A simple benchmark which repeatedly mounts and unmounts the filesystem |
|
|
557 and measures how long this takes. |
|
|
558 You can optionally use the <filename>mkfiles</filename> routine - also |
|
|
559 present in the tests directory - to create many short files so you can |
|
|
560 test performance on a loaded filesystem. |
|
|
561 </para></glossdef></glossentry> |
|
|
562 <glossentry><glossterm>hammer</glossterm><glossdef><para> |
|
|
563 A stress test designed to shake out corner cases. |
|
|
564 Repeatedly creates many files of varying sizes from multiple threads |
|
|
565 until the filesystem fills up, then verifies their contents and removes |
|
|
566 them. From time to time, all threads pause and the filesystem is |
|
|
567 unmounted and remounted. </para><para>This test is particularly useful when |
|
|
568 combined with the bad block injection functionality provided by |
|
|
569 the synthetic NAND device. It has been used in this way by eCosCentric to |
|
|
570 thoroughly test this package's stability under error conditions. |
|
|
571 <note><para>This test runs forever, until interrupted.</para></note> |
|
|
572 </para></glossdef></glossentry> |
|
|
573 </glosslist> |
|
|
574 </sect1> |
|
|
575 </chapter> |
|
|
576 |
|
|
577 <chapter id="yaffs-redboot"><title>Using YAFFS with RedBoot</title> |
|
|
578 <para> |
|
|
579 It is possible to link YAFFS into RedBoot and use it to boot an |
|
|
580 executable image stored on a NAND array. |
|
|
581 </para> |
|
|
582 |
|
|
583 <para> |
|
|
584 This is done by configuring and building RedBoot largely in the normal way. |
|
|
585 You will need to add <filename>CYGPKG_FS_YAFFS</filename> and |
|
|
586 <filename>CYGPKG_IO_FILEIO</filename> to your configuration, plus their |
|
|
587 attendant dependencies. |
|
|
588 </para> |
|
|
589 |
|
|
590 <para> |
|
|
591 The presence of CYGPKG_IO_FILEIO activates the <filename>fs</filename> series |
|
|
592 of RedBoot commands. The following (edited) transcript illustrates how |
|
|
593 they might |
|
|
594 be used in concert with other RedBoot commands to store an ELF image on |
|
|
595 a NAND partition, load it back and execute: |
|
|
596 </para> |
|
|
597 |
|
|
598 <programlisting> |
|
|
599 RedBoot> fs mount -d onboard/0 -t yaffs /nand |
|
|
600 yaffs: restored from checkpoint |
|
|
601 RedBoot> load -r -h my.tftp.ip.address -b %{freememlo} my.image |
|
|
602 Using default protocol (TFTP) |
|
|
603 Raw file loaded 0xa013f000-0xa01554b3, assumed entry at 0xa013f000 |
|
|
604 RedBoot> fs write /nand/myimg.elf |
|
|
605 RedBoot> fs list /nand |
|
|
606 1 drwxr-xr-x 0 size 0 . |
|
|
607 1 drwxr-xr-x 0 size 0 .. |
|
|
608 262 -rw-r--r-- 0 size 91316 myimg.elf |
|
|
609 2 drwxr-xr-x 0 size 0 lost+found |
|
|
610 RedBoot> load -m file /nand/myimg.elf |
|
|
611 RedBoot> go |
|
|
612 Hello, NAND world! |
|
|
613 </programlisting> |
|
|
614 |
|
|
615 <note><para>When you command RedBoot to execute an image, it |
|
|
616 first synchronises all mounted filesystems. Therefore, |
|
|
617 provided these filesystems support the synchronisation operation |
|
|
618 (which YAFFS does), it is not always necessary to unmount them before |
|
|
619 invoking an image. |
|
|
620 </para> |
|
|
621 </note> |
|
|
622 |
|
|
623 <sect1 id="yaffs-rb-mem"><title>Memory considerations under RedBoot</title> |
|
|
624 <para> |
|
|
625 RedBoot traditionally has very limited requirements for memory management; |
|
|
626 the main need is for there to be free space in RAM at the correct |
|
|
627 (physical) address to load an image before jumping to it. |
|
|
628 </para> |
|
|
629 |
|
|
630 <para> |
|
|
631 Introducing YAFFS brings with it not just the need to have dynamically |
|
|
632 allocatable RAM (<filename>CYGPKG_MEMALLOC</filename>), but enough |
|
|
633 to replay the filesystem journal. This must be balanced against the need |
|
|
634 for RAM to load images into. |
|
|
635 </para> |
|
|
636 |
|
|
637 <para> |
|
|
638 When the <filename>CYGPKG_MEMALLOC</filename> package is present in |
|
|
639 RedBoot, by default a small (64k) heap is set up so that the maximum RAM |
|
|
640 possible is available for loading images. This is not enough to |
|
|
641 support YAFFS in any circumstances, so the following definition has |
|
|
642 been included in the <filename>yaffs.cdl</filename> file: |
|
|
643 </para> |
|
|
644 |
|
|
645 <programlisting> |
|
|
646 requires { CYGPKG_REDBOOT implies (CYGMEM_REDBOOT_WORKSPACE_HEAP_SIZE >= 0x00014000) } |
|
|
647 </programlisting> |
|
|
648 |
|
|
649 <caution><para> |
|
|
650 This declaration only provideds the bare minimum heap required to mount a |
|
|
651 trivial YAFFS filesystem. More will be required for all but the simplest |
|
|
652 of cases and it is recommended that you test for typical use in your |
|
|
653 environment. Refer also to <xref linkend="yaffs-mem-reqs">. |
|
|
654 </para></caution> |
|
|
655 |
|
|
656 <para> |
|
|
657 It is recommended that, should you wish to make a filesystem usable by |
|
|
658 RedBoot, your platform HAL should make a similar |
|
|
659 declaration in its CDL to establish an appropriate heap size. |
|
|
660 |
|
|
661 For example, the platform HAL for the EA LPC2468 OEM board - which has |
|
|
662 a 128MB NAND chip on-board - contains the following declaration: |
|
|
663 </para> |
|
|
664 |
|
|
665 <programlisting> |
|
|
666 requires { (CYGPKG_REDBOOT && CYGPKG_FS_YAFFS) implies (CYGMEM_REDBOOT_WORKSPACE_HEAP_SIZE >= 0x20000) } |
|
|
667 </programlisting> |
|
|
668 |
|
|
669 <tip><para> |
|
|
670 If you wish to experiment with restricted heaps to determine |
|
|
671 much memory your application actually uses under YAFFS, |
|
|
672 you may find the option |
|
|
673 <constant>CYGSEM_MEMALLOC_INVOKE_OUT_OF_MEMORY</constant> of use. |
|
|
674 </para></tip> |
|
|
675 </sect1> |
|
|
676 </chapter> |
|
|
677 </part> |
|
|
678 |
|
|
679 <!-- ### Uncomment to make a standalone book: |
|
|
680 </book> |
|
|
681 /### --> |
