sched.7: Add lots of details on SCHED_DEADLINE

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man7/sched.7 b/man7/sched.7
index 9c6665bb0f8e49c30b62fd834c13d567a4f36cab..ffd7147f9d7d387c311fe3a21171d3e0791a878c 100644 (file)
--- a/man7/sched.7
+++ b/man7/sched.7
@@ -194,22 +194,35 @@ retrieved using
 .\" by the process nice value -- MTK
 .\"
 .SS SCHED_DEADLINE: Sporadic task model deadline scheduling
-SCHED_DEADLINE
-is currently implemented using GEDF (Global Earliest Deadline First)
-with additional CBS (Constant Bandwidth Server).
+Since version 3.14, Linux provides a deadline scheduling policy
+.RB ( SCHED_DEADLINE ).
+This policy is currently implemented using
+GEDF (Global Earliest Deadline First)
+in conjunction with CBS (Constant Bandwidth Server).
+To set and fetch this policy and associated attributes,
+one must use the Linux-specific
+.BR sched_setattr (2)
+and
+.BR sched_getattr (2)
+system calls.
 
 A sporadic task is one that has a sequence of jobs, where each
 job is activated at most once per period.
-Each job has also a relative deadline,
+Each job also has a
+.IR "relative deadline" ,
 before which it should finish execution, and a
-computation time, that is the time necessary for executing the
-job without interruption.
-The instant of time when a task wakes up,
-because a new job has to be executed, is called arrival time
-(and it is also referred to as request time or release time).
-Start time is instead the time at which a task starts its execution.
-The absolute deadline is thus obtained adding the
-relative deadline to the arrival time.
+.IR "computation time" ,
+which is the CPU time necessary for executing the job.
+The moment when a task wakes up
+because a new job has to be executed is called the
+.IR "arrival time"
+(also referred to as the request time or release time).
+The
+.IR "start time"
+is the time at which a task starts its execution.
+The
+.I "absolute deadline" 
+is thus obtained by adding the relative deadline to the arrival time.
 
 The following diagram clarifies these terms:
 
@@ -226,16 +239,22 @@ arrival/wakeup                   absolute deadline
 .fi
 .in
 
+When setting a
 .B SCHED_DEADLINE
-allows the user to specify three parameters (see
-.BR sched_setattr (2)):
-Runtime [ns], Deadline [ns] and Period [ns].
-Such parameters has not necessarily to correspond to the
-aforementioned terms, while usual practise is to set Runtime to
-something bigger than the average computation time (or worst-case
-execution time for hard real-time tasks), Deadline to the
-relative deadline and Period to the period of the task.
-With such a setting we would have:
+policy for a thread using
+.BR sched_setattr (2),
+one can specify three parameters:
+.IR Runtime ,
+.IR Deadline ,
+and
+.IR Period .
+These parameters do not necessarily correspond to the aforementioned terms:
+usual practice is to set Runtime to something bigger than the average
+computation time (or worst-case execution time for hard real-time tasks),
+Deadline to the relative deadline, and Period to the period of the task.
+Thus, for
+.BR SCHED_DEADLINE
+scheduling, we have:
 
 .in +4n
 .nf
@@ -250,54 +269,88 @@ arrival/wakeup                   absolute deadline
 .fi
 .in
 
-It is checked that: Runtime <= Deadline <= Period.
+The three deadline-scheduling parameters correspond to the
+.IR sched_runtime ,
+.IR sched_deadline ,
+and
+.IR sched_period
+fields of the
+.I sched_attr
+structure; see
+.BR sched_setattr (2).
+These fields express value in nanoseconds.
+.\" FIXME It looks as though specifying sched_period as 0 means
+.\"       "make sched_period the same as sched_deadline", right?
+.\"       This needs to be documented.
+If
+.IR sched_period
+is specified as 0, then it is made the same as
+.IR sched_deadline .
+
+The kernel requires that:
+
+    sched_runtime <= sched_deadline <= sched_period
+
+.\" See __checkparam_dl in kernel/sched/core.c
+In addition, under the current implementation,
+all of the parameter values must be at least 1024
+(i.e., just over one microsecond,
+which is the resolution of the implementation).
+If any of these checks fails,
+.BR sched_setattr (2)
+fails with the error
+.BR EINVAL .
 
 The CBS guarantees non-interference between tasks, by throttling
-tasks that attempt to over-run their specified Runtime.
+threads that attempt to over-run their specified Runtime.
 
-In general, the set of all
+To ensure deadline scheduling guarantees,
+the kernel must prevent situations where the set of 
 .B SCHED_DEADLINE
-tasks is not feasible/schedulable within the given constraints.
-To guarantee some degree of timeliness, we must do an admittance test on
-setting/changing
+threads is not feasible (schedulable) within the given constraints.
+The kernel thus performs an admittance test when setting or changing
 .B SCHED_DEADLINE
-policy/attributes.
-
-This admission test calculates that the task set is
-feasible/schedulable, failing this,
+policy and attributes.
+This admission test calculates whether the change is feasible;
+if it is not
 .BR sched_setattr (2)
-will return
--EBUSY.
+fails with the error
+.BR EBUSY .
 
 For example, it is required (but not necessarily sufficient) for
-the total utilization to be less or equal to the total amount of
-CPUs available, where, since each task can maximally run for
-Runtime per Period, that task's utilization is its
-Runtime/Period.
+the total utilization to be less than or equal to the total number of
+CPUs available, where, since each thread can maximally run for
+Runtime per Period, that thread's utilization is its
+Runtime divided by its Period.
 
-Because we must be able to calculate admittance
+In order to fulfil the guarantees that are made when
+a thread is admitted to the
+.BR SCHED_DEADLINE
+policy,
 .BR SCHED_DEADLINE
-tasks are the highest priority (user controllable) tasks in the
-system, if any
+threads are the highest priority (user controllable) threads in the
+system; if any
 .BR SCHED_DEADLINE
-task is runnable, it will preempt
-any FIFO/RR/OTHER/BATCH/IDLE task.
+thread is runnable,
+it will preempt any thread scheduled under one of the other policies.
 
-.B SCHED_DEADLINE
-tasks will fail
+A call to
 .BR fork (2)
-with
--EAGAIN,
-except when
-the forking task hascw
-SCHED_FLAG_RESET_ON_FORK
-set.
+by a thread scheduled under the
+.B SCHED_DEADLINE
+policy will fail with the error
+.BR EAGAIN ,
+unless the thread has its reset-on-fork flag set (see below).
 
 A
 .B SCHED_DEADLINE
-task calling
+thread that calls
 .BR sched_yield (2)
-will 'yield' the current job and wait for a new period to begin.
+will yield the current job and wait for a new period to begin.
+.\"
+.\" FIXME Calling sched_getparam() on a SCHED_DEADLINE thread
+.\"       fails with EINVAL, but sched_getscheduler() succeeds.
+.\"       Is that intended? (Why?)
 .\"
 .\"
 .SS SCHED_OTHER: Default Linux time-sharing scheduling
@@ -421,6 +474,12 @@ matches the real or effective user ID of the target thread
 .IR pid )
 whose policy is being changed.
 
+A thread must be privileged
+.RB ( CAP_SYS_NICE )
+in order to set or modify a 
+.BR SCHED_DEADLINE
+policy.
+
 Since Linux 2.6.12, the
 .B RLIMIT_RTPRIO
 resource limit defines a ceiling on an unprivileged thread's