[PATCH 0/3] NFSD IO MODES documentation fixes

[PATCH 0/3] NFSD IO MODES documentation fixes

[Bagas Sanjaya]

Hi,

Here are fixes for NFSD IO modes documentation as reported in linux-next [1].

Enjoy!

[1]: https://lore.kernel.org/linux-next/20251202152506.7a2d2d41@canb.auug.org.au/

Bagas Sanjaya (3):
  NFSD: Add toctree entry for NFSD IO modes docs
  NFSD: nfsd-io-modes: Wrap shell snippets in literal code blocks
  NFSD: nfsd-io-modes: Separate lists

 Documentation/filesystems/nfs/index.rst       |  1 +
 .../filesystems/nfs/nfsd-io-modes.rst         | 33 ++++++++++++-------
 2 files changed, 22 insertions(+), 12 deletions(-)


base-commit: fa8d4e6784d1b6a6eaa3911bac993181631d2856
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 1/3] NFSD: Add toctree entry for NFSD IO modes docs

[Bagas Sanjaya]

Commit fa8d4e6784d1b6 ("NFSD: add
Documentation/filesystems/nfs/nfsd-io-modes.rst") adds documentation for
NFSD I/O modes, but it forgets to add toctree entry for it. Hence,
Sphinx reports:

Documentation/filesystems/nfs/nfsd-io-modes.rst: WARNING: document isn't included in any toctree [toc.not_included]

Add the entry.

Fixes: fa8d4e6784d1b6 ("NFSD: add Documentation/filesystems/nfs/nfsd-io-modes.rst")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Closes: https://lore.kernel.org/linux-next/20251202152506.7a2d2d41@canb.auug.org.au/
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/filesystems/nfs/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/filesystems/nfs/index.rst b/Documentation/filesystems/nfs/index.rst
index 95c2c009874cef..a29a212b5b4df4 100644
--- a/Documentation/filesystems/nfs/index.rst
+++ b/Documentation/filesystems/nfs/index.rst
@@ -13,5 +13,6 @@ NFS
    rpc-cache
    rpc-server-gss
    nfs41-server
+   nfsd-io-modes
    knfsd-stats
    reexport
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 2/3] NFSD: nfsd-io-modes: Wrap shell snippets in literal code blocks

[Bagas Sanjaya]

Sphinx reports htmldocs indentation warnings:

Documentation/filesystems/nfs/nfsd-io-modes.rst:29: ERROR: Unexpected indentation. [docutils]
Documentation/filesystems/nfs/nfsd-io-modes.rst:34: ERROR: Unexpected indentation. [docutils]

Fix these by wrapping shell snippets in literal code blocks.

Fixes: fa8d4e6784d1b6 ("NFSD: add Documentation/filesystems/nfs/nfsd-io-modes.rst")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Closes: https://lore.kernel.org/linux-next/20251202152506.7a2d2d41@canb.auug.org.au/
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 .../filesystems/nfs/nfsd-io-modes.rst         | 28 +++++++++++--------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/Documentation/filesystems/nfs/nfsd-io-modes.rst b/Documentation/filesystems/nfs/nfsd-io-modes.rst
index e3a522d097666b..fa47c4d3dfb95d 100644
--- a/Documentation/filesystems/nfs/nfsd-io-modes.rst
+++ b/Documentation/filesystems/nfs/nfsd-io-modes.rst
@@ -25,12 +25,14 @@ Based on the configured settings, NFSD's IO will either be:
 - not cached stable_how=NFS_UNSTABLE (NFSD_IO_DIRECT=2)
 
 To set an NFSD IO mode, write a supported value (0 - 2) to the
-corresponding IO operation's debugfs interface, e.g.:
+corresponding IO operation's debugfs interface, e.g.::
+
   echo 2 > /sys/kernel/debug/nfsd/io_cache_read
   echo 2 > /sys/kernel/debug/nfsd/io_cache_write
 
 To check which IO mode NFSD is using for READ or WRITE, simply read the
-corresponding IO operation's debugfs interface, e.g.:
+corresponding IO operation's debugfs interface, e.g.::
+
   cat /sys/kernel/debug/nfsd/io_cache_read
   cat /sys/kernel/debug/nfsd/io_cache_write
 
@@ -128,17 +130,19 @@ Tracing:
     misaligned READ to the next DIO-aligned block (on either end of the
     original READ, as needed).
 
-    This combination of trace events is useful for READs:
-    echo 1 > /sys/kernel/tracing/events/nfsd/nfsd_read_vector/enable
-    echo 1 > /sys/kernel/tracing/events/nfsd/nfsd_read_direct/enable
-    echo 1 > /sys/kernel/tracing/events/nfsd/nfsd_read_io_done/enable
-    echo 1 > /sys/kernel/tracing/events/xfs/xfs_file_direct_read/enable
+    This combination of trace events is useful for READs::
+
+      echo 1 > /sys/kernel/tracing/events/nfsd/nfsd_read_vector/enable
+      echo 1 > /sys/kernel/tracing/events/nfsd/nfsd_read_direct/enable
+      echo 1 > /sys/kernel/tracing/events/nfsd/nfsd_read_io_done/enable
+      echo 1 > /sys/kernel/tracing/events/xfs/xfs_file_direct_read/enable
 
     The nfsd_write_direct trace event shows how NFSD splits a given
     misaligned WRITE into a DIO-aligned middle segment.
 
-    This combination of trace events is useful for WRITEs:
-    echo 1 > /sys/kernel/tracing/events/nfsd/nfsd_write_opened/enable
-    echo 1 > /sys/kernel/tracing/events/nfsd/nfsd_write_direct/enable
-    echo 1 > /sys/kernel/tracing/events/nfsd/nfsd_write_io_done/enable
-    echo 1 > /sys/kernel/tracing/events/xfs/xfs_file_direct_write/enable
+    This combination of trace events is useful for WRITEs::
+
+      echo 1 > /sys/kernel/tracing/events/nfsd/nfsd_write_opened/enable
+      echo 1 > /sys/kernel/tracing/events/nfsd/nfsd_write_direct/enable
+      echo 1 > /sys/kernel/tracing/events/nfsd/nfsd_write_io_done/enable
+      echo 1 > /sys/kernel/tracing/events/xfs/xfs_file_direct_write/enable
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 3/3] NFSD: nfsd-io-modes: Separate lists

[Bagas Sanjaya]

Sphinx reports htmldocs indentation warnings:

Documentation/filesystems/nfs/nfsd-io-modes.rst:58: ERROR: Unexpected indentation. [docutils]
Documentation/filesystems/nfs/nfsd-io-modes.rst:59: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]

These caused the lists to be shown as long running paragraphs merged
with their previous paragraphs.

Fix these by separating the lists with a blank line.

Fixes: fa8d4e6784d1b6 ("NFSD: add Documentation/filesystems/nfs/nfsd-io-modes.rst")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Closes: https://lore.kernel.org/linux-next/20251202152506.7a2d2d41@canb.auug.org.au/
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/filesystems/nfs/nfsd-io-modes.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/filesystems/nfs/nfsd-io-modes.rst b/Documentation/filesystems/nfs/nfsd-io-modes.rst
index fa47c4d3dfb95d..0fd6e82478fe6e 100644
--- a/Documentation/filesystems/nfs/nfsd-io-modes.rst
+++ b/Documentation/filesystems/nfs/nfsd-io-modes.rst
@@ -13,6 +13,7 @@ to override that default to use either DONTCACHE or DIRECT IO modes.
 
 Experimental NFSD debugfs interfaces are available to allow the NFSD IO
 mode used for READ and WRITE to be configured independently. See both:
+
 - /sys/kernel/debug/nfsd/io_cache_read
 - /sys/kernel/debug/nfsd/io_cache_write
 
@@ -20,6 +21,7 @@ The default value for both io_cache_read and io_cache_write reflects
 NFSD's default IO mode (which is NFSD_IO_BUFFERED=0).
 
 Based on the configured settings, NFSD's IO will either be:
+
 - cached using page cache (NFSD_IO_BUFFERED=0)
 - cached but removed from page cache on completion (NFSD_IO_DONTCACHE=1)
 - not cached stable_how=NFS_UNSTABLE (NFSD_IO_DIRECT=2)
@@ -56,6 +58,7 @@ because the page cache will eventually become a bottleneck to servicing
 new IO requests.
 
 For more context on DONTCACHE, please see these Linux commit headers:
+
 - Overview:  9ad6344568cc3 ("mm/filemap: change filemap_create_folio()
   to take a struct kiocb")
 - for READ:  8026e49bff9b1 ("mm/filemap: add read support for
@@ -87,7 +90,9 @@ be made.
 The performance win associated with using NFSD DIRECT was previously
 discussed on linux-nfs, see:
 https://lore.kernel.org/linux-nfs/aEslwqa9iMeZjjlV@kernel.org/
+
 But in summary:
+
 - NFSD DIRECT can significantly reduce memory requirements
 - NFSD DIRECT can reduce CPU load by avoiding costly page reclaim work
 - NFSD DIRECT can offer more deterministic IO performance
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 0/3] NFSD IO MODES documentation fixes

[Randy Dunlap]

On 12/2/25 5:09 PM, Bagas Sanjaya wrote:
> Hi,
> 
> Here are fixes for NFSD IO modes documentation as reported in linux-next [1].
> 
> Enjoy!
> 
> [1]: https://lore.kernel.org/linux-next/20251202152506.7a2d2d41@canb.auug.org.au/
> 
> Bagas Sanjaya (3):
>   NFSD: Add toctree entry for NFSD IO modes docs
>   NFSD: nfsd-io-modes: Wrap shell snippets in literal code blocks
>   NFSD: nfsd-io-modes: Separate lists
> 
>  Documentation/filesystems/nfs/index.rst       |  1 +
>  .../filesystems/nfs/nfsd-io-modes.rst         | 33 ++++++++++++-------
>  2 files changed, 22 insertions(+), 12 deletions(-)
> 
> 
> base-commit: fa8d4e6784d1b6a6eaa3911bac993181631d2856

for all 3 patches:

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.
-- 
~Randy

Re: [PATCH 0/3] NFSD IO MODES documentation fixes

[Jeff Layton]

On Wed, 2025-12-03 at 08:09 +0700, Bagas Sanjaya wrote:
> Hi,
> 
> Here are fixes for NFSD IO modes documentation as reported in linux-next [1].
> 
> Enjoy!
> 
> [1]: https://lore.kernel.org/linux-next/20251202152506.7a2d2d41@canb.auug.org.au/
> 
> Bagas Sanjaya (3):
>   NFSD: Add toctree entry for NFSD IO modes docs
>   NFSD: nfsd-io-modes: Wrap shell snippets in literal code blocks
>   NFSD: nfsd-io-modes: Separate lists
> 
>  Documentation/filesystems/nfs/index.rst       |  1 +
>  .../filesystems/nfs/nfsd-io-modes.rst         | 33 ++++++++++++-------
>  2 files changed, 22 insertions(+), 12 deletions(-)
> 
> 
> base-commit: fa8d4e6784d1b6a6eaa3911bac993181631d2856

Reviewed-by: Jeff Layton <jlayton@kernel.org>

Re: [PATCH 0/3] NFSD IO MODES documentation fixes

[Chuck Lever]

From: Chuck Lever <chuck.lever@oracle.com>

On Wed, 03 Dec 2025 08:09:08 +0700, Bagas Sanjaya wrote:
> Here are fixes for NFSD IO modes documentation as reported in linux-next [1].
> 
> Enjoy!
> 
> [1]: https://lore.kernel.org/linux-next/20251202152506.7a2d2d41@canb.auug.org.au/
> 
> Bagas Sanjaya (3):
>   NFSD: Add toctree entry for NFSD IO modes docs
>   NFSD: nfsd-io-modes: Wrap shell snippets in literal code blocks
>   NFSD: nfsd-io-modes: Separate lists
> 
> [...]

Applied to nfsd-next, thanks!

[1/3] NFSD: Add toctree entry for NFSD IO modes docs
      commit: 21478b6ecaa443ee5a89ae744559583ffbe50f30
[2/3] NFSD: nfsd-io-modes: Wrap shell snippets in literal code blocks
      commit: 4fcf9952fb3137c64e32edb5fcd03da6febe4724
[3/3] NFSD: nfsd-io-modes: Separate lists
      commit: df8c841dd92a7f262ad4fa649aa493b181e02812

--
Chuck Lever