1.. SPDX-License-Identifier: GPL-2.0
2
3Block Group Descriptors
4-----------------------
5
6Each block group on the filesystem has one of these descriptors
7associated with it. As noted in the Layout section above, the group
8descriptors (if present) are the second item in the block group. The
9standard configuration is for each block group to contain a full copy of
10the block group descriptor table unless the sparse\_super feature flag
11is set.
12
13Notice how the group descriptor records the location of both bitmaps and
14the inode table (i.e. they can float). This means that within a block
15group, the only data structures with fixed locations are the superblock
16and the group descriptor table. The flex\_bg mechanism uses this
17property to group several block groups into a flex group and lay out all
18of the groups' bitmaps and inode tables into one long run in the first
19group of the flex group.
20
21If the meta\_bg feature flag is set, then several block groups are
22grouped together into a meta group. Note that in the meta\_bg case,
23however, the first and last two block groups within the larger meta
24group contain only group descriptors for the groups inside the meta
25group.
26
27flex\_bg and meta\_bg do not appear to be mutually exclusive features.
28
29In ext2, ext3, and ext4 (when the 64bit feature is not enabled), the
30block group descriptor was only 32 bytes long and therefore ends at
31bg\_checksum. On an ext4 filesystem with the 64bit feature enabled, the
32block group descriptor expands to at least the 64 bytes described below;
33the size is stored in the superblock.
34
35If gdt\_csum is set and metadata\_csum is not set, the block group
36checksum is the crc16 of the FS UUID, the group number, and the group
37descriptor structure. If metadata\_csum is set, then the block group
38checksum is the lower 16 bits of the checksum of the FS UUID, the group
39number, and the group descriptor structure. Both block and inode bitmap
40checksums are calculated against the FS UUID, the group number, and the
41entire bitmap.
42
43The 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
157Block 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).
171