Re: [PATCH v4 21/63] Documentation: ACPI: move cppc_sysfs.txt to admin-guide/acpi and convert to reST

[Changbin Du]

On Wed, Apr 24, 2019 at 11:48:44AM -0300, Mauro Carvalho Chehab wrote:
> Em Wed, 24 Apr 2019 00:28:50 +0800
> Changbin Du <changbin.du@xxxxxxxxx> escreveu:
> 
> > This converts the plain text documentation to reStructuredText format and
> > add it to Sphinx TOC tree. No essential content change.
> > 
> > Signed-off-by: Changbin Du <changbin.du@xxxxxxxxx>
> > ---
> >  .../acpi/cppc_sysfs.rst}                      | 71 ++++++++++---------
> >  Documentation/admin-guide/acpi/index.rst      |  1 +
> >  2 files changed, 40 insertions(+), 32 deletions(-)
> >  rename Documentation/{acpi/cppc_sysfs.txt => admin-guide/acpi/cppc_sysfs.rst} (51%)
> > 
> > diff --git a/Documentation/acpi/cppc_sysfs.txt b/Documentation/admin-guide/acpi/cppc_sysfs.rst
> > similarity index 51%
> > rename from Documentation/acpi/cppc_sysfs.txt
> > rename to Documentation/admin-guide/acpi/cppc_sysfs.rst
> > index f20fb445135d..a4b99afbe331 100644
> > --- a/Documentation/acpi/cppc_sysfs.txt
> > +++ b/Documentation/admin-guide/acpi/cppc_sysfs.rst
> > @@ -1,5 +1,11 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> >  
> > -	Collaborative Processor Performance Control (CPPC)
> > +==================================================
> > +Collaborative Processor Performance Control (CPPC)
> > +==================================================
> > +
> > +CPPC
> > +====
> >  
> >  CPPC defined in the ACPI spec describes a mechanism for the OS to manage the
> >  performance of a logical processor on a contigious and abstract performance
> > @@ -10,31 +16,28 @@ For more details on CPPC please refer to the ACPI specification at:
> >  
> >  http://uefi.org/specifications
> >  
> > -Some of the CPPC registers are exposed via sysfs under:
> > -
> > -/sys/devices/system/cpu/cpuX/acpi_cppc/
> > -
> 
> 
> > -for each cpu X
> 
> Hmm... removed by mistake?
>
I comfirmed that no content removed.

> > +Some of the CPPC registers are exposed via sysfs under::
> >  
> > ---------------------------------------------------------------------------------
> > +  /sys/devices/system/cpu/cpuX/acpi_cppc/
> 
> Did you parse this with Sphinx? It doesn't sound a valid ReST construction
> to my eyes, as:
> 
> 1) I've seen some versions of Sphinx to abort with severe errors when 
>    there's no blank line after the horizontal bar markup;
> 
> 2) It will very likely ignore the "::" (I didn't test it myself), as you're
>    not indenting the horizontal bar. End of indentation will mean the end
>    of an (empty) literal block.
> 
> So, I would stick with:
> 
> 
> 	Some of the CPPC registers are exposed via sysfs under:
> 
> 	  /sys/devices/system/cpu/cpuX/acpi_cppc/
> 
> 	---------------------------------------------------------------------------------
> 
> 	for each cpu X::
> 
> 
> or:
> 
> 	Some of the CPPC registers are exposed via sysfs under:
> 
> 		/sys/devices/system/cpu/cpuX/acpi_cppc/
> 
> 	for each cpu X
> 
> 	--------------------------------------------------------------------------------
> 
> 	::
> 
> (with is closer to the original author's intent)
> 
> Same applies to the other similar changes on this document.
>
I didn't seen any warning here and the generated html is good. So I think it is
ok.

> >  
> > -$ ls -lR  /sys/devices/system/cpu/cpu0/acpi_cppc/
> > -/sys/devices/system/cpu/cpu0/acpi_cppc/:
> > -total 0
> > --r--r--r-- 1 root root 65536 Mar  5 19:38 feedback_ctrs
> > --r--r--r-- 1 root root 65536 Mar  5 19:38 highest_perf
> > --r--r--r-- 1 root root 65536 Mar  5 19:38 lowest_freq
> > --r--r--r-- 1 root root 65536 Mar  5 19:38 lowest_nonlinear_perf
> > --r--r--r-- 1 root root 65536 Mar  5 19:38 lowest_perf
> > --r--r--r-- 1 root root 65536 Mar  5 19:38 nominal_freq
> > --r--r--r-- 1 root root 65536 Mar  5 19:38 nominal_perf
> > --r--r--r-- 1 root root 65536 Mar  5 19:38 reference_perf
> > --r--r--r-- 1 root root 65536 Mar  5 19:38 wraparound_time
> > +for each cpu X::
> >  
> > ---------------------------------------------------------------------------------
> > +  $ ls -lR  /sys/devices/system/cpu/cpu0/acpi_cppc/
> > +  /sys/devices/system/cpu/cpu0/acpi_cppc/:
> > +  total 0
> > +  -r--r--r-- 1 root root 65536 Mar  5 19:38 feedback_ctrs
> > +  -r--r--r-- 1 root root 65536 Mar  5 19:38 highest_perf
> > +  -r--r--r-- 1 root root 65536 Mar  5 19:38 lowest_freq
> > +  -r--r--r-- 1 root root 65536 Mar  5 19:38 lowest_nonlinear_perf
> > +  -r--r--r-- 1 root root 65536 Mar  5 19:38 lowest_perf
> > +  -r--r--r-- 1 root root 65536 Mar  5 19:38 nominal_freq
> > +  -r--r--r-- 1 root root 65536 Mar  5 19:38 nominal_perf
> > +  -r--r--r-- 1 root root 65536 Mar  5 19:38 reference_perf
> > +  -r--r--r-- 1 root root 65536 Mar  5 19:38 wraparound_time
> >  
> >  * highest_perf : Highest performance of this processor (abstract scale).
> > -* nominal_perf : Highest sustained performance of this processor (abstract scale).
> > +* nominal_perf : Highest sustained performance of this processor
> > +  (abstract scale).
> >  * lowest_nonlinear_perf : Lowest performance of this processor with nonlinear
> >    power savings (abstract scale).
> >  * lowest_perf : Lowest performance of this processor (abstract scale).
> > @@ -48,22 +51,26 @@ total 0
> >  * feedback_ctrs : Includes both Reference and delivered performance counter.
> >    Reference counter ticks up proportional to processor's reference performance.
> >    Delivered counter ticks up proportional to processor's delivered performance.
> > -* wraparound_time: Minimum time for the feedback counters to wraparound (seconds).
> > +* wraparound_time: Minimum time for the feedback counters to wraparound
> > +  (seconds).
> >  * reference_perf : Performance level at which reference performance counter
> >    accumulates (abstract scale).
> >  
> > ---------------------------------------------------------------------------------
> >  
> > -		Computing Average Delivered Performance
> > +Computing Average Delivered Performance
> > +=======================================
> > +
> > +Below describes the steps to compute the average performance delivered by
> > +taking two different snapshots of feedback counters at time T1 and T2.
> > +
> > +  T1: Read feedback_ctrs as fbc_t1
> > +      Wait or run some workload
> >  
> > -Below describes the steps to compute the average performance delivered by taking
> > -two different snapshots of feedback counters at time T1 and T2.
> > +  T2: Read feedback_ctrs as fbc_t2
> >  
> > -T1: Read feedback_ctrs as fbc_t1
> > -    Wait or run some workload
> > -T2: Read feedback_ctrs as fbc_t2
> > +::
> >  
> > -delivered_counter_delta = fbc_t2[del] - fbc_t1[del]
> > -reference_counter_delta = fbc_t2[ref] - fbc_t1[ref]
> > +  delivered_counter_delta = fbc_t2[del] - fbc_t1[del]
> > +  reference_counter_delta = fbc_t2[ref] - fbc_t1[ref]
> >  
> > -delivered_perf = (refernce_perf x delivered_counter_delta) / reference_counter_delta
> > +  delivered_perf = (refernce_perf x delivered_counter_delta) / reference_counter_delta
> > diff --git a/Documentation/admin-guide/acpi/index.rst b/Documentation/admin-guide/acpi/index.rst
> > index d68e9914c5ff..9049a7b9f065 100644
> > --- a/Documentation/admin-guide/acpi/index.rst
> > +++ b/Documentation/admin-guide/acpi/index.rst
> > @@ -10,3 +10,4 @@ the Linux ACPI support.
> >  
> >     initrd_table_override
> >     dsdt-override
> > +   cppc_sysfs
> 
> 
> 
> Thanks,
> Mauro

-- 
Cheers,
Changbin Du