[PATCH v2] docs: scheduler: Convert schedutil.txt to ReST

[PATCH v2] docs: scheduler: Convert schedutil.txt to ReST

[Tang Yizhou]

All other scheduler documents have been converted to *.rst. Let's do
the same for schedutil.txt.

Also fixed some typos.

Signed-off-by: Tang Yizhou <tangyizhou@huawei.com>
---
v2:
Remove unnecessary space-to-tab conversions.

 Documentation/scheduler/index.rst             |  1 +
 .../{schedutil.txt => schedutil.rst}          | 30 +++++++++++--------
 2 files changed, 18 insertions(+), 13 deletions(-)
 rename Documentation/scheduler/{schedutil.txt => schedutil.rst} (92%)

diff --git a/Documentation/scheduler/index.rst b/Documentation/scheduler/index.rst
index 30cca8a37b3b..b430d856056a 100644
--- a/Documentation/scheduler/index.rst
+++ b/Documentation/scheduler/index.rst
@@ -14,6 +14,7 @@ Linux Scheduler
     sched-domains
     sched-capacity
     sched-energy
+    schedutil
     sched-nice-design
     sched-rt-group
     sched-stats
diff --git a/Documentation/scheduler/schedutil.txt b/Documentation/scheduler/schedutil.rst
similarity index 92%
rename from Documentation/scheduler/schedutil.txt
rename to Documentation/scheduler/schedutil.rst
index 78f6b91e2291..32c7d69fc86c 100644
--- a/Documentation/scheduler/schedutil.txt
+++ b/Documentation/scheduler/schedutil.rst
@@ -1,11 +1,15 @@
+=========
+Schedutil
+=========
 
+.. note::
 
-NOTE; all this assumes a linear relation between frequency and work capacity,
-we know this is flawed, but it is the best workable approximation.
+   All this assumes a linear relation between frequency and work capacity,
+   we know this is flawed, but it is the best workable approximation.
 
 
 PELT (Per Entity Load Tracking)
--------------------------------
+===============================
 
 With PELT we track some metrics across the various scheduler entities, from
 individual tasks to task-group slices to CPU runqueues. As the basis for this
@@ -38,8 +42,8 @@ while 'runnable' will increase to reflect the amount of contention.
 For more detail see: kernel/sched/pelt.c
 
 
-Frequency- / CPU Invariance
----------------------------
+Frequency / CPU Invariance
+==========================
 
 Because consuming the CPU for 50% at 1GHz is not the same as consuming the CPU
 for 50% at 2GHz, nor is running 50% on a LITTLE CPU the same as running 50% on
@@ -47,7 +51,7 @@ a big CPU, we allow architectures to scale the time delta with two ratios, one
 Dynamic Voltage and Frequency Scaling (DVFS) ratio and one microarch ratio.
 
 For simple DVFS architectures (where software is in full control) we trivially
-compute the ratio as:
+compute the ratio as::
 
 	    f_cur
   r_dvfs := -----
@@ -55,7 +59,7 @@ compute the ratio as:
 
 For more dynamic systems where the hardware is in control of DVFS we use
 hardware counters (Intel APERF/MPERF, ARMv8.4-AMU) to provide us this ratio.
-For Intel specifically, we use:
+For Intel specifically, we use::
 
 	   APERF
   f_cur := ----- * P0
@@ -87,7 +91,7 @@ For more detail see:
 
 
 UTIL_EST / UTIL_EST_FASTUP
---------------------------
+==========================
 
 Because periodic tasks have their averages decayed while they sleep, even
 though when running their expected utilization will be the same, they suffer a
@@ -106,7 +110,7 @@ For more detail see: kernel/sched/fair.c:util_est_dequeue()
 
 
 UCLAMP
-------
+======
 
 It is possible to set effective u_min and u_max clamps on each CFS or RT task;
 the runqueue keeps an max aggregate of these clamps for all running tasks.
@@ -115,7 +119,7 @@ For more detail see: include/uapi/linux/sched/types.h
 
 
 Schedutil / DVFS
-----------------
+================
 
 Every time the scheduler load tracking is updated (task wakeup, task
 migration, time progression) we call out to schedutil to update the hardware
@@ -123,7 +127,7 @@ DVFS state.
 
 The basis is the CPU runqueue's 'running' metric, which per the above it is
 the frequency invariant utilization estimate of the CPU. From this we compute
-a desired frequency like:
+a desired frequency like::
 
              max( running, util_est );	if UTIL_EST
   u_cfs := { running;			otherwise
@@ -135,7 +139,7 @@ a desired frequency like:
 
   f_des := min( f_max, 1.25 u * f_max )
 
-XXX IO-wait; when the update is due to a task wakeup from IO-completion we
+XXX IO-wait: when the update is due to a task wakeup from IO-completion we
 boost 'u' above.
 
 This frequency is then used to select a P-state/OPP or directly munged into a
@@ -153,7 +157,7 @@ For more information see: kernel/sched/cpufreq_schedutil.c
 
 
 NOTES
------
+=====
 
  - On low-load scenarios, where DVFS is most relevant, the 'running' numbers
    will closely reflect utilization.
-- 
2.17.1

Re: [PATCH v2] docs: scheduler: Convert schedutil.txt to ReST

[Jonathan Corbet]

Tang Yizhou <tangyizhou@huawei.com> writes:

> All other scheduler documents have been converted to *.rst. Let's do
> the same for schedutil.txt.
>
> Also fixed some typos.
>
> Signed-off-by: Tang Yizhou <tangyizhou@huawei.com>
> ---
> v2:
> Remove unnecessary space-to-tab conversions.
>
>  Documentation/scheduler/index.rst             |  1 +
>  .../{schedutil.txt => schedutil.rst}          | 30 +++++++++++--------
>  2 files changed, 18 insertions(+), 13 deletions(-)
>  rename Documentation/scheduler/{schedutil.txt => schedutil.rst} (92%)

I have applied this version.

Thanks,

jon

Re: [PATCH v2] docs: scheduler: Convert schedutil.txt to ReST

[Akira Yokosawa]

Hi Jon,

On Wed, 16 Mar 2022 15:07:10 -0600
Jonathan Corbet <corbet@lwn.net> wrote:
> Tang Yizhou <tangyizhou@huawei.com> writes:
> 
>> All other scheduler documents have been converted to *.rst. Let's do
>> the same for schedutil.txt.
>>
>> Also fixed some typos.
>>
>> Signed-off-by: Tang Yizhou <tangyizhou@huawei.com>
>> ---
>> v2:
>> Remove unnecessary space-to-tab conversions.
>>
>>  Documentation/scheduler/index.rst             |  1 +
>>  .../{schedutil.txt => schedutil.rst}          | 30 +++++++++++--------
>>  2 files changed, 18 insertions(+), 13 deletions(-)
>>  rename Documentation/scheduler/{schedutil.txt => schedutil.rst} (92%)
> 
> I have applied this version.

Jon, I think you missed Peter'z (implied) Nak on this conversion.

Quote from Peter's message [1]:

> As I'm sure you're aware, I'd *love* to convert the whole lot to plain
> text again :-)
> 
> People, throughout the ages, have been able to read plain text, I don't
> see why it should be made more difficult than that.

I'd recommend you to drop this from docs-next for now.
I think this should go through -tip.

I don't want to see another unfortunate removal of doc.
Remember what happened to atomc_opt.txt:

  - conversion [2]
  - addition of alternative plaintext docs [3] (See final words in the changelog.)
  - removal [4]

[1]: https://lore.kernel.org/r/20220312114017.GA6235@worktop.programming.kicks-ass.net
[2]: 326bc876fed4 ("Documentation/atomic_ops.txt: convert to ReST markup")
[3]: 706eeb3e9c6f ("Documentation/locking/atomic: Add documents for new atomic_t APIs")
[4]: f0400a77ebdc ("atomic: Delete obsolete documentation")

        Thanks, Akira
 

> 
> Thanks,
> 
> jon

Re: [PATCH v2] docs: scheduler: Convert schedutil.txt to ReST

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> Hi Jon,
>
> On Wed, 16 Mar 2022 15:07:10 -0600
> Jonathan Corbet <corbet@lwn.net> wrote:
>
>> I have applied this version.
>
> Jon, I think you missed Peter'z (implied) Nak on this conversion.
>
> Quote from Peter's message [1]:
>
>> As I'm sure you're aware, I'd *love* to convert the whole lot to plain
>> text again :-)
>> 
>> People, throughout the ages, have been able to read plain text, I don't
>> see why it should be made more difficult than that.
>
> I'd recommend you to drop this from docs-next for now.
> I think this should go through -tip.

I interpreted Peter's response differently.  I invited him to express
his opposition to *this patch* and he didn't do that.  As we know, Peter
does not suffer from an inability to express his thoughts explicitly and
succinctly; "implied NAK" is not normally his way.

Or are you saying that I should follow his message to the letter and
back out the entire RST conversion? :)

jon

Re: [PATCH v2] docs: scheduler: Convert schedutil.txt to ReST

[Akira Yokosawa]

On Thu, 17 Mar 2022 07:33:56 -0600,
Jonathan Corbet wrote:
> Akira Yokosawa <akiyks@gmail.com> writes:
> 
>> Hi Jon,
>>
>> On Wed, 16 Mar 2022 15:07:10 -0600
>> Jonathan Corbet <corbet@lwn.net> wrote:
>>
>>> I have applied this version.
>>
>> Jon, I think you missed Peter'z (implied) Nak on this conversion.
>>
>> Quote from Peter's message [1]:
>>
>>> As I'm sure you're aware, I'd *love* to convert the whole lot to plain
>>> text again :-)
>>>
>>> People, throughout the ages, have been able to read plain text, I don't
>>> see why it should be made more difficult than that.
>>
>> I'd recommend you to drop this from docs-next for now.
>> I think this should go through -tip.
> 
> I interpreted Peter's response differently.  I invited him to express
> his opposition to *this patch* and he didn't do that.  As we know, Peter
> does not suffer from an inability to express his thoughts explicitly and
> succinctly; "implied NAK" is not normally his way.

I see.  You know Peter much better than I.
Probably my interpretation was too pessimistic. ;-)

> 
> Or are you saying that I should follow his message to the letter and
> back out the entire RST conversion? :)

I know it is _not_ one of the options we can pursue at this stage of
kernel-doc.  It's too late.  Furthermore, If it stayed plaintext,
I could not have any chance of improving PDF docs.  There remains
plenty of rooms!

        Thanks, Akira

> 
> jon