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+desc) if the
 103        RO\_COMPAT\_GDT\_CSUM feature is set, or crc32c(sb\_uuid+group\_desc) &
 104        0xFFFF if the RO\_COMPAT\_METADATA\_CSUM feature is set.
 105    * -
 106      -
 107      -
 108      - These fields only exist if the 64bit feature is enabled and s_desc_size
 109        > 32.
 110    * - 0x20
 111      - \_\_le32
 112      - bg\_block\_bitmap\_hi
 113      - Upper 32-bits of location of block bitmap.
 114    * - 0x24
 115      - \_\_le32
 116      - bg\_inode\_bitmap\_hi
 117      - Upper 32-bits of location of inodes bitmap.
 118    * - 0x28
 119      - \_\_le32
 120      - bg\_inode\_table\_hi
 121      - Upper 32-bits of location of inodes table.
 122    * - 0x2C
 123      - \_\_le16
 124      - bg\_free\_blocks\_count\_hi
 125      - Upper 16-bits of free block count.
 126    * - 0x2E
 127      - \_\_le16
 128      - bg\_free\_inodes\_count\_hi
 129      - Upper 16-bits of free inode count.
 130    * - 0x30
 131      - \_\_le16
 132      - bg\_used\_dirs\_count\_hi
 133      - Upper 16-bits of directory count.
 134    * - 0x32
 135      - \_\_le16
 136      - bg\_itable\_unused\_hi
 137      - Upper 16-bits of unused inode count.
 138    * - 0x34
 139      - \_\_le32
 140      - bg\_exclude\_bitmap\_hi
 141      - Upper 32-bits of location of snapshot exclusion bitmap.
 142    * - 0x38
 143      - \_\_le16
 144      - bg\_block\_bitmap\_csum\_hi
 145      - Upper 16-bits of the block bitmap checksum.
 146    * - 0x3A
 147      - \_\_le16
 148      - bg\_inode\_bitmap\_csum\_hi
 149      - Upper 16-bits of the inode bitmap checksum.
 150    * - 0x3C
 151      - \_\_u32
 152      - bg\_reserved
 153      - Padding to 64 bytes.
 154
 155 .. _bgflags:
 156
 157 Block group flags can be any combination of the following:
 158
 159 .. list-table::
 160    :widths: 16 64
 161    :header-rows: 1
 162
 163    * - Value
 164      - Description
 165    * - 0x1
 166      - inode table and bitmap are not initialized (EXT4\_BG\_INODE\_UNINIT).
 167    * - 0x2
 168      - block bitmap is not initialized (EXT4\_BG\_BLOCK\_UNINIT).
 169    * - 0x4
 170      - inode table is zeroed (EXT4\_BG\_INODE\_ZEROED).