Product SiteDocumentation Site

Chapter 3. Allocation Groups

3.1. Superblocks
3.2. AG Free Space Management
3.2.1. AG Free Space Block
3.2.2. AG Free Space B+trees
3.2.3. AG Free List
3.3. AG Inode Management
3.3.1. Inode Numbers
3.3.2. Inode Information
3.3.3. Inode B+trees
3.4. Real-time Devices
XFS filesystems are divided into a number of equally sized chunks called Allocation Groups. Each AG can almost be thought of as an individual filesystem that maintains it's own space usage. Each AG can be up to one terabyte in size (512 bytes * 231), regardless of the underlying device's sector size.
Each AG has the following characteristics:
Having multiple AGs allows XFS to handle most operations in parallel without degrading performance as the number of concurrent accessing increases.
The only global information maintained by the first AG (primary) is free space across the filesystem and total inode counts. If the XFS_SB_VERSION2_LAZYSBCOUNTBIT flag is set in the superblock, these are only updated on-disk when the filesystem is cleanly unmounted (umount or shutdown).
Immediately after a mkfs.xfs, the primary AG has the following disk layout the subsequent AGs do not have any inodes allocated:
6
Each of these structures are expanded upon in the following sections.

3.1. Superblocks

Each AG starts with a superblock. The first one is the primary superblock that stores aggregate AG information. Secondary superblocks are only used by xfs_repair when the primary superblock has been corrupted.
The superblock is defined by the following structure. The description of each field follows.
typedef struct xfs_sb
{
	__uint32_t        sb_magicnum;
	__uint32_t        sb_blocksize;
	xfs_drfsbno_t     sb_dblocks;
	xfs_drfsbno_t     sb_rblocks;
	xfs_drtbno_t      sb_rextents;
	uuid_t            sb_uuid;
	xfs_dfsbno_t      sb_logstart;
	xfs_ino_t         sb_rootino;
	xfs_ino_t         sb_rbmino;
	xfs_ino_t         sb_rsumino;
	xfs_agblock_t     sb_rextsize;
	xfs_agblock_t     sb_agblocks;
	xfs_agnumber_t    sb_agcount;
	xfs_extlen_t      sb_rbmblocks;
	xfs_extlen_t      sb_logblocks;
	__uint16_t        sb_versionnum;
	__uint16_t        sb_sectsize;
	__uint16_t        sb_inodesize;
	__uint16_t        sb_inopblock;
	char              sb_fname[12];
	__uint8_t         sb_blocklog;
	__uint8_t         sb_sectlog;
	__uint8_t         sb_inodelog;
	__uint8_t         sb_inopblog;
	__uint8_t         sb_agblklog;
	__uint8_t         sb_rextslog;
	__uint8_t         sb_inprogress;
	__uint8_t         sb_imax_pct;
	__uint64_t        sb_icount;
	__uint64_t        sb_ifree;
	__uint64_t        sb_fdblocks;
	__uint64_t        sb_frextents;
	xfs_ino_t         sb_uquotino;
	xfs_ino_t         sb_gquotino;
	__uint16_t        sb_qflags;
	__uint8_t         sb_flags;
	__uint8_t         sb_shared_vn;
	xfs_extlen_t      sb_inoalignmt;
	__uint32_t        sb_unit;
	__uint32_t        sb_width;
	__uint8_t         sb_dirblklog;
	__uint8_t         sb_logsectlog;
	__uint16_t        sb_logsectsize;
	__uint32_t        sb_logsunit;
	__uint32_t        sb_features2;
} xfs_sb_t;
sb_magicnum
Identifies the filesystem. It's value is XFS_SB_MAGIC = 0x58465342 "XFSB".
sb_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.
sb_dblocks
Total number of blocks available for data and metadata on the filesystem.
sb_rblocks
Number blocks in the real-time disk device. Refer to Section 3.4, “ Real-time Devices” for more information.
sb_rextents
Number of extents on the real-time device.
sb_uuid
UUID (Universally Unique ID) for the filesystem. Filesystems can be mounted by the UUID instead of device name.
sb_logstart
First block number for the journaling log if the log is internal (ie. not on a separate disk device). For an external log device, this will be zero (the log will also start on the first block on the log device).
sb_rootino
Root inode number for the filesystem. Typically, this is 128 when using a 4KB block size.
sb_rbmino
Bitmap inode for real-time extents.
sb_rsumino
Summary inode for real-time bitmap.
sb_rextsize
Realtime extent size in blocks.
sb_agblocks
Size of each AG in blocks. For the actual size of the last AG, refer to the Section 3.2, “AG Free Space Management” agf_length value.
sb_agcount
Number of AGs in the filesystem.
sb_rbmblocks
Number of real-time bitmap blocks.
sb_logblocks
Number of blocks for the journaling log.
sb_versionnum
Filesystem version number. This is a bitmask specifying the features enabled when creating the filesystem. Any disk checking tools or drivers that do not recognize any set bits must not operate upon the filesystem. Most of the flags indicate features introduced over time. The value must be 4 including the following flags:
Flag
Description
XFS_SB_VERSION_ATTRBIT
Set if any inode have extended attributes.
XFS_SB_VERSION_NLINKBIT
Set if any inodes use 32-bit di_nlink values.
XFS_SB_VERSION_QUOTABIT
Quotas are enabled on the filesystem. This also brings in the various quota fields in the superblock.
XFS_SB_VERSION_ALIGNBIT
Set if sb_inoalignmt is used.
XFS_SB_VERSION_DALIGNBIT
Set if sb_unit and sb_width are used.
XFS_SB_VERSION_SHAREDBIT
Set if sb_shared_vn is used.
XFS_SB_VERSION_LOGV2BIT
Version 2 journaling logs are used.
XFS_SB_VERSION_SECTORBIT
Set if sb_sectsize is not 512.
XFS_SB_VERSION_EXTFLGBIT
Unwritten extents are used. This is always set.
XFS_SB_VERSION_DIRV2BIT
Version 2 directories are used. This is always set.
XFS_SB_VERSION_MOREBITSBIT
Set if the sb_features2 field in the superblock contains more flags.
sb_sectsize
Specifies the underlying disk sector size in bytes. Majority of the time, this is 512 bytes. This determines the minimum I/O alignment including Direct I/O.
sb_inodesize
Size of the inode in bytes. The default is 256 (2 inodes per standard sector) but can be made as large as 2048 bytes when creating the filesystem.
sb_inopblock
Number of inodes per block. This is equivalent to sb_blocksize / sb_inodesize.
sb_fname[12]
Name for the filesystem. This value can be used in the mount command.
sb_blocklog
log2 value of sb_blocksize. In other terms, sb_blocksize = 2sb_blocklog.
sb_sectlog
log2 value of sb_sectsize.
sb_inodelog
log2 value of sb_inodesize.
sb_inopblog
log2 value of sb_inopblock.
sb_agblklog
log2 value of sb_agblocks (rounded up). This value is used to generate inode numbers and absolute block numbers defined in extent maps.
sb_rextslog
log2 value of sb_rextents.
sb_inprogress
Flag specifying that the filesystem is being created.
sb_imax_pct
Maximum percentage of filesystem space that can be used for inodes. The default value is 25%.
sb_icount
Global count for number inodes allocated on the filesystem. This is only maintained in the first superblock.
sb_ifree
Global count of free inodes on the filesystem. This is only maintained in the first superblock.
sb_fdblocks
Global count of free data blocks on the filesystem. This is only maintained in the first superblock.
sb_frextents
Global count of free real-time extents on the filesystem. This is only maintained in the first superblock.
sb_uquotino
Inode for user quotas. This and the following two quota fields only apply if XFS_SB_VERSION_QUOTABIT flag is set in sb_versionnum. Refer to Section 9.1, “ Quota Inodes” for more information.
sb_gquotino
Inode for group or project quotas. Group and Project quotas cannot be used at the same time.
sb_qflags
Quota flags. It can be a combination of the following flags:
Flag
Description
XFS_UQUOTA_ACCT
User quota accounting is enabled.
XFS_UQUOTA_ENFD
User quotas are enforced.
XFS_UQUOTA_CHKD
User quotas have been checked and updated on disk.
XFS_PQUOTA_ACCT
Project quota accounting is enabled.
XFS_OQUOTA_ENFD
Other (group/project) quotas are enforced.
XFS_OQUOTA_CHKD
Other (group/project) quotas have been checked.
XFS_GQUOTA_ACCT
Group quota accounting is enabled.
sb_flags
Miscellaneous flags.
sb_shared_vn
Reserved and must be zero ("vn" stands for version number).
sb_inoalignmt
Inode chunk alignment in fsblocks.
sb_unit
Underlying stripe or raid unit in blocks.
sb_width
Underlying stripe or raid width in blocks.
sb_dirblklog
log2 value multiplier that determines the granularity of directory block allocations in fsblocks.
sb_logsectlog
log2 value of the log subvolume's sector size. This is only used if the journaling log is on a separate disk device (i.e. not internal).
sb_logsectsize
The log's sector size in bytes if the filesystem uses an external log device.
sb_logsunit
The log device's stripe or raid unit size. This only applies to version 2 logs (XFS_SB_VERSION_LOGV2BIT is set in sb_versionnum).
sb_features2
Additional version flags if XFS_SB_VERSION_MOREBITSBIT is set in sb_versionnum. The currently defined additional features include:
  1. XFS_SB_VERSION2_LAZYSBCOUNTBIT (0x02): Lazy global counters. Making a filesystem with this bit set can improve performance. The global free space and inode counts are only updated in the primary superblock when the filesystem is cleanly unmounted.
  2. XFS_SB_VERSION2_ATTR2BIT (0x08): Extended attributes version 2. Making a filesystem with this optimises the inode layout of extended attributes.
  3. XFS_SB_VERSION2_PARENTBIT (0x10): Parent pointers. All inodes must have an extended attribute that points back to its parent inode. The primary purpose for this information is in backup systems.

xfs_db Example:

A filesystem is made on a single SATA disk with the following command:
# mkfs.xfs -i attr=2 -n size=16384 -f /dev/sda7
meta-data=/dev/sda7              isize=256    agcount=16, agsize=3923122 blks
         =                       sectsz=512   attr=2
data     =                       bsize=4096   blocks=62769952, imaxpct=25
         =                       sunit=0      swidth=0 blks, unwritten=1
naming   =version 2              bsize=16384
log      =internal log           bsize=4096   blocks=30649, version=1
         =                       sectsz=512   sunit=0 blks
realtime =none                   extsz=65536  blocks=0, rtextents=0
And in xfs_db, inspecting the superblock:
xfs_db> sb
xfs_db> p
magicnum = 0x58465342
blocksize = 4096
dblocks = 62769952
rblocks = 0
rextents = 0
uuid = 32b24036-6931-45b4-b68c-cd5e7d9a1ca5
logstart = 33554436
rootino = 128
rbmino = 129
rsumino = 130
rextsize = 16
agblocks = 3923122
agcount = 16
rbmblocks = 0
logblocks = 30649
versionnum = 0xb084
sectsize = 512
inodesize = 256
inopblock = 16
fname = "\000\000\000\000\000\000\000\000\000\000\000\000"
blocklog = 12
sectlog = 9
inodelog = 8
inopblog = 4
agblklog = 22
rextslog = 0
inprogress = 0
imax_pct = 25
icount = 64
ifree = 61
fdblocks = 62739235
frextents = 0
uquotino = 0
gquotino = 0
qflags = 0
flags = 0
shared_vn = 0
inoalignmt = 2
unit = 0
width = 0
dirblklog = 2
logsectlog = 0
logsectsize = 0
logsunit = 0
features2 = 8