Documentation/filesystems/ext4/group_descr.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 Block Group Descriptors
   4 -----------------------
   5
   6 Each block group on the filesystem has one of these descriptors
   7 associated with it. As noted in the Layout section above, the group
   8 descriptors (if present) are the second item in the block group. The
   9 standard configuration is for each block group to contain a full copy of
  10 the block group descriptor table unless the sparse_super feature flag
  11 is set.
  12
  13 Notice how the group descriptor records the location of both bitmaps and
  14 the inode table (i.e. they can float). This means that within a block
  15 group, the only data structures with fixed locations are the superblock
  16 and the group descriptor table. The flex_bg mechanism uses this
  17 property to group several block groups into a flex group and lay out all
  18 of the groups' bitmaps and inode tables into one long run in the first
  19 group of the flex group.
  20
  21 If the meta_bg feature flag is set, then several block groups are
  22 grouped together into a meta group. Note that in the meta_bg case,
  23 however, the first and last two block groups within the larger meta
  24 group contain only group descriptors for the groups inside the meta
  25 group.
  26
  27 flex_bg and meta_bg do not appear to be mutually exclusive features.
  28
  29 In ext2, ext3, and ext4 (when the 64bit feature is not enabled), the
  30 block group descriptor was only 32 bytes long and therefore ends at
  31 bg_checksum. On an ext4 filesystem with the 64bit feature enabled, the
  32 block group descriptor expands to at least the 64 bytes described below;
  33 the size is stored in the superblock.
  34
  35 If gdt_csum is set and metadata_csum is not set, the block group
  36 checksum is the crc16 of the FS UUID, the group number, and the group
  37 descriptor structure. If metadata_csum is set, then the block group
  38 checksum is the lower 16 bits of the checksum of the FS UUID, the group
  39 number, and the group descriptor structure. Both block and inode bitmap
  40 checksums are calculated against the FS UUID, the group number, and the
  41 entire bitmap.
  42
  43 The block group descriptor is laid out in ``struct ext4_group_desc``.
  44
  45 .. list-table::
  46    :widths: 8 8 24 40
  47    :header-rows: 1
  48
  49    * - Offset
  50      - Size
  51      - Name
  52      - Description
  53    * - 0x0
  54      - __le32
  55      - bg_block_bitmap_lo
  56      - Lower 32-bits of location of block bitmap.
  57    * - 0x4
  58      - __le32
  59      - bg_inode_bitmap_lo
  60      - Lower 32-bits of location of inode bitmap.
  61    * - 0x8
  62      - __le32
  63      - bg_inode_table_lo
  64      - Lower 32-bits of location of inode table.
  65    * - 0xC
  66      - __le16
  67      - bg_free_blocks_count_lo
  68      - Lower 16-bits of free block count.
  69    * - 0xE
  70      - __le16
  71      - bg_free_inodes_count_lo
  72      - Lower 16-bits of free inode count.
  73    * - 0x10
  74      - __le16
  75      - bg_used_dirs_count_lo
  76      - Lower 16-bits of directory count.
  77    * - 0x12
  78      - __le16
  79      - bg_flags
  80      - Block group flags. See the bgflags_ table below.
  81    * - 0x14
  82      - __le32
  83      - bg_exclude_bitmap_lo
  84      - Lower 32-bits of location of snapshot exclusion bitmap.
  85    * - 0x18
  86      - __le16
  87      - bg_block_bitmap_csum_lo
  88      - Lower 16-bits of the block bitmap checksum.
  89    * - 0x1A
  90      - __le16
  91      - bg_inode_bitmap_csum_lo
  92      - Lower 16-bits of the inode bitmap checksum.
  93    * - 0x1C
  94      - __le16
  95      - bg_itable_unused_lo
  96      - Lower 16-bits of unused inode count. If set, we needn't scan past the
  97        ``(sb.s_inodes_per_group - gdt.bg_itable_unused)`` th entry in the
  98        inode table for this group.
  99    * - 0x1E
 100      - __le16
 101      - bg_checksum
 102      - Group descriptor checksum; crc16(sb_uuid+group_num+bg_desc) if the
 103        RO_COMPAT_GDT_CSUM feature is set, or
 104        crc32c(sb_uuid+group_num+bg_desc) & 0xFFFF if the
 105        RO_COMPAT_METADATA_CSUM feature is set.  The bg_checksum
 106        field in bg_desc is skipped when calculating crc16 checksum,
 107        and set to zero if crc32c checksum is used.
 108    * -
 109      -
 110      -
 111      - These fields only exist if the 64bit feature is enabled and s_desc_size
 112        > 32.
 113    * - 0x20
 114      - __le32
 115      - bg_block_bitmap_hi
 116      - Upper 32-bits of location of block bitmap.
 117    * - 0x24
 118      - __le32
 119      - bg_inode_bitmap_hi
 120      - Upper 32-bits of location of inodes bitmap.
 121    * - 0x28
 122      - __le32
 123      - bg_inode_table_hi
 124      - Upper 32-bits of location of inodes table.
 125    * - 0x2C
 126      - __le16
 127      - bg_free_blocks_count_hi
 128      - Upper 16-bits of free block count.
 129    * - 0x2E
 130      - __le16
 131      - bg_free_inodes_count_hi
 132      - Upper 16-bits of free inode count.
 133    * - 0x30
 134      - __le16
 135      - bg_used_dirs_count_hi
 136      - Upper 16-bits of directory count.
 137    * - 0x32
 138      - __le16
 139      - bg_itable_unused_hi
 140      - Upper 16-bits of unused inode count.
 141    * - 0x34
 142      - __le32
 143      - bg_exclude_bitmap_hi
 144      - Upper 32-bits of location of snapshot exclusion bitmap.
 145    * - 0x38
 146      - __le16
 147      - bg_block_bitmap_csum_hi
 148      - Upper 16-bits of the block bitmap checksum.
 149    * - 0x3A
 150      - __le16
 151      - bg_inode_bitmap_csum_hi
 152      - Upper 16-bits of the inode bitmap checksum.
 153    * - 0x3C
 154      - __u32
 155      - bg_reserved
 156      - Padding to 64 bytes.
 157
 158 .. _bgflags:
 159
 160 Block group flags can be any combination of the following:
 161
 162 .. list-table::
 163    :widths: 16 64
 164    :header-rows: 1
 165
 166    * - Value
 167      - Description
 168    * - 0x1
 169      - inode table and bitmap are not initialized (EXT4_BG_INODE_UNINIT).
 170    * - 0x2
 171      - block bitmap is not initialized (EXT4_BG_BLOCK_UNINIT).
 172    * - 0x4
 173      - inode table is zeroed (EXT4_BG_INODE_ZEROED).