Re: [PATCH v3 4/4] docs: add document to introduce CDP command

[Chao Peng <chao.p.peng@linux.intel.com>]

On Mon, Sep 14, 2015 at 11:27:07AM +0800, He Chen wrote:
> Add new CDP option with CAT commands in xl interface man page.
                   ^s to
> Add description of CDP in xl-psr.markdown.
> 
> Signed-off-by: He Chen <he.chen@linux.intel.com>
> ---
>  docs/man/xl.pod.1         | 14 ++++++++++++++
>  docs/misc/xl-psr.markdown | 42 +++++++++++++++++++++++++++++++++++++-----
>  2 files changed, 51 insertions(+), 5 deletions(-)
> 
> diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1
> index f22c3f3..3801039 100644
> --- a/docs/man/xl.pod.1
> +++ b/docs/man/xl.pod.1
> @@ -1530,6 +1530,12 @@ applications. In the Xen implementation, CAT is used to control cache allocation
>  on VM basis. To enforce cache on a specific domain, just set capacity bitmasks
>  (CBM) for the domain.
>  
> +Intel Broadwell and later server platforms also offer Code/Data Prioritization
> +(CDP) for cache allocation, which support specify code or data cache for
                                                    ^ing
> +applications. CDP is used on VM basis in the Xen implementation. To specify
> +code or data CBM for the domain, CDP feature must be enabled and CBM type
> +options need to be specified when setting CBM.
> +
>  =over 4
>  
>  =item B<psr-cat-cbm-set> [I<OPTIONS>] I<domain-id> I<cbm>
> @@ -1545,6 +1551,14 @@ B<OPTIONS>
>  
>  Specify the socket to process, otherwise all sockets are processed.
>  
> +=item B<-c>, B<--code>
> +
> +Set code CBM with CDP enabled.
               ^when CDP is enabled.
> +
> +=item B<-d>, B<--data>
> +
> +Set data CBM with CDP enabled.
Ditto.

> +
>  =back
>  
>  =item B<psr-cat-show> [I<domain-id>]
> diff --git a/docs/misc/xl-psr.markdown b/docs/misc/xl-psr.markdown
> index 3545912..538ea60 100644
> --- a/docs/misc/xl-psr.markdown
> +++ b/docs/misc/xl-psr.markdown
> @@ -14,7 +14,7 @@ tracks cache utilization of memory accesses according to the RMID and reports
>  monitored data via a counter register.
>  
>  For more detailed information please refer to Intel SDM chapter
> -"17.14 - Platform Shared Resource Monitoring: Cache Monitoring Technology".
> +"17.15 - Platform Shared Resource Monitoring: Cache Monitoring Technology".
>  
>  In Xen's implementation, each domain in the system can be assigned a RMID
>  independently, while RMID=0 is reserved for monitoring domains that don't
> @@ -91,17 +91,42 @@ For example, assuming a system with 8 portions and 3 domains:
>     first domain exclusive access to half the cache, and the other two exclusive
>     access to one quarter each.
>  
> -For more detailed information please refer to Intel SDM chapter
> -"17.15 - Platform Shared Resource Control: Cache Allocation Technology".
> -
>  In Xen's implementation, CBM can be configured with libxl/xl interfaces but
>  COS is maintained in hypervisor only. The cache partition granularity is per
>  domain, each domain has COS=0 assigned by default, the corresponding CBM is
>  all-ones, which means all the cache resource can be used by default.
>  
> +Code/Data Prioritization (CDP) Technology is an extension of CAT, which is
> +available on Intel Broadwell and later server platforms. CDP enables isolation
> +and separate prioritization of code and data fetches to the L3 cache in a
> +software configurable manner, which can enable workload prioritization and
> +tuning of cache capacity to the characteristics of the workload. CDP extends
> +Cache Allocation Technology (CAT) by providing separate code and data masks
> +per Class of Service (COS).
> +
> +CDP is disabled on the processor by default. If the CAT MSRs are used without
> +enabling CDP, the processor operates in a traditional CAT-only mode.

The last sentence can be ommited I think. You can however add such
sentence:

It can be enabled by adding 'cdp=1' to Xen bootline.

> +
> +When CDP is enabled,
> +
> + * the CAT mask MSRs are re-mapped into interleaved pairs of mask MSRs for
> +   data or code fetches.
> +
> + * the range of COS for CAT is re-indexed, with the lower-half of the COS
> +   range available for CDP.
> +
> +CDP allows OS or Hypervisor to partition cache allocation more fine-grained,
> +code cache and data cache can be specified respectively. With CDP enabled,
> +one COS corresponds to two CBMs (code CBM & data CBM), which means the number
> +of available COS will reduce to half when CDP is on.

This paragraph can be improved somehow.

> +
> +For more detailed information please refer to Intel SDM chapter
> +"17.16 - Platform Shared Resource Control: Cache Allocation Technology".
> +
>  ### xl interfaces
>  
> -System CAT information such as maximum COS and CBM length can be obtained by:
> +System CAT information such as maximum COS, CBM length and CDP status can be
> +obtained by:
>  
>  `xl psr-hwinfo --cat`
>  
> @@ -119,6 +144,13 @@ A cbm is valid only when:
>  In a multi-socket system, the same cbm will be set on each socket by default.
>  Per socket cbm can be specified with the `--socket SOCKET` option.
>  
> +To specify code CBM for the domain, `-c` or `--code` option is needed.
> +
> +To specify data CBM for the domain, `-d` or `--data` option is needed.
> +
> +If neither `-c` nor `-d` option is specified when CDP is on, the same code CBM
> +and data CBM will be set for the domain.
> +

I guess you can move these staff to the end of description for valid cbm,
right before "In a multi-socket system". And indicate they are OPTIONS.

Chao