Documentation/components/filesystem/smartfs.rst

=======
SMARTFS
=======

This page contains information about the implementation of the NuttX
Sector Mapped Allocation for Really Tiny (SMART) FLASH file system, SMARTFS.

Features
========

This implementation is a full-feature file system from the perspective of
file and directory access (i.e. not considering low-level details like the
lack of bad block management).  The SMART File System was designed specifically
for small SPI based FLASH parts (1-8 Mbyte for example), though this is not
a limitation.  It can certainly be used for any size FLASH and can work with
any MTD device by binding it with the SMART MTD layer and has been tested with
devices as large as 128MByte (using a 2048 byte sector size with 65534 sectors).
The FS includes support for:

- Multiple open files from different threads.
- Open for read/write access with seek capability.
- Appending to end of files in either write, append or read/write open modes.
- Directory support.
- Support for multiple mount points on a single volume / partition (see details
  below).
- Selectable FLASH Wear leveling algorithm
- Selectable CRC-8 or CRC-16 error detection for sector data
- Reduced RAM model for FLASH geometries with large number of sectors (16K-64K)

General operation
=================

The SMART File System divides the FLASH device or partition into equal
sized sectors which are allocated and "released" as needed to perform file
read/write and directory management operations.  Sectors are then "chained"
together to build files and directories.  The operations are split into two
layers:

1.  The MTD block layer (nuttx/drivers/mtd/smart.c).  This layer manages
    all low-level FLASH access operations including sector allocations,
    logical to physical sector mapping, erase operations, etc.
2.  The FS layer (nuttx/fs/smart/smartfs_smart.c).  This layer manages
    high-level file and directory creation, read/write, deletion, sector
    chaining, etc.

SMART MTD Block layer
=====================

The SMART MTD block layer divides the erase blocks of the FLASH device into
"sectors".  Sectors have both physical and logical number assignments.
The physicl sector number represents the actual offset from the beginning
of the device, while the logical sector number is assigned as needed.
A physical sector can have any logical sector assignment, and as files
are created, modified and destroyed, the logical sector number assignment
for a given physical sector will change over time.  The logical sector
number is saved in the physical sector header as the first 2 bytes, and
the MTD layer maintains an in-memory map of the logical to physical mapping.
Only physical sectors that are in use will have a logical assignment.

Also contained in the sector header is a flags byte and a sequence number.
When a sector is allocated, the COMMITTED flag will be "set" (changed from
erase state to non-erase state) to indicate the sector data is valid.  When
a sector's data needs to be deleted, the RELEASED flag will be "set" to
indicate the sector is no longer in use.  This is done because the erase
block containing the sector cannot necessarily be erased until all sectors
in that block have been "released".  This allows sectors in the erase
block to remain active while others are inactive until a "garbage collection"
operation is needed on the volume to reclaim released sectors.

The sequence number is used when a logical sector's data needs to be
updated with new information.  When this happens, a new physical sector
will be allocated which has a duplicate logical sector number but a
higher sequence number.  This allows maintaining flash consistency in the
event of a power failure by writing new data prior to releasing the old.
In the event of a power failure causing duplicate logical sector numbers,
the sector with the higher sequence number will win, and the older logical
sector will be released.

The SMART MTD block layer reserves some logical sector numbers for internal
use, including::

    Sector 0:     The Format Sector.  Has a format signature, format version, etc.
                  Also contains wear leveling information if enabled.
    Sector 1-2:   Additional wear-leveling info storage if needed.
    Sector 3:     The 1st (or only) Root Directory entry
    Sector 4-10:  Additional root directories when Multi-Mount points are supported.
    Sector 11-12: Reserved

To perform allocations, the SMART MTD block layer searches each erase block
on the device to identify the one with the most free sectors.  Free sectors
are those that have all bytes in the "erased state", meaning they have not
been previously allocated/released since the last block erase.  Not all
sectors on the device can be allocated ... the SMART MTD block driver must
reserve at least one erase-block worth of unused sectors to perform
garbage collection, which will be performed automatically when no free
sectors are available.  When wear leveling is enabled, the allocator also takes
into account the erase block erasure status to maintain level wearing.

Garbage collection is performed by identifying the erase block with the most
"released" sectors (those that were previously allocated but no longer being
used) and moving all still-active sectors to a different erase block.  Then
the now "vacant" erase block is erased, thus changing a group of released
sectors into free sectors.  This may occur several times depending on the
number of released sectors on the volume such that better "wear leveling"
is achieved.

Standard MTD block layer functions are provided for block read, block write,
etc. so that system utilities such as the "dd" command can be used,
however, all SMART operations are performed using SMART specific ioctl
codes to perform sector allocate, sector release, sector write, etc.

A couple of config items that the SMART MTD layer can take advantage of
in the underlying MTD drivers is SUBSECTOR_ERASE and BYTE_WRITE.  Most
flash devices have a 32K to 128K Erase block size, but some of them
have a smaller erase size available also.  Vendors have different names
for the smaller erase size; In the NuttX MTD layer it is called
SUBSECTOR_ERASE.  For FLASH devices that support the smaller erase size,
this configuration item can be added to the underlying MTD driver, and
SMART will use it.  As of the writing of this page, only the
drivers/mtd/m25px.c driver had support for SUBSECTOR_ERASE.

The BYTE_WRITE config option enables use of the underlying MTD driver's
ability to write data a byte or a few bytes at a time vs. a full page
at at time (which is typically 256 bytes).  For FLASH devices that support
byte write mode, support for this config item can be added to the MTD
driver.  Enabling and supporting this feature reduces the traffic on the
SPI bus considerably because SMARTFS performs many operations that affect
only a few bytes on the device.  Without BYTE_WRITE, the code must
perform a full page read-modify-write operation on a 256 or even 512
byte page.

Wear Leveling
=============

When wear leveling is enabled, the code automatically writes data across
the entire FLASH device in a manner that causes each erase block to be
worn (i.e. erased) evenly.  This is accomplished by maintaining a 4-bit
wear level count for each erase block and forcing less worn blocks to be
used for writing new data.  The code maintains each block's erase count
to be within 16 erases of each other, though through testing, the span
so far was never greater than 10 erases of each other.

As the data in a block is modified repeatedly, the erase count will
increase.  When the wear level reaches a value of 8 or higher, and the block
needs to be erased (because the data in it has been modified, etc.) the code
will select an erase block with the lowest wear count and relocate it to
this block (with the higher wear count).  The idea being that a block with
the lowest wear count contains more "static" data and should require fewer
additional erase operations.  This relocation process will continue on the
block (only when it needs to be erased again).

When the wear level of all erase blocks has increased to a level of
SMART_WEAR_MIN_LEVEL (currently set to 5), then the wear level counts
will all be reduced by this value.  This keeps the wear counts normalized
so they fit in a 4-bit value.  Note that theoretically, it *IS* possible to
write data to the flash in a manner that causes the wear count of a single
erase block to increment beyond it's maximum value of 15.  This would have
to be a very, very, very specific and un-predictable write sequence though
as data is always spread out across the sectors and relocated dynamically.
In the extremely rare event this does occur, the code will automatically
cap the maximum wear level at 15 an increment an "uneven wear count"
variable to indicate the number times this event has occurred.  So far, I
have not been able to get the wear count above 10 though my testing.

The wear level status bits are saved in the format sector (logical sector
number zero) with overflow saved in the reserved logical sectors one and
two.  Additionally, the uneven wear count (and total block erases if
PROCFS is enabled) are stored in the format sector.  When the PROCFS file
system is enabled and a SMARTFS volume is mounted, the SMART block driver
details and / or wear level details can be viewed with a command such as::

     cat /proc/fs/smartfs/smart0/status
        Format version:    1
        Name Len:          16
        Total Sectors:     2048
        Sector Size:       512
        Format Sector:     1487
        Dir Sector:        8
        Free Sectors:      67
        Released Sectors:  572
        Unused Sectors:    817
        Block Erases:      5680
        Sectors Per Block: 8
        Sector Utilization:98%
        Uneven Wear Count: 0

     cat /proc/fs/smartfs/smart0/erasemap
        DDDCGCCDDCDCCDCBDCCDDGBBDBCDCCDDDCDDDDCCDDCCCGCGDCCDBCDDGBDBDCDD
        BCCCDDCCDDDCBCCDGCCCBDDCCGBBCBCCGDCCDCBDBCCCDCDDCDDGCDCGDCBCDBDG
        BCDDCDCBGCCCDDCGBCCGBCCBDDBDDCGDCDDDCGCDDBCDCBDDBCDCGDDCCBCGBCCC
        GCBCCGCCCDDDBGCCCCGDCCCCCDCDDGBBDACABDBBABCAABCCCDAACBADADDDAECB

Enabling wear leveling can increase the total number of block erases on the
device in favor of even wearing (erasing).  This is caused by writing /
moving sectors that otherwise don't need to be written to move static data
to the more highly worn blocks.  This additional write requirement is known
as write amplification.  To get an idea of the amount of write amplification
incurred by enabling wear leveling, I conducted the smart_test example using
four different configurations (wear, no wear, CRC-8, no CRC) and the results
are shown below.  This was done on a 1M Byte simulated FLASH with 4K erase
block size, 512 sectors per byte.  The smart_test creates a 700K file and
then performs 20,000 random seek, write, verify tests.  The seek write forces
a multitude of sector relocation operations (with or without CRC enabled),
causing a boatload of block erases.

Enabling wear leveling actually decreased the number of erase operations
with CRC enabled or disabled.  This is only a single test point based one
testing method ... results will likely vary based on the method the data
is written, the amount of static vs. dynamic data, the amount of free space
on the volume, and the volume geometry (erase block size, sector size, etc.).

The results of the tests are::

    Case                          Total Block erases
    ================================================
    No wear leveling     CRC-8         6632
    Wear leveling        CRC-8         5585

    No wear leveling     no CRC        6658
    Wear leveling        no CRC        5398

Reduced RAM model
=================

On devices with a larger number of logical sectors (i.e. a lot of erase
blocks with a small selected sector size), the RAM requirement can become
fairly significant.  This is caused by the in-memory sector map which
keeps track of the logical to physical mapping of all sectors.  This is
a RAM array which is 2 * totalsectors in size.  For a device with 64K
sectors, this means 128K of RAM is required just for the sector map, not
counting RAM for read/write buffers, erase block management, etc.

So a reduced RAM model has been added which only keeps track of which
logical sectors have been used (a table which is totalsectors / 8 in size)
and a configurable sized sector map cache.  Each entry in the sector map
cache is 6 bytes (logical sector, physical sector and cache entry age).
ON DEVICES WITH SMALLER TOTAL SECTOR COUNT, ENABLING THIS OPTION COULD
ACTUALLY INCREASE THE RAM FOOTPRINT INSTEAD OF REDUCE IT.

The sector map cache size should be selected to balance the desired RAM
usage and the file system performance.  When a logical to physical sector
mapping is not found in the cache, the code must perform a physical search
of the FLASH to find the requested logical sector.  This involves reading
the 5-byte header from each sector on the device until the sector is
found.  Performing a full read, seek or open for append on a large file
can cause the sector map cache to flush completely if the file is larger
than (cache entries * sector size).  For example, in a configuration with
256 cache entries and a 512 byte sector size, a full read, seek or open for
append on a 128K file will flush the cache.

An additional RAM savings is realized on FLASH parts that contain 16 or
fewer logical sectors per erase block by packing the free and released
sector counts into a single byte (plus a little extra for 16 sectors per
erase block).  A device with a 64K erase block size can benefit from this
savings by selecting a 4096 or 8192 byte logical sector size, for example.

SMART FS Layer
==============

This layer interfaces with the SMART MTD block layer to allocate / release
logical sectors, create and destroy sector chains, and perform directory and
file I/O operations.  Each directory and file on the volume is represented
as a chain or "linked list" of logical sectors.  Thus the actual physical
sectors that a give file or directory uses does not need to be contiguous
and in fact can (and will) move around over time.  To manage the sector
chains, the SMARTFS layer adds a "chain header" after the sector's "sector
header".  This is a 5-byte header which contains the chain type (file or
directory), a "next logical sector" entry and the count of bytes actually
used within the sector.

Files are stored in directories, which are sector chains that have a
specific data format to track file names and "first" logical sector
numbers.  Each file in the directory has a fixed-size "directory entry"
that has bits to indicate if it is still active or has been deleted, file
permission bits, first sector number, date (utc stamp), and filename.  The
filename length is set from the CONFIG_SMARTFS_NAMLEN config value at the
time the mksmartfs command is executed.  Changes to the
CONFIG_SMARTFS_NAMLEN parameter will not be reflected on the volume
unless it is reformatted.  The same is true of the sector size parameter.

Subdirectories are supported by creating a new sector chain (of type
directory) and creating a standard directory entry for it in it's parent
directory.  Then files and additional sub-directories can be added to
that directory chain.  As such, each directory on the volume will occupy
a minimum of one sector on the device.  Subdirectories can be deleted
only if they are "empty" (i.e they reference no active entries).  There
are no provision made for performing a recursive directory delete.

New files and subdirectories can be added to a directory without needing
to copy and release the original directory sector.  This is done by
writing only the new entry data to the sector and ignoring the "bytes
used" field of the chain header for directories.  Updates (modifying
existing data) or appending to a sector for regular files requires copying
the file data to a new sector and releasing the old one.

SMARTFS organization
====================

The following example assumes 2 logical blocks per FLASH erase block.  The
actual relationship is determined by the FLASH geometry reported by the MTD
driver::

  ERASE LOGICAL                   Sectors begin with a sector header.  Sectors may
  BLOCK SECTOR      CONTENTS      be marked as "released," pending garbage collection
    n   2*n     --+---------------+
       Sector Hdr |LLLLLLLLLLLLLLL| Logical sector number (2 bytes)
                  |QQQQQQQQQQQQQQQ| Sequence number (2 bytes)
                  |SSSSSSSSSSSSSSS| Status bits (1 byte)
                  +---------------+
           FS Hdr |TTTTTTTTTTTTTTT| Sector Type (dir or file) (1 byte)
                  |NNNNNNNNNNNNNNN| Number of next logical sector in chain
                  |UUUUUUUUUUUUUUU| Number of bytes used in this sector
                  |               |
                  |               |
                  | (Sector Data) |
                  |               |
                  |               |
        2*n+1   --+---------------+
       Sector Hdr |LLLLLLLLLLLLLLL| Logical sector number (2 bytes)
                  |QQQQQQQQQQQQQQQ| Sequence number (2 bytes)
                  |SSSSSSSSSSSSSSS| Status bits (1 byte)
                  +---------------+
           FS Hdr |TTTTTTTTTTTTTTT| Sector Type (dir or file) (1 byte)
                  |NNNNNNNNNNNNNNN| Number of next logical sector in chain
                  |UUUUUUUUUUUUUUU| Number of bytes used in this sector
                  |               |
                  |               |
                  | (Sector Data) |
                  |               |
                  |               |
   n+1  2*(n+1) --+---------------+
       Sector Hdr |LLLLLLLLLLLLLLL| Logical sector number (2 bytes)
                  |QQQQQQQQQQQQQQQ| Sequence number (2 bytes)
                  |SSSSSSSSSSSSSSS| Status bits (1 byte)
                  +---------------+
           FS Hdr |TTTTTTTTTTTTTTT| Sector Type (dir or file) (1 byte)
                  |NNNNNNNNNNNNNNN| Number of next logical sector in chain
                  |UUUUUUUUUUUUUUU| Number of bytes used in this sector
                  |               |
                  |               |
                  | (Sector Data) |
                  |               |
                  |               |
                --+---------------+

Headers
=======
``SECTOR HEADER``
    Each sector contains a header (currently 5 bytes) for identifying the
    status of the sector.  The header contains the sector's logical sector
    number mapping, an incrementing sequence number to manage changes to
    logical sector data, and sector flags (committed, released, version, etc.).
    At the block level, there is no notion of sector chaining, only
    allocated sectors within erase blocks.

``FORMAT HEADER``
    Contains information regarding the format on the volume, including
    a format signature, formatted block size, name length within the directory
    chains, etc.

``CHAIN HEADER``
    The file system header (next 5 bytes) tracks file and directory sector
    chains and actual sector usage (number of bytes that are valid in the
    sector).  Also indicates the type of chain (file or directory).

Multiple Mount Points
=====================

Typically, a volume contains a single root directory entry (logical sector
number 1) and all files and subdirectories are "children" of that root
directory.  This is a traditional scheme and allows the volume to
be mounted in a single location within the VFS.  As a configuration
option, when the volume is formatted via the mksmartfs command, multiple
root directory entries can be created instead.  The number of entries to
be created is an added parameter to the mksmartfs command in this
configuration.

When this option has been enabled in the configuration and specified
during the format, then the volume will have multiple root directories
and can support a mount point in the VFS for each.  In this mode,
the device entries reported in the /dev directory will have a directory
number postfixed to the name, such as::

    /dev/smart0d1
    /dev/smart0d2
    /dev/smart1p1d1
    /dev/smart1p2d2
    etc.

Each device entry can then be mounted at different locations, such as::

    /dev/smart0d1 --> /usr
    /dev/smart0d2 --> /home
    etc.

Using multiple mount points is slightly different from using partitions
on the volume in that each mount point has the potential to use the
entire space on the volume vs. having a pre-allocated reservation of
space defined by the partition sizes.  Also, all files and directories
of all mount-points will be physically "mixed in" with data from the
other mount-points (though files from one will never logically "appear"
in the others).  Each directory structure is isolated from the others,
they simply share the same physical media for storage.

SMARTFS Limitations
===================

This implementation has several limitations that you should be aware
before opting to use SMARTFS:

1. There is currently no FLASH bad-block management code.  The reason for
   this is that the FS was geared for Serial NOR FLASH parts.  To use
   SMARTFS with a NAND FLASH, bad block management would need to be added,
   along with a few minor changes to eliminate single bit writes to release
   a sector, etc.

2. The implementation can support CRC-8 or CRC-16 error detection, and can
   relocate a failed write operation to a new sector.  However with no bad
   block management implementation, the code will continue it attempts at
   using failing block / sector, reducing efficiency and possibly successfully
   saving data in a block with questionable integrity.

3. The released-sector garbage collection process occurs only during a write
   when there are no free FLASH sectors.  Thus, occasionally, file writing
   may take a long time.  This typically isn't noticeable unless the volume
   is very full and multiple copy / erase cycles must be performed to
   complete the garbage collection.

4. The total number of logical sectors on the device must be 65534 or less.
   The number of logical sectors is based on the total device / partition
   size and the selected sector size.  For larger flash parts, a larger
   sector size would need to be used to meet this requirement. Creating a
   geometry which results in 65536 sectors (a 32MByte FLASH with 512 byte
   logical sector, for example) will cause the code to automatically reduce
   the total sector count to 65534, thus "wasting" the last two logical
   sectors on the device (they will never be used).

   This restriction exists because:

   a. The logical sector number is a 16-bit field (i.e. 65535 is the max).
   b. Logical sector number 65535 (0xFFFF) is reserved as this is typically
      the "erased state" of the FLASH.

ioctls
======

``BIOC_LLFORMAT``
    Performs a SMART low-level format on the volume.  This erases the volume
    and writes the FORMAT HEADER to the first physical sector on the volume.

``BIOC_GETFORMAT``
    Returns information about the format found on the volume during the
    "scan" operation which is performed when the volume is mounted.

``BIOC_ALLOCSECT``
    Allocates a logical sector on the device.

``BIOC_FREESECT``
    Frees a logical sector that had been previously allocated.  This
    causes the sector to be marked as "released" and possibly causes the
    erase block to be erased if it is the last active sector in the
    it's erase block.

``BIOC_READSECT``
    Reads data from a logical sector.  This uses a structure to identify
    the offset and count of data to be read.

``BIOC_WRITESECT``
    Writes data to a logical sector.  This uses a structure to identify
    the offset and count of data to be written.  May cause a logical
    sector to be physically relocated and may cause garbage collection
    if needed when moving data to a new physical sector.

Things to Do
============

- Add file permission checking to open / read / write routines.
- Add reporting of actual FLASH usage for directories (each directory
  occupies one or more physical sectors, yet the size is reported as
  zero for directories).