<commit_before>			  Deadline Task Scheduling
			  ------------------------

CONTENTS
========

 0. WARNING
 1. Overview
 2. Scheduling algorithm
 3. Scheduling Real-Time Tasks
 4. Bandwidth management
   4.1 System-wide settings
   4.2 Task interface
   4.3 Default behavior
 5. Tasks CPU affinity
   5.1 SCHED_DEADLINE and cpusets HOWTO
 6. Future plans
 A. Test suite
 B. Minimal main()


0. WARNING
==========

 Fiddling with these settings can result in an unpredictable or even unstable
 system behavior. As for -rt (group) scheduling, it is assumed that root users
 know what they're doing.


1. Overview
===========

 The SCHED_DEADLINE policy contained inside the sched_dl scheduling class is
 basically an implementation of the Earliest Deadline First (EDF) scheduling
 algorithm, augmented with a mechanism (called Constant Bandwidth Server, CBS)
 that makes it possible to isolate the behavior of tasks between each other.


2. Scheduling algorithm
==================

 SCHED_DEADLINE uses three parameters, named "runtime", "period", and
 "deadline", to schedule tasks. A SCHED_DEADLINE task should receive
 "runtime" microseconds of execution time every "period" microseconds, and
 these "runtime" microseconds are available within "deadline" microseconds
 from the beginning of the period.  In order to implement this behaviour,
 every time the task wakes up, the scheduler computes a "scheduling deadline"
 consistent with the guarantee (using the CBS[2,3] algorithm). Tasks are then
 scheduled using EDF[1] on these scheduling deadlines (the task with the
 earliest scheduling deadline is selected for execution). Notice that the
 task actually receives "runtime" time units within "deadline" if a proper
 "admission control" strategy (see Section "4. Bandwidth management") is used
 (clearly, if the system is overloaded this guarantee cannot be respected).

 Summing up, the CBS[2,3] algorithms assigns scheduling deadlines to tasks so
 that each task runs for at most its runtime every period, avoiding any
 interference between different tasks (bandwidth isolation), while the EDF[1]
 algorithm selects the task with the earliest scheduling deadline as the one
 to be executed next. Thanks to this feature, tasks that do not strictly comply
 with the "traditional" real-time task model (see Section 3) can effectively
 use the new policy.

 In more details, the CBS algorithm assigns scheduling deadlines to
 tasks in the following way:

  - Each SCHED_DEADLINE task is characterised by the "runtime",
    "deadline", and "period" parameters;

  - The state of the task is described by a "scheduling deadline", and
    a "remaining runtime". These two parameters are initially set to 0;

  - When a SCHED_DEADLINE task wakes up (becomes ready for execution),
    the scheduler checks if

                 remaining runtime                  runtime
        ----------------------------------    >    ---------
        scheduling deadline - current time           period

    then, if the scheduling deadline is smaller than the current time, or
    this condition is verified, the scheduling deadline and the
    remaining runtime are re-initialised as

         scheduling deadline = current time + deadline
         remaining runtime = runtime

    otherwise, the scheduling deadline and the remaining runtime are
    left unchanged;

  - When a SCHED_DEADLINE task executes for an amount of time t, its
    remaining runtime is decreased as

         remaining runtime = remaining runtime - t

    (technically, the runtime is decreased at every tick, or when the
    task is descheduled / preempted);

  - When the remaining runtime becomes less or equal than 0, the task is
    said to be "throttled" (also known as "depleted" in real-time literature)
    and cannot be scheduled until its scheduling deadline. The "replenishment
    time" for this task (see next item) is set to be equal to the current
    value of the scheduling deadline;

  - When the current time is equal to the replenishment time of a
    throttled task, the scheduling deadline and the remaining runtime are
    updated as

         scheduling deadline = scheduling deadline + period
         remaining runtime = remaining runtime + runtime


3. Scheduling Real-Time Tasks
=============================

 * BIG FAT WARNING ******************************************************
 *
 * This section contains a (not-thorough) summary on classical deadline
 * scheduling theory, and how it applies to SCHED_DEADLINE.
 * The reader can "safely" skip to Section 4 if only interested in seeing
 * how the scheduling policy can be used. Anyway, we strongly recommend
 * to come back here and continue reading (once the urge for testing is
 * satisfied :P) to be sure of fully understanding all technical details.
 ************************************************************************

 There are no limitations on what kind of task can exploit this new
 scheduling discipline, even if it must be said that it is particularly
 suited for periodic or sporadic real-time tasks that need guarantees on their
 timing behavior, e.g., multimedia, streaming, control applications, etc.

 A typical real-time task is composed of a repetition of computation phases
 (task instances, or jobs) which are activated on a periodic or sporadic
 fashion.
 Each job J_j (where J_j is the j^th job of the task) is characterised by an
 arrival time r_j (the time when the job starts), an amount of computation
 time c_j needed to finish the job, and a job absolute deadline d_j, which
 is the time within which the job should be finished. The maximum execution
 time max_j{c_j} is called "Worst Case Execution Time" (WCET) for the task.
 A real-time task can be periodic with period P if r_{j+1} = r_j + P, or
 sporadic with minimum inter-arrival time P is r_{j+1} >= r_j + P. Finally,
 d_j = r_j + D, where D is the task's relative deadline.
 The utilisation of a real-time task is defined as the ratio between its
 WCET and its period (or minimum inter-arrival time), and represents
 the fraction of CPU time needed to execute the task.

 If the total utilisation sum_i(WCET_i/P_i) is larger than M (with M equal
 to the number of CPUs), then the scheduler is unable to respect all the
 deadlines.
 Note that total utilisation is defined as the sum of the utilisations
 WCET_i/P_i over all the real-time tasks in the system. When considering
 multiple real-time tasks, the parameters of the i-th task are indicated
 with the "_i" suffix.
 Moreover, if the total utilisation is larger than M, then we risk starving
 non- real-time tasks by real-time tasks.
 If, instead, the total utilisation is smaller than M, then non real-time
 tasks will not be starved and the system might be able to respect all the
 deadlines.
 As a matter of fact, in this case it is possible to provide an upper bound
 for tardiness (defined as the maximum between 0 and the difference
 between the finishing time of a job and its absolute deadline).
 More precisely, it can be proven that using a global EDF scheduler the
 maximum tardiness of each task is smaller or equal than
	((M − 1) · WCET_max − WCET_min)/(M − (M − 2) · U_max) + WCET_max
 where WCET_max = max_i{WCET_i} is the maximum WCET, WCET_min=min_i{WCET_i}
 is the minimum WCET, and U_max = max_i{WCET_i/P_i} is the maximum utilisation.

 If M=1 (uniprocessor system), or in case of partitioned scheduling (each
 real-time task is statically assigned to one and only one CPU), it is
 possible to formally check if all the deadlines are respected.
 If D_i = P_i for all tasks, then EDF is able to respect all the deadlines
 of all the tasks executing on a CPU if and only if the total utilisation
 of the tasks running on such a CPU is smaller or equal than 1.
 If D_i != P_i for some task, then it is possible to define the density of
 a task as C_i/min{D_i,T_i}, and EDF is able to respect all the deadlines
 of all the tasks running on a CPU if the sum sum_i C_i/min{D_i,T_i} of the
 densities of the tasks running on such a CPU is smaller or equal than 1<commit_msg>sched/dl/Documentation: Correct the definition of density as C_i/min{D_i,P_i}<commit_after>			  Deadline Task Scheduling
			  ------------------------

CONTENTS
========

 0. WARNING
 1. Overview
 2. Scheduling algorithm
 3. Scheduling Real-Time Tasks
 4. Bandwidth management
   4.1 System-wide settings
   4.2 Task interface
   4.3 Default behavior
 5. Tasks CPU affinity
   5.1 SCHED_DEADLINE and cpusets HOWTO
 6. Future plans
 A. Test suite
 B. Minimal main()


0. WARNING
==========

 Fiddling with these settings can result in an unpredictable or even unstable
 system behavior. As for -rt (group) scheduling, it is assumed that root users
 know what they're doing.


1. Overview
===========

 The SCHED_DEADLINE policy contained inside the sched_dl scheduling class is
 basically an implementation of the Earliest Deadline First (EDF) scheduling
 algorithm, augmented with a mechanism (called Constant Bandwidth Server, CBS)
 that makes it possible to isolate the behavior of tasks between each other.


2. Scheduling algorithm
==================

 SCHED_DEADLINE uses three parameters, named "runtime", "period", and
 "deadline", to schedule tasks. A SCHED_DEADLINE task should receive
 "runtime" microseconds of execution time every "period" microseconds, and
 these "runtime" microseconds are available within "deadline" microseconds
 from the beginning of the period.  In order to implement this behaviour,
 every time the task wakes up, the scheduler computes a "scheduling deadline"
 consistent with the guarantee (using the CBS[2,3] algorithm). Tasks are then
 scheduled using EDF[1] on these scheduling deadlines (the task with the
 earliest scheduling deadline is selected for execution). Notice that the
 task actually receives "runtime" time units within "deadline" if a proper
 "admission control" strategy (see Section "4. Bandwidth management") is used
 (clearly, if the system is overloaded this guarantee cannot be respected).

 Summing up, the CBS[2,3] algorithms assigns scheduling deadlines to tasks so
 that each task runs for at most its runtime every period, avoiding any
 interference between different tasks (bandwidth isolation), while the EDF[1]
 algorithm selects the task with the earliest scheduling deadline as the one
 to be executed next. Thanks to this feature, tasks that do not strictly comply
 with the "traditional" real-time task model (see Section 3) can effectively
 use the new policy.

 In more details, the CBS algorithm assigns scheduling deadlines to
 tasks in the following way:

  - Each SCHED_DEADLINE task is characterised by the "runtime",
    "deadline", and "period" parameters;

  - The state of the task is described by a "scheduling deadline", and
    a "remaining runtime". These two parameters are initially set to 0;

  - When a SCHED_DEADLINE task wakes up (becomes ready for execution),
    the scheduler checks if

                 remaining runtime                  runtime
        ----------------------------------    >    ---------
        scheduling deadline - current time           period

    then, if the scheduling deadline is smaller than the current time, or
    this condition is verified, the scheduling deadline and the
    remaining runtime are re-initialised as

         scheduling deadline = current time + deadline
         remaining runtime = runtime

    otherwise, the scheduling deadline and the remaining runtime are
    left unchanged;

  - When a SCHED_DEADLINE task executes for an amount of time t, its
    remaining runtime is decreased as

         remaining runtime = remaining runtime - t

    (technically, the runtime is decreased at every tick, or when the
    task is descheduled / preempted);

  - When the remaining runtime becomes less or equal than 0, the task is
    said to be "throttled" (also known as "depleted" in real-time literature)
    and cannot be scheduled until its scheduling deadline. The "replenishment
    time" for this task (see next item) is set to be equal to the current
    value of the scheduling deadline;

  - When the current time is equal to the replenishment time of a
    throttled task, the scheduling deadline and the remaining runtime are
    updated as

         scheduling deadline = scheduling deadline + period
         remaining runtime = remaining runtime + runtime


3. Scheduling Real-Time Tasks
=============================

 * BIG FAT WARNING ******************************************************
 *
 * This section contains a (not-thorough) summary on classical deadline
 * scheduling theory, and how it applies to SCHED_DEADLINE.
 * The reader can "safely" skip to Section 4 if only interested in seeing
 * how the scheduling policy can be used. Anyway, we strongly recommend
 * to come back here and continue reading (once the urge for testing is
 * satisfied :P) to be sure of fully understanding all technical details.
 ************************************************************************

 There are no limitations on what kind of task can exploit this new
 scheduling discipline, even if it must be said that it is particularly
 suited for periodic or sporadic real-time tasks that need guarantees on their
 timing behavior, e.g., multimedia, streaming, control applications, etc.

 A typical real-time task is composed of a repetition of computation phases
 (task instances, or jobs) which are activated on a periodic or sporadic
 fashion.
 Each job J_j (where J_j is the j^th job of the task) is characterised by an
 arrival time r_j (the time when the job starts), an amount of computation
 time c_j needed to finish the job, and a job absolute deadline d_j, which
 is the time within which the job should be finished. The maximum execution
 time max_j{c_j} is called "Worst Case Execution Time" (WCET) for the task.
 A real-time task can be periodic with period P if r_{j+1} = r_j + P, or
 sporadic with minimum inter-arrival time P is r_{j+1} >= r_j + P. Finally,
 d_j = r_j + D, where D is the task's relative deadline.
 The utilisation of a real-time task is defined as the ratio between its
 WCET and its period (or minimum inter-arrival time), and represents
 the fraction of CPU time needed to execute the task.

 If the total utilisation sum_i(WCET_i/P_i) is larger than M (with M equal
 to the number of CPUs), then the scheduler is unable to respect all the
 deadlines.
 Note that total utilisation is defined as the sum of the utilisations
 WCET_i/P_i over all the real-time tasks in the system. When considering
 multiple real-time tasks, the parameters of the i-th task are indicated
 with the "_i" suffix.
 Moreover, if the total utilisation is larger than M, then we risk starving
 non- real-time tasks by real-time tasks.
 If, instead, the total utilisation is smaller than M, then non real-time
 tasks will not be starved and the system might be able to respect all the
 deadlines.
 As a matter of fact, in this case it is possible to provide an upper bound
 for tardiness (defined as the maximum between 0 and the difference
 between the finishing time of a job and its absolute deadline).
 More precisely, it can be proven that using a global EDF scheduler the
 maximum tardiness of each task is smaller or equal than
	((M − 1) · WCET_max − WCET_min)/(M − (M − 2) · U_max) + WCET_max
 where WCET_max = max_i{WCET_i} is the maximum WCET, WCET_min=min_i{WCET_i}
 is the minimum WCET, and U_max = max_i{WCET_i/P_i} is the maximum utilisation.

 If M=1 (uniprocessor system), or in case of partitioned scheduling (each
 real-time task is statically assigned to one and only one CPU), it is
 possible to formally check if all the deadlines are respected.
 If D_i = P_i for all tasks, then EDF is able to respect all the deadlines
 of all the tasks executing on a CPU if and only if the total utilisation
 of the tasks running on such a CPU is smaller or equal than 1.
 If D_i != P_i for some task, then it is possible to define the density of
 a task as C_i/min{D_i,P_i}, and EDF is able to respect all the deadlines
 of all the tasks running on a CPU if the sum sum_i C_i/min{D_i,P_i} of the
 densities of the tasks running on such a CPU is smaller or equal than 1
{'fraction_non_alphanumeric': 0.07521251693975607, 'fraction_numerical': 0.004681532585930763, 'mean_word_length': 3.693553050014455, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5819441', 'n_tokens_mistral': 4274, 'n_tokens_neox': 3999, 'n_words': 2376}