Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::3:5 as permitted sender) client-ip=2620:137:e000::3:5;
Message-ID: <0acbb031-a84e-1cbc-0857-f087b07a9056@amd.com>
Date:   Fri, 13 Oct 2023 16:39:23 -0500
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:91.0) Gecko/20100101
 Thunderbird/91.5.0
Reply-To: babu.moger@amd.com
Subject: Re: [PATCH v13 04/10] x86/resctrl: Add comments on RFTYPE flags
 hierarchy
Content-Language: en-US
To:     Reinette Chatre <reinette.chatre@intel.com>,
        Babu Moger <babu.moger@amd.com>, corbet@lwn.net,
        tglx@linutronix.de, mingo@redhat.com, bp@alien8.de
Cc:     fenghua.yu@intel.com, dave.hansen@linux.intel.com, x86@kernel.org,
        hpa@zytor.com, paulmck@kernel.org, akpm@linux-foundation.org,
        quic_neeraju@quicinc.com, rdunlap@infradead.org,
        damien.lemoal@opensource.wdc.com, songmuchun@bytedance.com,
        peterz@infradead.org, jpoimboe@kernel.org, pbonzini@redhat.com,
        chang.seok.bae@intel.com, pawan.kumar.gupta@linux.intel.com,
        jmattson@google.com, daniel.sneddon@linux.intel.com,
        sandipan.das@amd.com, tony.luck@intel.com, james.morse@arm.com,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        bagasdotme@gmail.com, eranian@google.com,
        christophe.leroy@csgroup.eu, jarkko@kernel.org,
        adrian.hunter@intel.com, quic_jiles@quicinc.com,
        peternewman@google.com
References: <20231013202602.2492645-1-babu.moger@amd.com>
 <20231013202602.2492645-5-babu.moger@amd.com>
 <d4a33013-0448-4c36-a168-b3a953024962@intel.com>
From:   "Moger, Babu" <bmoger@amd.com>
In-Reply-To: <d4a33013-0448-4c36-a168-b3a953024962@intel.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?NlRNL0tpN09YMGNKZS9GVUNHMmpLQ3JKN0NKR3daeWltZlIxbjc1Y2dpVmgr?=
 =?utf-8?B?cWVQVTBnQVNzQ0d2ZU1ndWNQcGgvdW0rNEFYeUVHVVMwOVNzS3hFaWEwMkht?=
 =?utf-8?B?YVcxbG05RjYyejlQTnNwNy80RDFudVExVWN1SHdRQ3RiSVdaNEo3NE1kUkJK?=
 =?utf-8?B?TVcxaUlaVkczSmNsQVJyUnpjT21UNGRNM0dncUpsalRHZ3FlcFVHeE5HTzVx?=
 =?utf-8?B?Vm1jdm1zK2x5Y0VlMjlqTzlxWElsNWJGRjVvZTlKbFErU1I0OUNRdFU4Y0tG?=
 =?utf-8?B?dnV2RmdnTmU2RVcwT1dCb0RTcDM2WWUvVDVTTC91dE5vem5QWlc5ZjdUeFU2?=
 =?utf-8?B?TzdWbWhKSXBta2dWS3NnUitMU3BQOFdjVlFFNDBtbjQ0eGtxM1grcFVycHY4?=
 =?utf-8?B?RXlKRTlaOHNZRnNVRkRyUC9HN1VyOFpGQ3phaldFaEs5bGg3djFnQ2xmWlZm?=
 =?utf-8?B?b1huMWp6OGQramw1OTE0aUJFK216RTN2My9nNmMxMzU4VzJhSHIza01nZGY0?=
 =?utf-8?B?dkJKeEg5UlRVUnMyWWlRVVcwWEFlZ0dJaDhja1dJUXIxcHJLcWFmeTR1Zm5Z?=
 =?utf-8?B?bktXRTc2N2tva2VwNzdlUlNlbTM3M21WSy9hVkViWkNJcThTem8xNUZPZE45?=
 =?utf-8?B?RXUrVWtXVTFEZU81R0lMczNsY0pSZjlHeFhma3E5TzJiN1BSTkZiWE5KaGg2?=
 =?utf-8?B?RGlnT2hCN2d0MjZhLzRMYW8rMjNXMnNTMzlWRlhKZXhxRENucUpSeUhRRVpU?=
 =?utf-8?B?YTg3aHVYN2tmN0xuSjZIVWxqdFo3LzN4UXErNFJ1TUFKenBuS1l3ejVNMnVR?=
 =?utf-8?B?M0xGb0Z5dDhFdktaNUpyNzdxM3JjN2k5bWpuL3J6aUNPMHpFcVI0WHJiWnMv?=
 =?utf-8?B?SVc3d3NNVG5xWXBzRXlRZkYycVhhUmZ6MmpRS0dWUVZCM0FZRjdwbnNzbm8w?=
 =?utf-8?B?VC9lTjJ6SkFubjdQZ0lrUkV3OTY3b0REM3JuSVhqRHNuYy9VL2RHNjN6djdn?=
 =?utf-8?B?a3dmb013aklSSWlWTzAwOTlZVEtvYU16Z0xvZnhua2dFUDE3d1AxUldWb2Fz?=
 =?utf-8?B?L1FVSzRYTWlmM2lxL3JSZjBNcWgvNXdyRjZSN3Vra3hIL2NxZER5YW1kUmFk?=
 =?utf-8?B?ZDUyOXJ0NXB3cm9odTJ3S0pDc3RpQnYrVTg5bnorQ09OWmxXTlVoNEMxSlAz?=
 =?utf-8?B?ejVrL05HRUJ6OWVSOHZLYWZwaWErY2Vld0hFWTlHK1dNbGhmNGlKUytpUVI1?=
 =?utf-8?B?TlhGNk4wdFVQTlNzSkUvWFpxNEF3VWR1eUxzOU1QQjNIQnVpRXp5TXJsL3hK?=
 =?utf-8?B?YnZOaEhRQi9IaDFCSVlGaklWcFY0dnExaHhBM2lKTnNYRVFaSzhrZmI2NXUw?=
 =?utf-8?B?MDg2K0ltSlJhdkYyblpOTzg4UHRIbXpVc1ZKUUZkWWlDbGFCaEZINGdMZGZr?=
 =?utf-8?B?eWdHa1JBZXNiMExZVDNRbmlyUzMvaGJDRVJtd1ppQXpLRHV6dVpZS3poUWhC?=
 =?utf-8?B?S0dGdXZFdHJUcmRiN1EyMGFsQWlrUjhQT28zamhoQ05IazdrVTk5dVR2aE44?=
 =?utf-8?B?ZDFiaDV6MGs5b2dHaDVTdUZLTGQwc05oZlhtTWNmNU1UUHNzL0NJbE5Ldlhl?=
 =?utf-8?B?a21Bc3huOU1ZK2kyQUo2alh6dmZKNWphNlNiZktKdW0wZTAybTNSNUVyQmNl?=
 =?utf-8?B?TE1PK2RlS1IzOUxPcmQrSmwvMlVqWURBbG1vakVOZFFzMmlYTCtDQk9uUjQ1?=
 =?utf-8?B?b0N1SVdqbGFoQjc0cE84bWxXTHhmb2hGNVduVUZ2UU5PL2ZiZjhxUnMxVUNB?=
 =?utf-8?B?anNkN0dvS292WUxTczF0LzRQdTlSSkVOdEpDMTRIaFVHUjZiUXNNMTZkT0dQ?=
 =?utf-8?B?OU9OTEQ4dXI3ajlHMDYzVmVaZ3lpcjFVLzc4Z3lZK3BwMFZxY0UzM1l6Mm1u?=
 =?utf-8?B?VHhnZk9BZkZXTEoyWC9hR2tjbzlDcUVqd3NLNXBMRW9pNnBUZHhzVE83U0xx?=
 =?utf-8?B?S0FqNUFYR0NCcTRxOVFzbWgyTkJQZVFmMnpwMFA3VEZkb0l0M3FkQkIvWk5l?=
 =?utf-8?B?SzJRb3N1bmNmSjl1NzhVSmEvQkRGQXNBeWU2bWw3TjhwZFc0WnZwVzcvUWVt?=
 =?utf-8?Q?RLKQPYKyrVx8G3EnHzGoPuijs?=
X-OriginatorOrg: amd.com
X-MS-Exchange-CrossTenant-Network-Message-Id: a8f80eb1-ebea-4210-6090-08dbcc34e133
X-MS-Exchange-CrossTenant-AuthSource: MW3PR12MB4553.namprd12.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 13 Oct 2023 21:39:29.3197
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 3dd8961f-e488-4e60-8e11-a82d994e183d
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: YEskCUpTzwK575BD0CgN23+P1CNuQX8yiTgH4fEOVXXLimmQcAnN+F/zlWauASzo
X-MS-Exchange-Transport-CrossTenantHeadersStamped: CH3PR12MB8481
X-Spam-Status: No, score=-4.2 required=5.0 tests=DKIMWL_WL_HIGH,DKIM_SIGNED,
	DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,
	MAILING_LIST_MULTI,NICE_REPLY_A,SPF_HELO_NONE,SPF_PASS
	autolearn=unavailable autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on groat.vger.email
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org
X-Greylist: Sender passed SPF test, not delayed by milter-greylist-4.6.4 (groat.vger.email [0.0.0.0]); Fri, 13 Oct 2023 14:39:44 -0700 (PDT)

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.


Yes. Messed up again.  Thought fixing the syntax was enough. Will look 
into this.


>
>> +	   (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
>> +
> You removed the separator in order to pass the syntax issue but now there is
> no indication that this is a heading and the content becomes harder to understand.
Yes. I played with this little bit. Dont know how to make this look as 
header. Will check it.
>
>> +	-> 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
>> +
> Same here.

Yes. Will check it.

thanks

Babu