nuttx/Documentation/components/filesystem/fat.rst

===
FAT
===

File Allocation Table (FAT) is a very simple file system designed by Microsoft
and, as the name suggests, it uses a table to track clusters on a storage
volume. There have been multiple versions of FAT, like ``FAT12``, ``FAT16``,
and lastly ``FAT32`` to consider for growing data volumes. Even though FAT
has been superseded by more recent file systems in most Windows computers,
current Windows editions, macOS, Linux, Unix as well as Apache NuttX support
FAT. It is still used for floppy disks, USB flash drives as well as for
storage media in smaller, portable devices like digital cameras.

FAT uses a magic number ``0x4D44``, and has been named as ``vfat`` in the
codebase, due to the implementation being actually VFAT, which is an extension
that allows for long file names. This page contains information about the FAT
file system from the perspective of the implementation of FAT that exists in
NuttX.

FAT Structure
=============

The number beside ``FAT`` (eg. ``16`` in ``FAT16``) represents the number of
bits used for each entry in the allocation table.  A FAT volume has multiple
sections:

* **Master Boot Record**: Master Boot Record (MBR) or Boot Sector contains 
  information needed by the file system to access the volume, including the
  volume's layout and file system structure, akin to a superblock in Linux
  file systems.
* **Allocation Table Region**: Stores the file allocation table, as well as
  its copy which acts as a backup. The file allocation table keeps a track of
  all the clusters in the volume, and thus has one entry for each cluster.
* **Root Directory**: It stores a directory table containing entries 
  describing the files and directories stored on the volume. Each entry
  contains metadata about file system objects.

.. NOTE::
  Root Directory exists as a separate section if the volume is for ``FAT12``
  or ``FAT16``, right after the Allocation Table Region and has a fixed upper
  limit to the number of entries. ``FAT32`` does not have a dedicated region
  for the Root Directory, but has it incorporated into the following Data
  Region, and thus ``FAT32`` does not have any hard coded upper limit to the
  number of entries.

* **Data Region**: This region stores the actual data of the files as well as
  directory data. Data Region is divided into multiple clusters, which are
  numbered sequentially and have corresponding entries in the allocation
  table. Cluster sizes can vary depending on the volume size as well as on
  the type of the FAT file system.

The first entry in the Allocation Table is for the volume's FAT ID while the
second entry indicates that the cluster is reserved. Given that ``FAT32`` does
not have a dedicated Root Directory section, in ``FAT32`` volume, the third
entry points to the root directory.

File names can be either `short <https://en.wikipedia.org/wiki/8.3_filename>`_
(also known as 8.3 filename or SFN), or long (LFN), till a maximum length
limit.

Master Boot Record (MBR)
========================

The Boot Record may be one of two types. One is a much older type which does
not contain partitions, and one more recent with them. One distinguishing
feature of FAT is that all MBRs contain ``0x55AA`` at an offset of 510 from
the start, which can be used to determine the type of FAT being used in the
block device.

For the older type, the MBR exists at the start of the drive. It does not
contain any partitions.

The newer type has a partition table at an offset of 446 from the start of
the drive. It allows for 4 primary partitions. It has FAT Boot Records (FBRs)
at the start of every partition, which, for most parts, are identical in
structure to the older MBRs.

Partition Table Entries
=======================

The partition table contains information for 4 primary partitions, each
partition having entries in the table of 16 bytes each. These have various
information about the partition including, but not limited to, type of the
partition, starting sector, and partition size.

Allocation Table
================

The allocation table follows the boot record, and has an entry for each
cluster available in the data region. Each entry has a size defined by the
file system type. ``FAT12`` has 12 byte long entries, ``FAT16`` has 16 byte
entries and ``FAT32`` has 32 byte entries.

File data is made up of a linked list (or chain) of clusters. Entries in the
allocation table, which correspond to actual clusters, contain the cluster
number of the next cluster that appears in the file. The last cluster of a
file has a value in their allocation table entry such that all of its bits
are set (``0xFFF`` for FAT12, ``0xFFFF`` for FAT16, ``0xFFFFFFFF`` for FAT32).

The starting cluster (head of the file chain) is pointed to by the directory
entry of that file.

Directory Entires
=================

A directory is basically a file which has a table that contains directory
entries that contain the metadata about the files and subdirectories in it.
Each directory entry describes a file or a subdirectory inside the directory.

Root directory in FAT12/16 have a dedicated region, separate from the data
area. In FAT32, root directory is just like a regular directory in the data
region (ie. without any dedicated region) except for:

* Its starting cluster is denoted in the boot record.
* It is not pointed to by any other directory.
* It has no entries corresponding to ``.`` and ``..`` (all non-root
  directories have both of these entries).

Directory entries are 32 bytes long, and start with an 11 bytes long SFN. The
rest of the directory entry contain information like the file attributes,
timestamps of creation as well as access and write, cluster number and
file size, to name a few.

8.3 filename
------------

The first byte of a directory's 8.3 filename (and hence first byte of the
entire directory entry) has a special meaning. It has 3 possible values:

* ``0xe5`` : Denotes that the current directory entry is empty.
* ``0x00`` : Denotes that this entry, as well as all following entries, are
  empty.
* ``0x05`` : Actual value is ``0xe5``.

The rest of the 7 + 3 byte of the directory entry are for the name (with
extension).

Files
=====

The starting cluster of data in a file is pointed by the directory entry of
the file.

File allocation is very primitive in FAT, and the first available location in
the volume is given to a file.

File attributes
--------------------

File attributes are denoted by a bit flag of the size of a single byte.
The file flags in FAT, with their bit representation, are as follows:

.. list-table:: File Attributes
  :header-rows: 1

  * - Attribute Macro
    - Bit representation
    - Hex value
  * - ``FATATTR_READONLY``
    - ``00000001``
    - 0x1
  * - ``FATATTR_HIDDEN``
    - ``00000010``
    - 0x2
  * - ``FATATTR_SYSTEM``
    - ``00000100``
    - 0x4
  * - ``FATATTR_VOLUMEID``
    - ``00001000``
    - 0x8
  * - ``FATATTR_DIRECTORY``
    - ``00010000``
    - 0x10
  * - ``FATATTR_ARCHIVE``
    - ``00100000``
    - 0x20

Out of these, FAT exposes a user to ``FATATTR_READONLY``, ``FATATTR_HIDDEN``,
``FATATTR_SYSTEM`` and ``FATATTR_ARCHIVE`` to the user.

Implementation
==============

The Apache NuttX implementation of VFAT can be found in:

* ``fs/fat`` directory.
* ``include/nuttx/fs/fat.h`` header file.