Skip to contentSkip to conversation

f2fs: documentation formatting cleanup and improvements

PATCH Applied Bagas Sanjaya 5 participants 12 messages Aug 20, 2025 – Sep 2, 2025

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

cover f2fs: documentation formatting cleanup and improvements

Hi,

Here are documentation formatting cleanup for f2fs. This also includes docs retitle at the end of series ([6/6]) as a bonus.

This series is based on docs-next tree.

Enjoy!

Bagas Sanjaya (6):
Documentation: f2fs: Separate errors mode subtable
Documentation: f2fs: Format compression level subtable
Documentation: f2fs: Span write hint table section rows
Documentation: f2fs: Wrap snippets in literal code blocks
Documentation: f2fs: Indent compression_mode option list
Documentation: f2fs: Reword title

 Documentation/filesystems/f2fs.rst | 88 +++++++++++++++++-------------
 1 file changed, 50 insertions(+), 38 deletions(-)

base-commit: 37c52167b007d9d0bb8c5ed53dd6efc4969a1356

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#1 lore raw

PATCH 1/6 Documentation: f2fs: Separate errors mode subtable

errors=%s subtable is shown in htmldocs output as long-running paragraph instead due to missing separator from its previous paragraph. Add it.

Fixes b62e71be2110 ("f2fs: support errors=remount-ro|continue|panic mountoption")
---
 Documentation/filesystems/f2fs.rst | 1 +
 1 file changed, 1 insertion(+)
Documentation/filesystems/f2fs.rst +1 -0
index e5bb89452aff29..203631566a2c58 100644
@@ -357,6 +357,7 @@ errors=%s		 Specify f2fs behavior on critical errors. This supports modes:
 			 panic immediately, continue without doing anything, and remount
 			 the partition in read-only mode. By default it uses "continue"
 			 mode.
+
 			 ====================== =============== =============== ========
 			 mode			continue	remount-ro	panic
 			 ====================== =============== =============== ========
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#2 lore raw

PATCH 2/6 Documentation: f2fs: Format compression level subtable

In reply to Bagas Sanjaya

Format compression_algorithm subtable as reST table as it does the semantic job rather than normal paragraph.

---
 Documentation/filesystems/f2fs.rst | 4 ++++
 1 file changed, 4 insertions(+)
Documentation/filesystems/f2fs.rst +4 -0
index 203631566a2c58..132c3080ad5c4c 100644
@@ -291,9 +291,13 @@ compress_algorithm=%s	 Control compress algorithm, currently f2fs supports "lzo"
 			 "lz4", "zstd" and "lzo-rle" algorithm.
 compress_algorithm=%s:%d Control compress algorithm and its compress level, now, only
 			 "lz4" and "zstd" support compress level config.
+
+                         =========      ===========
 			 algorithm	level range
+                         =========      ===========
 			 lz4		3 - 16
 			 zstd		1 - 22
+                         =========      ===========
 compress_log_size=%u	 Support configuring compress cluster size. The size will
 			 be 4KB * (1 << %u). The default and minimum sizes are 16KB.
 compress_extension=%s	 Support adding specified extension, so that f2fs can enable
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#3 lore raw

PATCH 3/6 Documentation: f2fs: Span write hint table section rows

In reply to Bagas Sanjaya

Write hint policy table has two rows which act as section rows: buffered io and direct io, yet these rows are written as normal rows instead.

Column-span them.

---
 Documentation/filesystems/f2fs.rst | 2 ++
 1 file changed, 2 insertions(+)
Documentation/filesystems/f2fs.rst +2 -0
index 132c3080ad5c4c..85e015b712c2e1 100644
@@ -800,11 +800,13 @@ ioctl(COLD)           COLD_DATA                WRITE_LIFE_EXTREME
 extension list        "                        "
 
 -- buffered io
+------------------------------------------------------------------
 N/A                   COLD_DATA                WRITE_LIFE_EXTREME
 N/A                   HOT_DATA                 WRITE_LIFE_SHORT
 N/A                   WARM_DATA                WRITE_LIFE_NOT_SET
 
 -- direct io
+------------------------------------------------------------------
 WRITE_LIFE_EXTREME    COLD_DATA                WRITE_LIFE_EXTREME
 WRITE_LIFE_SHORT      HOT_DATA                 WRITE_LIFE_SHORT
 WRITE_LIFE_NOT_SET    WARM_DATA                WRITE_LIFE_NOT_SET
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#4 lore raw

PATCH 4/6 Documentation: f2fs: Wrap snippets in literal code blocks

In reply to Bagas Sanjaya

Compression mode code and device aliasing shell snippets are shown in htmldocs output as long-running paragraph instead. Wrap them.

Fixes 602a16d58e9a ("f2fs: add compress_mode mount option")
Fixes 128d333f0dff ("f2fs: introduce device aliasing file")
---
 Documentation/filesystems/f2fs.rst | 58 +++++++++++++++---------------
 1 file changed, 29 insertions(+), 29 deletions(-)
Documentation/filesystems/f2fs.rst +29 -29
index 85e015b712c2e1..0f9472ae62f2cb 100644
@@ -931,15 +931,15 @@ target file and the timing. The user can do manual compression/decompression on
 compression enabled files using F2FS_IOC_DECOMPRESS_FILE and F2FS_IOC_COMPRESS_FILE
 ioctls like the below.
 
-To decompress a file,
+To decompress a file::
 
-fd = open(filename, O_WRONLY, 0);
-ret = ioctl(fd, F2FS_IOC_DECOMPRESS_FILE);
+  fd = open(filename, O_WRONLY, 0);
+  ret = ioctl(fd, F2FS_IOC_DECOMPRESS_FILE);
 
-To compress a file,
+To compress a file::
 
-fd = open(filename, O_WRONLY, 0);
-ret = ioctl(fd, F2FS_IOC_COMPRESS_FILE);
+  fd = open(filename, O_WRONLY, 0);
+  ret = ioctl(fd, F2FS_IOC_COMPRESS_FILE);
 
 NVMe Zoned Namespace devices
 ----------------------------
@@ -969,32 +969,32 @@ reserved and used by another filesystem or for different purposes. Once that
 external usage is complete, the device aliasing file can be deleted, releasing
 the reserved space back to F2FS for its own use.
 
-<use-case>
+.. code-block::
 
-# ls /dev/vd*
-/dev/vdb (32GB) /dev/vdc (32GB)
-# mkfs.ext4 /dev/vdc
-# mkfs.f2fs -c /dev/[email protected] /dev/vdb
-# mount /dev/vdb /mnt/f2fs
-# ls -l /mnt/f2fs
-vdc.file
-# df -h
-/dev/vdb                            64G   33G   32G  52% /mnt/f2fs
+   # ls /dev/vd*
+   /dev/vdb (32GB) /dev/vdc (32GB)
+   # mkfs.ext4 /dev/vdc
+   # mkfs.f2fs -c /dev/[email protected] /dev/vdb
+   # mount /dev/vdb /mnt/f2fs
+   # ls -l /mnt/f2fs
+   vdc.file
+   # df -h
+   /dev/vdb                            64G   33G   32G  52% /mnt/f2fs
 
-# mount -o loop /dev/vdc /mnt/ext4
-# df -h
-/dev/vdb                            64G   33G   32G  52% /mnt/f2fs
-/dev/loop7                          32G   24K   30G   1% /mnt/ext4
-# umount /mnt/ext4
+   # mount -o loop /dev/vdc /mnt/ext4
+   # df -h
+   /dev/vdb                            64G   33G   32G  52% /mnt/f2fs
+   /dev/loop7                          32G   24K   30G   1% /mnt/ext4
+   # umount /mnt/ext4
 
-# f2fs_io getflags /mnt/f2fs/vdc.file
-get a flag on /mnt/f2fs/vdc.file ret=0, flags=nocow(pinned),immutable
-# f2fs_io setflags noimmutable /mnt/f2fs/vdc.file
-get a flag on noimmutable ret=0, flags=800010
-set a flag on /mnt/f2fs/vdc.file ret=0, flags=noimmutable
-# rm /mnt/f2fs/vdc.file
-# df -h
-/dev/vdb                            64G  753M   64G   2% /mnt/f2fs
+   # f2fs_io getflags /mnt/f2fs/vdc.file
+   get a flag on /mnt/f2fs/vdc.file ret=0, flags=nocow(pinned),immutable
+   # f2fs_io setflags noimmutable /mnt/f2fs/vdc.file
+   get a flag on noimmutable ret=0, flags=800010
+   set a flag on /mnt/f2fs/vdc.file ret=0, flags=noimmutable
+   # rm /mnt/f2fs/vdc.file
+   # df -h
+   /dev/vdb                            64G  753M   64G   2% /mnt/f2fs
 
 So, the key idea is, user can do any file operations on /dev/vdc, and
 reclaim the space after the use, while the space is counted as /data.
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#5 lore raw

PATCH 5/6 Documentation: f2fs: Indent compression_mode option list

In reply to Bagas Sanjaya

Indent description text so that compression_mode numbered list gets rendered as such in htmldocs output.

---
 Documentation/filesystems/f2fs.rst | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)
Documentation/filesystems/f2fs.rst +8 -6
index 0f9472ae62f2cb..146511d63b684e 100644
@@ -922,14 +922,16 @@ compression enabled files (refer to "Compression implementation" section for how
 enable compression on a regular inode).
 
 1) compress_mode=fs
-This is the default option. f2fs does automatic compression in the writeback of the
-compression enabled files.
+
+   This is the default option. f2fs does automatic compression in the writeback of the
+   compression enabled files.
 
 2) compress_mode=user
-This disables the automatic compression and gives the user discretion of choosing the
-target file and the timing. The user can do manual compression/decompression on the
-compression enabled files using F2FS_IOC_DECOMPRESS_FILE and F2FS_IOC_COMPRESS_FILE
-ioctls like the below.
+
+   This disables the automatic compression and gives the user discretion of choosing the
+   target file and the timing. The user can do manual compression/decompression on the
+   compression enabled files using F2FS_IOC_DECOMPRESS_FILE and F2FS_IOC_COMPRESS_FILE
+   ioctls like the below.
 
 To decompress a file::
 
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#6 lore raw

PATCH 6/6 Documentation: f2fs: Reword title

In reply to Bagas Sanjaya

"What is F2FS" is rather a mistitle for the whole f2fs docs, as it implies the overview section (before "Background and design issues" section) and the docs covers beyond that: from mount options to filesystem implementation details.

Retitle and add explicit overview section.

---
 Documentation/filesystems/f2fs.rst | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)
Documentation/filesystems/f2fs.rst +6 -3
index 146511d63b684e..10504f774e1dff 100644
@@ -1,8 +1,11 @@
 .. SPDX-License-Identifier: GPL-2.0
 
-==========================================
-WHAT IS Flash-Friendly File System (F2FS)?
-==========================================
+=================================
+Flash-Friendly File System (F2FS)
+=================================
+
+Overview
+========
 
 NAND flash memory-based storage devices, such as SSD, eMMC, and SD cards, have
 been equipped on a variety systems ranging from mobile to server systems. Since
Signature · 1 line
An old man doll... just what I always wanted! - Clara
maintainer Reviewed-by on the v1 series
#7 lore raw
In reply to Bagas Sanjaya
Quoted 6 lines · Bagas Sanjaya

Hi,

Here are documentation formatting cleanup for f2fs. This also includes docs retitle at the end of series ([6/6]) as a bonus.

This series is based on docs-next tree.

This patchset looks good to me, thanks for your work.

Thanks,

Quoted 16 lines

Enjoy!

Bagas Sanjaya (6):
Documentation: f2fs: Separate errors mode subtable
Documentation: f2fs: Format compression level subtable
Documentation: f2fs: Span write hint table section rows
Documentation: f2fs: Wrap snippets in literal code blocks
Documentation: f2fs: Indent compression_mode option list
Documentation: f2fs: Reword title

 Documentation/filesystems/f2fs.rst | 88 +++++++++++++++++-------------
 1 file changed, 50 insertions(+), 38 deletions(-)

base-commit: 37c52167b007d9d0bb8c5ed53dd6efc4969a1356

maintainer
#8 lore raw
In reply to Bagas Sanjaya
Quoted 17 lines · Bagas Sanjaya

Hi,

Here are documentation formatting cleanup for f2fs. This also includes docs retitle at the end of series ([6/6]) as a bonus.

This series is based on docs-next tree.

Enjoy!

Bagas Sanjaya (6):
Documentation: f2fs: Separate errors mode subtable
Documentation: f2fs: Format compression level subtable
Documentation: f2fs: Span write hint table section rows
Documentation: f2fs: Wrap snippets in literal code blocks
Documentation: f2fs: Indent compression_mode option list
Documentation: f2fs: Reword title

Quoted 2 lines
 Documentation/filesystems/f2fs.rst | 88 +++++++++++++++++-------------
 1 file changed, 50 insertions(+), 38 deletions(-)

Jaegeuk, are you going to pick this up, or would you like me to?

Thanks,

jon

maintainer
#9 lore raw
Quoted 19 lines · Jonathan Corbet
Quoted 17 lines · Bagas Sanjaya

Hi,

Here are documentation formatting cleanup for f2fs. This also includes docs retitle at the end of series ([6/6]) as a bonus.

This series is based on docs-next tree.

Enjoy!

Bagas Sanjaya (6):
Documentation: f2fs: Separate errors mode subtable
Documentation: f2fs: Format compression level subtable
Documentation: f2fs: Span write hint table section rows
Documentation: f2fs: Wrap snippets in literal code blocks
Documentation: f2fs: Indent compression_mode option list
Documentation: f2fs: Reword title

Quoted 4 lines
Quoted 2 lines
 Documentation/filesystems/f2fs.rst | 88 +++++++++++++++++-------------
 1 file changed, 50 insertions(+), 38 deletions(-)

Jaegeuk, are you going to pick this up, or would you like me to?

Hi, I applied them in the f2fs tree, if you don't mind.

Quoted 4 lines

Thanks,

jon

maintainer
#10 lore raw
Quoted 20 lines · Jaegeuk Kim
Quoted 19 lines · Jonathan Corbet
Quoted 17 lines · Bagas Sanjaya

Hi,

Here are documentation formatting cleanup for f2fs. This also includes docs retitle at the end of series ([6/6]) as a bonus.

This series is based on docs-next tree.

Enjoy!

Bagas Sanjaya (6):
Documentation: f2fs: Separate errors mode subtable
Documentation: f2fs: Format compression level subtable
Documentation: f2fs: Span write hint table section rows
Documentation: f2fs: Wrap snippets in literal code blocks
Documentation: f2fs: Indent compression_mode option list
Documentation: f2fs: Reword title

Quoted 6 lines
Quoted 4 lines
Quoted 2 lines
 Documentation/filesystems/f2fs.rst | 88 +++++++++++++++++-------------
 1 file changed, 50 insertions(+), 38 deletions(-)

Jaegeuk, are you going to pick this up, or would you like me to?

Hi, I applied them in the f2fs tree, if you don't mind.

Not at all - thanks for letting me know!

jon

#11 lore raw
In reply to Bagas Sanjaya
This series was applied to jaegeuk/f2fs.git (dev) by Jaegeuk Kim <[email protected]>:

Hello:

This series was applied to jaegeuk/f2fs.git (dev)
by Jaegeuk Kim <[email protected]>:

Quoted 8 lines · On Wed, 20 Aug 2025 11:34:26 +0700 you wrote:

Hi,

Here are documentation formatting cleanup for f2fs. This also includes docs retitle at the end of series ([6/6]) as a bonus.

This series is based on docs-next tree.

[...]

Here is the summary with links:
- [f2fs-dev,1/6] Documentation: f2fs: Separate errors mode subtable

    https://git.kernel.org/jaegeuk/f2fs/c/4bc6bf7b8830
  - [f2fs-dev,2/6] Documentation: f2fs: Format compression level subtable
    https://git.kernel.org/jaegeuk/f2fs/c/f23044152af2
  - [f2fs-dev,3/6] Documentation: f2fs: Span write hint table section rows
    https://git.kernel.org/jaegeuk/f2fs/c/f9c97e496293
  - [f2fs-dev,4/6] Documentation: f2fs: Wrap snippets in literal code blocks
    https://git.kernel.org/jaegeuk/f2fs/c/f4f36fffd872
  - [f2fs-dev,5/6] Documentation: f2fs: Indent compression_mode option list
    https://git.kernel.org/jaegeuk/f2fs/c/e78223268878
  - [f2fs-dev,6/6] Documentation: f2fs: Reword title
    https://git.kernel.org/jaegeuk/f2fs/c/62242ac51061

You are awesome, thank you!

Signature · 2 lines
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html