Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <c7d563ce-13d9-ca6b-a5c9-7e08a3cdc3a9@intel.com>
Date:   Wed, 11 Jan 2023 14:06:40 -0800
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101
 Firefox/102.0 Thunderbird/102.6.1
Subject: Re: [PATCH v11 13/13] Documentation/x86: Update resctrl.rst for new
 features
Content-Language: en-US
To:     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: <20230109164405.569714-1-babu.moger@amd.com>
 <20230109164405.569714-14-babu.moger@amd.com>
From:   Reinette Chatre <reinette.chatre@intel.com>
In-Reply-To: <20230109164405.569714-14-babu.moger@amd.com>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: 7bit
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?R1NQR21YTFp4SXJ5c2dFMXBvdmpPRWlqYWgvLzlDdTEyK3Ivc1BRdU0wTFg1?=
 =?utf-8?B?VTJrdnFiQTNvb25LK1R4MTREMnNWRjhMUTNlVWJxK1NEdlJuNkxBMWJDL2U4?=
 =?utf-8?B?dG1yVlhTWGFjY3FOMDhCOFZUR0pLR09ZTFJRTDhoZithMTYyOWgxSHQyek55?=
 =?utf-8?B?QkJpc0FTQmFkUVNaZ0tjL2d1Z1JzdU4xeGtJZmlaQWZDU2pUYWJ3N3JCODRl?=
 =?utf-8?B?QXZuMC9WY1VKYk5vRVEvWmZ4VUZOMzhjNUREMGUrUG1aVUhtc3pmMXRhbVJN?=
 =?utf-8?B?U2pWWXV1c1pOTGJIZTlndk02bFZTbFowQ2ZCUGtoZ1o5bnBYQjhsYWViTDBD?=
 =?utf-8?B?ZTRnK2FIdmRsUFYrNXhKMCt5ekJabEdqNENBYTJMRENiaUJGVDhQTkhmSnJT?=
 =?utf-8?B?VjlvS2hzakZiNWtIZTV5YWo3ZWNIVjBHYVhxQmZqK2xQRUFTKzBPaWo4VDVy?=
 =?utf-8?B?dmU3TFZqa0VYbU8rUTI0UURQYnZHSldIUVRUL055Rk01Yk9nZTkxVllIclkx?=
 =?utf-8?B?cmpOQ0ttdzZNL3c5S0RWMUNCVjJueUR2ejlGeTZ5dU9KSWpCSmFEQ3BzREVM?=
 =?utf-8?B?cjZDQy9yUVBqWVFzazNPSUxxNEZnV3ZramVjMDJpSUtOTWd4dUVKV1J2bDBk?=
 =?utf-8?B?TzNnN1JBYVV6SGpIb3FodWxvc09QTG1hYlFGeG1MT2tQdWk0cmtLNE5BTlJK?=
 =?utf-8?B?S291RTRla0xRTVd5VWcrMDJqZkM2NjBSTjNZem54S0dVbHBKcDQwOEhyRERE?=
 =?utf-8?B?VFlVdWlrRy9UNGpoU051ajRVeWZYZXdhbmh3Q3l0d3lHZlFqcmpva1V2R0VE?=
 =?utf-8?B?enFhNndTc3dTdFBMb0VTcVJwYk5pVWU0MVdYWkw2ZFlHRXd5dENHMmtDZGZT?=
 =?utf-8?B?ZWlzSGpDY2dTa0E1MERVTmZZL0Q0RzQySjE3UC9rWjRXVlFKTFNCYWZIalV1?=
 =?utf-8?B?Q2pYdWF3T1ZKaXkxMDFmRDgwbktMOGp6emdUWElNRjRVTUoycXUwNWpFWmdw?=
 =?utf-8?B?cVlxZjFyU2FRNG1ubGZ0cGFJUDdlRXhEeUpXUGhhSG8ycVRHVERkSm00bFda?=
 =?utf-8?B?aEhuTTF3dUFIcjFVSnpPbFlEMmlWa2FSQ3ZDWXRCOEJja291eHRDZllNVEty?=
 =?utf-8?B?WHZHUGowQ1NleVlKalhySUx1bm5RSTVRczhWajVsT08vekhJTExpY2k0TWo1?=
 =?utf-8?B?elkrb0M4R3lieDlSWGJROCtVZ1FwQlgrZnliRE5yMHdlQ2NkNkxCcFFPZVc1?=
 =?utf-8?B?NFJWYUpLVzNaYlZTV0puYk1EVGRSQVhxcjdOY3Z2S3RrRFFuMkRBU0w3ZldD?=
 =?utf-8?B?Mkh4RXFqelJialhRTzZhNng3M1lkSy9Obi90REZuOWtxK1FxdjgyQkg3QWtB?=
 =?utf-8?B?bVlRMmZwdUpQVlhRMGcxaU5QanBKMHVweW9NeEdETjAwMmd1VExXOEhDY2E2?=
 =?utf-8?B?T1NQaDdoczh2S3VGM01GUlFhYnlwd2hwMGdnb3VwUVdaSmVHLzJjeUJqVWNR?=
 =?utf-8?B?a2RHeVZPZWZUOWVndy9lQkJYbEJCMThZdStsVXhLbHBrWUVhbDg2RFZ5UnZv?=
 =?utf-8?B?bWwvai9rcDJGT09RYXc3UUU0djhQeGlqWlhWRzAxV2hGUk1pY0pYOW04VTJV?=
 =?utf-8?B?T2gvOVhWODVvUnplQ2dZVW81bTB0TnZLT0ZCakVHNS9yUmFuRGlSeGtuMGNq?=
 =?utf-8?B?T2ZGZFZxenNBaTNBamN4cERuak5xMjRVY0wwTkhBMVNFTVFxa2tsNzlucXZP?=
 =?utf-8?B?cEQ1T2xqVk0wZzgvODZIWDhTbnRnREU1aUVlS1V5SmxyeDZmNUNuSXpVVytD?=
 =?utf-8?B?bENtdzY3aDBPRkh1amMzd05kYkdWRnJaaTZvYzZra2xJeTZqOHBzSFVJUXZy?=
 =?utf-8?B?dWNGQzZXQU9FaG5wKzZEbjM0NjZkUHhnUUwyVURCY242eWFNbEg0enl2UjE1?=
 =?utf-8?B?WHNzbjZOTHNFZi81L0thQ1h5TFVjM2FXaEdRY01Ub2xRaDcvUW5SK2g2ZlZU?=
 =?utf-8?B?L2hidEwvNXFCQkhQSUN4S3hlZGNxWW1Ia1RoUWh2RSs5QVZ4Ry9XeXkzaytR?=
 =?utf-8?B?U1I1a0t4RmpDcGR2YisvblQwYzExbGxKZ1A0ZFVTVG9zMEUxV25IazdZaldW?=
 =?utf-8?B?dE9GdFlkRlVBS3pFN1dRempIUlEvbWhWSFlGbnFmYVkwc2V1TVFiQWx2VUht?=
 =?utf-8?B?Y0E9PQ==?=
X-MS-Exchange-CrossTenant-Network-Message-Id: 9af573ba-bf92-4b10-ff09-08daf4202053
X-MS-Exchange-CrossTenant-AuthSource: CY4PR11MB1862.namprd11.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 11 Jan 2023 22:06:44.6907
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 46c98d88-e344-4ed4-8496-4ed7712e255d
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: 9LEVQknpxdWupeVWYHaE/8IHS4DV3A1uHIjvhZP9bFcdL3fMRyhS1UhTUd2+of7WXcppLsfmA56eqs1alf+GYuj9kv7yympffthFzHQwHCc=
X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM6PR11MB4706
X-OriginatorOrg: intel.com
X-Spam-Status: No, score=-4.4 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,
        DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,NICE_REPLY_A,
        RCVD_IN_DNSWL_MED,RCVD_IN_MSPIKE_H3,RCVD_IN_MSPIKE_WL,SPF_HELO_NONE,
        SPF_NONE autolearn=ham autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on
        lindbergh.monkeyblade.net
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

Hi Babu,

On 1/9/2023 8:44 AM, Babu Moger wrote:
> Update the documentation for the new features:
> 1. Slow Memory Bandwidth allocation (SMBA).
>    With this feature, the QOS  enforcement policies can be applied
>    to the external slow memory connected to the host. QOS enforcement
>    is accomplished by assigning a Class Of Service (COS) to a processor
>    and specifying allocations or limits for that COS for each resource
>    to be allocated.
> 
> 2. Bandwidth Monitoring Event Configuration (BMEC).
>    The bandwidth monitoring events mbm_total_bytes and mbm_local_bytes
>    are set to count all the total and local reads/writes respectively.
>    With the introduction of slow memory, the two counters are not
>    enough to count all the different types of memory events. With the
>    feature BMEC, the users have the option to configure mbm_total_bytes
>    and mbm_local_bytes to count the specific type of events.
> 
> Also add configuration instructions with examples.
> 
> Signed-off-by: Babu Moger <babu.moger@amd.com>
> ---
>  Documentation/x86/resctrl.rst | 142 +++++++++++++++++++++++++++++++++-
>  1 file changed, 140 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/x86/resctrl.rst b/Documentation/x86/resctrl.rst
> index 71a531061e4e..2860856f4463 100644
> --- a/Documentation/x86/resctrl.rst
> +++ b/Documentation/x86/resctrl.rst
> @@ -17,14 +17,16 @@ AMD refers to this feature as AMD Platform Quality of Service(AMD QoS).
>  This feature is enabled by the CONFIG_X86_CPU_RESCTRL and the x86 /proc/cpuinfo
>  flag bits:
>  
> -=============================================	================================
> +===============================================	================================
>  RDT (Resource Director Technology) Allocation	"rdt_a"
>  CAT (Cache Allocation Technology)		"cat_l3", "cat_l2"
>  CDP (Code and Data Prioritization)		"cdp_l3", "cdp_l2"
>  CQM (Cache QoS Monitoring)			"cqm_llc", "cqm_occup_llc"
>  MBM (Memory Bandwidth Monitoring)		"cqm_mbm_total", "cqm_mbm_local"
>  MBA (Memory Bandwidth Allocation)		"mba"
> -=============================================	================================
> +SMBA (Slow Memory Bandwidth Allocation)         "smba"
> +BMEC (Bandwidth Monitoring Event Configuration) "bmec"
> +===============================================	================================
>  

I expect that you will follow Boris's guidance here and not make these flags visible in
/proc/cpuinfo. That would imply that this addition will have no entries in the second
column. Perhaps this could be made easier to parse by using empty quotes ("") in the second
column to match syntax used in the existing flags as well as the cpufeatures.h change?

If/when making this change, could you please also add a note that documents this new
guidance for other resctrl developers? Something like below but I am looking forward to
improvements:
"Historically new features were made visible by default in /proc/cpuinfo. This resulted
in the flags field becoming hard to parse by humans. Adding a new flag to /proc/cpuinfo
should be avoided if user space can obtain information about the feature from resctrl's
info directory."

The rest of the document looks good to me.

Thank you

Reinette