design: document realtime groupsrealtime-groups_2023-12-31realtime-groups

Document the ondisk changes for realtime allocation groups.

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

3 files changed, 202 insertions, 0 deletions

diff --git a/design/XFS_Filesystem_Structure/allocation_groups.asciidoc b/design/XFS_Filesystem_Structure/allocation_groups.asciidoc
index 08151c7..ab8868d 100644
--- a/design/XFS_Filesystem_Structure/allocation_groups.asciidoc
+++ b/design/XFS_Filesystem_Structure/allocation_groups.asciidoc
@@ -55,6 +55,13 @@ struct xfs_sb
 	xfs_fsblock_t		sb_logstart;
 	xfs_ino_t		sb_rootino;
 	xfs_ino_t		sb_rbmino;
+	union {
+		xfs_ino_t	sb_rsumino;
+		struct {
+			xfs_rgnumber_t	sb_rgcount;
+			xfs_rgblock_t	sb_rgblocks;
+		};
+	};
 	xfs_ino_t		sb_rsumino;
 	xfs_agblock_t		sb_rextsize;
 	xfs_agblock_t		sb_agblocks;
@@ -150,6 +157,14 @@ to the inode for the root of the metadata directory tree.
 Summary inode for real-time bitmap if the +XFS_SB_FEAT_INCOMPAT_METADIR+
 feature is not enabled.
 
+*sb_rgcount*::
+Count of realtime groups in the filesystem, if the
++XFS_SB_FEAT_INCOMPAT_RTGROUPS+ feature is enabled.
+
+*sb_rgblocks*::
+Maximum number of filesystem blocks that can be contained within a realtime
+group, if the +XFS_SB_FEAT_INCOMPAT_RTGROUPS+ feature is enabled.
+
 *sb_rextsize*::
 Realtime extent size in blocks.
 
@@ -473,6 +488,10 @@ metadata directory tree] for more information.
 Directory parent pointers.  See the section about xref:Parent_Pointers[parent
 pointers] for more information.
 
+| +XFS_SB_FEAT_INCOMPAT_RTGROUPS+ |
+Realtime allocation groups.  See the section about the xref:Realtime_Groups[
+realtime groups] for more information.
+
 |=====
 
 *sb_features_log_incompat*::
diff --git a/design/XFS_Filesystem_Structure/magic.asciidoc b/design/XFS_Filesystem_Structure/magic.asciidoc
index 613e50c..c83f59a 100644
--- a/design/XFS_Filesystem_Structure/magic.asciidoc
+++ b/design/XFS_Filesystem_Structure/magic.asciidoc
@@ -48,6 +48,7 @@ relevant chapters.  Magic numbers tend to have consistent locations:
 | +XFS_RTRMAP_CRC_MAGIC+	| 0x4d415052	| MAPR	| xref:Real_time_Reverse_Mapping_Btree[Real-Time Reverse Mapping B+tree], v5 only
 | +XFS_REFC_CRC_MAGIC+		| 0x52334643	| R3FC	| xref:Reference_Count_Btree[Reference Count B+tree], v5 only
 | +XFS_MD_MAGIC+		| 0x5846534d	| XFSM	| xref:Metadata_Dumps[Metadata Dumps]
+| +XFS_RTSB_MAGIC+		| 0x58524750	| XRGP	| xref:Realtime_Groups[Realtime Groups]
 |=====
 
 The magic numbers for log items are at offset zero in each log item, but items
diff --git a/design/XFS_Filesystem_Structure/realtime.asciidoc b/design/XFS_Filesystem_Structure/realtime.asciidoc
index 11426e8..f5fdb4e 100644
--- a/design/XFS_Filesystem_Structure/realtime.asciidoc
+++ b/design/XFS_Filesystem_Structure/realtime.asciidoc
@@ -47,4 +47,186 @@ This data structure is not particularly space efficient, however it is a very
 fast way to provide the same data as the two free space B+trees for regular
 files since the space is preallocated and metadata maintenance is minimal.
 
+[[Realtime_Groups]]
+== Realtime Groups
+
+To reduce metadata contention for space allocation and remapping activities
+being applied to realtime files, the realtime volume can be split into
+allocation groups, just like the data volume.  The free space information is
+still contained in a single file that applies to the entire volume.
+
+Each realtime allocation group can contain up to (2^31^ - 1) filesystem blocks,
+regardless of the underlying realtime extent size.
+
+Each realtime group has the following characteristics:
+
+         * A super block describing overall filesystem info
+         * Free space bitmap
+         * Summary of free space
+
+Each of these structures are expanded upon in the following sections.
+
+[[Realtime_Group_Superblocks]]
+=== Superblocks
+
+The first block of each realtime group contains a superblock.  These fields
+must match their counterparts in the filesystem superblock on the data device.
+
+[source, c]
+----
+struct xfs_rtsb {
+	__be32		rsb_magicnum;
+	__be32		rsb_blocksize;
+	__be64		rsb_rblocks;
+
+	__be64		rsb_rextents;
+	__be64		rsb_lsn;
+
+	__be32		rsb_rgcount;
+	char		rsb_fname[XFSLABEL_MAX];
+
+	uuid_t		rsb_uuid;
+
+	__be32		rsb_rextsize;
+	__be32		rsb_rbmblocks;
+
+	__be32		rsb_rgblocks;
+	__u8		rsb_blocklog;
+	__u8		rsb_sectlog;
+	__u8		rsb_rextslog;
+	__u8		rsb_pad;
+
+	__le32		rsb_crc;
+	__le32		rsb_pad2;
+
+	uuid_t		rsb_meta_uuid;
+
+	/* must be padded to 64 bit alignment */
+};
+----
+
+*rsb_magicnum*::
+Identifies the filesystem. Its value is +XFS_RTSB_MAGIC+ ``XRGP'' (0x58524750).
+
+*rsb_blocksize*::
+The size of a basic unit of space allocation in bytes. Typically, this is 4096
+(4KB) but can range from 512 to 65536 bytes.
+
+*rsb_rblocks*::
+Number blocks in the real-time disk device.
+
+*rsb_rextents*::
+Number of extents on the real-time device.
+
+*rsb_lsn*::
+Log sequence number of the last superblock update.
+
+*rsb_rgcount*::
+Count of realtime groups in the filesystem, if the
++XFS_SB_FEAT_INCOMPAT_RTGROUPS+ feature is enabled.
+
+*rsb_fname[12]*::
+Name for the filesystem. This value can be used in the mount command.
+
+*rsb_uuid*::
+UUID (Universally Unique ID) for the filesystem. Filesystems can be mounted by
+the UUID instead of device name.
+
+*rsb_rextsize*::
+Realtime extent size in blocks.
+
+*rsb_rbmblocks*::
+Number of real-time bitmap blocks.
+
+*rsb_rgblocks*::
+Maximum number of filesystem blocks that can be contained within a realtime
+group, if the +XFS_SB_FEAT_INCOMPAT_RTGROUPS+ feature is enabled.
+
+*rsb_blocklog*::
+log~2~ value of +sb_blocksize+. In other terms, +sb_blocksize = 2^sb_blocklog^+.
+
+*rsb_sectlog*::
+log~2~ value of +sb_sectsize+.
+
+*rsb_rextslog*::
+log~2~ value of +sb_rextents+.
+
+*rsb_pad*::
+Must be zero.
+
+*rsb_crc*::
+Superblock checksum.
+
+*rsb_pad2*::
+Must be zero.
+
+*rsb_meta_uuid*::
+If the +XFS_SB_FEAT_INCOMPAT_META_UUID+ feature is set, then the UUID field in
+all metadata blocks must match this UUID.  If not, the block header UUID field
+must match +sb_uuid+.
+
+==== xfs_db rtgroup Superblock Example
+
+A filesystem is made on a multidisk filesystem with the following command:
+
+----
+# mkfs.xfs -r rtgroups=1,rgcount=4,rtdev=/dev/sdb /dev/sda -f
+meta-data=/dev/sda               isize=512    agcount=4, agsize=1298176 blks
+         =                       sectsz=512   attr=2, projid32bit=1
+         =                       crc=1        finobt=1, sparse=1, rmapbt=1
+         =                       reflink=1    bigtime=1 inobtcount=1 nrext64=1
+         =                       metadir=1
+data     =                       bsize=4096   blocks=5192704, imaxpct=25
+         =                       sunit=0      swidth=0 blks
+naming   =version 2              bsize=4096   ascii-ci=0, ftype=1
+log      =internal log           bsize=4096   blocks=16384, version=2
+         =                       sectsz=512   sunit=0 blks, lazy-count=1
+realtime =/dev/sdb               extsz=4096   blocks=5192704, rtextents=5192704
+         =                       rgcount=4    rgsize=1298176 blks
+----
+
+And in xfs_db, inspecting the realtime group superblock and then the regular
+superblock:
+
+----
+# xfs_db -R /dev/sdb /dev/sda
+xfs_db> rtsb 0
+xfs_db> print
+magicnum = 0x58524750
+blocksize = 4096
+rblocks = 5192704
+rextents = 5192704
+uuid = c52adb8a-48a6-4325-b251-d4dcb30889ea
+rextsize = 1
+rgblocks = 1048576
+rgcount = 5
+rbmblocks = 161
+fname = "\000\000\000\000\000\000\000\000\000\000\000\000"
+blocklog = 12
+sectlog = 9
+rextslog = 22
+crc = 0x36872867 (correct)
+lsn = 0
+meta_uuid = c52adb8a-48a6-4325-b251-d4dcb30889ea
+xfs_db> sb 0
+xfs_db> print magicnum blocksize rblocks rextents uuid rextsize rgblocks \
+rgcount rbmblocks fname blocklog sectlog rextslog crc lsn meta_uuid
+magicnum = 0x58465342
+blocksize = 4096
+rblocks = 5192704
+rextents = 5192704
+uuid = c52adb8a-48a6-4325-b251-d4dcb30889ea
+rextsize = 1
+rgblocks = 1048576
+rgcount = 5
+rbmblocks = 161
+fname = "\000\000\000\000\000\000\000\000\000\000\000\000"
+blocklog = 12
+sectlog = 9
+rextslog = 22
+crc = 0xfbd2b2d2 (correct)
+lsn = 0
+meta_uuid = c52adb8a-48a6-4325-b251-d4dcb30889ea
+----
+
 include::rtrmapbt.asciidoc[]