1========================
2Deadline Task Scheduling
3========================
4
5.. CONTENTS
6
7    0. WARNING
8    1. Overview
9    2. Scheduling algorithm
10      2.1 Main algorithm
11      2.2 Bandwidth reclaiming
12    3. Scheduling Real-Time Tasks
13      3.1 Definitions
14      3.2 Schedulability Analysis for Uniprocessor Systems
15      3.3 Schedulability Analysis for Multiprocessor Systems
16      3.4 Relationship with SCHED_DEADLINE Parameters
17    4. Bandwidth management
18      4.1 System-wide settings
19      4.2 Task interface
20      4.3 Default behavior
21      4.4 Behavior of sched_yield()
22    5. Tasks CPU affinity
23      5.1 SCHED_DEADLINE and cpusets HOWTO
24    6. Future plans
25    A. Test suite
26    B. Minimal main()
27
28
290. WARNING
30==========
31
32 Fiddling with these settings can result in an unpredictable or even unstable
33 system behavior. As for -rt (group) scheduling, it is assumed that root users
34 know what they're doing.
35
36
371. Overview
38===========
39
40 The SCHED_DEADLINE policy contained inside the sched_dl scheduling class is
41 basically an implementation of the Earliest Deadline First (EDF) scheduling
42 algorithm, augmented with a mechanism (called Constant Bandwidth Server, CBS)
43 that makes it possible to isolate the behavior of tasks between each other.
44
45
462. Scheduling algorithm
47=======================
48
492.1 Main algorithm
50------------------
51
52 SCHED_DEADLINE [18] uses three parameters, named "runtime", "period", and
53 "deadline", to schedule tasks. A SCHED_DEADLINE task should receive
54 "runtime" microseconds of execution time every "period" microseconds, and
55 these "runtime" microseconds are available within "deadline" microseconds
56 from the beginning of the period.  In order to implement this behavior,
57 every time the task wakes up, the scheduler computes a "scheduling deadline"
58 consistent with the guarantee (using the CBS[2,3] algorithm). Tasks are then
59 scheduled using EDF[1] on these scheduling deadlines (the task with the
60 earliest scheduling deadline is selected for execution). Notice that the
61 task actually receives "runtime" time units within "deadline" if a proper
62 "admission control" strategy (see Section "4. Bandwidth management") is used
63 (clearly, if the system is overloaded this guarantee cannot be respected).
64
65 Summing up, the CBS[2,3] algorithm assigns scheduling deadlines to tasks so
66 that each task runs for at most its runtime every period, avoiding any
67 interference between different tasks (bandwidth isolation), while the EDF[1]
68 algorithm selects the task with the earliest scheduling deadline as the one
69 to be executed next. Thanks to this feature, tasks that do not strictly comply
70 with the "traditional" real-time task model (see Section 3) can effectively
71 use the new policy.
72
73 In more details, the CBS algorithm assigns scheduling deadlines to
74 tasks in the following way:
75
76  - Each SCHED_DEADLINE task is characterized by the "runtime",
77    "deadline", and "period" parameters;
78
79  - The state of the task is described by a "scheduling deadline", and
80    a "remaining runtime". These two parameters are initially set to 0;
81
82  - When a SCHED_DEADLINE task wakes up (becomes ready for execution),
83    the scheduler checks if::
84
85                 remaining runtime                  runtime
86        ----------------------------------    >    ---------
87        scheduling deadline - current time           period
88
89    then, if the scheduling deadline is smaller than the current time, or
90    this condition is verified, the scheduling deadline and the
91    remaining runtime are re-initialized as
92
93         scheduling deadline = current time + deadline
94         remaining runtime = runtime
95
96    otherwise, the scheduling deadline and the remaining runtime are
97    left unchanged;
98
99  - When a SCHED_DEADLINE task executes for an amount of time t, its
100    remaining runtime is decreased as::
101
102         remaining runtime = remaining runtime - t
103
104    (technically, the runtime is decreased at every tick, or when the
105    task is descheduled / preempted);
106
107  - When the remaining runtime becomes less or equal than 0, the task is
108    said to be "throttled" (also known as "depleted" in real-time literature)
109    and cannot be scheduled until its scheduling deadline. The "replenishment
110    time" for this task (see next item) is set to be equal to the current
111    value of the scheduling deadline;
112
113  - When the current time is equal to the replenishment time of a
114    throttled task, the scheduling deadline and the remaining runtime are
115    updated as::
116
117         scheduling deadline = scheduling deadline + period
118         remaining runtime = remaining runtime + runtime
119
120 The SCHED_FLAG_DL_OVERRUN flag in sched_attr's sched_flags field allows a task
121 to get informed about runtime overruns through the delivery of SIGXCPU
122 signals.
123
124
1252.2 Bandwidth reclaiming
126------------------------
127
128 Bandwidth reclaiming for deadline tasks is based on the GRUB (Greedy
129 Reclamation of Unused Bandwidth) algorithm [15, 16, 17] and it is enabled
130 when flag SCHED_FLAG_RECLAIM is set.
131
132 The following diagram illustrates the state names for tasks handled by GRUB::
133
134                             ------------
135                 (d)        |   Active   |
136              ------------->|            |
137              |             | Contending |
138              |              ------------
139              |                A      |
140          ----------           |      |
141         |          |          |      |
142         | Inactive |          |(b)   | (a)
143         |          |          |      |
144          ----------           |      |
145              A                |      V
146              |              ------------
147              |             |   Active   |
148              --------------|     Non    |
149                 (c)        | Contending |
150                             ------------
151
152 A task can be in one of the following states:
153
154  - ActiveContending: if it is ready for execution (or executing);
155
156  - ActiveNonContending: if it just blocked and has not yet surpassed the 0-lag
157    time;
158
159  - Inactive: if it is blocked and has surpassed the 0-lag time.
160
161 State transitions:
162
163  (a) When a task blocks, it does not become immediately inactive since its
164      bandwidth cannot be immediately reclaimed without breaking the
165      real-time guarantees. It therefore enters a transitional state called
166      ActiveNonContending. The scheduler arms the "inactive timer" to fire at
167      the 0-lag time, when the task's bandwidth can be reclaimed without
168      breaking the real-time guarantees.
169
170      The 0-lag time for a task entering the ActiveNonContending state is
171      computed as::
172
173                        (runtime * dl_period)
174             deadline - ---------------------
175                             dl_runtime
176
177      where runtime is the remaining runtime, while dl_runtime and dl_period
178      are the reservation parameters.
179
180  (b) If the task wakes up before the inactive timer fires, the task re-enters
181      the ActiveContending state and the "inactive timer" is canceled.
182      In addition, if the task wakes up on a different runqueue, then
183      the task's utilization must be removed from the previous runqueue's active
184      utilization and must be added to the new runqueue's active utilization.
185      In order to avoid races between a task waking up on a runqueue while the
186      "inactive timer" is running on a different CPU, the "dl_non_contending"
187      flag is used to indicate that a task is not on a runqueue but is active
188      (so, the flag is set when the task blocks and is cleared when the
189      "inactive timer" fires or when the task  wakes up).
190
191  (c) When the "inactive timer" fires, the task enters the Inactive state and
192      its utilization is removed from the runqueue's active utilization.
193
194  (d) When an inactive task wakes up, it enters the ActiveContending state and
195      its utilization is added to the active utilization of the runqueue where
196      it has been enqueued.
197
198 For each runqueue, the algorithm GRUB keeps track of two different bandwidths:
199
200  - Active bandwidth (running_bw): this is the sum of the bandwidths of all
201    tasks in active state (i.e., ActiveContending or ActiveNonContending);
202
203  - Total bandwidth (this_bw): this is the sum of all tasks "belonging" to the
204    runqueue, including the tasks in Inactive state.
205
206
207 The algorithm reclaims the bandwidth of the tasks in Inactive state.
208 It does so by decrementing the runtime of the executing task Ti at a pace equal
209 to
210
211           dq = -max{ Ui / Umax, (1 - Uinact - Uextra) } dt
212
213 where:
214
215  - Ui is the bandwidth of task Ti;
216  - Umax is the maximum reclaimable utilization (subjected to RT throttling
217    limits);
218  - Uinact is the (per runqueue) inactive utilization, computed as
219    (this_bq - running_bw);
220  - Uextra is the (per runqueue) extra reclaimable utilization
221    (subjected to RT throttling limits).
222
223
224 Let's now see a trivial example of two deadline tasks with runtime equal
225 to 4 and period equal to 8 (i.e., bandwidth equal to 0.5)::
226
227         A            Task T1
228         |
229         |                               |
230         |                               |
231         |--------                       |----
232         |       |                       V
233         |---|---|---|---|---|---|---|---|--------->t
234         0   1   2   3   4   5   6   7   8
235
236
237         A            Task T2
238         |
239         |                               |
240         |                               |
241         |       ------------------------|
242         |       |                       V
243         |---|---|---|---|---|---|---|---|--------->t
244         0   1   2   3   4   5   6   7   8
245
246
247         A            running_bw
248         |
249       1 -----------------               ------
250         |               |               |
251      0.5-               -----------------
252         |                               |
253         |---|---|---|---|---|---|---|---|--------->t
254         0   1   2   3   4   5   6   7   8
255
256
257  - Time t = 0:
258
259    Both tasks are ready for execution and therefore in ActiveContending state.
260    Suppose Task T1 is the first task to start execution.
261    Since there are no inactive tasks, its runtime is decreased as dq = -1 dt.
262
263  - Time t = 2:
264
265    Suppose that task T1 blocks
266    Task T1 therefore enters the ActiveNonContending state. Since its remaining
267    runtime is equal to 2, its 0-lag time is equal to t = 4.
268    Task T2 start execution, with runtime still decreased as dq = -1 dt since
269    there are no inactive tasks.
270
271  - Time t = 4:
272
273    This is the 0-lag time for Task T1. Since it didn't woken up in the
274    meantime, it enters the Inactive state. Its bandwidth is removed from
275    running_bw.
276    Task T2 continues its execution. However, its runtime is now decreased as
277    dq = - 0.5 dt because Uinact = 0.5.
278    Task T2 therefore reclaims the bandwidth unused by Task T1.
279
280  - Time t = 8:
281
282    Task T1 wakes up. It enters the ActiveContending state again, and the
283    running_bw is incremented.
284
285
2862.3 Energy-aware scheduling
287---------------------------
288
289 When cpufreq's schedutil governor is selected, SCHED_DEADLINE implements the
290 GRUB-PA [19] algorithm, reducing the CPU operating frequency to the minimum
291 value that still allows to meet the deadlines. This behavior is currently
292 implemented only for ARM architectures.
293
294 A particular care must be taken in case the time needed for changing frequency
295 is of the same order of magnitude of the reservation period. In such cases,
296 setting a fixed CPU frequency results in a lower amount of deadline misses.
297
298
2993. Scheduling Real-Time Tasks
300=============================
301
302
303
304 ..  BIG FAT WARNING ******************************************************
305
306 .. warning::
307
308   This section contains a (not-thorough) summary on classical deadline
309   scheduling theory, and how it applies to SCHED_DEADLINE.
310   The reader can "safely" skip to Section 4 if only interested in seeing
311   how the scheduling policy can be used. Anyway, we strongly recommend
312   to come back here and continue reading (once the urge for testing is
313   satisfied :P) to be sure of fully understanding all technical details.
314
315 .. ************************************************************************
316
317 There are no limitations on what kind of task can exploit this new
318 scheduling discipline, even if it must be said that it is particularly
319 suited for periodic or sporadic real-time tasks that need guarantees on their
320 timing behavior, e.g., multimedia, streaming, control applications, etc.
321
3223.1 Definitions
323------------------------
324
325 A typical real-time task is composed of a repetition of computation phases
326 (task instances, or jobs) which are activated on a periodic or sporadic
327 fashion.
328 Each job J_j (where J_j is the j^th job of the task) is characterized by an
329 arrival time r_j (the time when the job starts), an amount of computation
330 time c_j needed to finish the job, and a job absolute deadline d_j, which
331 is the time within which the job should be finished. The maximum execution
332 time max{c_j} is called "Worst Case Execution Time" (WCET) for the task.
333 A real-time task can be periodic with period P if r_{j+1} = r_j + P, or
334 sporadic with minimum inter-arrival time P is r_{j+1} >= r_j + P. Finally,
335 d_j = r_j + D, where D is the task's relative deadline.
336 Summing up, a real-time task can be described as
337
338	Task = (WCET, D, P)
339
340 The utilization of a real-time task is defined as the ratio between its
341 WCET and its period (or minimum inter-arrival time), and represents
342 the fraction of CPU time needed to execute the task.
343
344 If the total utilization U=sum(WCET_i/P_i) is larger than M (with M equal
345 to the number of CPUs), then the scheduler is unable to respect all the
346 deadlines.
347 Note that total utilization is defined as the sum of the utilizations
348 WCET_i/P_i over all the real-time tasks in the system. When considering
349 multiple real-time tasks, the parameters of the i-th task are indicated
350 with the "_i" suffix.
351 Moreover, if the total utilization is larger than M, then we risk starving
352 non- real-time tasks by real-time tasks.
353 If, instead, the total utilization is smaller than M, then non real-time
354 tasks will not be starved and the system might be able to respect all the
355 deadlines.
356 As a matter of fact, in this case it is possible to provide an upper bound
357 for tardiness (defined as the maximum between 0 and the difference
358 between the finishing time of a job and its absolute deadline).
359 More precisely, it can be proven that using a global EDF scheduler the
360 maximum tardiness of each task is smaller or equal than
361
362	((M − 1) · WCET_max − WCET_min)/(M − (M − 2) · U_max) + WCET_max
363
364 where WCET_max = max{WCET_i} is the maximum WCET, WCET_min=min{WCET_i}
365 is the minimum WCET, and U_max = max{WCET_i/P_i} is the maximum
366 utilization[12].
367
3683.2 Schedulability Analysis for Uniprocessor Systems
369----------------------------------------------------
370
371 If M=1 (uniprocessor system), or in case of partitioned scheduling (each
372 real-time task is statically assigned to one and only one CPU), it is
373 possible to formally check if all the deadlines are respected.
374 If D_i = P_i for all tasks, then EDF is able to respect all the deadlines
375 of all the tasks executing on a CPU if and only if the total utilization
376 of the tasks running on such a CPU is smaller or equal than 1.
377 If D_i != P_i for some task, then it is possible to define the density of
378 a task as WCET_i/min{D_i,P_i}, and EDF is able to respect all the deadlines
379 of all the tasks running on a CPU if the sum of the densities of the tasks
380 running on such a CPU is smaller or equal than 1:
381
382	sum(WCET_i / min{D_i, P_i}) <= 1
383
384 It is important to notice that this condition is only sufficient, and not
385 necessary: there are task sets that are schedulable, but do not respect the
386 condition. For example, consider the task set {Task_1,Task_2} composed by
387 Task_1=(50ms,50ms,100ms) and Task_2=(10ms,100ms,100ms).
388 EDF is clearly able to schedule the two tasks without missing any deadline
389 (Task_1 is scheduled as soon as it is released, and finishes just in time
390 to respect its deadline; Task_2 is scheduled immediately after Task_1, hence
391 its response time cannot be larger than 50ms + 10ms = 60ms) even if
392
393	50 / min{50,100} + 10 / min{100, 100} = 50 / 50 + 10 / 100 = 1.1
394
395 Of course it is possible to test the exact schedulability of tasks with
396 D_i != P_i (checking a condition that is both sufficient and necessary),
397 but this cannot be done by comparing the total utilization or density with
398 a constant. Instead, the so called "processor demand" approach can be used,
399 computing the total amount of CPU time h(t) needed by all the tasks to
400 respect all of their deadlines in a time interval of size t, and comparing
401 such a time with the interval size t. If h(t) is smaller than t (that is,
402 the amount of time needed by the tasks in a time interval of size t is
403 smaller than the size of the interval) for all the possible values of t, then
404 EDF is able to schedule the tasks respecting all of their deadlines. Since
405 performing this check for all possible values of t is impossible, it has been
406 proven[4,5,6] that it is sufficient to perform the test for values of t
407 between 0 and a maximum value L. The cited papers contain all of the
408 mathematical details and explain how to compute h(t) and L.
409 In any case, this kind of analysis is too complex as well as too
410 time-consuming to be performed on-line. Hence, as explained in Section
411 4 Linux uses an admission test based on the tasks' utilizations.
412
4133.3 Schedulability Analysis for Multiprocessor Systems
414------------------------------------------------------
415
416 On multiprocessor systems with global EDF scheduling (non partitioned
417 systems), a sufficient test for schedulability can not be based on the
418 utilizations or densities: it can be shown that even if D_i = P_i task
419 sets with utilizations slightly larger than 1 can miss deadlines regardless
420 of the number of CPUs.
421
422 Consider a set {Task_1,...Task_{M+1}} of M+1 tasks on a system with M
423 CPUs, with the first task Task_1=(P,P,P) having period, relative deadline
424 and WCET equal to P. The remaining M tasks Task_i=(e,P-1,P-1) have an
425 arbitrarily small worst case execution time (indicated as "e" here) and a
426 period smaller than the one of the first task. Hence, if all the tasks
427 activate at the same time t, global EDF schedules these M tasks first
428 (because their absolute deadlines are equal to t + P - 1, hence they are
429 smaller than the absolute deadline of Task_1, which is t + P). As a
430 result, Task_1 can be scheduled only at time t + e, and will finish at
431 time t + e + P, after its absolute deadline. The total utilization of the
432 task set is U = M · e / (P - 1) + P / P = M · e / (P - 1) + 1, and for small
433 values of e this can become very close to 1. This is known as "Dhall's
434 effect"[7]. Note: the example in the original paper by Dhall has been
435 slightly simplified here (for example, Dhall more correctly computed
436 lim_{e->0}U).
437
438 More complex schedulability tests for global EDF have been developed in
439 real-time literature[8,9], but they are not based on a simple comparison
440 between total utilization (or density) and a fixed constant. If all tasks
441 have D_i = P_i, a sufficient schedulability condition can be expressed in
442 a simple way:
443
444	sum(WCET_i / P_i) <= M - (M - 1) · U_max
445
446 where U_max = max{WCET_i / P_i}[10]. Notice that for U_max = 1,
447 M - (M - 1) · U_max becomes M - M + 1 = 1 and this schedulability condition
448 just confirms the Dhall's effect. A more complete survey of the literature
449 about schedulability tests for multi-processor real-time scheduling can be
450 found in [11].
451
452 As seen, enforcing that the total utilization is smaller than M does not
453 guarantee that global EDF schedules the tasks without missing any deadline
454 (in other words, global EDF is not an optimal scheduling algorithm). However,
455 a total utilization smaller than M is enough to guarantee that non real-time
456 tasks are not starved and that the tardiness of real-time tasks has an upper
457 bound[12] (as previously noted). Different bounds on the maximum tardiness
458 experienced by real-time tasks have been developed in various papers[13,14],
459 but the theoretical result that is important for SCHED_DEADLINE is that if
460 the total utilization is smaller or equal than M then the response times of
461 the tasks are limited.
462
4633.4 Relationship with SCHED_DEADLINE Parameters
464-----------------------------------------------
465
466 Finally, it is important to understand the relationship between the
467 SCHED_DEADLINE scheduling parameters described in Section 2 (runtime,
468 deadline and period) and the real-time task parameters (WCET, D, P)
469 described in this section. Note that the tasks' temporal constraints are
470 represented by its absolute deadlines d_j = r_j + D described above, while
471 SCHED_DEADLINE schedules the tasks according to scheduling deadlines (see
472 Section 2).
473 If an admission test is used to guarantee that the scheduling deadlines
474 are respected, then SCHED_DEADLINE can be used to schedule real-time tasks
475 guaranteeing that all the jobs' deadlines of a task are respected.
476 In order to do this, a task must be scheduled by setting:
477
478  - runtime >= WCET
479  - deadline = D
480  - period <= P
481
482 IOW, if runtime >= WCET and if period is <= P, then the scheduling deadlines
483 and the absolute deadlines (d_j) coincide, so a proper admission control
484 allows to respect the jobs' absolute deadlines for this task (this is what is
485 called "hard schedulability property" and is an extension of Lemma 1 of [2]).
486 Notice that if runtime > deadline the admission control will surely reject
487 this task, as it is not possible to respect its temporal constraints.
488
489 References:
490
491  1 - C. L. Liu and J. W. Layland. Scheduling algorithms for multiprogram-
492      ming in a hard-real-time environment. Journal of the Association for
493      Computing Machinery, 20(1), 1973.
494  2 - L. Abeni , G. Buttazzo. Integrating Multimedia Applications in Hard
495      Real-Time Systems. Proceedings of the 19th IEEE Real-time Systems
496      Symposium, 1998. http://retis.sssup.it/~giorgio/paps/1998/rtss98-cbs.pdf
497  3 - L. Abeni. Server Mechanisms for Multimedia Applications. ReTiS Lab
498      Technical Report. http://disi.unitn.it/~abeni/tr-98-01.pdf
499  4 - J. Y. Leung and M.L. Merril. A Note on Preemptive Scheduling of
500      Periodic, Real-Time Tasks. Information Processing Letters, vol. 11,
501      no. 3, pp. 115-118, 1980.
502  5 - S. K. Baruah, A. K. Mok and L. E. Rosier. Preemptively Scheduling
503      Hard-Real-Time Sporadic Tasks on One Processor. Proceedings of the
504      11th IEEE Real-time Systems Symposium, 1990.
505  6 - S. K. Baruah, L. E. Rosier and R. R. Howell. Algorithms and Complexity
506      Concerning the Preemptive Scheduling of Periodic Real-Time tasks on
507      One Processor. Real-Time Systems Journal, vol. 4, no. 2, pp 301-324,
508      1990.
509  7 - S. J. Dhall and C. L. Liu. On a real-time scheduling problem. Operations
510      research, vol. 26, no. 1, pp 127-140, 1978.
511  8 - T. Baker. Multiprocessor EDF and Deadline Monotonic Schedulability
512      Analysis. Proceedings of the 24th IEEE Real-Time Systems Symposium, 2003.
513  9 - T. Baker. An Analysis of EDF Schedulability on a Multiprocessor.
514      IEEE Transactions on Parallel and Distributed Systems, vol. 16, no. 8,
515      pp 760-768, 2005.
516  10 - J. Goossens, S. Funk and S. Baruah, Priority-Driven Scheduling of
517       Periodic Task Systems on Multiprocessors. Real-Time Systems Journal,
518       vol. 25, no. 2–3, pp. 187–205, 2003.
519  11 - R. Davis and A. Burns. A Survey of Hard Real-Time Scheduling for
520       Multiprocessor Systems. ACM Computing Surveys, vol. 43, no. 4, 2011.
521       http://www-users.cs.york.ac.uk/~robdavis/papers/MPSurveyv5.0.pdf
522  12 - U. C. Devi and J. H. Anderson. Tardiness Bounds under Global EDF
523       Scheduling on a Multiprocessor. Real-Time Systems Journal, vol. 32,
524       no. 2, pp 133-189, 2008.
525  13 - P. Valente and G. Lipari. An Upper Bound to the Lateness of Soft
526       Real-Time Tasks Scheduled by EDF on Multiprocessors. Proceedings of
527       the 26th IEEE Real-Time Systems Symposium, 2005.
528  14 - J. Erickson, U. Devi and S. Baruah. Improved tardiness bounds for
529       Global EDF. Proceedings of the 22nd Euromicro Conference on
530       Real-Time Systems, 2010.
531  15 - G. Lipari, S. Baruah, Greedy reclamation of unused bandwidth in
532       constant-bandwidth servers, 12th IEEE Euromicro Conference on Real-Time
533       Systems, 2000.
534  16 - L. Abeni, J. Lelli, C. Scordino, L. Palopoli, Greedy CPU reclaiming for
535       SCHED DEADLINE. In Proceedings of the Real-Time Linux Workshop (RTLWS),
536       Dusseldorf, Germany, 2014.
537  17 - L. Abeni, G. Lipari, A. Parri, Y. Sun, Multicore CPU reclaiming: parallel
538       or sequential?. In Proceedings of the 31st Annual ACM Symposium on Applied
539       Computing, 2016.
540  18 - J. Lelli, C. Scordino, L. Abeni, D. Faggioli, Deadline scheduling in the
541       Linux kernel, Software: Practice and Experience, 46(6): 821-839, June
542       2016.
543  19 - C. Scordino, L. Abeni, J. Lelli, Energy-Aware Real-Time Scheduling in
544       the Linux Kernel, 33rd ACM/SIGAPP Symposium On Applied Computing (SAC
545       2018), Pau, France, April 2018.
546
547
5484. Bandwidth management
549=======================
550
551 As previously mentioned, in order for -deadline scheduling to be
552 effective and useful (that is, to be able to provide "runtime" time units
553 within "deadline"), it is important to have some method to keep the allocation
554 of the available fractions of CPU time to the various tasks under control.
555 This is usually called "admission control" and if it is not performed, then
556 no guarantee can be given on the actual scheduling of the -deadline tasks.
557
558 As already stated in Section 3, a necessary condition to be respected to
559 correctly schedule a set of real-time tasks is that the total utilization
560 is smaller than M. When talking about -deadline tasks, this requires that
561 the sum of the ratio between runtime and period for all tasks is smaller
562 than M. Notice that the ratio runtime/period is equivalent to the utilization
563 of a "traditional" real-time task, and is also often referred to as
564 "bandwidth".
565 The interface used to control the CPU bandwidth that can be allocated
566 to -deadline tasks is similar to the one already used for -rt
567 tasks with real-time group scheduling (a.k.a. RT-throttling - see
568 Documentation/scheduler/sched-rt-group.rst), and is based on readable/
569 writable control files located in procfs (for system wide settings).
570 Notice that per-group settings (controlled through cgroupfs) are still not
571 defined for -deadline tasks, because more discussion is needed in order to
572 figure out how we want to manage SCHED_DEADLINE bandwidth at the task group
573 level.
574
575 A main difference between deadline bandwidth management and RT-throttling
576 is that -deadline tasks have bandwidth on their own (while -rt ones don't!),
577 and thus we don't need a higher level throttling mechanism to enforce the
578 desired bandwidth. In other words, this means that interface parameters are
579 only used at admission control time (i.e., when the user calls
580 sched_setattr()). Scheduling is then performed considering actual tasks'
581 parameters, so that CPU bandwidth is allocated to SCHED_DEADLINE tasks
582 respecting their needs in terms of granularity. Therefore, using this simple
583 interface we can put a cap on total utilization of -deadline tasks (i.e.,
584 \Sum (runtime_i / period_i) < global_dl_utilization_cap).
585
5864.1 System wide settings
587------------------------
588
589 The system wide settings are configured under the /proc virtual file system.
590
591 For now the -rt knobs are used for -deadline admission control and the
592 -deadline runtime is accounted against the -rt runtime. We realize that this
593 isn't entirely desirable; however, it is better to have a small interface for
594 now, and be able to change it easily later. The ideal situation (see 5.) is to
595 run -rt tasks from a -deadline server; in which case the -rt bandwidth is a
596 direct subset of dl_bw.
597
598 This means that, for a root_domain comprising M CPUs, -deadline tasks
599 can be created while the sum of their bandwidths stays below:
600
601   M * (sched_rt_runtime_us / sched_rt_period_us)
602
603 It is also possible to disable this bandwidth management logic, and
604 be thus free of oversubscribing the system up to any arbitrary level.
605 This is done by writing -1 in /proc/sys/kernel/sched_rt_runtime_us.
606
607
6084.2 Task interface
609------------------
610
611 Specifying a periodic/sporadic task that executes for a given amount of
612 runtime at each instance, and that is scheduled according to the urgency of
613 its own timing constraints needs, in general, a way of declaring:
614
615  - a (maximum/typical) instance execution time,
616  - a minimum interval between consecutive instances,
617  - a time constraint by which each instance must be completed.
618
619 Therefore:
620
621  * a new struct sched_attr, containing all the necessary fields is
622    provided;
623  * the new scheduling related syscalls that manipulate it, i.e.,
624    sched_setattr() and sched_getattr() are implemented.
625
626 For debugging purposes, the leftover runtime and absolute deadline of a
627 SCHED_DEADLINE task can be retrieved through /proc/<pid>/sched (entries
628 dl.runtime and dl.deadline, both values in ns). A programmatic way to
629 retrieve these values from production code is under discussion.
630
631
6324.3 Default behavior
633---------------------
634
635 The default value for SCHED_DEADLINE bandwidth is to have rt_runtime equal to
636 950000. With rt_period equal to 1000000, by default, it means that -deadline
637 tasks can use at most 95%, multiplied by the number of CPUs that compose the
638 root_domain, for each root_domain.
639 This means that non -deadline tasks will receive at least 5% of the CPU time,
640 and that -deadline tasks will receive their runtime with a guaranteed
641 worst-case delay respect to the "deadline" parameter. If "deadline" = "period"
642 and the cpuset mechanism is used to implement partitioned scheduling (see
643 Section 5), then this simple setting of the bandwidth management is able to
644 deterministically guarantee that -deadline tasks will receive their runtime
645 in a period.
646
647 Finally, notice that in order not to jeopardize the admission control a
648 -deadline task cannot fork.
649
650
6514.4 Behavior of sched_yield()
652-----------------------------
653
654 When a SCHED_DEADLINE task calls sched_yield(), it gives up its
655 remaining runtime and is immediately throttled, until the next
656 period, when its runtime will be replenished (a special flag
657 dl_yielded is set and used to handle correctly throttling and runtime
658 replenishment after a call to sched_yield()).
659
660 This behavior of sched_yield() allows the task to wake-up exactly at
661 the beginning of the next period. Also, this may be useful in the
662 future with bandwidth reclaiming mechanisms, where sched_yield() will
663 make the leftoever runtime available for reclamation by other
664 SCHED_DEADLINE tasks.
665
666
6675. Tasks CPU affinity
668=====================
669
670 -deadline tasks cannot have an affinity mask smaller that the entire
671 root_domain they are created on. However, affinities can be specified
672 through the cpuset facility (Documentation/admin-guide/cgroup-v1/cpusets.rst).
673
6745.1 SCHED_DEADLINE and cpusets HOWTO
675------------------------------------
676
677 An example of a simple configuration (pin a -deadline task to CPU0)
678 follows (rt-app is used to create a -deadline task)::
679
680   mkdir /dev/cpuset
681   mount -t cgroup -o cpuset cpuset /dev/cpuset
682   cd /dev/cpuset
683   mkdir cpu0
684   echo 0 > cpu0/cpuset.cpus
685   echo 0 > cpu0/cpuset.mems
686   echo 1 > cpuset.cpu_exclusive
687   echo 0 > cpuset.sched_load_balance
688   echo 1 > cpu0/cpuset.cpu_exclusive
689   echo 1 > cpu0/cpuset.mem_exclusive
690   echo $$ > cpu0/tasks
691   rt-app -t 100000:10000:d:0 -D5 # it is now actually superfluous to specify
692				  # task affinity
693
6946. Future plans
695===============
696
697 Still missing:
698
699  - programmatic way to retrieve current runtime and absolute deadline
700  - refinements to deadline inheritance, especially regarding the possibility
701    of retaining bandwidth isolation among non-interacting tasks. This is
702    being studied from both theoretical and practical points of view, and
703    hopefully we should be able to produce some demonstrative code soon;
704  - (c)group based bandwidth management, and maybe scheduling;
705  - access control for non-root users (and related security concerns to
706    address), which is the best way to allow unprivileged use of the mechanisms
707    and how to prevent non-root users "cheat" the system?
708
709 As already discussed, we are planning also to merge this work with the EDF
710 throttling patches [https://lkml.org/lkml/2010/2/23/239] but we still are in
711 the preliminary phases of the merge and we really seek feedback that would
712 help us decide on the direction it should take.
713
714Appendix A. Test suite
715======================
716
717 The SCHED_DEADLINE policy can be easily tested using two applications that
718 are part of a wider Linux Scheduler validation suite. The suite is
719 available as a GitHub repository: https://github.com/scheduler-tools.
720
721 The first testing application is called rt-app and can be used to
722 start multiple threads with specific parameters. rt-app supports
723 SCHED_{OTHER,FIFO,RR,DEADLINE} scheduling policies and their related
724 parameters (e.g., niceness, priority, runtime/deadline/period). rt-app
725 is a valuable tool, as it can be used to synthetically recreate certain
726 workloads (maybe mimicking real use-cases) and evaluate how the scheduler
727 behaves under such workloads. In this way, results are easily reproducible.
728 rt-app is available at: https://github.com/scheduler-tools/rt-app.
729
730 Thread parameters can be specified from the command line, with something like
731 this::
732
733  # rt-app -t 100000:10000:d -t 150000:20000:f:10 -D5
734
735 The above creates 2 threads. The first one, scheduled by SCHED_DEADLINE,
736 executes for 10ms every 100ms. The second one, scheduled at SCHED_FIFO
737 priority 10, executes for 20ms every 150ms. The test will run for a total
738 of 5 seconds.
739
740 More interestingly, configurations can be described with a json file that
741 can be passed as input to rt-app with something like this::
742
743  # rt-app my_config.json
744
745 The parameters that can be specified with the second method are a superset
746 of the command line options. Please refer to rt-app documentation for more
747 details (`<rt-app-sources>/doc/*.json`).
748
749 The second testing application is a modification of schedtool, called
750 schedtool-dl, which can be used to setup SCHED_DEADLINE parameters for a
751 certain pid/application. schedtool-dl is available at:
752 https://github.com/scheduler-tools/schedtool-dl.git.
753
754 The usage is straightforward::
755
756  # schedtool -E -t 10000000:100000000 -e ./my_cpuhog_app
757
758 With this, my_cpuhog_app is put to run inside a SCHED_DEADLINE reservation
759 of 10ms every 100ms (note that parameters are expressed in microseconds).
760 You can also use schedtool to create a reservation for an already running
761 application, given that you know its pid::
762
763  # schedtool -E -t 10000000:100000000 my_app_pid
764
765Appendix B. Minimal main()
766==========================
767
768 We provide in what follows a simple (ugly) self-contained code snippet
769 showing how SCHED_DEADLINE reservations can be created by a real-time
770 application developer::
771
772   #define _GNU_SOURCE
773   #include <unistd.h>
774   #include <stdio.h>
775   #include <stdlib.h>
776   #include <string.h>
777   #include <time.h>
778   #include <linux/unistd.h>
779   #include <linux/kernel.h>
780   #include <linux/types.h>
781   #include <sys/syscall.h>
782   #include <pthread.h>
783
784   #define gettid() syscall(__NR_gettid)
785
786   #define SCHED_DEADLINE	6
787
788   /* XXX use the proper syscall numbers */
789   #ifdef __x86_64__
790   #define __NR_sched_setattr		314
791   #define __NR_sched_getattr		315
792   #endif
793
794   #ifdef __i386__
795   #define __NR_sched_setattr		351
796   #define __NR_sched_getattr		352
797   #endif
798
799   #ifdef __arm__
800   #define __NR_sched_setattr		380
801   #define __NR_sched_getattr		381
802   #endif
803
804   static volatile int done;
805
806   struct sched_attr {
807	__u32 size;
808
809	__u32 sched_policy;
810	__u64 sched_flags;
811
812	/* SCHED_NORMAL, SCHED_BATCH */
813	__s32 sched_nice;
814
815	/* SCHED_FIFO, SCHED_RR */
816	__u32 sched_priority;
817
818	/* SCHED_DEADLINE (nsec) */
819	__u64 sched_runtime;
820	__u64 sched_deadline;
821	__u64 sched_period;
822   };
823
824   int sched_setattr(pid_t pid,
825		  const struct sched_attr *attr,
826		  unsigned int flags)
827   {
828	return syscall(__NR_sched_setattr, pid, attr, flags);
829   }
830
831   int sched_getattr(pid_t pid,
832		  struct sched_attr *attr,
833		  unsigned int size,
834		  unsigned int flags)
835   {
836	return syscall(__NR_sched_getattr, pid, attr, size, flags);
837   }
838
839   void *run_deadline(void *data)
840   {
841	struct sched_attr attr;
842	int x = 0;
843	int ret;
844	unsigned int flags = 0;
845
846	printf("deadline thread started [%ld]\n", gettid());
847
848	attr.size = sizeof(attr);
849	attr.sched_flags = 0;
850	attr.sched_nice = 0;
851	attr.sched_priority = 0;
852
853	/* This creates a 10ms/30ms reservation */
854	attr.sched_policy = SCHED_DEADLINE;
855	attr.sched_runtime = 10 * 1000 * 1000;
856	attr.sched_period = attr.sched_deadline = 30 * 1000 * 1000;
857
858	ret = sched_setattr(0, &attr, flags);
859	if (ret < 0) {
860		done = 0;
861		perror("sched_setattr");
862		exit(-1);
863	}
864
865	while (!done) {
866		x++;
867	}
868
869	printf("deadline thread dies [%ld]\n", gettid());
870	return NULL;
871   }
872
873   int main (int argc, char **argv)
874   {
875	pthread_t thread;
876
877	printf("main thread [%ld]\n", gettid());
878
879	pthread_create(&thread, NULL, run_deadline, NULL);
880
881	sleep(10);
882
883	done = 1;
884	pthread_join(thread, NULL);
885
886	printf("main dies [%ld]\n", gettid());
887	return 0;
888   }
889