From 91c76340b4a8213b48d72d42d32c5cae9f238e9a Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 2 Sep 2021 16:08:53 -0600 Subject: ext4: docs: switch away from list-table Commit 3a6541e97c03 (Add documentation about the orphan file feature) added a new document on orphan files, which is great. But the use of "list-table" results in documents that are absolutely unreadable in their plain-text form. Switch this file to the regular RST table format instead; the rendered (HTML) output is identical. Reviewed-by: Jan Kara Link: https://lore.kernel.org/r/20210902220854.198850-2-corbet@lwn.net Signed-off-by: Jonathan Corbet --- Documentation/filesystems/ext4/orphan.rst | 32 +++++++++++-------------------- 1 file changed, 11 insertions(+), 21 deletions(-) (limited to 'Documentation/filesystems') diff --git a/Documentation/filesystems/ext4/orphan.rst b/Documentation/filesystems/ext4/orphan.rst index bb19ecd1b626..d096fe0ba19e 100644 --- a/Documentation/filesystems/ext4/orphan.rst +++ b/Documentation/filesystems/ext4/orphan.rst @@ -21,27 +21,17 @@ in heavy creation of orphan inodes. When orphan file feature (referenced from the superblock through s\_orphan_file_inum) with several blocks. Each of these blocks has a structure: -.. list-table:: - :widths: 8 8 24 40 - :header-rows: 1 - - * - Offset - - Type - - Name - - Description - * - 0x0 - - Array of \_\_le32 entries - - Orphan inode entries - - Each \_\_le32 entry is either empty (0) or it contains inode number of - an orphan inode. - * - blocksize - 8 - - \_\_le32 - - ob\_magic - - Magic value stored in orphan block tail (0x0b10ca04) - * - blocksize - 4 - - \_\_le32 - - ob\_checksum - - Checksum of the orphan block. +============= ================ =============== =============================== +Offset Type Name Description +============= ================ =============== =============================== +0x0 Array of Orphan inode Each \_\_le32 entry is either + \_\_le32 entries entries empty (0) or it contains + inode number of an orphan + inode. +blocksize-8 \_\_le32 ob\_magic Magic value stored in orphan + block tail (0x0b10ca04) +blocksize-4 \_\_le32 ob\_checksum Checksum of the orphan block. +============= ================ =============== =============================== When a filesystem with orphan file feature is writeably mounted, we set RO\_COMPAT\_ORPHAN\_PRESENT feature in the superblock to indicate there may -- cgit v1.2.3 From 7275423c177e5dcf53e350ab9db38f99946b8ec5 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 2 Sep 2021 16:08:54 -0600 Subject: ext4: docs: Take out unneeded escaping The new file Documentation/orphan/ext4.rst escapes underscores ("\_") throughout. However, RST doesn't actually require that, so the escaping only succeeds in making the document less readable. Remove the unneeded escapes. Reviewed-by: Jan Kara Link: https://lore.kernel.org/r/20210902220854.198850-3-corbet@lwn.net Signed-off-by: Jonathan Corbet --- Documentation/filesystems/ext4/orphan.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'Documentation/filesystems') diff --git a/Documentation/filesystems/ext4/orphan.rst b/Documentation/filesystems/ext4/orphan.rst index d096fe0ba19e..03cca178864b 100644 --- a/Documentation/filesystems/ext4/orphan.rst +++ b/Documentation/filesystems/ext4/orphan.rst @@ -12,31 +12,31 @@ track the inode as orphan so that in case of crash extra blocks allocated to the file get truncated. Traditionally ext4 tracks orphan inodes in a form of single linked list where -superblock contains the inode number of the last orphan inode (s\_last\_orphan +superblock contains the inode number of the last orphan inode (s_last_orphan field) and then each inode contains inode number of the previously orphaned -inode (we overload i\_dtime inode field for this). However this filesystem +inode (we overload i_dtime inode field for this). However this filesystem global single linked list is a scalability bottleneck for workloads that result in heavy creation of orphan inodes. When orphan file feature -(COMPAT\_ORPHAN\_FILE) is enabled, the filesystem has a special inode -(referenced from the superblock through s\_orphan_file_inum) with several +(COMPAT_ORPHAN_FILE) is enabled, the filesystem has a special inode +(referenced from the superblock through s_orphan_file_inum) with several blocks. Each of these blocks has a structure: ============= ================ =============== =============================== Offset Type Name Description ============= ================ =============== =============================== -0x0 Array of Orphan inode Each \_\_le32 entry is either - \_\_le32 entries entries empty (0) or it contains +0x0 Array of Orphan inode Each __le32 entry is either + __le32 entries entries empty (0) or it contains inode number of an orphan inode. -blocksize-8 \_\_le32 ob\_magic Magic value stored in orphan +blocksize-8 __le32 ob_magic Magic value stored in orphan block tail (0x0b10ca04) -blocksize-4 \_\_le32 ob\_checksum Checksum of the orphan block. +blocksize-4 __le32 ob_checksum Checksum of the orphan block. ============= ================ =============== =============================== When a filesystem with orphan file feature is writeably mounted, we set -RO\_COMPAT\_ORPHAN\_PRESENT feature in the superblock to indicate there may +RO_COMPAT_ORPHAN_PRESENT feature in the superblock to indicate there may be valid orphan entries. In case we see this feature when mounting the filesystem, we read the whole orphan file and process all orphan inodes found there as usual. When cleanly unmounting the filesystem we remove the -RO\_COMPAT\_ORPHAN\_PRESENT feature to avoid unnecessary scanning of the orphan +RO_COMPAT_ORPHAN_PRESENT feature to avoid unnecessary scanning of the orphan file and also make the filesystem fully compatible with older kernels. -- cgit v1.2.3 From ff9c3d4360dbb47f8830b021788b19d3f0f3dc03 Mon Sep 17 00:00:00 2001 From: Christoph Anton Mitterer Date: Thu, 7 Oct 2021 06:00:01 +0200 Subject: docs: proc.rst: mountinfo: improved field numbering Without reading thoroughly, one could easily oversee that there may be several fields after #6. Made it more clearly by changing the field numbering. Signed-off-by: Christoph Anton Mitterer Link: https://lore.kernel.org/r/20211007040001.103413-2-mail@christoph.anton.mitterer.name Signed-off-by: Jonathan Corbet --- Documentation/filesystems/proc.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'Documentation/filesystems') diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 042c418f4090..d2542f737a0a 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -1857,7 +1857,7 @@ For example:: This file contains lines of the form:: 36 35 98:0 /mnt1 /mnt2 rw,noatime master:1 - ext3 /dev/root rw,errors=continue - (1)(2)(3) (4) (5) (6) (7) (8) (9) (10) (11) + (1)(2)(3) (4) (5) (6) (n…m) (m+1)(m+2) (m+3) (m+4) (1) mount ID: unique identifier of the mount (may be reused after umount) (2) parent ID: ID of parent (or of self for the top of the mount tree) @@ -1865,11 +1865,11 @@ This file contains lines of the form:: (4) root: root of the mount within the filesystem (5) mount point: mount point relative to the process's root (6) mount options: per mount options - (7) optional fields: zero or more fields of the form "tag[:value]" - (8) separator: marks the end of the optional fields - (9) filesystem type: name of filesystem of the form "type[.subtype]" - (10) mount source: filesystem specific information or "none" - (11) super options: per super block options + (n…m) optional fields: zero or more fields of the form "tag[:value]" + (m+1) separator: marks the end of the optional fields + (m+2) filesystem type: name of filesystem of the form "type[.subtype]" + (m+3) mount source: filesystem specific information or "none" + (m+4) super options: per super block options Parsers should ignore all unrecognised optional fields. Currently the possible optional fields are: -- cgit v1.2.3 From b0b719cea870dfe4284817a6c9668550913f07b9 Mon Sep 17 00:00:00 2001 From: Christoph Anton Mitterer Date: Thu, 7 Oct 2021 06:00:02 +0200 Subject: docs: proc.rst: mountinfo: align columns Signed-off-by: Christoph Anton Mitterer Link: https://lore.kernel.org/r/20211007040001.103413-3-mail@christoph.anton.mitterer.name Signed-off-by: Jonathan Corbet --- Documentation/filesystems/proc.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) (limited to 'Documentation/filesystems') diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index d2542f737a0a..8d7f141c6fc7 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -1859,17 +1859,17 @@ This file contains lines of the form:: 36 35 98:0 /mnt1 /mnt2 rw,noatime master:1 - ext3 /dev/root rw,errors=continue (1)(2)(3) (4) (5) (6) (n…m) (m+1)(m+2) (m+3) (m+4) - (1) mount ID: unique identifier of the mount (may be reused after umount) - (2) parent ID: ID of parent (or of self for the top of the mount tree) - (3) major:minor: value of st_dev for files on filesystem - (4) root: root of the mount within the filesystem - (5) mount point: mount point relative to the process's root - (6) mount options: per mount options - (n…m) optional fields: zero or more fields of the form "tag[:value]" - (m+1) separator: marks the end of the optional fields - (m+2) filesystem type: name of filesystem of the form "type[.subtype]" - (m+3) mount source: filesystem specific information or "none" - (m+4) super options: per super block options + (1) mount ID: unique identifier of the mount (may be reused after umount) + (2) parent ID: ID of parent (or of self for the top of the mount tree) + (3) major:minor: value of st_dev for files on filesystem + (4) root: root of the mount within the filesystem + (5) mount point: mount point relative to the process's root + (6) mount options: per mount options + (n…m) optional fields: zero or more fields of the form "tag[:value]" + (m+1) separator: marks the end of the optional fields + (m+2) filesystem type: name of filesystem of the form "type[.subtype]" + (m+3) mount source: filesystem specific information or "none" + (m+4) super options: per super block options Parsers should ignore all unrecognised optional fields. Currently the possible optional fields are: -- cgit v1.2.3 From 8c3b018874e819e60b87d44851a52782d8ee7986 Mon Sep 17 00:00:00 2001 From: Fengnan Chang Date: Sat, 23 Oct 2021 10:58:33 +0800 Subject: docs: f2fs: fix text alignment The docs build was generating this warning: Documentation/filesystems/f2fs.rst:306: WARNING: Block quote ends without a blank line; unexpected unindent. Remove the extra white space that was confusing sphinx. Fixes: 151b1982be5d (f2fs: compress: add nocompress extensions support) Signed-off-by: Fengnan Chang Reviewed-by: Chao Yu Link: https://lore.kernel.org/r/20211023025833.216030-1-changfengnan@vivo.com Signed-off-by: Jonathan Corbet --- Documentation/filesystems/f2fs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/filesystems') diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst index 09de6ebbbdfa..6f3c6e91346d 100644 --- a/Documentation/filesystems/f2fs.rst +++ b/Documentation/filesystems/f2fs.rst @@ -283,7 +283,7 @@ compress_extension=%s Support adding specified extension, so that f2fs can enab For other files, we can still enable compression via ioctl. Note that, there is one reserved special extension '*', it can be set to enable compression for all files. -nocompress_extension=%s Support adding specified extension, so that f2fs can disable +nocompress_extension=%s Support adding specified extension, so that f2fs can disable compression on those corresponding files, just contrary to compression extension. If you know exactly which files cannot be compressed, you can use this. The same extension name can't appear in both compress and nocompress -- cgit v1.2.3