design: document the parent pointer ondisk formatpptrs_2023-12-31pptrs

Add parent pointers to the ondisk format documentation.

Signed-off-by: Darrick J. Wong <djwong@kernel.org>

2 files changed, 98 insertions, 0 deletions

diff --git a/design/XFS_Filesystem_Structure/allocation_groups.asciidoc b/design/XFS_Filesystem_Structure/allocation_groups.asciidoc
index c91a06b..bd82520 100644
--- a/design/XFS_Filesystem_Structure/allocation_groups.asciidoc
+++ b/design/XFS_Filesystem_Structure/allocation_groups.asciidoc
@@ -469,6 +469,10 @@ space mappings allowed in data and extended attribute file forks.
 Metadata directory tree.  See the section about the xref:Metadata_Directories[
 metadata directory tree] for more information.
 
+| +XFS_SB_FEAT_INCOMPAT_PARENT+ |
+Directory parent pointers.  See the section about xref:Parent_Pointers[parent
+pointers] for more information.
+
 |=====
 
 *sb_features_log_incompat*::
diff --git a/design/XFS_Filesystem_Structure/extended_attributes.asciidoc b/design/XFS_Filesystem_Structure/extended_attributes.asciidoc
index 19bff70..6f905a1 100644
--- a/design/XFS_Filesystem_Structure/extended_attributes.asciidoc
+++ b/design/XFS_Filesystem_Structure/extended_attributes.asciidoc
@@ -90,6 +90,7 @@ A combination of the following:
 | +XFS_ATTR_SECURE+		| The attribute's namespace is ``secure''.
 | +XFS_ATTR_INCOMPLETE+		| This attribute is being modified.
 | +XFS_ATTR_LOCAL+		| The attribute value is contained within this block.
+| +XFS_ATTR_PARENT+		| This attribute is a parent pointer.
 |=====
 
 .Short form attribute layout
@@ -911,6 +912,99 @@ Log sequence number of the last write to this block.
 Filesystems formatted prior to v5 do not have this header in the remote block.
 Value data begins immediately at offset zero.
 
+[[Parent_Pointers]]
+== Directory Parent Pointers
+
+If this feature is enabled, each directory entry pointing from a parent
+directory to a child file has a corresponding back link from the child file
+back to the parent.  In other words, if directory P has an entry "foo" pointing
+to child C, then child C will have a parent pointer entry "foo" pointing to
+parent P.  This redundancy enables validation and repairs of the directory tree
+if the tree structure is damaged.
+
+Parent pointers are stored in a private namespace within the extended attribute
+structure.  The attribute name contains the following binary structure, and
+the attribute value contains the directory entry name.
+
+[source, c]
+----
+struct xfs_parent_name_rec {
+	__be64	p_ino;
+	__be32	p_gen;
+	__be32	p_namehash;
+};
+----
+
+*p_ino*::
+Inode number of the parent directory.
+
+*p_gen*::
+Generation number of the parent directory.
+
+*p_namehash*::
+The directory name hash of the directory entry name in the parent.
+
+=== xfs_db Parent Pointer Example
+
+Create a directory tree with the following structure, assuming that the
+XFS filesystem is mounted on +/mnt+:
+
+----
+$ mkdir /mnt/a/ /mnt/b
+$ touch /mnt/a/autoexec.bat
+$ ln /mnt/a/autoexec.bat /mnt/b/config.sys
+----
+
+Now we open this up in the debugger:
+
+----
+xfs_db> path /a
+xfs_db> ls
+8          131                directory      0x0000002e   1 . (good)
+10         128                directory      0x0000172e   2 .. (good)
+12         132                regular        0x5a1f6ea0  12 autoexec.bat (good)
+xfs_db> path /b
+xfs_db> ls
+8          8388736            directory      0x0000002e   1 . (good)
+10         128                directory      0x0000172e   2 .. (good)
+15         132                regular        0x9a01678c  10 config.sys (good)
+xfs_db> path /b/config.sys
+xfs_db> p a
+a.sfattr.hdr.totsize = 64
+a.sfattr.hdr.count = 2
+a.sfattr.list[0].namelen = 16
+a.sfattr.list[0].valuelen = 12
+a.sfattr.list[0].root = 0
+a.sfattr.list[0].secure = 0
+a.sfattr.list[0].parent = 1
+a.sfattr.list[0].parent_ino = 131
+a.sfattr.list[0].parent_gen = 3772462576
+a.sfattr.list[0].parent_namehash = 0x5a1f6ea0
+a.sfattr.list[0].parent_name = "autoexec.bat"
+a.sfattr.list[1].namelen = 16
+a.sfattr.list[1].valuelen = 10
+a.sfattr.list[1].root = 0
+a.sfattr.list[1].secure = 0
+a.sfattr.list[1].parent = 1
+a.sfattr.list[1].parent_ino = 8388736
+a.sfattr.list[1].parent_gen = 1161632072
+a.sfattr.list[1].parent_namehash = 0x9a01678c
+a.sfattr.list[1].parent_name = "config.sys"
+----
+
+In this example, +/a+ and +/b+ are subdirectories of the root.  A regular file
+is hardlinked into both subdirectories, under different names.  Directory +/a+
+is inode 131 and has an entry +autoexec.bat+ pointing to the child file.
+Directory +/b+ is inode 8388736 and has an entry +config.sys+ pointing to the
+same child file.
+
+Within the child file, notice that there are two parent pointers in the
+extended attribute structure.  The first parent pointer tells us that directory
+inode 131 should have an entry +autoexec.bat+ pointing down to the child; the
+second parent pointer tells us that directory inode 8388736 should have an
+entry +config.sys+ pointing down to the child.  Note that the name hashes are
+the same between each directory entry and its parent pointer.
+
 == Key Differences Between Directories and Extended Attributes
 
 Directories and extended attributes share the function of mapping names to