design: document the zoned on-disk format

Document the feature flags, superblock fields and new dinode union.

Signed-off-by: Christoph Hellwig <hch@lst.de>

diff --git a/design/XFS_Filesystem_Structure/ondisk_inode.asciidoc b/design/XFS_Filesystem_Structure/ondisk_inode.asciidoc
index ab4a503b4da6df0b43b7af158876fc9a6df1e1ab..ba111ebe6e3a98c86d844d7b36201f5980183040 100644 (file)
--- a/design/XFS_Filesystem_Structure/ondisk_inode.asciidoc
+++ b/design/XFS_Filesystem_Structure/ondisk_inode.asciidoc
@@ -139,7 +139,10 @@ struct xfs_dinode_core {
      __be64                    di_changecount;
      __be64                    di_lsn;
      __be64                    di_flags2;
-     __be32                    di_cowextsize;
+     union {
+             __be32            di_cowextsize;
+             __be32            di_used_blocks;
+     };
      __u8                      di_pad2[12];
      xfs_timestamp_t           di_crtime;
      __be64                    di_ino;
@@ -425,6 +428,14 @@ the source file to the destination file if the sharing operation completely
 overwrites the destination file's contents and the destination file does not
 already have +di_cowextsize+ set.
 
+*di_used_blocks*::
+
+Used only for the xref:Real_time_Reverse_Mapping_Btree[Reverse-Mapping B+tree]
+inode on filesystems with a xref:Zoned[Zoned Real-time Device].  Tracks the
+number of filesystem blocks in the rtgroup that have been written but not
+unmapped, i.e. the number of blocks that are referenced by at least one rmap
+entry.
+
 *di_pad2*::
 Padding for future expansion of the inode.
 

diff --git a/design/XFS_Filesystem_Structure/realtime.asciidoc b/design/XFS_Filesystem_Structure/realtime.asciidoc
index 16641525e201282aea681e9c61c3e2e458717951..fff0f691594a55259c5c563a39ac061c9a968cea 100644 (file)
--- a/design/XFS_Filesystem_Structure/realtime.asciidoc
+++ b/design/XFS_Filesystem_Structure/realtime.asciidoc
@@ -397,3 +397,37 @@ meta_uuid = 7e55b909-8728-4d69-a1fa-891427314eea
 include::rtrmapbt.asciidoc[]
 
 include::rtrefcountbt.asciidoc[]
+
+[[Zoned]]
+== Zoned Real-time Devices
+
+If the +XFS_SB_FEAT_INCOMPAT_ZONED+ feature is enabled, the real time device
+uses an entirely different space allocator.  This features does not use the
+xref:Real-Time_Bitmap_Inode[Free Space Bitmap Inode] and
+xref:Real-Time_Summary_Inode[Free Space Summary Inode].
+Instead, writes to the storage hardware must always occur sequentially
+from the start to the end of a rtgroup.  To support this requirement,
+file data are always written out of place using the so called copy on write
+or COW write path (which actually just redirects on write and never copies).
+
+When an rtgroup runs out of space to write, free space is reclaimed by
+copying and remapping still valid data from the full rtgroups into
+another rtgroup.  Once the rtgroup is empty, it is written to from the
+beginning again.  For this, the
+xref:Real_time_Reverse_Mapping_Btree[Reverse-Mapping B+tree] is required.
+
+For storage hardware that supports hardware zones, each rtgroup is mapped
+to exactly one zone.  When a file system is created on a a zoned storage
+device that does support conventional (aka random writable) zones at the
+beginning of the LBA space, those zones are used for the xfs data device
+(which in this case is primarily used for metadata), and the zoned requiring
+sequential writes are presented as the real-time device.  But when an external
+real-time device is used, rtgroups might also map to conventional zones.
+
+Filesystems with a zoned real-time device by default use the real-time device
+for all data, and the data device only for metadata, which makes the
+terminology a bit confusing.  But this is merely the default setting.  Like
+any other filesystem with a realtime volume, the +XFS_DIFLAG_REALTIME+ flag
+can be cleared on an empty regular file to target the data device; and the
++XFS_DIFLAG_RTINHERIT+ flag can be cleared on a directory so that new
+children will target the data device."

diff --git a/design/XFS_Filesystem_Structure/superblock.asciidoc b/design/XFS_Filesystem_Structure/superblock.asciidoc
index f0455304635737db44058a433126a91efc2e52ca..bd34eb0d30666d90e0c66f138110f79ee07088aa 100644 (file)
--- a/design/XFS_Filesystem_Structure/superblock.asciidoc
+++ b/design/XFS_Filesystem_Structure/superblock.asciidoc
@@ -74,6 +74,8 @@ struct xfs_dsb {
        __be32          sb_rgextents;
        __u8            sb_rgblklog;
        __u8            sb_pad[7];
+       __be64          sb_rtstart;
+       __be64          sb_rtreserved;
 
        /* must be padded to 64 bit alignment */
 };
@@ -449,6 +451,16 @@ pointers] for more information.
 Metadata directory tree.  See the section about the xref:Metadata_Directories[
 metadata directory tree] for more information.
 
+| +XFS_SB_FEAT_INCOMPAT_ZONED+ |
+Zoned RT device.  See the section about the xref:Zoned[Zoned Real-time Devices]
+for more information.
+
+| +XFS_SB_FEAT_INCOMPAT_ZONE_GAPS+ |
+Each hardware zone has unusable space at the end of its LBA range, which is
+mirrored by unusable filesystem blocks at the end of the rtgroup.  The
++xfs_rtblock_t startblock+ in file mappings is linearly mapped to the
+hardware LBA space.
+
 |=====
 
 *sb_features_log_incompat*::
@@ -505,6 +517,19 @@ generate absolute block numbers defined in extent maps from the segmented
 *sb_pad[7]*::
 Zeroes, if the +XFS_SB_FEAT_RO_INCOMPAT_METADIR+ feature is enabled.
 
+*sb_rtstart*::
+
+If the +XFS_SB_FEAT_INCOMPAT_ZONED+ feature is enabled, this is the start
+of the internal RT section.  That is the RT section is placed on the same
+device as the data device, and starts at this offset into the device.
+The value is in units of file system blocks.
+
+*sb_rtreserved*::
+
+If the +XFS_SB_FEAT_INCOMPAT_ZONED+ feature is enabled, this is the amount
+of space in the realtime section that is reserved for internal use
+by garbage collection and reorganization algorithms.
+
 === xfs_db Superblock Example
 
 A filesystem is made on a single disk with the following command: