[PATCH 07/22] docs: add XFS common types and magic numbers to DS&A book

Darrick J. Wong
2018-10-04T04:19:14Z

.../xfs-data-structures/common_types.rst | 61 ++++
.../filesystems/xfs-data-structures/magic.rst | 277 ++++++++++++++++++++
.../filesystems/xfs-data-structures/overview.rst | 2
3 files changed, 340 insertions(+)
create mode 100644 Documentation/filesystems/xfs-data-structures/common_types.rst
create mode 100644 Documentation/filesystems/xfs-data-structures/magic.rst

diff --git a/Documentation/filesystems/xfs-data-structures/common_types.rst b/Documentation/filesystems/xfs-data-structures/common_types.rst
new file mode 100644
index 000000000000..63de847924c6
--- /dev/null
+++ b/Documentation/filesystems/xfs-data-structures/common_types.rst
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+Common XFS Types
+----------------
+
+All the following XFS types can be found in xfs\_types.h. NULL values are
+always -1 on disk (ie. all bits for the value set to one).
+
+**xfs\_ino\_t**
+ Unsigned 64 bit absolute `inode number <#inode-numbers>`__.
+
+**xfs\_off\_t**
+ Signed 64 bit file offset.
+
+**xfs\_daddr\_t**
+ Signed 64 bit disk address (sectors).
+
+**xfs\_agnumber\_t**
+ Unsigned 32 bit `AG number <#allocation-groups>`__.
+
+**xfs\_agblock\_t**
+ Unsigned 32 bit AG relative block number.
+
+**xfs\_extlen\_t**
+ Unsigned 32 bit `extent <#data-extents>`__ length in blocks.
+
+**xfs\_extnum\_t**
+ Signed 32 bit number of extents in a data fork.
+
+**xfs\_aextnum\_t**
+ Signed 16 bit number of extents in an attribute fork.
+
+**xfs\_dablk\_t**
+ Unsigned 32 bit block number for `directories <#directories>`__ and
+ `extended attributes <#extended-attributes>`__.
+
+**xfs\_dahash\_t**
+ Unsigned 32 bit hash of a directory file name or extended attribute name.
+
+**xfs\_fsblock\_t**
+ Unsigned 64 bit filesystem block number combining `AG
+ number <#allocation-groups>`__ and block offset into the AG.
+
+**xfs\_rfsblock\_t**
+ Unsigned 64 bit raw filesystem block number.
+
+**xfs\_rtblock\_t**
+ Unsigned 64 bit extent number in the `real-time <#real-time-devices>`__
+ sub-volume.
+
+**xfs\_fileoff\_t**
+ Unsigned 64 bit block offset into a file.
+
+**xfs\_filblks\_t**
+ Unsigned 64 bit block count for a file.
+
+**uuid\_t**
+ 16-byte universally unique identifier (UUID).
+
+**xfs\_fsize\_t**
+ Signed 64 bit byte size of a file.
diff --git a/Documentation/filesystems/xfs-data-structures/magic.rst b/Documentation/filesystems/xfs-data-structures/magic.rst
new file mode 100644
index 000000000000..f5e57581645d
--- /dev/null
+++ b/Documentation/filesystems/xfs-data-structures/magic.rst
@@ -0,0 +1,277 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+Magic Numbers
+-------------
+
+These are the magic numbers that are known to XFS, along with links to the
+relevant chapters. Magic numbers tend to have consistent locations:
+
+- 32-bit magic numbers are always at offset zero in the block.
+
+- 16-bit magic numbers for the directory and attribute B+tree are at offset
+ eight.
+
+- The quota magic number is at offset zero.
+
+- The inode magic is at the beginning of each inode.
+
+.. list-table::
+ :widths: 28 12 8 34
+ :header-rows: 1
+
+ * - Flag
+ - Hexadecimal
+ - ASCII
+ - Data structure
+ * - XFS_SB_MAGIC
+ - 0x58465342
+ - XFSB
+ - `Superblock <#superblocks>`__
+ * - XFS_AGF_MAGIC
+ - 0x58414746
+ - XAGF
+ - `Free Space <#ag-free-space-block>`__
+ * - XFS_AGI_MAGIC
+ - 0x58414749
+ - XAGI
+ - `Inode Information <#inode-information>`__
+ * - XFS_AGFL_MAGIC
+ - 0x5841464c
+ - XAFL
+ - `Free Space List <#ag-free-list>`__, v5 only
+ * - XFS_DINODE_MAGIC
+ - 0x494e
+ - IN
+ - `Inodes <#inode-core>`__
+ * - XFS_DQUOT_MAGIC
+ - 0x4451
+ - DQ
+ - `Quota Inodes <#quota-inodes>`__
+ * - XFS_SYMLINK_MAGIC
+ - 0x58534c4d
+ - XSLM
+ - `Symbolic Links <#extent-symbolic-links>`__
+ * - XFS_ABTB_MAGIC
+ - 0x41425442
+ - ABTB
+ - `Free Space by Block B+tree <#ag-free-space-b-trees>`__
+ * - XFS_ABTB_CRC_MAGIC
+ - 0x41423342
+ - AB3B
+ - `Free Space by Block B+tree <#ag-free-space-b-trees>`__, v5 only
+ * - XFS_ABTC_MAGIC
+ - 0x41425443
+ - ABTC
+ - `Free Space by Size B+tree <#ag-free-space-b-trees>`__
+ * - XFS_ABTC_CRC_MAGIC
+ - 0x41423343
+ - AB3C
+ - `Free Space by Size B+tree <#ag-free-space-b-trees>`__, v5 only
+ * - XFS_IBT_MAGIC
+ - 0x49414254
+ - IABT
+ - `Inode B+tree <#inode-b-trees>`__
+ * - XFS_IBT_CRC_MAGIC
+ - 0x49414233
+ - IAB3
+ - `Inode B+tree <#inode-b-trees>`__, v5 only
+ * - XFS_FIBT_MAGIC
+ - 0x46494254
+ - FIBT
+ - `Free Inode B+tree <#inode-b-trees>`__
+ * - XFS_FIBT_CRC_MAGIC
+ - 0x46494233
+ - FIB3
+ - `Free Inode B+tree <#inode-b-trees>`__, v5 only
+ * - XFS_BMAP_MAGIC
+ - 0x424d4150
+ - BMAP
+ - `B+Tree Extent List <#b-tree-extent-list>`__
+ * - XFS_BMAP_CRC_MAGIC
+ - 0x424d4133
+ - BMA3
+ - `B+Tree Extent List <#b-tree-extent-list>`__, v5 only
+ * - XLOG_HEADER_MAGIC_NUM
+ - 0xfeedbabe
+ -
+ - `Log Records <#log-records>`__
+ * - XFS_DA_NODE_MAGIC
+ - 0xfebe
+ -
+ - `Directory/Attribute Node <#directory-attribute-internal-node>`__
+ * - XFS_DA3_NODE_MAGIC
+ - 0x3ebe
+ -
+ - `Directory/Attribute Node <#directory-attribute-internal-node>`__, v5 only
+ * - XFS_DIR2_BLOCK_MAGIC
+ - 0x58443242
+ - XD2B
+ - `Block Directory Data <#block-directories>`__
+ * - XFS_DIR3_BLOCK_MAGIC
+ - 0x58444233
+ - XDB3
+ - `Block Directory Data <#block-directories>`__, v5 only
+ * - XFS_DIR2_DATA_MAGIC
+ - 0x58443244
+ - XD2D
+ - `Leaf Directory Data <#leaf-directories>`__
+ * - XFS_DIR3_DATA_MAGIC
+ - 0x58444433
+ - XDD3
+ - `Leaf Directory Data <#leaf-directories>`__, v5 only
+ * - XFS_DIR2_LEAF1_MAGIC
+ - 0xd2f1
+ -
+ - `Leaf Directory <#leaf-directories>`__
+ * - XFS_DIR3_LEAF1_MAGIC
+ - 0x3df1
+ -
+ - `Leaf Directory <#leaf-directories>`__, v5 only
+ * - XFS_DIR2_LEAFN_MAGIC
+ - 0xd2ff
+ -
+ - `Node Directory <#node-directories>`__
+ * - XFS_DIR3_LEAFN_MAGIC
+ - 0x3dff
+ -
+ - `Node Directory <#node-directories>`__, v5 only
+ * - XFS_DIR2_FREE_MAGIC
+ - 0x58443246
+ - XD2F
+ - `Node Directory Free Space <#node-directories>`__
+ * - XFS_DIR3_FREE_MAGIC
+ - 0x58444633
+ - XDF3
+ - `Node Directory Free Space <#node-directories>`__, v5 only
+ * - XFS_ATTR_LEAF_MAGIC
+ - 0xfbee
+ -
+ - `Leaf Attribute <#leaf-attributes>`__
+ * - XFS_ATTR3_LEAF_MAGIC
+ - 0x3bee
+ -
+ - `Leaf Attribute <#leaf-attributes>`__, v5 only
+ * - XFS_ATTR3_RMT_MAGIC
+ - 0x5841524d
+ - XARM
+ - `Remote Attribute Value <#remote-attribute-values>`__, v5 only
+ * - XFS_RMAP_CRC_MAGIC
+ - 0x524d4233
+ - RMB3
+ - `Reverse Mapping B+tree <#reverse-mapping-b-tree>`__, v5 only
+ * - XFS_RTRMAP_CRC_MAGIC
+ - 0x4d415052
+ - MAPR
+ - `Real-Time Reverse Mapping B+tree <#real-time-reverse-mapping-b-tree>`__, v5 only
+ * - XFS_REFC_CRC_MAGIC
+ - 0x52334643
+ - R3FC
+ - `Reference Count B+tree <#reference-count-b-tree>`__, v5 only
+ * - XFS_MD_MAGIC
+ - 0x5846534d
+ - XFSM
+ - `Metadata Dumps <#metadata-dumps>`__
+
+The magic numbers for log items are at offset zero in each log item, but items
+are not aligned to blocks.
+
+.. list-table::
+ :widths: 24 12 8 36
+ :header-rows: 1
+
+ * - Flag
+ - Hexadecimal
+ - ASCII
+ - Data structure
+ * - XFS_TRANS_HEADER_MAGIC
+ - 0x5452414e
+ - TRAN
+ - `Log Transactions <#transaction-headers>`__
+ * - XFS_LI_EFI
+ - 0x1236
+ -
+ - `Extent Freeing Intent Log Item <#intent-to-free-an-extent>`__
+ * - XFS_LI_EFD
+ - 0x1237
+ -
+ - `Extent Freeing Done Log Item <#completion-of-intent-to-free-an-extent>`__
+ * - XFS_LI_IUNLINK
+ - 0x1238
+ -
+ - Unknown?
+ * - XFS_LI_INODE
+ - 0x123b
+ -
+ - `Inode Updates Log Item <#inode-updates>`__
+ * - XFS_LI_BUF
+ - 0x123c
+ -
+ - `Buffer Writes Log Item <#buffer-log-item>`__
+ * - XFS_LI_DQUOT
+ - 0x123d
+ -
+ - `Update Quota Log Item <#quota-update-data-log-item>`__
+ * - XFS_LI_QUOTAOFF
+ - 0x123e
+ -
+ - `Quota Off Log Item <#disable-quota-log-item>`__
+ * - XFS_LI_ICREATE
+ - 0x123f
+ -
+ - `Inode Creation Log Item <#inode-creation-log-item>`__
+ * - XFS_LI_RUI
+ - 0x1240
+ -
+ - `Reverse Mapping Update Intent <#reverse-mapping-updates-intent>`__
+ * - XFS_LI_RUD
+ - 0x1241
+ -
+ - `Reverse Mapping Update Done <#completion-of-reverse-mapping-updates>`__
+ * - XFS_LI_CUI
+ - 0x1242
+ -
+ - `Reference Count Update Intent <#reference-count-updates-intent>`__
+ * - XFS_LI_CUD
+ - 0x1243
+ -
+ - `Reference Count Update Done <#completion-of-reference-count-updates>`__
+ * - XFS_LI_BUI
+ - 0x1244
+ -
+ - `File Block Mapping Update Intent <#file-block-mapping-intent>`__
+ * - XFS_LI_BUD
+ - 0x1245
+ -
+ - `File Block Mapping Update Done <#completion-of-file-block-mapping-updates>`__
+
+Theoretical Limits
+------------------
+
+XFS can create really big filesystems!
+
++---------------------+---------------------+---------------------+---------------------+
+| Item | 1KiB blocks | 4KiB blocks | 64KiB blocks |
++=====================+=====================+=====================+=====================+
+| Blocks | 2\ :sup:`52` | 2\ :sup:`52` | 2\ :sup:`52` |
++---------------------+---------------------+---------------------+---------------------+
+| Inodes | 2\ :sup:`63` | 2\ :sup:`63` | 2\ :sup:`64` |
++---------------------+---------------------+---------------------+---------------------+
+| Allocation Groups | 2\ :sup:`32` | 2\ :sup:`32` | 2\ :sup:`32` |
++---------------------+---------------------+---------------------+---------------------+
+| File System Size | 8EiB | 8EiB | 8EiB |
++---------------------+---------------------+---------------------+---------------------+
+| Blocks per AG | 2\ :sup:`31` | 2\ :sup:`31` | 2\ :sup:`31` |
++---------------------+---------------------+---------------------+---------------------+
+| Inodes per AG | 2\ :sup:`32` | 2\ :sup:`32` | 2\ :sup:`32` |
++---------------------+---------------------+---------------------+---------------------+
+| Max AG Size | 2TiB | 8TiB | 128TiB |
++---------------------+---------------------+---------------------+---------------------+
+| Blocks Per File | 2\ :sup:`54` | 2\ :sup:`54` | 2\ :sup:`54` |
++---------------------+---------------------+---------------------+---------------------+
+| File Size | 8EiB | 8EiB | 8EiB |
++---------------------+---------------------+---------------------+---------------------+
+| Max Dir Size | 32GiB | 32GiB | 32GiB |
++---------------------+---------------------+---------------------+---------------------+
+
+Linux doesn’t suppport files or devices larger than 8EiB, so the block
+limitations are largely ignorable.
diff --git a/Documentation/filesystems/xfs-data-structures/overview.rst b/Documentation/filesystems/xfs-data-structures/overview.rst
index b1b3f711638b..23eb71d65c93 100644
--- a/Documentation/filesystems/xfs-data-structures/overview.rst
+++ b/Documentation/filesystems/xfs-data-structures/overview.rst
@@ -47,3 +47,5 @@ latency.
.. include:: delayed_logging.rst
.. include:: reflink.rst
.. include:: reconstruction.rst
+.. include:: common_types.rst
+.. include:: magic.rst