import-group-descriptors-chapter-from-wiki-page

   1 ext4: import group descriptors chapter from wiki page
   2
   3 From: Darrick J. Wong <darrick.wong@oracle.com>
   4
   5 Import the chapter about group descriptors from the on-disk format wiki
   6 page into the kernel documentation.
   7
   8 Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
   9 Signed-off-by: Theodore Ts'o <tytso@mit.edu>
  10 ---
  11  Documentation/filesystems/ext4/ondisk/globals.rst  |    1
  12  .../filesystems/ext4/ondisk/group_descr.rst        |  170 ++++++++++++++++++++
  13  2 files changed, 171 insertions(+)
  14  create mode 100644 Documentation/filesystems/ext4/ondisk/group_descr.rst
  15
  16
  17 diff --git a/Documentation/filesystems/ext4/ondisk/globals.rst b/Documentation/filesystems/ext4/ondisk/globals.rst
  18 index 4a33d0571bf2..c0dea6297e7f 100644
  19 --- a/Documentation/filesystems/ext4/ondisk/globals.rst
  20 +++ b/Documentation/filesystems/ext4/ondisk/globals.rst
  21 @@ -7,3 +7,4 @@ The filesystem is sharded into a number of block groups, each of which
  22  have static metadata at fixed locations.
  23
  24  .. include:: super.rst
  25 +.. include:: group_descr.rst
  26 diff --git a/Documentation/filesystems/ext4/ondisk/group_descr.rst b/Documentation/filesystems/ext4/ondisk/group_descr.rst
  27 new file mode 100644
  28 index 000000000000..759827e5d2cf
  29 --- /dev/null
  30 +++ b/Documentation/filesystems/ext4/ondisk/group_descr.rst
  31 @@ -0,0 +1,170 @@
  32 +.. SPDX-License-Identifier: GPL-2.0
  33 +
  34 +Block Group Descriptors
  35 +-----------------------
  36 +
  37 +Each block group on the filesystem has one of these descriptors
  38 +associated with it. As noted in the Layout section above, the group
  39 +descriptors (if present) are the second item in the block group. The
  40 +standard configuration is for each block group to contain a full copy of
  41 +the block group descriptor table unless the sparse\_super feature flag
  42 +is set.
  43 +
  44 +Notice how the group descriptor records the location of both bitmaps and
  45 +the inode table (i.e. they can float). This means that within a block
  46 +group, the only data structures with fixed locations are the superblock
  47 +and the group descriptor table. The flex\_bg mechanism uses this
  48 +property to group several block groups into a flex group and lay out all
  49 +of the groups' bitmaps and inode tables into one long run in the first
  50 +group of the flex group.
  51 +
  52 +If the meta\_bg feature flag is set, then several block groups are
  53 +grouped together into a meta group. Note that in the meta\_bg case,
  54 +however, the first and last two block groups within the larger meta
  55 +group contain only group descriptors for the groups inside the meta
  56 +group.
  57 +
  58 +flex\_bg and meta\_bg do not appear to be mutually exclusive features.
  59 +
  60 +In ext2, ext3, and ext4 (when the 64bit feature is not enabled), the
  61 +block group descriptor was only 32 bytes long and therefore ends at
  62 +bg\_checksum. On an ext4 filesystem with the 64bit feature enabled, the
  63 +block group descriptor expands to at least the 64 bytes described below;
  64 +the size is stored in the superblock.
  65 +
  66 +If gdt\_csum is set and metadata\_csum is not set, the block group
  67 +checksum is the crc16 of the FS UUID, the group number, and the group
  68 +descriptor structure. If metadata\_csum is set, then the block group
  69 +checksum is the lower 16 bits of the checksum of the FS UUID, the group
  70 +number, and the group descriptor structure. Both block and inode bitmap
  71 +checksums are calculated against the FS UUID, the group number, and the
  72 +entire bitmap.
  73 +
  74 +The block group descriptor is laid out in ``struct ext4_group_desc``.
  75 +
  76 +.. list-table::
  77 +   :widths: 1 1 1 77
  78 +   :header-rows: 1
  79 +
  80 +   * - Offset
  81 +     - Size
  82 +     - Name
  83 +     - Description
  84 +   * - 0x0
  85 +     - \_\_le32
  86 +     - bg\_block\_bitmap\_lo
  87 +     - Lower 32-bits of location of block bitmap.
  88 +   * - 0x4
  89 +     - \_\_le32
  90 +     - bg\_inode\_bitmap\_lo
  91 +     - Lower 32-bits of location of inode bitmap.
  92 +   * - 0x8
  93 +     - \_\_le32
  94 +     - bg\_inode\_table\_lo
  95 +     - Lower 32-bits of location of inode table.
  96 +   * - 0xC
  97 +     - \_\_le16
  98 +     - bg\_free\_blocks\_count\_lo
  99 +     - Lower 16-bits of free block count.
 100 +   * - 0xE
 101 +     - \_\_le16
 102 +     - bg\_free\_inodes\_count\_lo
 103 +     - Lower 16-bits of free inode count.
 104 +   * - 0x10
 105 +     - \_\_le16
 106 +     - bg\_used\_dirs\_count\_lo
 107 +     - Lower 16-bits of directory count.
 108 +   * - 0x12
 109 +     - \_\_le16
 110 +     - bg\_flags
 111 +     - Block group flags. See the bgflags_ table below.
 112 +   * - 0x14
 113 +     - \_\_le32
 114 +     - bg\_exclude\_bitmap\_lo
 115 +     - Lower 32-bits of location of snapshot exclusion bitmap.
 116 +   * - 0x18
 117 +     - \_\_le16
 118 +     - bg\_block\_bitmap\_csum\_lo
 119 +     - Lower 16-bits of the block bitmap checksum.
 120 +   * - 0x1A
 121 +     - \_\_le16
 122 +     - bg\_inode\_bitmap\_csum\_lo
 123 +     - Lower 16-bits of the inode bitmap checksum.
 124 +   * - 0x1C
 125 +     - \_\_le16
 126 +     - bg\_itable\_unused\_lo
 127 +     - Lower 16-bits of unused inode count. If set, we needn't scan past the
 128 +       ``(sb.s_inodes_per_group - gdt.bg_itable_unused)``\ th entry in the
 129 +       inode table for this group.
 130 +   * - 0x1E
 131 +     - \_\_le16
 132 +     - bg\_checksum
 133 +     - Group descriptor checksum; crc16(sb\_uuid+group+desc) if the
 134 +       RO\_COMPAT\_GDT\_CSUM feature is set, or crc32c(sb\_uuid+group\_desc) &
 135 +       0xFFFF if the RO\_COMPAT\_METADATA\_CSUM feature is set.
 136 +   * -
 137 +     -
 138 +     -
 139 +     - These fields only exist if the 64bit feature is enabled and s_desc_size
 140 +       > 32.
 141 +   * - 0x20
 142 +     - \_\_le32
 143 +     - bg\_block\_bitmap\_hi
 144 +     - Upper 32-bits of location of block bitmap.
 145 +   * - 0x24
 146 +     - \_\_le32
 147 +     - bg\_inode\_bitmap\_hi
 148 +     - Upper 32-bits of location of inodes bitmap.
 149 +   * - 0x28
 150 +     - \_\_le32
 151 +     - bg\_inode\_table\_hi
 152 +     - Upper 32-bits of location of inodes table.
 153 +   * - 0x2C
 154 +     - \_\_le16
 155 +     - bg\_free\_blocks\_count\_hi
 156 +     - Upper 16-bits of free block count.
 157 +   * - 0x2E
 158 +     - \_\_le16
 159 +     - bg\_free\_inodes\_count\_hi
 160 +     - Upper 16-bits of free inode count.
 161 +   * - 0x30
 162 +     - \_\_le16
 163 +     - bg\_used\_dirs\_count\_hi
 164 +     - Upper 16-bits of directory count.
 165 +   * - 0x32
 166 +     - \_\_le16
 167 +     - bg\_itable\_unused\_hi
 168 +     - Upper 16-bits of unused inode count.
 169 +   * - 0x34
 170 +     - \_\_le32
 171 +     - bg\_exclude\_bitmap\_hi
 172 +     - Upper 32-bits of location of snapshot exclusion bitmap.
 173 +   * - 0x38
 174 +     - \_\_le16
 175 +     - bg\_block\_bitmap\_csum\_hi
 176 +     - Upper 16-bits of the block bitmap checksum.
 177 +   * - 0x3A
 178 +     - \_\_le16
 179 +     - bg\_inode\_bitmap\_csum\_hi
 180 +     - Upper 16-bits of the inode bitmap checksum.
 181 +   * - 0x3C
 182 +     - \_\_u32
 183 +     - bg\_reserved
 184 +     - Padding to 64 bytes.
 185 +
 186 +.. _bgflags:
 187 +
 188 +Block group flags can be any combination of the following:
 189 +
 190 +.. list-table::
 191 +   :widths: 1 79
 192 +   :header-rows: 1
 193 +
 194 +   * - Value
 195 +     - Description
 196 +   * - 0x1
 197 +     - inode table and bitmap are not initialized (EXT4\_BG\_INODE\_UNINIT).
 198 +   * - 0x2
 199 +     - block bitmap is not initialized (EXT4\_BG\_BLOCK\_UNINIT).
 200 +   * - 0x4
 201 +     - inode table is zeroed (EXT4\_BG\_INODE\_ZEROED).
 202
 203