%
% JFFS3 design issues.
%
% Copyright (C) 2005 Artem B. Bityuckiy, dedekind@infradead.org
%
% $Id: JFFS3design.tex,v 1.25 2005/02/26 14:54:26 dedekind Exp $
%

\documentclass[12pt,a4paper,oneside,titlepage]{article}
\usepackage{hyperref}
\usepackage{html}
\textwidth=18cm
\oddsidemargin=0cm
\topmargin=0cm
\textheight=24cm

\begin{document}

%
%  TITLE PAGE
%
\title{JFFS3 design issues}
\author{Artem B. Bityuckiy}
\maketitle

%
% ABSTRACT
%
\pagestyle{empty}
\begin{abstract}
This document discusses various JFFS3 high-level design aspects.
Additionally, it defines standard JFFS3 dictionary and terms.
\end{abstract}

%
% TABLE OF CONTENTS
%
\tableofcontents
\newpage

\pagestyle{plain}
\pagenumbering{arabic}

\section*{Document status}
Incomplete, working draft.

%
% CHECKSUM
%
\section{Checksum}
Any data (including actual file content and internal JFFS3 data) stored within
JFFS3 file-system is protected by checksum. Nothing is stored on the flash media
without checksum.

Checksums are destined to detect errors caused by wearing, BB appearance
or external factors (radiation, abnormal temperatures and the
like). Errors fall into the following caticories.

\begin{itemize}
\item \emph{Permanent} error is an error which stays after the corresponding block has
been erased.
\item \emph{Occasional} error is an error which becomes fixed after the corresponding
block has been erased.
\end{itemize}

Different flash technologies imply different reliability. The following is the
brief overview of Flash technologies in this perspective.

\begin{itemize}
\item \emph{NOR}
flash is the most trustworthy type of flashes which doesn't admit of permanent
errors. Any permanent error is critical and means that the chip is not workable anymore.
Nevertheless, some kinds of NOR flash are not avoid of very rare bit flipping
events and the use of checksum still might make sense here.

\item \emph{DataFlash} is based on NOR technology and inherits its properties.
[\ref{ref_AtmelDataFlash}].

\item \emph{ECC NOR} may be regarded as not very robust NOR flash plus extra ECC
protection.

\item \emph{NAND} flash is not so reliable as NOR and it admits of permanent errors, let
alone occasional ones which are also possible. The NAND technology itself
implies bad blocks may dynamically appear during its utilization, albeit this is
rather rare event [\ref{ref_NANDMTD}, \ref{ref_ToshibaNAND}].

\item \emph{OneNAND} is based on NAND technology and has similar properties
[\ref{ref_SamsungOneNAND}].

\item \emph{AND} (\emph{AG-AND} and \emph{SuperAND}),
like NAND technology, implies bad blocks either factory marked
or dynamically found [\ref{ref_RenesasAND}].

\end{itemize}

%
% Checksum modes
%
\subsection{Checksum modes}
Because of a significant disparity in the reliability between different types of
flashes JFFS3 might operate in either of the following modes.

\begin{enumerate}
\item \emph{Strict mode} -- checksums are always verified i.e. anything JFFS2
reads from the flash is validated by checksum. This is safest operation mode and
should probably always be enabled by default at least with NAND/AND flashes.

\item \emph{Relaxed mode} -- data checksums are not ever being checked, i.e
JFFS3 still checks node headers and other internal data but doesn't check actual
file's content. This is dangerous working mode and may probably only be enabled
by default when JFFS3 works on top of NOR flash.
\end{enumerate}

Both of the above mentioned operation modes imply that JFFS3 calculates and
saves checksums when it is performing write operations.

If the underlying flash makes use of ECC (e.g., NAND), and JFFS3 has been
reported ECC error, JFFS3 checks the corresponding data that had been read.

The checksum mode might be set on the per file basis with
help of the corresponding extended attribute. In this case the extended
attribute overrides the default mode. This is very handy mechanism
whereby users might, for example, disable the checking of multimedia
file's content.

%
% Checksum and unclean reboots
%
\subsection{Checksum and unclean reboots}
Unlike JFFS2, JFFS3 does not utilize checksum to detect unclean reboots, albeit
might do this. The primary aim of checksum is to prevent problems
related to physical media corruptions. Unclean reboots are substantially
detected by means of summary nodes. This property makes it possible to distinct
between checksum errors caused by media problems and by unclean reboots.

%
% Checksum errors
%
\subsection{Checksum errors}
If a checksum error has been found and if it has not been caused by
an unclean reboot, JFFS3 behaves as follows.

\begin{enumerate}
\item Reports the fact of the checksum error.

\item Takes an attempt to recover the erroneous node. 
Ignores the erroneous node (possibly, marking it obsolete) irrespective
of the recovery procedure result (success or failure).

\item Locks the inode to whom the erroneous node belongs. Namely,
rejects any further access to the inode. This might be implementing by
means of setting the relating extended attribute. JFFS3
must not reject xattr operation whereby user might clean the
attribute that locks the inode.

\item Returns an error if the operation was being done on behalf of an
user process (not Garbage Collector). Otherwise, let the GC to carry on.

\end{enumerate}

%
% Checksum error recovery
%
\subsubsection{Checksum error recovery}
The recovery procedure
has not been designed so far and probably we may postpone this work as
unimportant although it should be kept in mind during JFFS3
implementation.

Conceivably, JFFS3 might try to find older obsolete node
containing the corrupted information as well as to reconstruct the
corrupted data using the corresponding in-memory data if it is present.
The recovery is especially important in case of corrupted direntry node
as if we just ignore it we might loose the whole file or directory with
children.

%
% Miscellaneous
%
\subsection{Miscellaneous}
Like JFFS2, JFFS3 makes use of CRC32 checksum algorithm with the start seed
0xFFFFFFFF.

If zlib library is used to compress node's data it is worth asking zlib not to
generate redundant adler32 checksum for better performance.

%
% ABBREVIATIONS
%
\section{Abbreviations}
\begin{enumerate}
\item \emph{BB} - Bad Block
\item \emph{CRC} - Cyclic Redundancy Check
\item \emph{JFFS2} - Journalling Flash File System version 2
\item \emph{JFFS3} - Journalling Flash File System version 3
\end{enumerate}

%
% DEFINITIONS
%
\section{Definitions}

\begin{enumerate}
\item \emph{Block, Sector} --
the minimal flash erasable unit.

\item \emph{Bad block} -- unreliable flash block which must not be exploited.
NAND and AND flash chips may be shipped with bad blocks. These blocks are marked
bad and must not be ever used (read, written or erased). The technology also implies
that new bad blocks may appear during the flash's life-cycle. These blocks
have to be marked bad too.

\item \emph{Direntry node} -- node representing JFFS3 directory entry.
Each JFFS3 directory entry is represented by one valid direntry node.

\item \emph{Dirt, dirty space} -- the flash space which was once used
but doesn't contain useful information anymore. Due to flash nature this
space can't be used before the relating block has been erased. To put it
differently, the dirty space is comprised of obsolete nodes and
paddings.

\item \emph{Garbage Collector} -- very important part of JFFS3
design designated to reclaim dirt. Namely, GC moves
valid nodes from dirty vblocks to newly erased vblocks reclaiming the space
occupied by dirt. Another substantial aspect GC is responsible for is
the wear-levelling support and the production of pristine nodes.

\item \emph{Node} --
basic JFFS3 data structure. Anything that JFFS3 stores on flash is
stored in form of node(s). There are different types of nodes defined.

\item \emph{Node header} --
node and the relative data structure consists of two main data parts - header and
data. Node header contains internal information while node data contains some
user-visible data like file's content or name.

\item \emph{Inode node} -- node representing JFFS3 inode.
Any inode in JFFS3 is represented by one (for directory inodes) or more
(for file inodes) inode nodes.

\item \emph{Obsolete node} - a node which does not contain any
actual information. The exact semantic of obsolete node depends on its
type.

\item \emph{Padding node} -- fake node representing nothing and
as a rule produced when JFFS3 synchronizes the write buffer(s) or the end
of vblock has been reached and there is no enough space to write
any meaningful node. Padding nodes facilitate the faster filesystem
scanning.

\item \emph{Summary node, summary} --
describes the layout of full vblock. Summary is  situated at the end
of each vblock and describes the vblock's layout, e.g. position, type,
length, etc of all the vblock's nodes.

\item \emph{Valid node} -- not obsolete node.

\item \emph{Vblock, virtual block} --
JFFS3 may treat several blocks as one vblock of larger size.
Thus, the minimal erasable flash unit from the JFFS3's viewpoint
is vblock which consists of one or more flash blocks.

\end{enumerate}

%
% REFERENCES
%
\section{References}

\begin{enumerate}
\item \raggedright \label{ref_MTD}
Memory Technology Device (MTD) Subsystem for Linux,\\
\url{www.linux-mtd.infradead.org}.

\item \raggedright \label{ref_JFFSdwmw2}
JFFS : The Journalling Flash File System,\\
\url{http://sources.redhat.com/jffs2/jffs2-html/}

\item \raggedright \label{ref_NANDMTD}
NAND Flash,\\
\url{http://www.linux-mtd.infradead.org/tech/nand.html}.

\item \raggedright \label{ref_ToshibaNAND}
Toshiba NAND Flash Applications Design Guide,\\
\url{www.semicon.toshiba.co.jp/eng/prd/memory/doc/pdf/nand\_applicationguide\_e.pdf}.

\item \raggedright \label{ref_SamsungOneNAND}
Samsung OneNAND, might be found at\\
\url{http://www.samsung.com}.

\item \raggedright \label{ref_RenesasAND}
Renesas Technology - AG-AND / superAND Flash Memory, might be found at\\
\url{http://www.renesas.com}.

\item \raggedright \label{ref_AtmelDataFlash}
Atmel DataFlash,\\
\url{http://www.atmel.com/products/DataFlash/.}

\item \raggedright \label{ref_GormanVM}
Mel Gorman, Linux VM Documentation,\\
\url{www.csn.ul.ie/~mel/projects/vm}.

\end{enumerate}

%
% CREDITS
%
\section{Credits}
David Woodhouse\\
Joern Engel\\
Thomas Gleixner\\
Josh Boyer\\
Ferenc Havasi\\
Joakim Tjernlund\\
Jared Hulbert

\small{Note: feel free to remind us to include your name if it has been
forgotten.}

%
% MISCELLANIOUS
%
\section{Miscellaneous}
This section contains the gathered list of different ideas and thoughts
suggested by different people but have not yet highlighted/used in this
document. Many of them may be quite useful.

\begin{enumerate}
\item Have some global or per-inode flag telling that there was a checksum
error detected. In this flag is set, print big warning saying that flash
device in not reliable anymore. Should be controlled by user, though
(may be using xattr).\\
\url{http://lists.infradead.org/pipermail/linux-mtd/2005-January/011608.html}.

\item Make the compression selectable per-file (may be using xattr).\\
\url{http://lists.infradead.org/pipermail/linux-mtd/2005-January/011645.html}.

\item Make one more checksum mode when checksums are neither
generated nor checked.\\
\url{http://lists.infradead.org/pipermail/linux-mtd/2005-January/011640.html}.

\item Have special type of nodes where we may store static inode node's
(and may be other's) attributes like UID and GID. Perhaps, the xattr
support may be used here.\\
\url{http://lists.infradead.org/pipermail/linux-mtd/2005-January/011615.html}.

\item Implement xattr support. There are a lot of cases when having it
would be very handy.\\
\url{http://lists.infradead.org/pipermail/linux-mtd/2005-January/011617.html}\\
\url{http://lists.infradead.org/pipermail/linux-mtd/2005-January/011632.html}\\
\url{http://lists.infradead.org/pipermail/linux-mtd/2005-January/011644.html}\\
\url{http://lists.infradead.org/pipermail/linux-mtd/2005-January/011556.html}

\item Make compression selectable per file.\\
\url{http://lists.infradead.org/pipermail/linux-mtd/2005-January/011641.html}

\item Have the end magic bitmask on all note types in order to be able
to quickly detect the partially written nodes.\\
\url{http://lists.infradead.org/pipermail/linux-mtd/2005-January/011529.html}.

\item Increase the maximum node size. We may keep several pages in one node.
This leads to better compression and less memory consumption. Use
zisofs-like technique when reading the node with several pages of data
(compressed).\\
\url{http://lists.infradead.org/pipermail/linux-mtd/2005-January/011672.html}\\
and following.

\item Implement write-back cache in JFFS3.\\
\url{http://lists.infradead.org/pipermail/linux-mtd/2005-January/011672.html}\\
and following.
\end{enumerate}

\end{document}

