--- a/packages/fs/yaffs/current/ChangeLog
+++ b/packages/fs/yaffs/current/ChangeLog
@@ -1,3 +1,7 @@
+2009-08-28  Ross Younger  <wry@ecoscentric.com>
+
+	* doc/yaffs.sgml: Bring explanations of CDL options up-to-date.
+
 2009-08-26  Ross Younger  <wry@ecoscentric.com>
 
 	* Added support for small-page chips: incorporates and builds on work

--- a/packages/fs/yaffs/current/doc/yaffs.sgml
+++ b/packages/fs/yaffs/current/doc/yaffs.sgml
@@ -30,7 +30,7 @@
 
 <!-- }}} -->
 
-<!-- ### Uncomment to make a standalone book:
+<!-- ### Uncomment to make a standalone book: 
 <!DOCTYPE book  PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
 <book id="fs-yaffs-book">
     <bookinfo>
@@ -50,9 +50,9 @@
             </para>
         </legalnotice>
     </bookinfo>
- !   /### -->
+     !   /### -->
 
-<part id="fs-yaffs-p">
+<part id="fs-yaffs">
 <title>The YAFFS filesystem</title>
 
 <chapter id="yaffs-overview-c">
@@ -98,7 +98,7 @@ RedBoot's usual flexible scripting syste
 For more information about NAND flash chips,
 how they differ from NOR flash parts
 and other ways to access them, refer to the documentation for the
-<xref linkend="io-nand-overview" endterm="io-nand-short">.
+<xref linkend="io-nand-overview" endterm="io-nand-short"/>.
 </para>
 
 <para>
@@ -211,9 +211,6 @@ YAFFS provides a number of package optio
 </para>
 
 <variablelist>
-<varlistentry><term><constant>CYGPKG_FS_YAFFS_CFLAGS_ADD</constant></term><term><constant>CYGPKG_FS_YAFFS_CFLAGS_REMOVE</constant></term><listitem><para>
-Allows specific build options to be added to or removed from the CFLAGS
-list when building this library.</para></listitem></varlistentry>
 <varlistentry><term><constant>CYGSEM_FS_YAFFS_CACHE_SHORT_NAMES</constant></term><listitem><para>If
 set, caches files' short names in RAM. This consumes more RAM but
 improves performance.</para></listitem></varlistentry>
@@ -223,18 +220,49 @@ field in a <structname>struct dirent</st
 this, leave it switched off to save a little code size.</para></listitem></varlistentry>
 <varlistentry><term><constant>CYGNUM_FS_YAFFS_RESERVED_BLOCKS</constant></term><listitem><para>
 The number of blocks to keep in reserve to allow for garbage collection
-and block failures. The recommended value is 5, but you can tune it
-for performance.  <emphasis>This setting is a global default and may be
+and block failures. The recommended value is 5, but it can be tuned to suit your application:
+higher numbers can reduce the delay caused by garbage collection, at the cost of removing
+available space for storing files.
+<emphasis>This setting is a global default and may be
 changed by a mount-time option.</emphasis></para></listitem></varlistentry>
 <varlistentry><term><constant>CYGNUM_FS_YAFFS_SHORTOP_CACHES</constant></term><listitem><para>
 The number of page cache entries to use. Values of 10 to 20 are
-recommended; increasing the number consumes more RAM, and  0 disables
-it altogether.  <emphasis>This setting is a global default and may be
+recommended as a good compromise; increasing the number consumes more RAM but may
+improve performance.
+Set to 0 to disable these caches altogether. 
+<emphasis>This setting is a global default and may be
 changed by a mount-time option.</emphasis></para></listitem></varlistentry>
 <varlistentry><term><constant>CYGNUM_FS_YAFFS_TRACEMASK</constant></term><listitem><para>This
 is a 32-bit bitfield which controls diagnostic output. The bit definitions
-are found in <filename>yportenv.h</filename>; they are only useful if
-you are debugging YAFFS itself.</para></listitem></varlistentry>
+are found in <filename>yportenv.h</filename>; changing this setting tends to only be useful
+if you wish to debug YAFFS itself.</para></listitem></varlistentry>
+<varlistentry><term><constant>CYGPKG_FS_YAFFS_CFLAGS_ADD</constant></term>
+<term><constant>CYGPKG_FS_YAFFS_CFLAGS_REMOVE</constant></term><listitem><para>
+These settings allow specific build options to be added to or removed from the CFLAGS
+list when building YAFFS.</para></listitem></varlistentry>
+<varlistentry><term><constant>CYGSEM_FS_YAFFS_SMALLPAGE_MODE</constant></term>
+<listitem><para>This option only affects behaviour on so-called "small page" NAND devices
+(those whose pages are 512 bytes long).
+Such devices do not have enough space in their Out Of Band area to
+store a full set of YAFFS metadata tags. There are two ways to work
+around this: <itemizedlist><listitem><para><constant>YAFFS2</constant> mode -
+the default - uses regular tags, but at
+a price: it steals 16 bytes from the available space per page to store
+them. <emphasis>This reduces the apparent available
+size of your filesystem by 1/32!</emphasis></para></listitem>
+<listitem><para><constant>YAFFS1</constant> mode places a smaller tagset
+in the OOB area, but with a different side-effect: whenever a page is
+deleted, one byte of the tags area has to be rewritten.  Some devices
+forbid rewrite-without-erase in this way, so it may not be safe for you
+to use this option.  <emphasis>You must refer to the spec sheet for the chip on
+your board before selecting this option!</emphasis></para></listitem></itemizedlist>
+</para></listitem></varlistentry>
+<varlistentry><term><constant>CYGSEM_FS_YAFFS_OMIT_YAFFS2_CODE</constant></term><listitem><para>
+This causes all YAFFS2 code to be omitted from the build. This option only makes sense when
+all the devices on which YAFFS is to be used are small-page and operating in YAFFS1 mode.
+<note><para>There is no corresponding option to omit YAFFS1 code, because that code is only
+compiled when <constant>CYGSEM_FS_YAFFS_SMALLPAGE_MODE</constant> is set to YAFFS1.  </para></note>
+</para></listitem></varlistentry>
 </variablelist>
 </sect2>
 </sect1>
@@ -575,7 +603,7 @@ requires        { CYGPKG_REDBOOT implies
 This declaration only provideds the bare minimum heap required to mount a 
 trivial YAFFS filesystem. More will be required for all but the simplest
 of cases and it is recommended that you test for typical use in your
-environment. Refer also to <xref linkend="yaffs-mem-reqs">.
+environment. Refer also to <xref linkend="yaffs-mem-reqs"/>.
 </para></caution>
 
 <para>
@@ -603,4 +631,4 @@ you may find the option
 
 <!-- ### Uncomment to make a standalone book:
 </book>
- !   /### -->
+     /### -->