Re: [PATCH] design: document the zoned on-disk format

["Darrick J. Wong" <djwong@kernel.org>]

On Thu, Mar 20, 2025 at 05:05:41PM +0100, Christoph Hellwig wrote:
> Document the feature flags, superblock fields and new dinode union.
> 
> Signed-off-by: Christoph Hellwig <hch@lst.de>
> ---
>  .../ondisk_inode.asciidoc                     | 13 ++++++-
>  .../realtime.asciidoc                         | 34 +++++++++++++++++++
>  .../superblock.asciidoc                       | 25 ++++++++++++++
>  3 files changed, 71 insertions(+), 1 deletion(-)
> 
> diff --git a/design/XFS_Filesystem_Structure/ondisk_inode.asciidoc b/design/XFS_Filesystem_Structure/ondisk_inode.asciidoc
> index ab4a503b4da6..ba111ebe6e3a 100644
> --- 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 16641525e201..fff0f691594a 100644
> --- 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

Dumb nit: sentence doesn't need to begin with "But", e.g.

"When an external real-time device is used..."

Otherwise I think this description matches what I saw in the kernel
changes so with that one silly nit fixed,

Reviewed-by: "Darrick J. Wong" <djwong@kernel.org>

Actually, wait, I'm the maintainer of xfs-docs.  I'll fix it on commit
if there isn't a v2 in the next week or so.

--D

> +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 f04553046357..bd34eb0d3066 100644
> --- 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:
> -- 
> 2.45.2
> 
>