Re: [PATCH v2 for Xen 4.6 5/6] docs: make xl-psr.markdown more precise

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

On Tue, Sep 29, 2015 at 10:55:40AM +0100, Ian Campbell wrote:
> On Tue, 2015-09-29 at 10:27 +0100, Andrew Cooper wrote:
> > On 29/09/15 08:49, Chao Peng wrote:
> > > Drop the chapter number as it can be confusing when it gets changed in
> > > the referred document.
> > > 
> > > Signed-off-by: Chao Peng <chao.p.peng@linux.intel.com>
> > > Reviewed-by: Dario Faggioli <dario.faggioli@citrix.com>
> > > Acked-by: Wei Liu <wei.liu2@citrix.com>
> > > ---
> > > v2:
> > > * minor commit message adjustment.
> > > ---
> > >  docs/misc/xl-psr.markdown | 8 ++++----
> > >  1 file changed, 4 insertions(+), 4 deletions(-)
> > > 
> > > diff --git a/docs/misc/xl-psr.markdown b/docs/misc/xl-psr.markdown
> > > index 3545912..737f0f7 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".
> > > +"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
> > > @@ -52,7 +52,7 @@ event type to monitor system total/local memory
> > > bandwidth. The same RMID can
> > >  be used to monitor both cache usage and memory bandwidth at the same
> > > time.
> > >  
> > >  For more detailed information please refer to Intel SDM chapter
> > > -"17.14 - Platform Shared Resource Monitoring: Cache Monitoring
> > > Technology".
> > > +"Overview of Cache Monitoring Technology and Memory Bandwidth
> > > Monitoring".
> > >  
> > >  In Xen's implementation, MBM shares the same set of underlying
> > > monitoring
> > >  service with CMT and can be used to monitor memory bandwidth on a per
> > > domain
> > > @@ -92,7 +92,7 @@ For example, assuming a system with 8 portions and 3
> > > domains:
> > >     access to one quarter each.
> > >  
> > >  For more detailed information please refer to Intel SDM chapter
> > > -"17.15 - Platform Shared Resource Control: Cache Allocation
> > > Technology".
> > > +"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
> > > @@ -130,4 +130,4 @@ Per domain CBM settings can be shown by:
> > >  ## Reference
> > >  
> > >  [1] Intel SDM
> > > -(http://www.intel.com/content/www/us/en/processors/architectures-softw
> > > are-developer-manuals.html).
> > > +(http://www.intel.com/content/dam/www/public/us/en/documents/manuals/6
> > > 4-ia-32-architectures-software-developer-system-programming-manual
> > > -325384.pdf).
> > 
> > The other two changes look fine, but this change now points to a
> > specific instance of the SDM, not the most recent version.  I would
> > leave the link as it previously was.
> 
> I agree, we either want a specific revision with specific chapter numbers
> _or_ an up to date revision with just the titles and no specific chapter
> numbers. This commit removes the chapter numbers but switches to a specific
> revision, which is undesirable IMHO.
> 
> I therefore intend to drop this last hunk during commit.

I feel confortable, too. Actually this is a suggestion from Lars during
he reviewing the documents for the 4.6 release. Because when one opens
the generic page he/she will see several options (combined volume set,
three-volume set and seven-volume set), it may be not easy to find out
the related chapters and especially because we have chapter number which
is actually from the three-volume set, in such case it does look a bit
confusing.

As now we have removed the chapter number, then the confusion doesn't
exit because one can grab any volume set and will find the related
chapters. I think this addressed Lars' concern.

Chao