document magic numbers and theoretical limits

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Reviewed-by: Christoph Hellwig <hch@lst.de>
Signed-off-by: Dave Chinner <david@fromorbit.com>

3 files changed, 89 insertions, 0 deletions

diff --git a/design/XFS_Filesystem_Structure/docinfo.xml b/design/XFS_Filesystem_Structure/docinfo.xml
index 8ed38d9..6189fd6 100644
--- a/design/XFS_Filesystem_Structure/docinfo.xml
+++ b/design/XFS_Filesystem_Structure/docinfo.xml
@@ -103,6 +103,7 @@
 				<member>Add v5 fields.</member>
 				<member>Discuss metadata integrity.</member>
 				<member>Document the free inode B+tree.</member>
+				<member>Create an index of magic numbers.</member>
 			</simplelist>
 		</revdescription>
 	</revision>
diff --git a/design/XFS_Filesystem_Structure/magic.asciidoc b/design/XFS_Filesystem_Structure/magic.asciidoc
new file mode 100644
index 0000000..301cfa0
--- /dev/null
+++ b/design/XFS_Filesystem_Structure/magic.asciidoc
@@ -0,0 +1,86 @@
+= 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.
+
+[options="header"]
+|=====
+| Flag				| Hexadecimal	| ASCII	| Data structure
+| +XFS_SB_MAGIC+		| 0x58465342	| XFSB	| xref:Superblocks[Superblock]
+| +XFS_AGF_MAGIC+		| 0x58414746	| XAGF	| xref:AG_Free_Space_Block[Free Space]
+| +XFS_AGI_MAGIC+		| 0x58414749	| XAGI	| xref:Inode_Information[Inode Information]
+| +XFS_AGFL_MAGIC+		| 0x5841464c	| XAFL	| xref:AG_Free_List[Free Space List], v5 only
+| +XFS_DINODE_MAGIC+		| 0x494e	| IN	| xref:Inode_Core[Inodes]
+| +XFS_DQUOT_MAGIC+		| 0x4451	| DQ	| xref:Quota_Inodes[Quota Inodes]
+| +XFS_SYMLINK_MAGIC+		| 0x58534c4d	| XSLM	| xref:Extent_Symbolic_Links[Symbolic Links]
+| +XFS_ABTB_MAGIC+		| 0x41425442	| ABTB	| xref:AG_Free_Space_Btrees[Free Space by Block B+tree]
+| +XFS_ABTB_CRC_MAGIC+		| 0x41423342	| AB3B	| xref:AG_Free_Space_Btrees[Free Space by Block B+tree], v5 only
+| +XFS_ABTC_MAGIC+		| 0x41425443	| ABTC	| xref:AG_Free_Space_Btrees[Free Space by Size B+tree]
+| +XFS_ABTC_CRC_MAGIC+		| 0x41423343	| AB3C	| xref:AG_Free_Space_Btrees[Free Space by Size B+tree], v5 only
+| +XFS_IBT_MAGIC+		| 0x49414254	| IABT	| xref:Inode_Btrees[Inode B+tree]
+| +XFS_IBT_CRC_MAGIC+		| 0x49414233	| IAB3	| xref:Inode_Btrees[Inode B+tree], v5 only
+| +XFS_FIBT_MAGIC+		| 0x46494254	| FIBT	| xref:Inode_Btrees[Free Inode B+tree]
+| +XFS_FIBT_CRC_MAGIC+		| 0x46494233	| FIB3	| xref:Inode_Btrees[Free Inode B+tree], v5 only
+| +XFS_BMAP_MAGIC+		| 0x424d4150	| BMAP	| xref:Btree_Extent_List[B+Tree Extent List]
+| +XFS_BMAP_CRC_MAGIC+		| 0x424d4133	| BMA3	| xref:Btree_Extent_List[B+Tree Extent List], v5 only
+| +XLOG_HEADER_MAGIC_NUM+	| 0xfeedbabe	|     	| xref:Log_Records[Log Records]
+| +XFS_DA_NODE_MAGIC+		| 0xfebe	|     	| xref:Directory_Attribute_Internal_Node[Directory/Attribute Node]
+| +XFS_DA3_NODE_MAGIC+		| 0x3ebe	|     	| xref:Directory_Attribute_Internal_Node[Directory/Attribute Node], v5 only
+| +XFS_DIR2_BLOCK_MAGIC+	| 0x58443242	| XD2B	| xref:Block_Directories[Block Directory Data]
+| +XFS_DIR3_BLOCK_MAGIC+	| 0x58444233	| XDB3	| xref:Block_Directories[Block Directory Data], v5 only
+| +XFS_DIR2_DATA_MAGIC+		| 0x58443244	| XD2D	| xref:Leaf_Directories[Leaf Directory Data]
+| +XFS_DIR3_DATA_MAGIC+		| 0x58444433	| XDD3	| xref:Leaf_Directories[Leaf Directory Data], v5 only
+| +XFS_DIR2_LEAF1_MAGIC+	| 0xd2f1	|     	| xref:Leaf_Directories[Leaf Directory]
+| +XFS_DIR3_LEAF1_MAGIC+	| 0x3df1	|     	| xref:Leaf_Directories[Leaf Directory], v5 only
+| +XFS_DIR2_LEAFN_MAGIC+	| 0xd2ff	|     	| xref:Node_Directories[Node Directory]
+| +XFS_DIR3_LEAFN_MAGIC+	| 0x3dff	|     	| xref:Node_Directories[Node Directory], v5 only
+| +XFS_DIR2_FREE_MAGIC+		| 0x58443246	| XD2F	| xref:Node_Directories[Node Directory Free Space]
+| +XFS_DIR3_FREE_MAGIC+		| 0x58444633	| XDF3	| xref:Node_Directories[Node Directory Free Space], v5 only
+| +XFS_ATTR_LEAF_MAGIC+		| 0xfbee	|     	| xref:Leaf_Attributes[Leaf Attribute]
+| +XFS_ATTR3_LEAF_MAGIC+	| 0x3bee	|     	| xref:Leaf_Attributes[Leaf Attribute], v5 only
+| +XFS_ATTR3_RMT_MAGIC+		| 0x5841524d	| XARM	| xref:Remote_Values[Remote Attribute Value], v5 only
+|=====
+
+The magic numbers for log items are at offset zero in each log item, but items
+are not aligned to blocks.
+
+[options="header"]
+|=====
+| Flag				| Hexadecimal	| ASCII	| Data structure
+| +XFS_TRANS_HEADER_MAGIC+	| 0x5452414e	| TRAN	| xref:Log_Transaction_Headers[Log Transactions]
+| +XFS_LI_EFI+			| 0x1236        |       | xref:EFI_Log_Item[Extent Freeing Intent Log Item]
+| +XFS_LI_EFD+			| 0x1237        |       | xref:EFD_Log_Item[Extent Freeing Done Log Item]
+| +XFS_LI_IUNLINK+		| 0x1238        |       |  Unknown?
+| +XFS_LI_INODE+		| 0x123b        |       | xref:Inode_Log_Item[Inode Updates Log Item]
+| +XFS_LI_BUF+			| 0x123c        |       | xref:Buffer_Log_Item[Buffer Writes Log Item]
+| +XFS_LI_DQUOT+		| 0x123d        |       | xref:Quota_Update_Log_Item[Update Quota Log Item]
+| +XFS_LI_QUOTAOFF+		| 0x123e        |       | xref:Quota_Off_Log_Item[Quota Off Log Item]
+| +XFS_LI_ICREATE+		| 0x123f        |       | xref:Inode_Create_Log_Item[Inode Creation Log Item]
+|=====
+
+= Theoretical Limits
+
+XFS can create really big filesystems!
+
+[options="header"]
+|=====
+| Item			| 1KiB blocks | 4KiB blocks | 64KiB blocks
+| Blocks		| 2^52^ | 2^52^ | 2^52^
+| Inodes		| 2^63^ | 2^63^ | 2^64^
+| Allocation Groups	| 2^32^ | 2^32^ | 2^32^
+| File System Size	| 8EiB  | 8EiB | 8EiB
+| Blocks per AG		| 2^31^ | 2^31^ | 2^31^
+| Inodes per AG		| 2^32^ | 2^32^ | 2^32^
+| Max AG Size		| 2TiB  | 8TiB  | 128TiB
+| Blocks Per File	| 2^54^ | 2^54^ | 2^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/design/XFS_Filesystem_Structure/xfs_filesystem_structure.asciidoc b/design/XFS_Filesystem_Structure/xfs_filesystem_structure.asciidoc
index 8aacbb7..0ab4906 100644
--- a/design/XFS_Filesystem_Structure/xfs_filesystem_structure.asciidoc
+++ b/design/XFS_Filesystem_Structure/xfs_filesystem_structure.asciidoc
@@ -50,6 +50,8 @@ include::metadata_integrity.asciidoc[]
 
 include::common_types.asciidoc[]
 
+include::magic.asciidoc[]
+
 // return titles to normal
 :leveloffset: 0