diff mbox series

[v12,04/10] x86/resctrl: Add comments on RFTYPE flags hierarchy

Message ID 20231010233335.998475-5-babu.moger@amd.com
State New
Headers
Series x86/resctrl: Miscellaneous resctrl features |

Commit Message

Moger, Babu Oct. 10, 2023, 11:33 p.m. UTC 
  resctrl uses RFTYPE flags for creating resctrl directory structure.

Definitions and directory structures are not documented. Add
comments to improve the readability and help future additions.

Signed-off-by: Babu Moger <babu.moger@amd.com>
Tested-by: Peter Newman <peternewman@google.com>
Reviewed-by: Peter Newman <peternewman@google.com>
Tested-by: Tan Shaopeng <tan.shaopeng@jp.fujitsu.com>
Reviewed-by: Tan Shaopeng <tan.shaopeng@jp.fujitsu.com>
Reviewed-by: Fenghua Yu <fenghua.yu@intel.com>
Reviewed-by: Reinette Chatre <reinette.chatre@intel.com>
Reviewed-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
---
v12: Moved the comments from arch/x86/kernel/cpu/resctrl/internal.h
     to Documentation/arch/x86/resctrl.rst. (Boris)
---
 Documentation/arch/x86/resctrl.rst | 60 ++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

Comments

Reinette Chatre Oct. 11, 2023, 12:56 a.m. UTC | #1 
Hi Babu,

On 10/10/2023 4:33 PM, Babu Moger wrote:
> resctrl uses RFTYPE flags for creating resctrl directory structure.
> 
> Definitions and directory structures are not documented. Add
> comments to improve the readability and help future additions.
> 
> Signed-off-by: Babu Moger <babu.moger@amd.com>
> Tested-by: Peter Newman <peternewman@google.com>
> Reviewed-by: Peter Newman <peternewman@google.com>
> Tested-by: Tan Shaopeng <tan.shaopeng@jp.fujitsu.com>
> Reviewed-by: Tan Shaopeng <tan.shaopeng@jp.fujitsu.com>
> Reviewed-by: Fenghua Yu <fenghua.yu@intel.com>
> Reviewed-by: Reinette Chatre <reinette.chatre@intel.com>
> Reviewed-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
> ---
> v12: Moved the comments from arch/x86/kernel/cpu/resctrl/internal.h
>      to Documentation/arch/x86/resctrl.rst. (Boris)
> ---

It seems like you just copied the text to the documentation without
taking into account the destination's use of reST syntax.

I tried a "make htmldocs" to see how this looks but encountered:
docutils.utils.SystemMessage: [snip]/linux/Documentation/arch/x86/resctrl.rst:398: (SEVERE/4) Unexpected section title.

Please remove my Reviewed-by.

Reinette
Moger, Babu Oct. 11, 2023, 4:57 p.m. UTC | #2 
Hi Reinette,

On 10/10/23 19:56, Reinette Chatre wrote:
> Hi Babu,
> 
> On 10/10/2023 4:33 PM, Babu Moger wrote:
>> resctrl uses RFTYPE flags for creating resctrl directory structure.
>>
>> Definitions and directory structures are not documented. Add
>> comments to improve the readability and help future additions.
>>
>> Signed-off-by: Babu Moger <babu.moger@amd.com>
>> Tested-by: Peter Newman <peternewman@google.com>
>> Reviewed-by: Peter Newman <peternewman@google.com>
>> Tested-by: Tan Shaopeng <tan.shaopeng@jp.fujitsu.com>
>> Reviewed-by: Tan Shaopeng <tan.shaopeng@jp.fujitsu.com>
>> Reviewed-by: Fenghua Yu <fenghua.yu@intel.com>
>> Reviewed-by: Reinette Chatre <reinette.chatre@intel.com>
>> Reviewed-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
>> ---
>> v12: Moved the comments from arch/x86/kernel/cpu/resctrl/internal.h
>>      to Documentation/arch/x86/resctrl.rst. (Boris)
>> ---
> 
> It seems like you just copied the text to the documentation without
> taking into account the destination's use of reST syntax.
> 
> I tried a "make htmldocs" to see how this looks but encountered:
> docutils.utils.SystemMessage: [snip]/linux/Documentation/arch/x86/resctrl.rst:398: (SEVERE/4) Unexpected section title.

My bad. Just tested the format by opening using the browser. Forgot about
make htmldocs. Will fix it now.
> 
> Please remove my Reviewed-by.

Sure. Will remove Reviewed-by on this patch. Please let me know about
other patches when you get a chance.
Reinette Chatre Oct. 12, 2023, 4:01 p.m. UTC | #3 
Hi Babu,

On 10/11/2023 9:57 AM, Moger, Babu wrote:
> Sure. Will remove Reviewed-by on this patch. Please let me know about
> other patches when you get a chance.

From what I can tell, apart from moving the flags text to Documentation,
there is only one other code related change and that is just moving the
RFTYPE_MON_BASE definition to a later patch. That looks good to me.

The other changes are all in the commit messages and that mostly looks
good to me ... some issues seemed to have slipped in during this version
and I will point them out in responses to the individual patches.

Reinette
Moger, Babu Oct. 12, 2023, 6:28 p.m. UTC | #4 
Hi Reinette,

On 10/12/23 11:01, Reinette Chatre wrote:
> Hi Babu,
> 
> On 10/11/2023 9:57 AM, Moger, Babu wrote:
>> Sure. Will remove Reviewed-by on this patch. Please let me know about
>> other patches when you get a chance.
> 
> From what I can tell, apart from moving the flags text to Documentation,
> there is only one other code related change and that is just moving the
> RFTYPE_MON_BASE definition to a later patch. That looks good to me.
> 
> The other changes are all in the commit messages and that mostly looks
> good to me ... some issues seemed to have slipped in during this version
> and I will point them out in responses to the individual patches.

Sure. Thanks
Babu Moger
diff mbox series

Patch

diff --git a/Documentation/arch/x86/resctrl.rst b/Documentation/arch/x86/resctrl.rst
index 8154e9975d1e..520a7753d829 100644
--- a/Documentation/arch/x86/resctrl.rst
+++ b/Documentation/arch/x86/resctrl.rst
@@ -362,6 +362,66 @@  When monitoring is enabled all MON groups will also contain:
 	the sum for all tasks in the CTRL_MON group and all tasks in
 	MON groups. Please see example section for more details on usage.
 
+RESCTRL filesystem implementation notes
+=======================================
+RESCTRL filesystem has two main components
+	a. info
+	b. base
+
+/sys/fs/resctrl/
+	|
+	--> info (Top level directory named "info". Contains files that
+	|	  provide details on control and monitoring resources)
+	|
+	--> base (Root directory associated with default resource group
+		  as well as directories created by user for MON and CTRL
+		  groups. Contains files to interact with MON and CTRL
+		  groups)
+
+	Note: resctrl uses flags for files, not for directories.
+	      Directories are created based on the resource type. Added
+	      directories below for better understanding. The RFTYPE flags
+	      are defined in arch/x86/kernel/cpu/resctrl/internal.h.
+
+	info directory structure
+	---------------------------------------------------------------
+	--> RFTYPE_INFO
+	    Directory: info
+	--> RFTYPE_TOP (Files in top level of info directory)
+	    File: last_cmd_status
+
+	--> RFTYPE_MON (Files for all monitoring resources)
+	    Directory: L3_MON
+	        Files: mon_features, num_rmids
+
+		--> RFTYPE_RES_CACHE (Files for cache monitoring resources)
+		    Directory: L3_MON
+		        Files: max_threshold_occupancy,
+		               mbm_total_bytes_config,
+		               mbm_local_bytes_config
+
+	--> RFTYPE_CTRL (Files for all control resources)
+	    Directories: L2, L3, MB, SMBA, L2CODE, L2DATA, L3CODE, L3DATA
+	           File: num_closids
+
+		--> RFTYPE_RES_CACHE (Files for cache control resources)
+		    Directories: L2, L3, L2CODE, L2DATA, L3CODE, L3DATA
+		          Files: bit_usage, cbm_mask, min_cbm_bits,
+		                 shareable_bits
+
+		--> RFTYPE_RES_MB (Files for memory control resources)
+		    Directories: MB, SMBA
+		          Files: bandwidth_gran, delay_linear,
+		                 min_bandwidth, thread_throttle_mode
+
+	base directory structure
+	---------------------------------------------------------------
+	--> RFTYPE_BASE (Files common for both MON and CTRL groups)
+	    Files: cpus, cpus_list, tasks
+
+		--> RFTYPE_CTRL (Files for CTRL group)
+		    Files: mode, schemata, size
+
 Resource allocation rules
 -------------------------