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).