Re: [PATCH v6 3/3] x86/resctrl: Add new "mba_MBps_event" mount option to documentation

[Reinette Chatre]

Hi Tony,

On 12/7/2023 11:56 AM, Tony Luck wrote:
> New mount option may be used to choose a specific memory bandwidth
> monitoring event to feed the MBA Software Controller(mba_sc) feedback
> loop.
> 
> Signed-off-by: Tony Luck <tony.luck@xxxxxxxxx>
> ---
>  Documentation/arch/x86/resctrl.rst | 16 ++++++++++++++--
>  1 file changed, 14 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/arch/x86/resctrl.rst b/Documentation/arch/x86/resctrl.rst
> index a6279df64a9d..a0c521db6786 100644
> --- a/Documentation/arch/x86/resctrl.rst
> +++ b/Documentation/arch/x86/resctrl.rst
> @@ -35,7 +35,8 @@ about the feature from resctrl's info directory.
>  
>  To use the feature mount the file system::
>  
> - # mount -t resctrl resctrl [-o cdp[,cdpl2][,mba_MBps][,debug]] /sys/fs/resctrl
> + # mount -t resctrl resctrl [-o cdp[,cdpl2][,mba_MBps] \
> + [,mba_MBps_event=[mbm_local_bytes|mbm_total_bytes]][,debug]] /sys/fs/resctrl
>  
>  mount options are:
>  
> @@ -45,7 +46,12 @@ mount options are:
>  	Enable code/data prioritization in L2 cache allocations.
>  "mba_MBps":
>  	Enable the MBA Software Controller(mba_sc) to specify MBA
> -	bandwidth in MBps
> +	bandwidth in MBps. Defaults to using MBM local bandwidth,
> +	but will use total bandwidth on systems that do not support
> +	local bandwidth monitoring.

This document is intended as user documentation. With this perspective
I find the above change to have potential for confusion. The first
(original) sentence is clearly aimed at the user, informing that when this
option is enabled bandwidth allocation can be specified in MBps. The
second sentence jumps into kernel internals mentioning bandwidth monitoring
(user may wonder - what does this have to do with allocation?) without any
transition or context.

> +"mba_MBps_event=[mbm_local_bytes|mbm_total_bytes]":
> +	Enable the MBA Software Controller(mba_sc) with a specific
> +	MBM event as input to the feedback loop.

I think it should be made obvious what the relationship between the
mba_MBps and mba_MBps_event mount options are. As it is written the
user may believe that both options are needed. The user is also
left needing to interpret cryptic information regarding kernel internals
- for example, note how "feedback loop" does not occur in this document. 

>  "debug":
>  	Make debug files accessible. Available debug files are annotated with
>  	"Available only with debug option".
> @@ -538,6 +544,12 @@ where as user can switch to the "MBA software controller" mode using
>  a mount option 'mba_MBps'. The schemata format is specified in the below
>  sections.
>  
> +By default the software feedback mechanism uses measurement of local
> +memory bandwidth to make adjustments to throttling levels. If a system
> +is running applications with poor NUMA locality users may want to use
> +the "mba_MBps_event=mbm_total_bytes" mount option which will use total
> +memory bandwidth measurements instead of local.

The paragraph is just appended to existing MBps documentation instead of
integrated with existing content. User is left to parse and connect the
different sections attempting to make sense of it all.

Reinette