Re: [PATCH v8 21/21] x86,fs/resctrl: Move resctrl.rst to live under Documentation/filesystems

[Reinette Chatre]

Hi James,

On 4/11/25 9:42 AM, James Morse wrote:
> The filesystem code has moved from arch/x86 to fs. Move the documentation
> too.
> 
> Signed-off-by: James Morse <james.morse@xxxxxxx>
> Tested-by: Peter Newman <peternewman@xxxxxxxxxx>
> Tested-by: Shaopeng Tan <tan.shaopeng@xxxxxxxxxxxxxx>
> Tested-by: Amit Singh Tomar <amitsinght@xxxxxxxxxxx> # arm64
> Tested-by: Shanker Donthineni <sdonthineni@xxxxxxxxxx> # arm64
> Tested-by: Babu Moger <babu.moger@xxxxxxx>
> Reviewed-by: Fenghua Yu <fenghuay@xxxxxxxxxx>
> ---
>  Documentation/arch/x86/index.rst                    | 1 -
>  Documentation/filesystems/index.rst                 | 1 +
>  Documentation/{arch/x86 => filesystems}/resctrl.rst | 0
>  MAINTAINERS                                         | 2 +-
>  arch/x86/kernel/cpu/resctrl/monitor.c               | 2 +-
>  fs/resctrl/Kconfig                                  | 2 +-
>  6 files changed, 4 insertions(+), 4 deletions(-)
>  rename Documentation/{arch/x86 => filesystems}/resctrl.rst (100%)
> 
> diff --git a/Documentation/arch/x86/index.rst b/Documentation/arch/x86/index.rst
> index 8ac64d7de4dc..00f9a99689fb 100644
> --- a/Documentation/arch/x86/index.rst
> +++ b/Documentation/arch/x86/index.rst
> @@ -31,7 +31,6 @@ x86-specific Documentation
>     pti
>     mds
>     microcode
> -   resctrl
>     tsx_async_abort
>     buslock
>     usb-legacy-support
> diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
> index a9cf8e950b15..32618512a965 100644
> --- a/Documentation/filesystems/index.rst
> +++ b/Documentation/filesystems/index.rst
> @@ -113,6 +113,7 @@ Documentation for filesystem implementations.
>     qnx6
>     ramfs-rootfs-initramfs
>     relay
> +   resctrl
>     romfs
>     smb/index
>     spufs/index

I built the htmldocs with this change and the filesystem's index.html is quite big
making the resctrl parts not be obvious. The title of the documentation is used as
a heading so the resctrl documentation's heading is "User Interface for Resource
Control feature" that I think makes a text search hard to use since it may not be
obvious to users what to search for.

What do you think of a snippet like below that will include "resctrl" as a term
in the title that should make the documentation easier to find?

---8<---
diff --git a/Documentation/filesystems/resctrl.rst b/Documentation/filesystems/resctrl.rst
index 6768fc1fad16..c7949dd44f2f 100644
--- a/Documentation/filesystems/resctrl.rst
+++ b/Documentation/filesystems/resctrl.rst
@@ -1,9 +1,9 @@
 .. SPDX-License-Identifier: GPL-2.0
 .. include:: <isonum.txt>
 
-===========================================
-User Interface for Resource Control feature
-===========================================
+=====================================================
+User Interface for Resource Control feature (resctrl)
+=====================================================
 
 :Copyright: |copy| 2016 Intel Corporation
 :Authors: - Fenghua Yu <fenghua.yu@xxxxxxxxx>
---8<---

> diff --git a/Documentation/arch/x86/resctrl.rst b/Documentation/filesystems/resctrl.rst
> similarity index 100%
> rename from Documentation/arch/x86/resctrl.rst
> rename to Documentation/filesystems/resctrl.rst
> diff --git a/MAINTAINERS b/MAINTAINERS
> index c30c6fbd1f7a..f7a829898344 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -20281,7 +20281,7 @@ M:	Tony Luck <tony.luck@xxxxxxxxx>
>  M:	Reinette Chatre <reinette.chatre@xxxxxxxxx>
>  L:	linux-kernel@xxxxxxxxxxxxxxx
>  S:	Supported
> -F:	Documentation/arch/x86/resctrl*
> +F:	Documentation/filesystems/resctrl.rst
>  F:	arch/x86/include/asm/resctrl.h
>  F:	arch/x86/kernel/cpu/resctrl/
>  F:	fs/resctrl/

On the topic of MAINTAINERS file ... if this is ok with you I would like to suggest
that you add your name as reviewer to this area with the goal of you being CCed on
any patches that touch any of these files so that you could highlight if anything
impacts Arm.

> diff --git a/arch/x86/kernel/cpu/resctrl/monitor.c b/arch/x86/kernel/cpu/resctrl/monitor.c
> index 182f0514cc88..41af0ed18259 100644
> --- a/arch/x86/kernel/cpu/resctrl/monitor.c
> +++ b/arch/x86/kernel/cpu/resctrl/monitor.c
> @@ -40,7 +40,7 @@ unsigned int rdt_mon_features;
>  static int snc_nodes_per_l3_cache = 1;
>  
>  /*
> - * The correction factor table is documented in Documentation/arch/x86/resctrl.rst.
> + * The correction factor table is documented in Documentation/filesystems/resctrl.rst.
>   * If rmid > rmid threshold, MBM total and local values should be multiplied
>   * by the correction factor.
>   *
> diff --git a/fs/resctrl/Kconfig b/fs/resctrl/Kconfig
> index 478a8e2ad99f..21671301bd8a 100644
> --- a/fs/resctrl/Kconfig
> +++ b/fs/resctrl/Kconfig
> @@ -21,7 +21,7 @@ config RESCTRL_FS
>  	  On architectures where this can be disabled independently, it is
>  	  safe to say N.
>  
> -	  See <file:Documentation/arch/x86/resctrl.rst> for more information.
> +	  See <file:Documentation/filesystems/resctrl.rst> for more information.
>  
>  config RESCTRL_FS_PSEUDO_LOCK
>  	bool

Reinette