Documentation/filesystems/xfs-self-describing-metadata.rst

1 .. SPDX-License-Identifier: GPL-2.0
4 XFS Self Describing Metadata
39 Self Describing Metadata
60 self describing metadata.
62 The first, fundamental requirement of self describing metadata is that the
69 Luckily, almost all XFS metadata has magic numbers embedded already - only the
71 magic numbers. Hence we can change the on-disk format of all these objects to
74 the metadata isn't self identifying. If it contains a new magic number, it is
75 self identifying and we can do much more expansive automated verification of the
78 As a primary concern, self describing metadata needs some form of overall
86 hence a 32 bit CRC is more than sufficient to detect multi-bit errors in
95 Self describing metadata needs to contain enough information so that the
99 mis-directed writes - a write might be misdirected to the wrong LUN and so be
122 Self describing metadata also needs to contain some indication of when it was
128 present that the run-time verification is not detecting.
150 Validation of self-describing metadata takes place at runtime in two places:
152 	- immediately after a successful read from disk
153 	- immediately prior to write IO submission
155 The verification is completely stateless - it is done independently of the
162 body, but in general most of the per-field validation is handled by the
181 Write verification is the opposite of the read verification - first the object
191 A typical on-disk structure needs to contain the following information::
210 	- short btree blocks have a 32 bit owner (ag number) and a 32 bit block
215 	- directory/attribute node blocks have a 16 bit magic number, and the
228 	struct xfs_mount *mp = bp->b_mount;
230 	    if ((xfs_sb_version_hascrc(&mp->m_sb) &&
231 		!xfs_verify_cksum(bp->b_addr, BBTOB(bp->b_length),
234 		    XFS_CORRUPTION_ERROR(__func__, XFS_ERRLEVEL_LOW, mp, bp->b_addr);
251 	    struct xfs_mount	*mp = bp->b_mount;
252 	    struct xfs_ondisk_hdr	*hdr = bp->b_addr;
254 	    if (hdr->magic != cpu_to_be32(XFS_FOO_MAGIC))
257 	    if (!xfs_sb_version_hascrc(&mp->m_sb)) {
258 		    if (!uuid_equal(&hdr->uuid, &mp->m_sb.sb_uuid))
260 		    if (bp->b_bn != be64_to_cpu(hdr->blkno))
262 		    if (hdr->owner == 0)
278 	    struct xfs_mount	*mp = bp->b_mount;
279 	    struct xfs_ondisk_hdr	*hdr = bp->b_addr;
281 	    if (hdr->magic == cpu_to_be32(XFS_FOO_CRC_MAGIC)) {
282 		    if (!uuid_equal(&hdr->uuid, &mp->m_sb.sb_uuid))
284 		    if (bp->b_bn != be64_to_cpu(hdr->blkno))
286 		    if (hdr->owner == 0)
288 	    } else if (hdr->magic != cpu_to_be32(XFS_FOO_MAGIC))
303 	    struct xfs_mount	*mp = bp->b_mount;
304 	    struct xfs_buf_log_item	*bip = bp->b_fspriv;
307 		    XFS_CORRUPTION_ERROR(__func__, XFS_ERRLEVEL_LOW, mp, bp->b_addr);
312 	    if (!xfs_sb_version_hascrc(&mp->m_sb))
317 		    struct xfs_ondisk_hdr	*hdr = bp->b_addr;
318 		    hdr->lsn = cpu_to_be64(bip->bli_item.li_lsn);
320 	    xfs_update_cksum(bp->b_addr, BBTOB(bp->b_length), XFS_FOO_CRC_OFF);
332 Inodes and dquots are special snowflakes. They have per-object CRC and
333 self-identifiers, but they are packed so that there are multiple objects per
334 buffer. Hence we do not use per-buffer verifiers to do the work of per-object
335 verification and CRC calculations. The per-buffer verifiers simply perform basic
336 identification of the buffer - that they contain inodes or dquots, and that
351 log recovery. So, it's gone unnoticed until now. This won't matter immediately -
352 repair will probably complain about it - but it needs to be fixed.