From: Darrick J. Wong <djwong@xxxxxxxxxx>
Document the ondisk format of v2 metadumps.
Signed-off-by: Darrick J. Wong <djwong@xxxxxxxxxx>
---
design/XFS_Filesystem_Structure/metadump.asciidoc | 112 ++++++++++++++++++++-
1 file changed, 109 insertions(+), 3 deletions(-)
diff --git a/design/XFS_Filesystem_Structure/metadump.asciidoc b/design/XFS_Filesystem_Structure/metadump.asciidoc
index 2bddb77f..a32d6423 100644
--- a/design/XFS_Filesystem_Structure/metadump.asciidoc
+++ b/design/XFS_Filesystem_Structure/metadump.asciidoc
@@ -6,6 +6,9 @@ snapshot of a live file system and to restore that snapshot onto a block
device for debugging purposes. Only the metadata are captured in the
snapshot, and the metadata blocks may be obscured for privacy reasons.
+[[Metadump_v1]]
+== Metadump v1
+
A metadump file starts with a +xfs_metablock+ that records the addresses of
the blocks that follow. Following that are the metadata blocks captured
from the filesystem. The first block following the first superblock
@@ -21,7 +24,7 @@ struct xfs_metablock {
__be32 mb_magic;
__be16 mb_count;
uint8_t mb_blocklog;
- uint8_t mb_reserved;
+ uint8_t mb_info;
__be64 mb_daddr[];
};
----
@@ -37,14 +40,117 @@ Number of blocks indexed by this record. This value must not exceed +(1
The log size of a metadump block. This size of a metadump block 512
bytes, so this value should be 9.
-*mb_reserved*::
-Reserved. Should be zero.
+*mb_info*::
+A combination of the following flags:
+
+.Metadump information flags
+[options="header"]
+|=====
+| Flag | Description
+| +XFS_METADUMP_INFO_FLAGS+ |
+This field is nonzero.
+
+| +XFS_METADUMP_OBFUSCATED+ |
+User-supplied directory entry and extended attribute names have been obscured,
+and extended attribute values are zeroed to protect privacy.
+
+| +XFS_METADUMP_FULLBLOCKS+ |
+Entire metadata blocks have been dumped, including unused areas.
+If not set, the unused areas are zeroed.
+
+| +XFS_METADUMP_DIRTYLOG+ |
+The log was dirty when the dump was captured.
+
+|=====
*mb_daddr*::
An array of disk addresses. Each of the +mb_count+ blocks (of size +(1
<< mb_blocklog+) following the +xfs_metablock+ should be written back to
the address pointed to by the corresponding +mb_daddr+ entry.
+[[Metadump_v2]]
+== Metadump v2
+
+A v2 metadump file starts with a +xfs_metadump_header+ structure that records
+information about the dump itself. Immediately after this header is a sequence
+of a +xfs_meta_extent+ structure describing an extent of data and the data
+itself. Data areas must be a multiple of 512 bytes in length.
+
+.Metadata v2 Dump Format
+
+[source, c]
+----
+struct xfs_metadump_header {
+ __be32 xmh_magic;
+ __be32 xmh_version;
+ __be32 xmh_compat_flags;
+ __be32 xmh_incompat_flags;
+ __be64 xmh_reserved;
+} __packed;
+----
+
+*xmh_magic*::
+The magic number, ``XMD2'' (0x584D4432).
+
+*xmh_version*::
+The value 2.
+
+*xmh_compat_flags*::
+A combination of the following flags:
+
+.Metadump v2 compat flags
+[options="header"]
+|=====
+| Flag | Description
+| +XFS_MD2_COMPAT_OBFUSCATED+ |
+User-supplied directory entry and extended attribute names have been obscured,
+and extended attribute values are zeroed to protect privacy.
+
+| +XFS_MD2_COMPAT_FULLBLOCKS+ |
+Entire metadata blocks have been dumped, including unused areas.
+If not set, the unused areas are zeroed.
+
+| +XFS_MD2_COMPAT_DIRTYLOG+ |
+The log was dirty when the dump was captured.
+
+| +XFS_MD2_COMPAT_EXTERNALLOG+ |
+Dump contains external log contents.
+
+|=====
+
+*xmh_incompat_flags*::
+Must be zero.
+
+*xmh_reserved*::
+Must be zero.
+
+.Metadata v2 Extent Format
+
+[source, c]
+----
+struct xfs_meta_extent {
+ __be64 xme_addr;
+ __be32 xme_len;
+} __packed;
+----
+
+*xme_addr*::
+Bits 55-56 determine the device from which the metadata dump data was extracted.
+
+.Metadump v2 extent flags
+[options="header"]
+|=====
+| Value | Description
+| 0 | Data device
+| 1 | External log
+|=====
+
+The lower 54 bits determine the device address from which the dump data was
+extracted, in units of 512 bytes.
+
+*xme_length*::
+Length of the metadata dump data region, in units of 512 bytes.
+
== Dump Obfuscation
Unless explicitly disabled, the +xfs_metadump+ tool obfuscates empty block
