documentation-fixes

   1 ext4: documentation fixes
   2
   3 From: Ayush Ranjan <ayushr2@illinois.edu>
   4
   5 This commit aims to fix the following issues in ext4 documentation:
   6 - Flexible block group docs said that the aim was to group block
   7   metadata together instead of block group metadata.
   8 - The documentation consistly uses "location" instead of "block number".
   9   It is easy to confuse location to be an absolute offset on disk. Added
  10   a line to clarify all location values are in terms of block numbers.
  11 - Dirent2 docs said that the rec_len field is shortened instead of the
  12   name_len field.
  13 - Typo in bg_checksum description.
  14 - Inode size is 160 bytes now, and hence i_extra_isize is now 32.
  15 - Cluster size formula was incorrect, it did not include the +10 to
  16   s_log_cluster_size value.
  17 - Typo: there were two s_wtime_hi in the superblock struct.
  18 - Superblock struct was outdated, added the new fields which were part
  19   of s_reserved earlier.
  20 - Multiple mount protection seems to be implemented in fs/ext4/mmp.c.
  21
  22 Signed-off-by: Ayush Ranjan <ayushr2@illinois.edu>
  23 Signed-off-by: Theodore Ts'o <tytso@mit.edu>
  24 Reviewed-by: Andreas Dilger <adilger@dilger.ca>
  25 ---
  26  Documentation/filesystems/ext4/blockgroup.rst  | 10 +++++-----
  27  Documentation/filesystems/ext4/blocks.rst      |  4 +++-
  28  Documentation/filesystems/ext4/directory.rst   |  2 +-
  29  Documentation/filesystems/ext4/group_descr.rst |  9 ++++++---
  30  Documentation/filesystems/ext4/inodes.rst      |  4 ++--
  31  Documentation/filesystems/ext4/super.rst       | 20 ++++++++++++++------
  32  6 files changed, 31 insertions(+), 18 deletions(-)
  33
  34 diff --git a/Documentation/filesystems/ext4/blockgroup.rst b/Documentation/filesystems/ext4/blockgroup.rst
  35 index baf888e4c06a..3da156633339 100644
  36 --- a/Documentation/filesystems/ext4/blockgroup.rst
  37 +++ b/Documentation/filesystems/ext4/blockgroup.rst
  38 @@ -71,11 +71,11 @@ if the flex\_bg size is 4, then group 0 will contain (in order) the
  39  superblock, group descriptors, data block bitmaps for groups 0-3, inode
  40  bitmaps for groups 0-3, inode tables for groups 0-3, and the remaining
  41  space in group 0 is for file data. The effect of this is to group the
  42 -block metadata close together for faster loading, and to enable large
  43 -files to be continuous on disk. Backup copies of the superblock and
  44 -group descriptors are always at the beginning of block groups, even if
  45 -flex\_bg is enabled. The number of block groups that make up a flex\_bg
  46 -is given by 2 ^ ``sb.s_log_groups_per_flex``.
  47 +block group metadata close together for faster loading, and to enable
  48 +large files to be continuous on disk. Backup copies of the superblock
  49 +and group descriptors are always at the beginning of block groups, even
  50 +if flex\_bg is enabled. The number of block groups that make up a
  51 +flex\_bg is given by 2 ^ ``sb.s_log_groups_per_flex``.
  52
  53  Meta Block Groups
  54  -----------------
  55 diff --git a/Documentation/filesystems/ext4/blocks.rst b/Documentation/filesystems/ext4/blocks.rst
  56 index 73d4dc0f7bda..bd722ecd92d6 100644
  57 --- a/Documentation/filesystems/ext4/blocks.rst
  58 +++ b/Documentation/filesystems/ext4/blocks.rst
  59 @@ -10,7 +10,9 @@ block groups. Block size is specified at mkfs time and typically is
  60  4KiB. You may experience mounting problems if block size is greater than
  61  page size (i.e. 64KiB blocks on a i386 which only has 4KiB memory
  62  pages). By default a filesystem can contain 2^32 blocks; if the '64bit'
  63 -feature is enabled, then a filesystem can have 2^64 blocks.
  64 +feature is enabled, then a filesystem can have 2^64 blocks. The location
  65 +of structures is stored in terms of the block number the structure lives
  66 +in and not the absolute offset on disk.
  67
  68  For 32-bit filesystems, limits are as follows:
  69
  70 diff --git a/Documentation/filesystems/ext4/directory.rst b/Documentation/filesystems/ext4/directory.rst
  71 index 614034e24669..073940cc64ed 100644
  72 --- a/Documentation/filesystems/ext4/directory.rst
  73 +++ b/Documentation/filesystems/ext4/directory.rst
  74 @@ -59,7 +59,7 @@ is at most 263 bytes long, though on disk you'll need to reference
  75       - File name.
  76
  77  Since file names cannot be longer than 255 bytes, the new directory
  78 -entry format shortens the rec\_len field and uses the space for a file
  79 +entry format shortens the name\_len field and uses the space for a file
  80  type flag, probably to avoid having to load every inode during directory
  81  tree traversal. This format is ``ext4_dir_entry_2``, which is at most
  82  263 bytes long, though on disk you'll need to reference
  83 diff --git a/Documentation/filesystems/ext4/group_descr.rst b/Documentation/filesystems/ext4/group_descr.rst
  84 index 0f783ed88592..7ba6114e7f5c 100644
  85 --- a/Documentation/filesystems/ext4/group_descr.rst
  86 +++ b/Documentation/filesystems/ext4/group_descr.rst
  87 @@ -99,9 +99,12 @@ The block group descriptor is laid out in ``struct ext4_group_desc``.
  88     * - 0x1E
  89       - \_\_le16
  90       - bg\_checksum
  91 -     - Group descriptor checksum; crc16(sb\_uuid+group+desc) if the
  92 -       RO\_COMPAT\_GDT\_CSUM feature is set, or crc32c(sb\_uuid+group\_desc) &
  93 -       0xFFFF if the RO\_COMPAT\_METADATA\_CSUM feature is set.
  94 +     - Group descriptor checksum; crc16(sb\_uuid+group\_num+bg\_desc) if the
  95 +       RO\_COMPAT\_GDT\_CSUM feature is set, or
  96 +       crc32c(sb\_uuid+group\_num+bg\_desc) & 0xFFFF if the
  97 +       RO\_COMPAT\_METADATA\_CSUM feature is set.  The bg\_checksum
  98 +       field in bg\_desc is skipped when calculating crc16 checksum,
  99 +       and set to zero if crc32c checksum is used.
 100     * -
 101       -
 102       -
 103 diff --git a/Documentation/filesystems/ext4/inodes.rst b/Documentation/filesystems/ext4/inodes.rst
 104 index 6bd35e506b6f..34f62928cebc 100644
 105 --- a/Documentation/filesystems/ext4/inodes.rst
 106 +++ b/Documentation/filesystems/ext4/inodes.rst
 107 @@ -470,8 +470,8 @@ inode, which allows struct ext4\_inode to grow for a new kernel without
 108  having to upgrade all of the on-disk inodes. Access to fields beyond
 109  EXT2\_GOOD\_OLD\_INODE\_SIZE should be verified to be within
 110  ``i_extra_isize``. By default, ext4 inode records are 256 bytes, and (as
 111 -of October 2013) the inode structure is 156 bytes
 112 -(``i_extra_isize = 28``). The extra space between the end of the inode
 113 +of August 2019) the inode structure is 160 bytes
 114 +(``i_extra_isize = 32``). The extra space between the end of the inode
 115  structure and the end of the inode record can be used to store extended
 116  attributes. Each inode record can be as large as the filesystem block
 117  size, though this is not terribly efficient.
 118 diff --git a/Documentation/filesystems/ext4/super.rst b/Documentation/filesystems/ext4/super.rst
 119 index 04ff079a2acf..48b6c78fc38e 100644
 120 --- a/Documentation/filesystems/ext4/super.rst
 121 +++ b/Documentation/filesystems/ext4/super.rst
 122 @@ -58,7 +58,7 @@ The ext4 superblock is laid out as follows in
 123     * - 0x1C
 124       - \_\_le32
 125       - s\_log\_cluster\_size
 126 -     - Cluster size is (2 ^ s\_log\_cluster\_size) blocks if bigalloc is
 127 +     - Cluster size is 2 ^ (10 + s\_log\_cluster\_size) blocks if bigalloc is
 128         enabled. Otherwise s\_log\_cluster\_size must equal s\_log\_block\_size.
 129     * - 0x20
 130       - \_\_le32
 131 @@ -447,7 +447,7 @@ The ext4 superblock is laid out as follows in
 132       - Upper 8 bits of the s_wtime field.
 133     * - 0x275
 134       - \_\_u8
 135 -     - s\_wtime_hi
 136 +     - s\_mtime_hi
 137       - Upper 8 bits of the s_mtime field.
 138     * - 0x276
 139       - \_\_u8
 140 @@ -466,12 +466,20 @@ The ext4 superblock is laid out as follows in
 141       - s\_last_error_time_hi
 142       - Upper 8 bits of the s_last_error_time_hi field.
 143     * - 0x27A
 144 -     - \_\_u8[2]
 145 -     - s\_pad
 146 +     - \_\_u8
 147 +     - s\_pad[2]
 148       - Zero padding.
 149     * - 0x27C
 150 +     - \_\_le16
 151 +     - s\_encoding
 152 +     - Filename charset encoding.
 153 +   * - 0x27E
 154 +     - \_\_le16
 155 +     - s\_encoding_flags
 156 +     - Filename charset encoding flags.
 157 +   * - 0x280
 158       - \_\_le32
 159 -     - s\_reserved[96]
 160 +     - s\_reserved[95]
 161       - Padding to the end of the block.
 162     * - 0x3FC
 163       - \_\_le32
 164 @@ -617,7 +625,7 @@ following:
 165     * - 0x80
 166       - Enable a filesystem size of 2^64 blocks (INCOMPAT\_64BIT).
 167     * - 0x100
 168 -     - Multiple mount protection. Not implemented (INCOMPAT\_MMP).
 169 +     - Multiple mount protection (INCOMPAT\_MMP).
 170     * - 0x200
 171       - Flexible block groups. See the earlier discussion of this feature
 172         (INCOMPAT\_FLEX\_BG).