Re: [PATCH 28/31] sched_ext: Add Documentation/scheduler/sched-ext.rst

Re: [PATCH 28/31] sched_ext: Add Documentation/scheduler/sched-ext.rst

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 3535 bytes --]

On Tue, Nov 29, 2022 at 10:23:10PM -1000, Tejun Heo wrote:
> Signed-off-by: Tejun Heo <tj@kernel.org>
> Reviewed-by: David Vernet <dvernet@meta.com>
> Acked-by: Josh Don <joshdon@google.com>
> Acked-by: Hao Luo <haoluo@google.com>
> Acked-by: Barret Rhoden <brho@google.com>

No patch description? Really? Please write one.

For patch subject, better write "Documentation: scheduler: document
extensible scheduler class".

> +* The system integrity is maintained no matter what the BPF scheduler does.
> +  The default scheduling behavior is restored anytime an error is detected,
> +  a runnable task stalls, or on sysrq-S.
> +
> <snipped>...
> +Terminating the sched_ext scheduler program, triggering sysrq-S, or
> +detection of any internal error including stalled runnable tasks aborts the
> +BPF scheduler and reverts all tasks back to CFS.

IMO the reference to SysRq key can be reworded:

---- >8 ----
diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
index a2ad963b227a1b..404b820119b4a4 100644
--- a/Documentation/scheduler/sched-ext.rst
+++ b/Documentation/scheduler/sched-ext.rst
@@ -15,7 +15,8 @@ programs - the BPF scheduler.
 
 * The system integrity is maintained no matter what the BPF scheduler does.
   The default scheduling behavior is restored anytime an error is detected,
-  a runnable task stalls, or on sysrq-S.
+  a runnable task stalls, or on invoking SysRq key sequence like
+  :kbd:`SysRq-s`.
 
 Switching to and from sched_ext
 ===============================
@@ -35,7 +36,7 @@ case, all ``SCHED_NORMAL``, ``SCHED_BATCH``, ``SCHED_IDLE`` and
 ``SCHED_EXT`` tasks are scheduled by sched_ext. In the example schedulers,
 this mode can be selected with the ``-a`` option.
 
-Terminating the sched_ext scheduler program, triggering sysrq-S, or
+Terminating the sched_ext scheduler program, triggering SysRq key, or
 detection of any internal error including stalled runnable tasks aborts the
 BPF scheduler and reverts all tasks back to CFS.
 

> +A task is always *dispatch*ed to a dsq for execution. The task starts
> +execution when a CPU *consume*s the task from the dsq.

Sphinx reported two warnings:

Documentation/scheduler/sched-ext.rst:117: WARNING: Inline emphasis start-string without end-string.
Documentation/scheduler/sched-ext.rst:117: WARNING: Inline emphasis start-string without end-string.

I have to replace with quotes (since "dispatch" and "consume" have different
meaning in this context):

---- >8 ----
diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
index 81f78e05a6c214..a2ad963b227a1b 100644
--- a/Documentation/scheduler/sched-ext.rst
+++ b/Documentation/scheduler/sched-ext.rst
@@ -114,8 +114,8 @@ there is one global FIFO (``SCX_DSQ_GLOBAL``), and one local dsq per CPU
 (``SCX_DSQ_LOCAL``). The BPF scheduler can manage an arbitrary number of
 dsq's using ``scx_bpf_create_dsq()`` and ``scx_bpf_destroy_dsq()``.
 
-A task is always *dispatch*ed to a dsq for execution. The task starts
-execution when a CPU *consume*s the task from the dsq.
+A task is always "dispatched" to a dsq for execution. The task starts
+execution when a CPU "consumes" the task from the dsq.
 
 Internally, a CPU only executes tasks which are running on its local dsq,
 and the ``.consume()`` operation is in fact a transfer of a task from a

Otherwise the doc LGTM.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 28/31] sched_ext: Add Documentation/scheduler/sched-ext.rst

[Tejun Heo]

Hello,

On Mon, Dec 12, 2022 at 11:01:42AM +0700, Bagas Sanjaya wrote:
> On Tue, Nov 29, 2022 at 10:23:10PM -1000, Tejun Heo wrote:
> > Signed-off-by: Tejun Heo <tj@kernel.org>
> > Reviewed-by: David Vernet <dvernet@meta.com>
> > Acked-by: Josh Don <joshdon@google.com>
> > Acked-by: Hao Luo <haoluo@google.com>
> > Acked-by: Barret Rhoden <brho@google.com>
> 
> No patch description? Really? Please write one.

That's unnecessarily grating. I can add some blurb but here's an honest
question. What pertinent information would the description contain that
shouldn't be in the doc itself?

> For patch subject, better write "Documentation: scheduler: document
> extensible scheduler class".

Sounds good.

> ---- >8 ----
> diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
> index a2ad963b227a1b..404b820119b4a4 100644
> --- a/Documentation/scheduler/sched-ext.rst
> +++ b/Documentation/scheduler/sched-ext.rst
> @@ -15,7 +15,8 @@ programs - the BPF scheduler.
>  
>  * The system integrity is maintained no matter what the BPF scheduler does.
>    The default scheduling behavior is restored anytime an error is detected,
> -  a runnable task stalls, or on sysrq-S.
> +  a runnable task stalls, or on invoking SysRq key sequence like
> +  :kbd:`SysRq-s`.
>  
>  Switching to and from sched_ext
>  ===============================
> @@ -35,7 +36,7 @@ case, all ``SCHED_NORMAL``, ``SCHED_BATCH``, ``SCHED_IDLE`` and
>  ``SCHED_EXT`` tasks are scheduled by sched_ext. In the example schedulers,
>  this mode can be selected with the ``-a`` option.
>  
> -Terminating the sched_ext scheduler program, triggering sysrq-S, or
> +Terminating the sched_ext scheduler program, triggering SysRq key, or
>  detection of any internal error including stalled runnable tasks aborts the
>  BPF scheduler and reverts all tasks back to CFS.
>  
> 
> > +A task is always *dispatch*ed to a dsq for execution. The task starts
> > +execution when a CPU *consume*s the task from the dsq.
> 
> Sphinx reported two warnings:
> 
> Documentation/scheduler/sched-ext.rst:117: WARNING: Inline emphasis start-string without end-string.
> Documentation/scheduler/sched-ext.rst:117: WARNING: Inline emphasis start-string without end-string.
> 
> I have to replace with quotes (since "dispatch" and "consume" have different
> meaning in this context):
> 
> ---- >8 ----
> diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
> index 81f78e05a6c214..a2ad963b227a1b 100644
> --- a/Documentation/scheduler/sched-ext.rst
> +++ b/Documentation/scheduler/sched-ext.rst
> @@ -114,8 +114,8 @@ there is one global FIFO (``SCX_DSQ_GLOBAL``), and one local dsq per CPU
>  (``SCX_DSQ_LOCAL``). The BPF scheduler can manage an arbitrary number of
>  dsq's using ``scx_bpf_create_dsq()`` and ``scx_bpf_destroy_dsq()``.
>  
> -A task is always *dispatch*ed to a dsq for execution. The task starts
> -execution when a CPU *consume*s the task from the dsq.
> +A task is always "dispatched" to a dsq for execution. The task starts
> +execution when a CPU "consumes" the task from the dsq.
>  
>  Internally, a CPU only executes tasks which are running on its local dsq,
>  and the ``.consume()`` operation is in fact a transfer of a task from a
> 
> Otherwise the doc LGTM.

Will apply the suggested changes.

Thanks.

-- 
tejun

Re: [PATCH 28/31] sched_ext: Add Documentation/scheduler/sched-ext.rst

[Bagas Sanjaya]

On 12/12/22 13:28, Tejun Heo wrote:
>> No patch description? Really? Please write one.
> 
> That's unnecessarily grating. I can add some blurb but here's an honest
> question. What pertinent information would the description contain that
> shouldn't be in the doc itself?
> 

Sorry I don't know the answer, but the description should at least
expand from the patch subject.

Thanks anyway.

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 28/31] sched_ext: Add Documentation/scheduler/sched-ext.rst

[Tejun Heo]

On Mon, Dec 12, 2022 at 08:07:32PM +0700, Bagas Sanjaya wrote:
> On 12/12/22 13:28, Tejun Heo wrote:
> >> No patch description? Really? Please write one.
> > 
> > That's unnecessarily grating. I can add some blurb but here's an honest
> > question. What pertinent information would the description contain that
> > shouldn't be in the doc itself?
> > 
> 
> Sorry I don't know the answer, but the description should at least
> expand from the patch subject.

Yeah, I can put some filler text. It just feels a bit silly. Not a big deal
at all either way.

Thanks.

-- 
tejun