Btrees
======

Btrees Introduction
-------------------

Btrfs uses a single set of btree manipulation code for all metadata in
the filesystem. For performance or organizational purposes, the trees
are broken up into a few different types, and each type of tree will
hold a few different types of keys. The super block holds pointers to
the tree roots of the tree of tree roots and the chunk tree.


Tree of Tree roots
------------------

This tree is used for indexing and finding the root of most of the other
trees in the filesystem. It attaches names to subvolumes and snapshots,
and stores the location of the extent allocation tree root. It also
stores pointers to all of the subvolumes or snapshots that are being
deleted by the transaction code. This allows the deletion to pick up
where it left off after a crash.


Chunk Tree
----------

The chunk tree does all of the logical to physical block address mapping
for the filesystem, and it stores information about all of the devices
in the FS. In order to bootstrap lookup in the chunk tree, the super
block also duplicates the chunk items needed to resolve blocks in the
chunk tree. Over time, the chunk tree will be split into multiple roots
to allow access of larger storage pools.

There are back references from the chunk items to the extent tree that
allocated them. Only a single extent tree can allocate extents out of a
given chunk.

Two types of key are stored in the chunk tree:

-  DEV_ITEM (where the offset field is the internal devid), which
   contain information on all of the underlying block devices in the
   filesystem
-  CHUNK_ITEM (where the offset field is the start of the chunk as a
   virtual address), which maps a section of the virtual address space
   (a chunk) into physical storage.


Device Allocation Tree
----------------------

The device allocation tree records which parts of each physical device
have been allocated into chunks. This is a relatively small tree that is
only updated as new chunks are allocated. It stores back references to
the chunk tree that allocated each physical extent on the device.


Extent Allocation Tree
----------------------

The extent allocation tree records byte ranges that are in use,
maintains reference counts on each extent and records back references to
the tree or file that is using each extent. Logical block groups are
created inside the extent allocation tree, and these reference large
logical extents from the chunk tree.

Each block group can only store a specific type of extent. This might
include metadata, or mirrored metadata, or striped data blocks etc.

Currently there is only one extent allocation tree shared by all the
other trees. This will change in order to scale better under load.

Keys for the extent tree use the start of the extent as the objectid. A BLOCK_GROUP_ITEM key will be followed by the EXTENT_ITEM keys for extents within that block group.


FS Trees
--------

These store files and directories, and all of the normal metadata you
would expect to find in a filesystem. There is one root for each
subvolume or snapshot, but snapshots will share blocks between roots.

Keys in FS trees always use the inode number of the filesystem object as the objectid.

Each object will have one or more of:

-  Inode.
-  Inode ref, indicating what name this object is known as, and in which
   directory.
-  For files, a set of extent information, indicating where on the
   filesystem this file's data is.
-  For directories, two sequences of dir_items, one indexed by a hash of
   the object name, and one indexed by a unique sequential index number.


Checksum Tree
-------------

The checksum tree stores block checksums. Every 4k block of data stored
on disk has a checksum associated with it. The "offset" part of the keys
in the checksum tree indicates the start of the checksummed data on
disk. The value stored with the key is a sequence of (currently 4-byte)
checksums, for the 4k blocks starting at the offset.


Data Relocation Tree
--------------------


Log Root Tree
-------------