Re: [PATCH v13 04/10] x86/resctrl: Add comments on RFTYPE flags hierarchy

["Moger, Babu" <bmoger@amd.com>]

[-- Attachment #1: Type: text/plain, Size: 6433 bytes --]

Hi Reinette,

On 10/13/2023 4:39 PM, Moger, Babu wrote:
> Hi Reinette,
>
> On 10/13/2023 4:23 PM, Reinette Chatre wrote:
>> Hi Babu,
>>
>> On 10/13/2023 1:25 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>
>>> ---
>>> v13: Fixed the format issues in the documentation. Needed few minor 
>>> format
>>>       changes to address the syntax issues.(Reinette)
>>>       Removed "Reviewed-by and Tested-by" flags as the patch has 
>>> changed.
>>>
>>> v12: Moved the comments from arch/x86/kernel/cpu/resctrl/internal.h
>>>       to Documentation/arch/x86/resctrl.rst. (Boris)
>>> ---
>>>   Documentation/arch/x86/resctrl.rst | 64 
>>> ++++++++++++++++++++++++++++++
>>>   1 file changed, 64 insertions(+)
>>>
>>> diff --git a/Documentation/arch/x86/resctrl.rst 
>>> b/Documentation/arch/x86/resctrl.rst
>>> index 178ab1d8f747..1163da74f734 100644
>>> --- a/Documentation/arch/x86/resctrl.rst
>>> +++ b/Documentation/arch/x86/resctrl.rst
>>> @@ -369,6 +369,70 @@ 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
>>> +
>> Could you please do a "make htmldocs" and then ensure that the output 
>> looks sane?
>> The resulting output does not look right to me. For example, the 
>> above turns into
>> a single line that looks like:
>>
>> /sys/fs/resctrl/ | -> info | | (Top level directory named "info". 
>> Contains files that | provide details on control and monitoring 
>> resources") | -> base
>>
>>
>> The spacing also looks off when viewing this in html.
>
I have fixed the all the format issues. Please let me know if it looks 
ok. I will send the final version after that.

Attached the patch and also added the diff inline.

Thanks

diff --git a/Documentation/arch/x86/resctrl.rst 
b/Documentation/arch/x86/resctrl.rst
index 178ab1d8f747..e990272e9a4f 100644
--- a/Documentation/arch/x86/resctrl.rst
+++ b/Documentation/arch/x86/resctrl.rst
@@ -396,6 +396,67 @@ Resource monitoring rules
  3) Otherwise RDT events for the task will be reported in the root level
     "mon_data" group.

+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 the 
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

  Notes on cache occupancy monitoring and control
  ===============================================


[-- Attachment #2: patch4-10 --]
[-- Type: text/plain, Size: 3346 bytes --]

commit 6fc3d73890386c18b69568444411ac9763391752
Author: Babu Moger <babu.moger@amd.com>
Date:   Fri Oct 13 10:45:13 2023 -0500

    x86/resctrl: Add comments on RFTYPE flags hierarchy
    
    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>
    ---
    v13: Fixed the format issues in the documentation. Needed few minor format
         changes to address the syntax issues.(Reinette)
         Removed "Reviewed-by and Tested-by" flags as the patch has changed.
    
    v12: Moved the comments from arch/x86/kernel/cpu/resctrl/internal.h
         to Documentation/arch/x86/resctrl.rst. (Boris)

diff --git a/Documentation/arch/x86/resctrl.rst b/Documentation/arch/x86/resctrl.rst
index 178ab1d8f747..e990272e9a4f 100644
--- a/Documentation/arch/x86/resctrl.rst
+++ b/Documentation/arch/x86/resctrl.rst
@@ -396,6 +396,67 @@ Resource monitoring rules
 3) Otherwise RDT events for the task will be reported in the root level
    "mon_data" group.
 
+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 the 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
 
 Notes on cache occupancy monitoring and control
 ===============================================