[PATCH] sched/deadline: document behavior of sched_yield()

[PATCH] sched/deadline: document behavior of sched_yield()

[Tommaso Cucinotta]

This is a documentation only patch, explaining the
behavior of sched_yield() when a SCHED_DEADLINE
task calls it (give up remaining runtime and
suspend till next period).
---
 Documentation/scheduler/sched-deadline.txt | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/scheduler/sched-deadline.txt b/Documentation/scheduler/sched-deadline.txt
index 53a2fe1..cb43421 100644
--- a/Documentation/scheduler/sched-deadline.txt
+++ b/Documentation/scheduler/sched-deadline.txt
@@ -16,6 +16,7 @@ CONTENTS
    4.1 System-wide settings
    4.2 Task interface
    4.3 Default behavior
+   4.4 Behavior of sched_yield()
  5. Tasks CPU affinity
    5.1 SCHED_DEADLINE and cpusets HOWTO
  6. Future plans
@@ -426,6 +427,18 @@ CONTENTS
  Finally, notice that in order not to jeopardize the admission control a
  -deadline task cannot fork.
 
+4.4 Behavior of sched_yield()
+-----------------------------
+
+ When a SCHED_DEADLINE task calls sched_yield(), it gives up its
+ remaining runtime and is suspended till the next reservation period,
+ when its runtime will be replenished.  This allows the task to
+ wake-up exactly at the beginning of the next period. Also, this may
+ be useful in the future with bandwidth reclaiming mechanisms, where
+ sched_yield() will make the leftoever runtime available for
+ reclamation by other SCHED_DEADLINE tasks.
+
+
 5. Tasks CPU affinity
 =====================
 
-- 
2.7.4

Re: [PATCH] sched/deadline: document behavior of sched_yield()

[Juri Lelli]

Hi Tommaso,

On 08/09/16 22:09, Tommaso Cucinotta wrote:
> This is a documentation only patch, explaining the
> behavior of sched_yield() when a SCHED_DEADLINE
> task calls it (give up remaining runtime and
> suspend till next period).

I like the patch, but changelog lacks a SoB.

Thanks,

- Juri

> ---
>  Documentation/scheduler/sched-deadline.txt | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
> 
> diff --git a/Documentation/scheduler/sched-deadline.txt b/Documentation/scheduler/sched-deadline.txt
> index 53a2fe1..cb43421 100644
> --- a/Documentation/scheduler/sched-deadline.txt
> +++ b/Documentation/scheduler/sched-deadline.txt
> @@ -16,6 +16,7 @@ CONTENTS
>     4.1 System-wide settings
>     4.2 Task interface
>     4.3 Default behavior
> +   4.4 Behavior of sched_yield()
>   5. Tasks CPU affinity
>     5.1 SCHED_DEADLINE and cpusets HOWTO
>   6. Future plans
> @@ -426,6 +427,18 @@ CONTENTS
>   Finally, notice that in order not to jeopardize the admission control a
>   -deadline task cannot fork.
>  
> +4.4 Behavior of sched_yield()
> +-----------------------------
> +
> + When a SCHED_DEADLINE task calls sched_yield(), it gives up its
> + remaining runtime and is suspended till the next reservation period,
> + when its runtime will be replenished.  This allows the task to
> + wake-up exactly at the beginning of the next period. Also, this may
> + be useful in the future with bandwidth reclaiming mechanisms, where
> + sched_yield() will make the leftoever runtime available for
> + reclamation by other SCHED_DEADLINE tasks.
> +
> +
>  5. Tasks CPU affinity
>  =====================
>  
> -- 
> 2.7.4
> 

[PATCH] sched/deadline: document behavior of sched_yield()

[Tommaso Cucinotta]

Added SoB, as per Juri's comment (thanks).

This is a documentation only patch, explaining the
behavior of sched_yield() when a SCHED_DEADLINE
task calls it (give up remaining runtime and
suspend till next period).

      T.

[PATCH] sched/deadline: document behavior of sched_yield()

[Tommaso Cucinotta]

This is a documentation only patch, explaining the
behavior of sched_yield() when a SCHED_DEADLINE
task calls it (give up remaining runtime and
suspend till next period).

Signed-off-by: Tommaso Cucinotta <tommaso.cucinotta@sssup.it>
Reviewed-by: Juri Lelli <juri.lelli@arm.com>
---
 Documentation/scheduler/sched-deadline.txt | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/scheduler/sched-deadline.txt b/Documentation/scheduler/sched-deadline.txt
index 53a2fe1..cb43421 100644
--- a/Documentation/scheduler/sched-deadline.txt
+++ b/Documentation/scheduler/sched-deadline.txt
@@ -16,6 +16,7 @@ CONTENTS
    4.1 System-wide settings
    4.2 Task interface
    4.3 Default behavior
+   4.4 Behavior of sched_yield()
  5. Tasks CPU affinity
    5.1 SCHED_DEADLINE and cpusets HOWTO
  6. Future plans
@@ -426,6 +427,18 @@ CONTENTS
  Finally, notice that in order not to jeopardize the admission control a
  -deadline task cannot fork.
 
+4.4 Behavior of sched_yield()
+-----------------------------
+
+ When a SCHED_DEADLINE task calls sched_yield(), it gives up its
+ remaining runtime and is suspended till the next reservation period,
+ when its runtime will be replenished.  This allows the task to
+ wake-up exactly at the beginning of the next period. Also, this may
+ be useful in the future with bandwidth reclaiming mechanisms, where
+ sched_yield() will make the leftoever runtime available for
+ reclamation by other SCHED_DEADLINE tasks.
+
+
 5. Tasks CPU affinity
 =====================
 
-- 
2.7.4

Re: [PATCH] sched/deadline: document behavior of sched_yield()

[luca abeni]

Hi Tommaso,


On Fri,  9 Sep 2016 10:44:10 +0200
Tommaso Cucinotta <tommaso.cucinotta@sssup.it> wrote:
[...]
> +4.4 Behavior of sched_yield()
> +-----------------------------
> +
> + When a SCHED_DEADLINE task calls sched_yield(), it gives up its
> + remaining runtime and is suspended till the next reservation period,
Maybe I am nitpicking, but I suspect "until" would be more appropriate
than "till" :)

More seriously: the concept of "reservation period" has not been
defined in the document until now... So, I suspect this sentence should
be rephrased using the concepts and terminology defined in the
document...
Maybe instead of saying that the task is suspended you can say that
since the remaining runtime goes to 0 the task is immediately throttled,
and will be able to execute again only after the time is equal to the
scheduling deadline (as explained in "2. Scheduling algorithm").

Except for this, the patch looks good to me, thanks for documenting
yield()!



			Thanks,
				Luca

			

> + when its runtime will be replenished.  This allows the task to
> + wake-up exactly at the beginning of the next period. Also, this may
> + be useful in the future with bandwidth reclaiming mechanisms, where
> + sched_yield() will make the leftoever runtime available for
> + reclamation by other SCHED_DEADLINE tasks.
> +
> +
>  5. Tasks CPU affinity
>  =====================
>  

Re: [PATCH] sched/deadline: document behavior of sched_yield()

[Daniel Bristot de Oliveira]

On 09/09/2016 07:00 AM, luca abeni wrote:
> Maybe instead of saying that the task is suspended you can say that
> since the remaining runtime goes to 0 the task is immediately throttled,
> and will be able to execute again only after the time is equal to the
> scheduling deadline (as explained in "2. Scheduling algorithm").

well, that is not true anymore. Since:

48be3a6 sched/deadline: Always calculate end of period on sched_yield()

the runtime is zeroed at the replenishment, if dl_se->dl_yielded is set
and runtime > 0.

-- Daniel

Re: [PATCH] sched/deadline: document behavior of sched_yield()

[luca abeni]

On Fri, 9 Sep 2016 09:17:56 -0300
Daniel Bristot de Oliveira <bristot@redhat.com> wrote:

> On 09/09/2016 07:00 AM, luca abeni wrote:
> > Maybe instead of saying that the task is suspended you can say that
> > since the remaining runtime goes to 0 the task is immediately throttled,
> > and will be able to execute again only after the time is equal to the
> > scheduling deadline (as explained in "2. Scheduling algorithm").  
> 
> well, that is not true anymore. Since:
> 
> 48be3a6 sched/deadline: Always calculate end of period on sched_yield()
> 
> the runtime is zeroed at the replenishment, if dl_se->dl_yielded is set
> and runtime > 0.

Ok, but the task is still throttled, right?



			Thanks,
				Luca

Re: [PATCH] sched/deadline: document behavior of sched_yield()

[Daniel Bristot de Oliveira]

On 09/09/2016 09:24 AM, luca abeni wrote:
> Ok, but the task is still throttled, right?

I see your point, but... it is important to keep the documentation sync
with the code, and the code/explanation can be simpler now... :-)

-- Daniel

Re: [PATCH] sched/deadline: document behavior of sched_yield()

[luca abeni]

On Fri, 9 Sep 2016 09:31:56 -0300
Daniel Bristot de Oliveira <bristot@redhat.com> wrote:

> On 09/09/2016 09:24 AM, luca abeni wrote:
> > Ok, but the task is still throttled, right?  
> 
> I see your point, but... it is important to keep the documentation sync
> with the code, and the code/explanation can be simpler now... :-)

I perfectly agree with this...

My main point was that the word "throttled" should probably be used
instead of "blocked", and that the term "reservation period" should
not be used because it has not been defined...
Then, the "since the remaining runtime goes to 0" part of my suggestion
is wrong and the sentence should be rephrased in some other way.

Or am I misunderstanding what you are saying?


			Thanks,
				Luca

Re: [PATCH] sched/deadline: document behavior of sched_yield()

[Daniel Bristot de Oliveira]

On 09/09/2016 09:38 AM, luca abeni wrote:
> Then, the "since the remaining runtime goes to 0" part of my suggestion
> is wrong and the sentence should be rephrased in some other way.
> 
> Or am I misunderstanding what you are saying

Ack, maybe I was not precise enough, sorry... I was just talking about
the "since the remaining runtime goes to 0" part of your suggestion.

-- Daniel

[PATCH] sched/deadline: document behavior of sched_yield()

[Tommaso Cucinotta]

Hi again,

this is the reworked text following the comments by Luca, Juri and Daniel
(thanks everybody), namely:
-) "throttled" instead of "suspended"
-) no more "reservation period" is mentioned -- just "period"

Please, let me know if this sounds better now, thanks!

	T.

[PATCH] sched/deadline: document behavior of sched_yield()

[Tommaso Cucinotta]

This is a documentation only patch, explaining the
behavior of sched_yield() when a SCHED_DEADLINE
task calls it (give up remaining runtime and be
throttled until next period begins).

Signed-off-by: Tommaso Cucinotta <tommaso.cucinotta@sssup.it>
Reviewed-by: Juri Lelli <juri.lelli@arm.com>
Reviewed-by: Luca Abeni <luca.abeni@unitn.it>
Reviewed-by: Daniel Bristot de Oliveira <bristot@redhat.com>
---
 Documentation/scheduler/sched-deadline.txt | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/scheduler/sched-deadline.txt b/Documentation/scheduler/sched-deadline.txt
index 53a2fe1..8e37b0b 100644
--- a/Documentation/scheduler/sched-deadline.txt
+++ b/Documentation/scheduler/sched-deadline.txt
@@ -16,6 +16,7 @@ CONTENTS
    4.1 System-wide settings
    4.2 Task interface
    4.3 Default behavior
+   4.4 Behavior of sched_yield()
  5. Tasks CPU affinity
    5.1 SCHED_DEADLINE and cpusets HOWTO
  6. Future plans
@@ -426,6 +427,23 @@ CONTENTS
  Finally, notice that in order not to jeopardize the admission control a
  -deadline task cannot fork.
 
+
+4.4 Behavior of sched_yield()
+-----------------------------
+
+ When a SCHED_DEADLINE task calls sched_yield(), it gives up its
+ remaining runtime and is immediately throttled, until the next
+ period, when its runtime will be replenished (a special flag
+ dl_yielded is set and used to handle correctly throttling and runtime
+ replenishment after a call to sched_yield()).
+
+ This behavior of sched_yield() allows the task to wake-up exactly at
+ the beginning of the next period. Also, this may be useful in the
+ future with bandwidth reclaiming mechanisms, where sched_yield() will
+ make the leftoever runtime available for reclamation by other
+ SCHED_DEADLINE tasks.
+
+
 5. Tasks CPU affinity
 =====================
 
-- 
2.7.4

[tip:sched/core] sched/deadline: Document behavior of sched_yield()

[tip-bot for Tommaso Cucinotta]

Commit-ID:  b95202a3b6bb8715a716dbdb15cdb82bf622260b
Gitweb:     http://git.kernel.org/tip/b95202a3b6bb8715a716dbdb15cdb82bf622260b
Author:     Tommaso Cucinotta <tommaso.cucinotta@sssup.it>
AuthorDate: Fri, 9 Sep 2016 19:45:17 +0200
Committer:  Ingo Molnar <mingo@kernel.org>
CommitDate: Sat, 10 Sep 2016 11:17:41 +0200

sched/deadline: Document behavior of sched_yield()

This is a documentation only patch, explaining the
behavior of sched_yield() when a SCHED_DEADLINE
task calls it (give up remaining runtime and be
throttled until next period begins).

Signed-off-by: Tommaso Cucinotta <tommaso.cucinotta@sssup.it>
Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>
Reviewed-by: Juri Lelli <juri.lelli@arm.com>
Reviewed-by: Luca Abeni <luca.abeni@unitn.it>
Reviewed-by: Daniel Bristot de Oliveira <bristot@redhat.com>
Cc: Juri Lelli <juri.lelli@gmail.com>
Cc: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: linux-dl@retis.sssup.it
Link: http://lkml.kernel.org/r/1473443117-11794-2-git-send-email-tommaso.cucinotta@sssup.it
Signed-off-by: Ingo Molnar <mingo@kernel.org>
---
 Documentation/scheduler/sched-deadline.txt | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/scheduler/sched-deadline.txt b/Documentation/scheduler/sched-deadline.txt
index 53a2fe1..8e37b0b 100644
--- a/Documentation/scheduler/sched-deadline.txt
+++ b/Documentation/scheduler/sched-deadline.txt
@@ -16,6 +16,7 @@ CONTENTS
    4.1 System-wide settings
    4.2 Task interface
    4.3 Default behavior
+   4.4 Behavior of sched_yield()
  5. Tasks CPU affinity
    5.1 SCHED_DEADLINE and cpusets HOWTO
  6. Future plans
@@ -426,6 +427,23 @@ CONTENTS
  Finally, notice that in order not to jeopardize the admission control a
  -deadline task cannot fork.
 
+
+4.4 Behavior of sched_yield()
+-----------------------------
+
+ When a SCHED_DEADLINE task calls sched_yield(), it gives up its
+ remaining runtime and is immediately throttled, until the next
+ period, when its runtime will be replenished (a special flag
+ dl_yielded is set and used to handle correctly throttling and runtime
+ replenishment after a call to sched_yield()).
+
+ This behavior of sched_yield() allows the task to wake-up exactly at
+ the beginning of the next period. Also, this may be useful in the
+ future with bandwidth reclaiming mechanisms, where sched_yield() will
+ make the leftoever runtime available for reclamation by other
+ SCHED_DEADLINE tasks.
+
+
 5. Tasks CPU affinity
 =====================