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

From: Mauro Carvalho Chehab
Date: Wed Apr 24 2019 - 10:48:59 EST

Next message: Sasha Levin: "[PATCH AUTOSEL 4.14 32/35] kernel/sysctl.c: fix out-of-bounds access when setting file-max"
Previous message: Sasha Levin: "[PATCH AUTOSEL 4.14 35/35] ARM: iop: don't use using 64-bit DMA masks"
Next in thread: Changbin Du: "Re: [PATCH v4 21/63] Documentation: ACPI: move cppc_sysfs.txt to admin-guide/acpi and convert to reST"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

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?

> +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.

>
> -$ 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

Next message: Sasha Levin: "[PATCH AUTOSEL 4.14 32/35] kernel/sysctl.c: fix out-of-bounds access when setting file-max"
Previous message: Sasha Levin: "[PATCH AUTOSEL 4.14 35/35] ARM: iop: don't use using 64-bit DMA masks"
Next in thread: Changbin Du: "Re: [PATCH v4 21/63] Documentation: ACPI: move cppc_sysfs.txt to admin-guide/acpi and convert to reST"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]