From 328da1d1ba668dd27e70ccd7951315caf6d1601a Mon Sep 17 00:00:00 2001 From: Theodore Ts'o Date: Thu, 22 Aug 2019 23:19:01 -0400 Subject: [PATCH] add patch documentation-fixes --- documentation-fixes | 165 ++++++++++++++++++++++++++++++++++++++++++++++++++++ series | 1 + timestamps | 7 ++- 3 files changed, 170 insertions(+), 3 deletions(-) create mode 100644 documentation-fixes diff --git a/documentation-fixes b/documentation-fixes new file mode 100644 index 00000000..f01178b4 --- /dev/null +++ b/documentation-fixes @@ -0,0 +1,165 @@ +ext4: documentation fixes + +From: Ayush Ranjan + +This commit aims to fix the following issues in ext4 documentation: +- Flexible block group docs said that the aim was to group block + metadata together instead of block group metadata. +- The documentation consistly uses "location" instead of "block number". + It is easy to confuse location to be an absolute offset on disk. Added + a line to clarify all location values are in terms of block numbers. +- Dirent2 docs said that the rec_len field is shortened instead of the + name_len field. +- Typo in bg_checksum description. +- Inode size is 160 bytes now, and hence i_extra_isize is now 32. +- Cluster size formula was incorrect, it did not include the +10 to + s_log_cluster_size value. +- Typo: there were two s_wtime_hi in the superblock struct. +- Superblock struct was outdated, added the new fields which were part + of s_reserved earlier. +- Multiple mount protection seems to be implemented in fs/ext4/mmp.c. + +Signed-off-by: Ayush Ranjan +Signed-off-by: Theodore Ts'o +Reviewed-by: Andreas Dilger +--- + Documentation/filesystems/ext4/blockgroup.rst | 10 +++++----- + Documentation/filesystems/ext4/blocks.rst | 4 +++- + Documentation/filesystems/ext4/directory.rst | 2 +- + Documentation/filesystems/ext4/group_descr.rst | 2 +- + Documentation/filesystems/ext4/inodes.rst | 4 ++-- + Documentation/filesystems/ext4/super.rst | 20 ++++++++++++++------ + 6 files changed, 26 insertions(+), 16 deletions(-) + +diff --git a/Documentation/filesystems/ext4/blockgroup.rst b/Documentation/filesystems/ext4/blockgroup.rst +index baf888e4c06a..3da156633339 100644 +--- a/Documentation/filesystems/ext4/blockgroup.rst ++++ b/Documentation/filesystems/ext4/blockgroup.rst +@@ -71,11 +71,11 @@ if the flex\_bg size is 4, then group 0 will contain (in order) the + superblock, group descriptors, data block bitmaps for groups 0-3, inode + bitmaps for groups 0-3, inode tables for groups 0-3, and the remaining + space in group 0 is for file data. The effect of this is to group the +-block metadata close together for faster loading, and to enable large +-files to be continuous on disk. Backup copies of the superblock and +-group descriptors are always at the beginning of block groups, even if +-flex\_bg is enabled. The number of block groups that make up a flex\_bg +-is given by 2 ^ ``sb.s_log_groups_per_flex``. ++block group metadata close together for faster loading, and to enable ++large files to be continuous on disk. Backup copies of the superblock ++and group descriptors are always at the beginning of block groups, even ++if flex\_bg is enabled. The number of block groups that make up a ++flex\_bg is given by 2 ^ ``sb.s_log_groups_per_flex``. + + Meta Block Groups + ----------------- +diff --git a/Documentation/filesystems/ext4/blocks.rst b/Documentation/filesystems/ext4/blocks.rst +index 73d4dc0f7bda..bd722ecd92d6 100644 +--- a/Documentation/filesystems/ext4/blocks.rst ++++ b/Documentation/filesystems/ext4/blocks.rst +@@ -10,7 +10,9 @@ block groups. Block size is specified at mkfs time and typically is + 4KiB. You may experience mounting problems if block size is greater than + page size (i.e. 64KiB blocks on a i386 which only has 4KiB memory + pages). By default a filesystem can contain 2^32 blocks; if the '64bit' +-feature is enabled, then a filesystem can have 2^64 blocks. ++feature is enabled, then a filesystem can have 2^64 blocks. The location ++of structures is stored in terms of the block number the structure lives ++in and not the absolute offset on disk. + + For 32-bit filesystems, limits are as follows: + +diff --git a/Documentation/filesystems/ext4/directory.rst b/Documentation/filesystems/ext4/directory.rst +index 614034e24669..073940cc64ed 100644 +--- a/Documentation/filesystems/ext4/directory.rst ++++ b/Documentation/filesystems/ext4/directory.rst +@@ -59,7 +59,7 @@ is at most 263 bytes long, though on disk you'll need to reference + - File name. + + Since file names cannot be longer than 255 bytes, the new directory +-entry format shortens the rec\_len field and uses the space for a file ++entry format shortens the name\_len field and uses the space for a file + type flag, probably to avoid having to load every inode during directory + tree traversal. This format is ``ext4_dir_entry_2``, which is at most + 263 bytes long, though on disk you'll need to reference +diff --git a/Documentation/filesystems/ext4/group_descr.rst b/Documentation/filesystems/ext4/group_descr.rst +index 0f783ed88592..85f5d02dcf6f 100644 +--- a/Documentation/filesystems/ext4/group_descr.rst ++++ b/Documentation/filesystems/ext4/group_descr.rst +@@ -99,7 +99,7 @@ The block group descriptor is laid out in ``struct ext4_group_desc``. + * - 0x1E + - \_\_le16 + - bg\_checksum +- - Group descriptor checksum; crc16(sb\_uuid+group+desc) if the ++ - Group descriptor checksum; crc16(sb\_uuid+group\_desc) if the + RO\_COMPAT\_GDT\_CSUM feature is set, or crc32c(sb\_uuid+group\_desc) & + 0xFFFF if the RO\_COMPAT\_METADATA\_CSUM feature is set. + * - +diff --git a/Documentation/filesystems/ext4/inodes.rst b/Documentation/filesystems/ext4/inodes.rst +index 6bd35e506b6f..34f62928cebc 100644 +--- a/Documentation/filesystems/ext4/inodes.rst ++++ b/Documentation/filesystems/ext4/inodes.rst +@@ -470,8 +470,8 @@ inode, which allows struct ext4\_inode to grow for a new kernel without + having to upgrade all of the on-disk inodes. Access to fields beyond + EXT2\_GOOD\_OLD\_INODE\_SIZE should be verified to be within + ``i_extra_isize``. By default, ext4 inode records are 256 bytes, and (as +-of October 2013) the inode structure is 156 bytes +-(``i_extra_isize = 28``). The extra space between the end of the inode ++of August 2019) the inode structure is 160 bytes ++(``i_extra_isize = 32``). The extra space between the end of the inode + structure and the end of the inode record can be used to store extended + attributes. Each inode record can be as large as the filesystem block + size, though this is not terribly efficient. +diff --git a/Documentation/filesystems/ext4/super.rst b/Documentation/filesystems/ext4/super.rst +index 04ff079a2acf..48b6c78fc38e 100644 +--- a/Documentation/filesystems/ext4/super.rst ++++ b/Documentation/filesystems/ext4/super.rst +@@ -58,7 +58,7 @@ The ext4 superblock is laid out as follows in + * - 0x1C + - \_\_le32 + - s\_log\_cluster\_size +- - Cluster size is (2 ^ s\_log\_cluster\_size) blocks if bigalloc is ++ - Cluster size is 2 ^ (10 + s\_log\_cluster\_size) blocks if bigalloc is + enabled. Otherwise s\_log\_cluster\_size must equal s\_log\_block\_size. + * - 0x20 + - \_\_le32 +@@ -447,7 +447,7 @@ The ext4 superblock is laid out as follows in + - Upper 8 bits of the s_wtime field. + * - 0x275 + - \_\_u8 +- - s\_wtime_hi ++ - s\_mtime_hi + - Upper 8 bits of the s_mtime field. + * - 0x276 + - \_\_u8 +@@ -466,12 +466,20 @@ The ext4 superblock is laid out as follows in + - s\_last_error_time_hi + - Upper 8 bits of the s_last_error_time_hi field. + * - 0x27A +- - \_\_u8[2] +- - s\_pad ++ - \_\_u8 ++ - s\_pad[2] + - Zero padding. + * - 0x27C ++ - \_\_le16 ++ - s\_encoding ++ - Filename charset encoding. ++ * - 0x27E ++ - \_\_le16 ++ - s\_encoding_flags ++ - Filename charset encoding flags. ++ * - 0x280 + - \_\_le32 +- - s\_reserved[96] ++ - s\_reserved[95] + - Padding to the end of the block. + * - 0x3FC + - \_\_le32 +@@ -617,7 +625,7 @@ following: + * - 0x80 + - Enable a filesystem size of 2^64 blocks (INCOMPAT\_64BIT). + * - 0x100 +- - Multiple mount protection. Not implemented (INCOMPAT\_MMP). ++ - Multiple mount protection (INCOMPAT\_MMP). + * - 0x200 + - Flexible block groups. See the earlier discussion of this feature + (INCOMPAT\_FLEX\_BG). diff --git a/series b/series index 743502a0..a6c54482 100644 --- a/series +++ b/series @@ -10,6 +10,7 @@ drop-legacy-pre-1970-encoding-workaround set-error-return-correctly-when-ext4_htree_store_dirent-fails fix-warning-inside-ext4_convert_unwritten_extents_endio treat-buffers-with-write-errors-as-contining-valid-data +documentation-fixes #################################################### # unstable patches diff --git a/timestamps b/timestamps index 359d0c1a..0380e368 100755 --- a/timestamps +++ b/timestamps @@ -20,8 +20,9 @@ touch -d @1565555561 return-extent-cache-info-via-fiemap touch -d @1565555621 stable-boundary touch -d @1565631889 drop-legacy-pre-1970-encoding-workaround touch -d @1565634578 set-error-return-correctly-when-ext4_htree_store_dirent-fails -touch -d @1566528768 series touch -d @1566528826 fix-warning-inside-ext4_convert_unwritten_extents_endio -touch -d @1566528843 status touch -d @1566529232 treat-buffers-with-write-errors-as-contining-valid-data -touch -d @1566529253 timestamps +touch -d @1566529781 series +touch -d @1566530313 documentation-fixes +touch -d @1566530321 status +touch -d @1566530330 timestamps -- 2.11.4.GIT