Re: [PATCH 20/33] docs: ABI: testing: make the files compatible with ReST output
On Wed, Oct 28, 2020 at 03:23:18PM +0100, Mauro Carvalho Chehab wrote: > From: Mauro Carvalho Chehab > > Some files over there won't parse well by Sphinx. > [..snip..] > diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu > b/Documentation/ABI/testing/sysfs-devices-system-cpu > index b555df825447..274c337ec6a9 100644 > --- a/Documentation/ABI/testing/sysfs-devices-system-cpu > +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu > @@ -151,23 +151,28 @@ Description: > The processor idle states which are available for use have the > following attributes: > > - name: (RO) Name of the idle state (string). > + = > + name:(RO) Name of the idle state (string). > > latency: (RO) The latency to exit out of this idle state (in > - microseconds). > + microseconds). > > - power: (RO) The power consumed while in this idle state (in > - milliwatts). > + power: (RO) The power consumed while in this idle state (in > + milliwatts). > > - time: (RO) The total time spent in this idle state (in > microseconds). > + time:(RO) The total time spent in this idle state > + (in microseconds). > > - usage: (RO) Number of times this state was entered (a count). > + usage: (RO) Number of times this state was entered (a count). > > - above: (RO) Number of times this state was entered, but the > -observed CPU idle duration was too short for it (a > count). > + above: (RO) Number of times this state was entered, but the > + observed CPU idle duration was too short for it > + (a count). > > - below: (RO) Number of times this state was entered, but the > -observed CPU idle duration was too long for it (a count). > + below: (RO) Number of times this state was entered, but the > + observed CPU idle duration was too long for it > + (a count). > + = > > What:/sys/devices/system/cpu/cpuX/cpuidle/stateN/desc > Date:February 2008 > @@ -290,6 +295,7 @@ Description: Processor frequency boosting control > This switch controls the boost setting for the whole system. > Boosting allows the CPU and the firmware to run at a frequency > beyound it's nominal limit. > + > More details can be found in > Documentation/admin-guide/pm/cpufreq.rst > The changes to cpuidle states look good to me. [..snip..] > @@ -414,30 +434,30 @@ Description:POWERNV CPUFreq driver's frequency > throttle stats directory and > throttle attributes exported in the 'throttle_stats' directory: > > - turbo_stat : This file gives the total number of times the max > - frequency is throttled to lower frequency in turbo (at and above > - nominal frequency) range of frequencies. > + frequency is throttled to lower frequency in turbo (at and > above > + nominal frequency) range of frequencies. > > - sub_turbo_stat : This file gives the total number of times the > - max frequency is throttled to lower frequency in sub-turbo(below > - nominal frequency) range of frequencies. > + max frequency is throttled to lower frequency in > sub-turbo(below > + nominal frequency) range of frequencies. > > - unthrottle : This file gives the total number of times the max > - frequency is unthrottled after being throttled. > + frequency is unthrottled after being throttled. > > - powercap : This file gives the total number of times the max > - frequency is throttled due to 'Power Capping'. > + frequency is throttled due to 'Power Capping'. > > - overtemp : This file gives the total number of times the max > - frequency is throttled due to 'CPU Over Temperature'. > + frequency is throttled due to 'CPU Over Temperature'. > > - supply_fault : This file gives the total number of times the > - max frequency is throttled due to 'Power Supply Failure'. > + max frequency is throttled due to 'Power Supply Failure'. > > - overcurrent : This file gives the total number of times the > - max frequency is throttled due to 'Overcurrent'. > + max frequency is throttled due to 'Overcurrent'. > > - occ_reset : This file gives the
Re: [PATCH 20/33] docs: ABI: testing: make the files compatible with ReST output
Em Thu, 29 Oct 2020 14:49:12 + Jonathan Cameron escreveu: > On Wed, 28 Oct 2020 15:23:18 +0100 > Mauro Carvalho Chehab wrote: > > > From: Mauro Carvalho Chehab > > > > Some files over there won't parse well by Sphinx. > > > > Fix them. > > > > Signed-off-by: Mauro Carvalho Chehab > > Signed-off-by: Mauro Carvalho Chehab > > Query below... I'm going to guess a rebase issue? Yes. I sent this series about 1,5 years ago. On that time, it ended by not being merged, as there were too much docs patches floating around. The second SoB is not there on my tree. It was added by git send-email ;-) Anyway, fixed. Thanks, Mauro
Re: [PATCH 20/33] docs: ABI: testing: make the files compatible with ReST output
On Wed, 28 Oct 2020 15:23:18 +0100 Mauro Carvalho Chehab wrote: > From: Mauro Carvalho Chehab > > Some files over there won't parse well by Sphinx. > > Fix them. > > Signed-off-by: Mauro Carvalho Chehab > Signed-off-by: Mauro Carvalho Chehab Query below... I'm going to guess a rebase issue? Other than that Acked-by: Jonathan Cameron # for IIO > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 > b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 > index b7259234ad70..a10a4de3e5fe 100644 > --- a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 > +++ b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 > @@ -3,67 +3,85 @@ KernelVersion: 4.11 > Contact: benjamin.gaign...@st.com > Description: > Reading returns the list possible master modes which are: > - - "reset" : The UG bit from the TIMx_EGR register is > + > + > + - "reset" > + The UG bit from the TIMx_EGR register is > used as trigger output (TRGO). > - - "enable": The Counter Enable signal CNT_EN is used > + - "enable" > + The Counter Enable signal CNT_EN is used > as trigger output. > - - "update": The update event is selected as trigger output. > + - "update" > + The update event is selected as trigger output. > For instance a master timer can then be used > as a prescaler for a slave timer. > - - "compare_pulse" : The trigger output send a positive pulse > - when the CC1IF flag is to be set. > - - "OC1REF": OC1REF signal is used as trigger output. > - - "OC2REF": OC2REF signal is used as trigger output. > - - "OC3REF": OC3REF signal is used as trigger output. > - - "OC4REF": OC4REF signal is used as trigger output. > + - "compare_pulse" > + The trigger output send a positive pulse > + when the CC1IF flag is to be set. > + - "OC1REF" > + OC1REF signal is used as trigger output. > + - "OC2REF" > + OC2REF signal is used as trigger output. > + - "OC3REF" > + OC3REF signal is used as trigger output. > + - "OC4REF" > + OC4REF signal is used as trigger output. > + > Additional modes (on TRGO2 only): > - - "OC5REF": OC5REF signal is used as trigger output. > - - "OC6REF": OC6REF signal is used as trigger output. > + > + - "OC5REF" > + OC5REF signal is used as trigger output. > + - "OC6REF" > + OC6REF signal is used as trigger output. > - "compare_pulse_OC4REF": > - OC4REF rising or falling edges generate pulses. > + OC4REF rising or falling edges generate pulses. > - "compare_pulse_OC6REF": > - OC6REF rising or falling edges generate pulses. > + OC6REF rising or falling edges generate pulses. > - "compare_pulse_OC4REF_r_or_OC6REF_r": > - OC4REF or OC6REF rising edges generate pulses. > + OC4REF or OC6REF rising edges generate pulses. > - "compare_pulse_OC4REF_r_or_OC6REF_f": > - OC4REF rising or OC6REF falling edges generate pulses. > + OC4REF rising or OC6REF falling edges generate > + pulses. > - "compare_pulse_OC5REF_r_or_OC6REF_r": > - OC5REF or OC6REF rising edges generate pulses. > + OC5REF or OC6REF rising edges generate pulses. > - "compare_pulse_OC5REF_r_or_OC6REF_f": > - OC5REF rising or OC6REF falling edges generate pulses. > + OC5REF rising or OC6REF falling edges generate > + pulses. > > - +---+ +-++-+ > - | Prescaler +-> | Counter |+-> | Master | TRGO(2) > - +---+ +--++-+|-> | Control +--> > -|| || +-+ > - +--v+-+ OCxREF || +-+ > - | Chx compare +--> | Output | ChX > - +---+-+ | | Control +--> > - . | | +-+ > - . | |. > - +---
Re: [PATCH 20/33] docs: ABI: testing: make the files compatible with ReST output
Hi Richard,
Em Wed, 28 Oct 2020 10:44:27 -0700
Richard Cochran escreveu:
> On Wed, Oct 28, 2020 at 03:23:18PM +0100, Mauro Carvalho Chehab wrote:
>
> > diff --git a/Documentation/ABI/testing/sysfs-uevent
> > b/Documentation/ABI/testing/sysfs-uevent
> > index aa39f8d7bcdf..d0893dad3f38 100644
> > --- a/Documentation/ABI/testing/sysfs-uevent
> > +++ b/Documentation/ABI/testing/sysfs-uevent
> > @@ -19,7 +19,8 @@ Description:
> > a transaction identifier so it's possible to use the same
> > UUID
> > value for one or more synthetic uevents in which case we
> > logically group these uevents together for any userspace
> > -listeners. The UUID value appears in uevent as
> > +listeners. The UUID value appears in uevent as:
>
> I know almost nothing about Sphinx, but why have one colon here ^^^ and ...
Good point. After re-reading the text, this ":" doesn't belong here.
>
> > +
> > "SYNTH_UUID=----"
> > environment
> > variable.
> >
> > @@ -30,18 +31,19 @@ Description:
> > It's possible to define zero or more pairs - each pair is
> > then
> > delimited by a space character ' '. Each pair appears in
> > synthetic uevent as "SYNTH_ARG_KEY=VALUE". That means the
> > KEY
> > -name gains "SYNTH_ARG_" prefix to avoid possible collisions
> > +name gains `SYNTH_ARG_` prefix to avoid possible collisions
> > with existing variables.
> >
> > -Example of valid sequence written to the uevent file:
> > +Example of valid sequence written to the uevent file::
>
> ... two here?
The main issue that this patch wants to solve is here:
This generates synthetic uevent including these variables::
ACTION=add
SYNTH_ARG_A=1
SYNTH_ARG_B=abc
SYNTH_UUID=fe4d7c9d-b8c6-4a70-9ef1-3d8a58d18eed
On Sphinx, consecutive lines with the same indent belongs to the same
paragraph. So, without "::", the above will be displayed on a single line,
which is undesired.
using "::" tells Sphinx to display as-is. It will also place it into a a
box (colored for html output) and using a monospaced font.
The change at the "uevent file:" line was done just for coherency
purposes.
Yet, after re-reading the text, there are other things that are not
coherent. So, I guess the enclosed patch will work better for sys-uevent.
Thanks,
Mauro
docs: ABI: sysfs-uevent: make it compatible with ReST output
- Replace " by ``, in order to use monospaced fonts;
- mark literal blocks as such.
Signed-off-by: Mauro Carvalho Chehab
diff --git a/Documentation/ABI/testing/sysfs-uevent
b/Documentation/ABI/testing/sysfs-uevent
index aa39f8d7bcdf..0b6227706b35 100644
--- a/Documentation/ABI/testing/sysfs-uevent
+++ b/Documentation/ABI/testing/sysfs-uevent
@@ -6,42 +6,46 @@ Description:
Enable passing additional variables for synthetic uevents that
are generated by writing /sys/.../uevent file.
-Recognized extended format is ACTION [UUID [KEY=VALUE ...].
+Recognized extended format is::
-The ACTION is compulsory - it is the name of the uevent action
-("add", "change", "remove"). There is no change compared to
-previous functionality here. The rest of the extended format
-is optional.
+ ACTION [UUID [KEY=VALUE ...]
+
+The ACTION is compulsory - it is the name of the uevent
+action (``add``, ``change``, ``remove``). There is no change
+compared to previous functionality here. The rest of the
+extended format is optional.
You need to pass UUID first before any KEY=VALUE pairs.
-The UUID must be in "----"
+The UUID must be in ``----``
format where 'x' is a hex digit. The UUID is considered to be
a transaction identifier so it's possible to use the same UUID
value for one or more synthetic uevents in which case we
logically group these uevents together for any userspace
listeners. The UUID value appears in uevent as
-"SYNTH_UUID=----" environment
+``SYNTH_UUID=----`` environment
variable.
If UUID is not passed in, the generated synthetic uevent gains
-"SYNTH_UUID=0" environment variable automatically.
+``SYNTH_UUID=0`` environment variable automatically.
The KEY=VALUE pairs can contain alphanumeric char
Re: [PATCH 20/33] docs: ABI: testing: make the files compatible with ReST output
On Wed, Oct 28, 2020 at 03:23:18PM +0100, Mauro Carvalho Chehab wrote: > diff --git a/Documentation/ABI/testing/sysfs-uevent > b/Documentation/ABI/testing/sysfs-uevent > index aa39f8d7bcdf..d0893dad3f38 100644 > --- a/Documentation/ABI/testing/sysfs-uevent > +++ b/Documentation/ABI/testing/sysfs-uevent > @@ -19,7 +19,8 @@ Description: > a transaction identifier so it's possible to use the same > UUID > value for one or more synthetic uevents in which case we > logically group these uevents together for any userspace > -listeners. The UUID value appears in uevent as > +listeners. The UUID value appears in uevent as: I know almost nothing about Sphinx, but why have one colon here ^^^ and ... > + > "SYNTH_UUID=----" environment > variable. > > @@ -30,18 +31,19 @@ Description: > It's possible to define zero or more pairs - each pair is > then > delimited by a space character ' '. Each pair appears in > synthetic uevent as "SYNTH_ARG_KEY=VALUE". That means the KEY > -name gains "SYNTH_ARG_" prefix to avoid possible collisions > +name gains `SYNTH_ARG_` prefix to avoid possible collisions > with existing variables. > > -Example of valid sequence written to the uevent file: > +Example of valid sequence written to the uevent file:: ... two here? Thanks, Richard
