<h1>Brief HOWTO on incorporating yaffs as a root fs.</h1>
<h4>By N C Bane &lt;nick@cecomputing.co.uk&gt;</h4>
<h3>Document status</h3>
<p>
This document is very much work in progress. It currently refers to YAFFS1 and needs updating for YAFFS2. It has been edited by different people with no attempt to keep a consistent style. Beauty will come with age.
</p>
<h2>What is yaffs?</h2>
<p>
Yaffs stands for Yet Another Flash Filing System.
</p>
<p>
It is a journaling filesystem designed to run on NAND flash with special reference to embedded systems.
</p>
<h2>Why would I want to use it?</h2>
<p>
NAND flash (SmartMedia cards are repackaged raw NAND chips) is cheap and has a fast erase time as compared with NOR flash.
</p>
<p>
The NAND physical interface is very simple.
</p>
<p>
The small size and low current requirements make it very suitable for embedded systems.
</p>
<p>
However, NAND has its problems. These are mainly due to bad block management as blocks of memory can be bad when the device is shipped and further blocks can become unusable over time.
</p>
<p>
Power can die unpredictably in embedded systems leading to data loss and possibly file system corruption.
</p>
<p>
This is where yaffs comes in; it handles bad blocks and uses formats which are resistant to corruption.
</p>
<h2>What do I need to know?</h2>
<p>
It is assumed that the reader has a development system with direct access to NAND flash (ie not a CF/SmartMedia adaptor which).
</p>
<p>
The user should be familiar with building linux kernels and patching build trees.
</p>
<p>
It is strongly suggested that you also read more about NAND flash on the Linux mtd site.
</p>
<h3>Assumptions:</h3>
<p>
You have already downloaded the yaffs sources from the cvs at Aleph1.
</p>
<p>
You have mtd code that exposes NAND as an mtdblock device.
</p>
<h3>Nand interface:</h3>
<p>
For yaffs to function, it must be able to be the only code that writes to the oob area on the NAND device.
</p>
<p>
The existing NAND driver in kernel 2.4.19 assumes that it will do the ecc/oob management for the host fs. For yaffs, this is quite wrong.
</p>
<p>
You can disable ecc/oob calculations either by hand patching the mtd code to bypass ecc calculations or by merging the latest mtd cvs.
</p>
<p>
The patches at http://www.toby-churchill.org have done the latter.
</p>
<h3>Including yaffs as a kernel fs:</h3>
<p>
1) Create [linux]/fs/yaffs directory in your kernel test source.
</p>
<p>
2) Copy devextras.h yaffs_fs.c yaffs_gets.c yaffs_guts.h yaffs_mtdif.c yaffs_mtdif.h yaffsinterface.h and yportenv.h from the yaffs sources to that directory.
</p>
<p>
3) Copy the Makefile from either the yaffs sources (Makefile.kernel) or the Balloon download site below to [linux]/fs/yaffs/Makefile.
</p>
<p>
4) Modify [linux]/fs/Config.in to include the 3 lines
</p>
<p>
<br />
</p>
<p>
if [ &quot;CONFIG_MTD_NAND&quot; = &quot;y&quot; ]; then
</p>
<p>
    tristate &quot;Yaffs filesystem on NAND&quot; CONFIG_YAFFS_FS
</p>
<p>
fi
</p>
<p>
5) Modify [linux]/fs/Makefile to include the yaffs fs reference
</p>
<p>
<br />
</p>
<p>
 subdir-$(CONFIG_YAFFS_FS) +=yaffs
</p>
<p>
<br />
</p>
<p>
6) Configure the kernel to include (not modules) all the mtd nand code (incl nand_ecc and mtdblock device) and yaffs fs.
</p>
<p>
You should now be able to build a kernel with yaffs as a root fs using the normal tools.
</p>
<h3>Creating a bootable yaffs partition:</h3>
<p>
You can
</p>
<p>
1) Create the partition by mounting it from a running linux os and copying the data there. The mkyaffs utility in the yaffs source simply erases a NAND mtdblock device without removing bad block data.
</p>
<p>
2) Make and download a filesystem image. The mkyaffsimage utility that came with the sources will create a YAFFS block list in a file from a root tree. This is a list of 512+16 byte blocks that need to be placed (in any order) on a NAND device.
</p>
<p>
You will need to write code to copy these data blocks and add in the block numbers in the oob areas.
</p>
<p>
Examples of a modified handhelds.org bootldr for the Balloon board can be found on the toby-churchill.org website.
</p>
<h3>Booting into yaffs:</h3>
<p>
Modify your bootloader to pass a  command line to linux to specifying the mtdblock/n that refers to the root partition.
</p>
<p>
&nbsp;
</p>
<p>
Balloon page at http://www.toby-churchill.org.uk
</p>
<p>
Yaffs mailing list - to join go to http://stoneboat.aleph1.co.uk/cgi-bin/mailman/listinfo/yaffs and enter your email address

</p>
<p>
Linux MTD http://www.linux-mtd.infradead.org/
</p>
<p>
$Id$
</p>
