xfs_format.hpp

Go to the documentation of this file.

// xfs_format.hpp -- XFS on-disk format definitions.
//
// Reference: "XFS Algorithms & Data Structures, 3rd Edition" (Red Hat,
//             SGI / Christoph Hellwig / Dave Chinner et al.) and the
//             Linux kernel sources at fs/xfs/.
//
// XFS uses BIG-ENDIAN on disk (heritage from SGI/IRIX). All multi-byte
// integers in this file are stored big-endian. We provide be16/be32/be64
// helpers below; do NOT memcpy directly into native structs.
//
// XFS supports two on-disk versions:
//   - V4: classic XFS, no CRCs, version_num low 4 bits = 4
//   - V5: introduced ~2013, all metadata blocks have CRC32 + UUID + LSN,
//         version_num low 4 bits = 5
//
// Both are still seen in the wild. V4 is still the default on RHEL 7,
// V5 is the default on RHEL 8+ and modern distros. We support both.
//
// This header contains DEFINITIONS ONLY -- no implementation. The layout
// in memory matches the on-disk layout (we use packed structs only where
// strictly necessary; otherwise we read raw bytes and decode field by
// field, which is more portable across compilers).
 
#pragma once
 
#include <array>
#include <cstdint>
#include <cstddef>
#include <string>
#include <vector>
 
namespace xfs {
 
// -----------------------------------------------------------------------------
//  Big-endian readers (XFS is big-endian on disk)
// -----------------------------------------------------------------------------
 
inline uint16_t be16(const unsigned char* p) {
    return static_cast<uint16_t>((p[0] << 8) | p[1]);
}
inline uint32_t be32(const unsigned char* p) {
    return (static_cast<uint32_t>(p[0]) << 24) |
           (static_cast<uint32_t>(p[1]) << 16) |
           (static_cast<uint32_t>(p[2]) << 8)  |
            static_cast<uint32_t>(p[3]);
}
inline uint64_t be64(const unsigned char* p) {
    return (static_cast<uint64_t>(p[0]) << 56) |
           (static_cast<uint64_t>(p[1]) << 48) |
           (static_cast<uint64_t>(p[2]) << 40) |
           (static_cast<uint64_t>(p[3]) << 32) |
           (static_cast<uint64_t>(p[4]) << 24) |
           (static_cast<uint64_t>(p[5]) << 16) |
           (static_cast<uint64_t>(p[6]) << 8)  |
            static_cast<uint64_t>(p[7]);
}
 
// -----------------------------------------------------------------------------
//  Magic numbers (all values are the BIG-ENDIAN ASCII representation)
// -----------------------------------------------------------------------------
 
constexpr uint32_t XFS_SB_MAGIC      = 0x58465342u; // "XFSB" -- superblock
constexpr uint32_t XFS_AGF_MAGIC_V4  = 0x58414746u; // "XAGF" -- AG free space
constexpr uint32_t XFS_AGF_MAGIC_V5  = 0x58414746u; // "XAGF" (same magic, V5 has CRC trailer)
constexpr uint32_t XFS_AGI_MAGIC_V4  = 0x58414749u; // "XAGI" -- AG inode info
constexpr uint32_t XFS_AGI_MAGIC_V5  = 0x58414749u; // "XAGI"
constexpr uint32_t XFS_AGFL_MAGIC_V5 = 0x5841464Cu; // "XAFL" -- AG free list (V5 only)
constexpr uint32_t XFS_DINODE_MAGIC  = 0x494Eu;     // "IN"   -- dinode (16-bit)
 
// B+tree magics
constexpr uint32_t XFS_ABTB_MAGIC_V4 = 0x41425442u; // "ABTB" -- alloc B+ by block
constexpr uint32_t XFS_ABTB_MAGIC_V5 = 0x41423342u; // "AB3B" -- V5 variant
constexpr uint32_t XFS_ABTC_MAGIC_V4 = 0x41425443u; // "ABTC" -- alloc B+ by count
constexpr uint32_t XFS_ABTC_MAGIC_V5 = 0x41423343u; // "AB3C"
constexpr uint32_t XFS_IBT_MAGIC_V4  = 0x49414254u; // "IABT" -- inode B+
constexpr uint32_t XFS_IBT_MAGIC_V5  = 0x49414233u; // "IAB3"
constexpr uint32_t XFS_FIBT_MAGIC_V4 = 0x46494254u; // "FIBT" -- free inode B+
constexpr uint32_t XFS_FIBT_MAGIC_V5 = 0x46494233u; // "FIB3"
constexpr uint32_t XFS_BMAP_MAGIC_V4 = 0x424D4150u; // "BMAP" -- block-map B+
constexpr uint32_t XFS_BMAP_MAGIC_V5 = 0x424D4133u; // "BMA3"
 
// -----------------------------------------------------------------------------
//  Version flags (sb_versionnum)
// -----------------------------------------------------------------------------
 
constexpr uint16_t XFS_SB_VERSION_NUMBITS    = 0x000F;
constexpr uint16_t XFS_SB_VERSION_4          = 4;
constexpr uint16_t XFS_SB_VERSION_5          = 5;
 
// V4 feature flags (sb_versionnum bits 4..15)
constexpr uint16_t XFS_SB_VERSION_ATTRBIT    = 0x0010;
constexpr uint16_t XFS_SB_VERSION_NLINKBIT   = 0x0020;
constexpr uint16_t XFS_SB_VERSION_QUOTABIT   = 0x0040;
constexpr uint16_t XFS_SB_VERSION_ALIGNBIT   = 0x0080;
constexpr uint16_t XFS_SB_VERSION_DALIGNBIT  = 0x0100;
constexpr uint16_t XFS_SB_VERSION_SHAREDBIT  = 0x0200;
constexpr uint16_t XFS_SB_VERSION_LOGV2BIT   = 0x0400;
constexpr uint16_t XFS_SB_VERSION_SECTORBIT  = 0x0800;
constexpr uint16_t XFS_SB_VERSION_EXTFLGBIT  = 0x1000;
constexpr uint16_t XFS_SB_VERSION_DIRV2BIT   = 0x2000;
constexpr uint16_t XFS_SB_VERSION_BORGBIT    = 0x4000;
constexpr uint16_t XFS_SB_VERSION_MOREBITSBIT= 0x8000;
 
// V5 feature flags (sb_features_*) -- only meaningful when version==5
constexpr uint32_t XFS_SB_FEAT_RO_COMPAT_FINOBT       = 0x00000001;
constexpr uint32_t XFS_SB_FEAT_RO_COMPAT_RMAPBT       = 0x00000002;
constexpr uint32_t XFS_SB_FEAT_RO_COMPAT_REFLINK      = 0x00000004;
constexpr uint32_t XFS_SB_FEAT_RO_COMPAT_INOBTCNT     = 0x00000008;
 
constexpr uint32_t XFS_SB_FEAT_INCOMPAT_FTYPE         = 0x00000001;
constexpr uint32_t XFS_SB_FEAT_INCOMPAT_SPINODES      = 0x00000002;
constexpr uint32_t XFS_SB_FEAT_INCOMPAT_META_UUID     = 0x00000004;
constexpr uint32_t XFS_SB_FEAT_INCOMPAT_BIGTIME       = 0x00000008;
constexpr uint32_t XFS_SB_FEAT_INCOMPAT_NEEDSREPAIR   = 0x00000010;
constexpr uint32_t XFS_SB_FEAT_INCOMPAT_NREXT64       = 0x00000020;
 
// -----------------------------------------------------------------------------
//  Superblock (struct xfs_dsb)
//
//  Sits at offset 0 of the volume. Each AG also has a copy of the superblock
//  at offset 0 of the AG (so AG0 SB == volume SB).
//
//  Size: 264 bytes for V5 (with feature/UUID/etc fields), 208 bytes for V4
//  (older fields only). We always read 512 bytes (one sector) to be safe.
//
//  IMPORTANT: V4 fields end at offset 0xC8 (200 bytes). V5-specific fields
//  start at offset 0xD0 (sb_features_compat, sb_features_ro_compat, etc.).
//  We expose ALL fields here as offset-based helpers below, not as a packed
//  struct, because compilers disagree on alignment of nested arrays.
// -----------------------------------------------------------------------------
 
struct Superblock {
    // V4 + V5 common fields
    uint32_t magicnum {0};           // 0x00 -- must be XFS_SB_MAGIC
    uint32_t blocksize {0};          // 0x04 -- bytes/block, power of 2 in [512..65536]
    uint64_t dblocks {0};            // 0x08 -- total data blocks
    uint64_t rblocks {0};            // 0x10 -- realtime blocks
    uint64_t rextents {0};           // 0x18 -- realtime extents
    std::array<uint8_t, 16> uuid {}; // 0x20 -- volume UUID
    uint64_t logstart {0};           // 0x30 -- log start block (0 if external log)
    uint64_t rootino {0};            // 0x38 -- root inode number
    uint64_t rbmino {0};             // 0x40 -- realtime bitmap inode
    uint64_t rsumino {0};            // 0x48 -- realtime summary inode
    uint32_t rextsize {0};           // 0x50 -- realtime extent size (blocks)
    uint32_t agblocks {0};           // 0x54 -- blocks per allocation group
    uint32_t agcount {0};            // 0x58 -- number of allocation groups
    uint32_t rbmblocks {0};          // 0x5C -- realtime bitmap blocks
    uint32_t logblocks {0};          // 0x60 -- log size in blocks
    uint16_t versionnum {0};         // 0x64 -- version + feature bits
    uint16_t sectsize {0};           // 0x66 -- sector size (bytes)
    uint16_t inodesize {0};          // 0x68 -- inode size (bytes)
    uint16_t inopblock {0};          // 0x6A -- inodes per block
    std::array<char, 12> fname {};   // 0x6C -- volume label (NUL-padded)
    uint8_t  blocklog {0};           // 0x78 -- log2(blocksize)
    uint8_t  sectlog {0};            // 0x79 -- log2(sectsize)
    uint8_t  inodelog {0};           // 0x7A -- log2(inodesize)
    uint8_t  inopblog {0};           // 0x7B -- log2(inopblock)
    uint8_t  agblklog {0};           // 0x7C -- log2(agblocks rounded up)
    uint8_t  rextslog {0};           // 0x7D -- log2(rextents)
    uint8_t  inprogress {0};         // 0x7E -- mkfs is in progress
    uint8_t  imax_pct {0};           // 0x7F -- max % of FS for inode space
    uint64_t icount {0};             // 0x80 -- allocated inodes
    uint64_t ifree {0};              // 0x88 -- free inodes
    uint64_t fdblocks {0};           // 0x90 -- free data blocks
    uint64_t frextents {0};          // 0x98 -- free realtime extents
    uint64_t uquotino {0};           // 0xA0 -- user quota inode
    uint64_t gquotino {0};           // 0xA8 -- group quota inode
    uint16_t qflags {0};             // 0xB0 -- quota flags
    uint8_t  flags {0};              // 0xB2 -- misc flags
    uint8_t  shared_vn {0};          // 0xB3 -- reserved
    uint32_t inoalignmt {0};         // 0xB4 -- inode chunk alignment
    uint32_t unit {0};               // 0xB8 -- stripe/raid unit
    uint32_t width {0};              // 0xBC -- stripe/raid width
    uint8_t  dirblklog {0};          // 0xC0 -- log2(dir-block factor)
    uint8_t  logsectlog {0};         // 0xC1 -- log2(log sector size) -- v2 logs
    uint16_t logsectsize {0};        // 0xC2 -- log sector size in bytes
    uint32_t logsunit {0};           // 0xC4 -- log device stripe unit
    uint32_t features2 {0};          // 0xC8 -- additional feature flags
 
    // V5-only fields (only valid if (versionnum & 0xF) == 5)
    uint32_t bad_features2 {0};       // 0xCC -- mirrored copy for compat
    uint32_t features_compat {0};     // 0xD0
    uint32_t features_ro_compat {0};  // 0xD4
    uint32_t features_incompat {0};   // 0xD8
    uint32_t features_log_incompat {0};// 0xDC
    uint32_t crc {0};                 // 0xE0 -- CRC of the SB itself
    uint32_t spino_align {0};         // 0xE4 -- sparse inode alignment
    uint64_t pquotino {0};            // 0xE8 -- project quota inode
    uint64_t lsn {0};                 // 0xF0 -- log seq # of last write
    std::array<uint8_t, 16> meta_uuid {}; // 0xF8 -- metadata UUID (V5 + META_UUID feature)
 
    // ---- Convenience getters ----
    unsigned format_version() const { return versionnum & XFS_SB_VERSION_NUMBITS; }
    bool is_v5() const { return format_version() == XFS_SB_VERSION_5; }
    bool is_v4() const { return format_version() == XFS_SB_VERSION_4; }
    bool has_crc() const { return is_v5(); }
    bool has_ftype() const {
        // FTYPE bit on V5 lives in features_incompat; on V4 it's part of features2
        if (is_v5()) return (features_incompat & XFS_SB_FEAT_INCOMPAT_FTYPE) != 0;
        // V4 stored ftype in features2 bit 0x80 (XFS_SB_VERSION2_FTYPE)
        return (features2 & 0x00000080u) != 0;
    }
    uint64_t volume_size_bytes() const { return dblocks * blocksize; }
    std::string label() const {
        std::string s(fname.data(), fname.size());
        while (!s.empty() && (s.back() == '\0' || s.back() == ' ')) s.pop_back();
        return s;
    }
};
 
// Parse a 512-byte sector into a Superblock. Returns true if magic matches
// and the parsed values pass basic sanity. Does NOT verify CRC even on V5.
//
// `buf` must point to at least 512 bytes.
bool parse_superblock(const unsigned char* buf, Superblock& out);
 
// -----------------------------------------------------------------------------
//  AG header: AGF (allocation group free space)
//
//  Sits at offset (sectsize) within each AG. Length: variable (V4=64 bytes,
//  V5=92 bytes header + sectsize-92 padding to a sector boundary).
//
//  We only need a few fields for level-3 base recovery: pointers to the
//  free-space B+trees (we don't actually traverse them in this session,
//  but having them parsed keeps the scaffolding in place).
// -----------------------------------------------------------------------------
 
struct AGF {
    uint32_t magicnum {0};       // 0x00 -- "XAGF"
    uint32_t versionnum {0};     // 0x04 -- 1
    uint32_t seqno {0};          // 0x08 -- AG number
    uint32_t length {0};         // 0x0C -- size of AG in blocks
    uint32_t roots[3] {};        // 0x10 -- roots of by-block, by-cnt, rmap (V5)
    uint32_t levels[3] {};       // 0x1C -- depths of those B+trees
    uint32_t flfirst {0};        // 0x28 -- AGFL first index
    uint32_t fllast {0};         // 0x2C -- AGFL last index
    uint32_t flcount {0};        // 0x30 -- AGFL count
    uint32_t freeblks {0};       // 0x34 -- total free blocks in AG
    uint32_t longest {0};        // 0x38 -- longest free extent
    uint32_t btreeblks {0};      // 0x3C -- blocks used by B+trees
    // V5-only fields (uuid/lsn/crc) skipped here -- we don't need them now.
};
 
bool parse_agf(const unsigned char* buf, AGF& out);
 
// -----------------------------------------------------------------------------
//  AG header: AGI (allocation group inode info)
//
//  Sits at offset (2 * sectsize) within each AG. Holds the root of the
//  inode B+tree and the unlinked-inode hash list.
//
//  This is the entry point for ALL inode iteration. When we add inode
//  walking in session 2, we'll start from agi.root.
// -----------------------------------------------------------------------------
 
struct AGI {
    uint32_t magicnum {0};        // 0x00 -- "XAGI"
    uint32_t versionnum {0};      // 0x04 -- 1
    uint32_t seqno {0};           // 0x08 -- AG number
    uint32_t length {0};          // 0x0C -- size of AG in blocks
    uint32_t count {0};           // 0x10 -- # allocated inodes in AG
    uint32_t root {0};            // 0x14 -- root of inode B+tree
    uint32_t level {0};           // 0x18 -- depth of inode B+tree
    uint32_t freecount {0};       // 0x1C -- # free inodes in AG
    uint32_t newino {0};          // 0x20 -- last allocated chunk
    uint32_t dirino {0};          // 0x24 -- unused
    uint32_t unlinked[64] {};     // 0x28 -- AGI_UNLINKED_BUCKETS hash
    // V5-only: free inode B+tree root/level (free_root, free_level)
    uint32_t free_root {0};       // V5 -- finobt root (XFS_SB_FEAT_RO_COMPAT_FINOBT)
    uint32_t free_level {0};      // V5 -- finobt depth
};
 
bool parse_agi(const unsigned char* buf, AGI& out);
 
// Same as above, but reads V5-only fields (free_root, free_level for FINOBT)
// when `is_v5` is true. On V4 those bytes don't exist and stay zero.
bool parse_agi(const unsigned char* buf, bool is_v5, AGI& out);
 
// -----------------------------------------------------------------------------
//  Inode number conversion helpers
//
//  XFS inode numbers are 64-bit but really encode (AG#, AG-relative block,
//  in-block offset). The split depends on agblklog and inopblog.
//
//      ino = (agno << (agblklog + inopblog))
//          | ((agbno) << inopblog)
//          | (agino_offset)
//
//  So we need agblklog and inopblog from the SB to crack an inode number.
// -----------------------------------------------------------------------------
 
struct InodeAddress {
    uint32_t agno {0};        // allocation group number
    uint32_t agbno {0};       // AG-relative block number where inode chunk starts
    uint32_t offset {0};      // in-block inode offset (0..inopblock-1)
 
    // Disk byte offset = sb.agblocks * agno * sb.blocksize
    //                  + agbno * sb.blocksize
    //                  + offset * sb.inodesize
};
 
InodeAddress crack_inode(uint64_t ino, const Superblock& sb);
 
// -----------------------------------------------------------------------------
//  Volume-level handle (lightweight; no I/O happens here)
//
//  Holds parsed SB plus per-AG headers. Built once at open-time and reused
//  for all subsequent operations. AG headers are read lazily.
// -----------------------------------------------------------------------------
 
struct AGContext {
    bool agf_loaded {false};
    bool agi_loaded {false};
    AGF  agf {};
    AGI  agi {};
};
 
struct VolumeContext {
    Superblock sb {};
    uint64_t volume_offset {0};       // disk byte offset where the XFS volume starts
    std::vector<AGContext> ag {};     // sized to sb.agcount after open
};
 
} // namespace xfs