[489740f] | 1 | .. comment SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
| 2 | |
---|
[b8d3f6b] | 3 | .. COMMENT: COPYRIGHT (c) 1988-2008. |
---|
| 4 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
| 5 | .. COMMENT: All rights reserved. |
---|
| 6 | |
---|
[fd6dc8c8] | 7 | .. index:: scheduling |
---|
| 8 | .. index:: task scheduling |
---|
| 9 | |
---|
[3bb3e57] | 10 | .. _SchedulingConcepts: |
---|
| 11 | |
---|
[6c56401] | 12 | Scheduling Concepts |
---|
| 13 | ******************* |
---|
| 14 | |
---|
[fd6dc8c8] | 15 | Introduction |
---|
| 16 | ============ |
---|
| 17 | |
---|
[b8d3f6b] | 18 | The concept of scheduling in real-time systems dictates the ability to provide |
---|
| 19 | immediate response to specific external events, particularly the necessity of |
---|
| 20 | scheduling tasks to run within a specified time limit after the occurrence of |
---|
| 21 | an event. For example, software embedded in life-support systems used to |
---|
| 22 | monitor hospital patients must take instant action if a change in the patient's |
---|
| 23 | status is detected. |
---|
[fd6dc8c8] | 24 | |
---|
| 25 | The component of RTEMS responsible for providing this capability is |
---|
[b8d3f6b] | 26 | appropriately called the scheduler. The scheduler's sole purpose is to |
---|
| 27 | allocate the all important resource of processor time to the various tasks |
---|
| 28 | competing for attention. |
---|
[fd6dc8c8] | 29 | |
---|
[ba781f9] | 30 | The directives provided by the scheduler manager are: |
---|
| 31 | |
---|
| 32 | - rtems_scheduler_ident_ - Get ID of a scheduler |
---|
| 33 | |
---|
[a31dbcb] | 34 | - rtems_scheduler_ident_by_processor_ - Get ID of a scheduler by processor |
---|
| 35 | |
---|
| 36 | - rtems_scheduler_ident_by_processor_set_ - Get ID of a scheduler by processor set |
---|
| 37 | |
---|
[ba781f9] | 38 | - rtems_scheduler_get_processor_set_ - Get processor set of a scheduler |
---|
| 39 | |
---|
| 40 | - rtems_scheduler_add_processor_ - Add processor to a scheduler |
---|
| 41 | |
---|
| 42 | - rtems_scheduler_remove_processor_ - Remove processor from a scheduler |
---|
| 43 | |
---|
[6c56401] | 44 | .. index:: scheduling algorithms |
---|
| 45 | |
---|
[fd6dc8c8] | 46 | Scheduling Algorithms |
---|
[9037998] | 47 | --------------------- |
---|
[fd6dc8c8] | 48 | |
---|
[b8d3f6b] | 49 | RTEMS provides a plugin framework which allows it to support multiple |
---|
[9037998] | 50 | scheduling algorithms. RTEMS includes multiple scheduling algorithms and the |
---|
| 51 | user can select which of these they wish to use in their application at |
---|
| 52 | link-time. In addition, the user can implement their own scheduling algorithm |
---|
| 53 | and configure RTEMS to use it. |
---|
[b8d3f6b] | 54 | |
---|
| 55 | Supporting multiple scheduling algorithms gives the end user the option to |
---|
| 56 | select the algorithm which is most appropriate to their use case. Most |
---|
| 57 | real-time operating systems schedule tasks using a priority based algorithm, |
---|
| 58 | possibly with preemption control. The classic RTEMS scheduling algorithm which |
---|
[9037998] | 59 | was the only algorithm available in RTEMS 4.10 and earlier, is a fixed-priority |
---|
| 60 | scheduling algorithm. This scheduling algoritm is suitable for uniprocessor |
---|
| 61 | (e.g. non-SMP) systems and is known as the *Deterministic Priority |
---|
[b8d3f6b] | 62 | Scheduler*. Unless the user configures another scheduling algorithm, RTEMS |
---|
[9037998] | 63 | will use this on uniprocessor systems. |
---|
[fd6dc8c8] | 64 | |
---|
[6c56401] | 65 | .. index:: priority scheduling |
---|
| 66 | |
---|
[fd6dc8c8] | 67 | Priority Scheduling |
---|
| 68 | ------------------- |
---|
| 69 | |
---|
[b8d3f6b] | 70 | When using priority based scheduling, RTEMS allocates the processor using a |
---|
| 71 | priority-based, preemptive algorithm augmented to provide round-robin |
---|
| 72 | characteristics within individual priority groups. The goal of this algorithm |
---|
| 73 | is to guarantee that the task which is executing on the processor at any point |
---|
| 74 | in time is the one with the highest priority among all tasks in the ready |
---|
| 75 | state. |
---|
| 76 | |
---|
| 77 | When a task is added to the ready chain, it is placed behind all other tasks of |
---|
| 78 | the same priority. This rule provides a round-robin within priority group |
---|
| 79 | scheduling characteristic. This means that in a group of equal priority tasks, |
---|
| 80 | tasks will execute in the order they become ready or FIFO order. Even though |
---|
| 81 | there are ways to manipulate and adjust task priorities, the most important |
---|
| 82 | rule to remember is: |
---|
| 83 | |
---|
| 84 | .. note:: |
---|
| 85 | |
---|
| 86 | Priority based scheduling algorithms will always select the highest priority |
---|
| 87 | task that is ready to run when allocating the processor to a task. |
---|
| 88 | |
---|
| 89 | Priority scheduling is the most commonly used scheduling algorithm. It should |
---|
| 90 | be used by applications in which multiple tasks contend for CPU time or other |
---|
| 91 | resources and there is a need to ensure certain tasks are given priority over |
---|
| 92 | other tasks. |
---|
[fd6dc8c8] | 93 | |
---|
| 94 | There are a few common methods of accomplishing the mechanics of this |
---|
| 95 | algorithm. These ways involve a list or chain of tasks in the ready state. |
---|
| 96 | |
---|
[b8d3f6b] | 97 | - The least efficient method is to randomly place tasks in the ready chain |
---|
| 98 | forcing the scheduler to scan the entire chain to determine which task |
---|
| 99 | receives the processor. |
---|
[fd6dc8c8] | 100 | |
---|
[b8d3f6b] | 101 | - A more efficient method is to schedule the task by placing it in the proper |
---|
| 102 | place on the ready chain based on the designated scheduling criteria at the |
---|
| 103 | time it enters the ready state. Thus, when the processor is free, the first |
---|
| 104 | task on the ready chain is allocated the processor. |
---|
[fd6dc8c8] | 105 | |
---|
[b8d3f6b] | 106 | - Another mechanism is to maintain a list of FIFOs per priority. When a task |
---|
| 107 | is readied, it is placed on the rear of the FIFO for its priority. This |
---|
| 108 | method is often used with a bitmap to assist in locating which FIFOs have |
---|
[9037998] | 109 | ready tasks on them. This data structure has :math:`O(1)` insert, extract |
---|
| 110 | and find highest ready run-time complexities. |
---|
| 111 | |
---|
| 112 | - A red-black tree may be used for the ready queue with the priority as the |
---|
| 113 | key. This data structure has :math:`O(log(n))` insert, extract and find |
---|
| 114 | highest ready run-time complexities while :math:`n` is the count of tasks in |
---|
| 115 | the ready queue. |
---|
[fd6dc8c8] | 116 | |
---|
[b8d3f6b] | 117 | RTEMS currently includes multiple priority based scheduling algorithms as well |
---|
| 118 | as other algorithms which incorporate deadline. Each algorithm is discussed in |
---|
| 119 | the following sections. |
---|
[fd6dc8c8] | 120 | |
---|
[9037998] | 121 | Uniprocessor Schedulers |
---|
| 122 | ======================= |
---|
| 123 | |
---|
| 124 | All uniprocessor schedulers included in RTEMS are priority based. The |
---|
| 125 | processor is allocated to the highest priority task allowed to run. |
---|
| 126 | |
---|
[8010b6e] | 127 | .. _SchedulerPriority: |
---|
| 128 | |
---|
[fd6dc8c8] | 129 | Deterministic Priority Scheduler |
---|
| 130 | -------------------------------- |
---|
| 131 | |
---|
[b8d3f6b] | 132 | This is the scheduler implementation which has always been in RTEMS. After the |
---|
| 133 | 4.10 release series, it was factored into pluggable scheduler selection. It |
---|
| 134 | schedules tasks using a priority based algorithm which takes into account |
---|
| 135 | preemption. It is implemented using an array of FIFOs with a FIFO per |
---|
| 136 | priority. It maintains a bitmap which is used to track which priorities have |
---|
| 137 | ready tasks. |
---|
[fd6dc8c8] | 138 | |
---|
[b8d3f6b] | 139 | This algorithm is deterministic (e.g. predictable and fixed) in execution time. |
---|
| 140 | This comes at the cost of using slightly over three (3) kilobytes of RAM on a |
---|
| 141 | system configured to support 256 priority levels. |
---|
[fd6dc8c8] | 142 | |
---|
| 143 | This scheduler is only aware of a single core. |
---|
| 144 | |
---|
[8010b6e] | 145 | .. _SchedulerPrioritySimple: |
---|
| 146 | |
---|
[fd6dc8c8] | 147 | Simple Priority Scheduler |
---|
| 148 | ------------------------- |
---|
| 149 | |
---|
| 150 | This scheduler implementation has the same behaviour as the Deterministic |
---|
[b8d3f6b] | 151 | Priority Scheduler but uses only one linked list to manage all ready tasks. |
---|
| 152 | When a task is readied, a linear search of that linked list is performed to |
---|
| 153 | determine where to insert the newly readied task. |
---|
[fd6dc8c8] | 154 | |
---|
[b8d3f6b] | 155 | This algorithm uses much less RAM than the Deterministic Priority Scheduler but |
---|
| 156 | is *O(n)* where *n* is the number of ready tasks. In a small system with a |
---|
| 157 | small number of tasks, this will not be a performance issue. Reducing RAM |
---|
| 158 | consumption is often critical in small systems which are incapable of |
---|
| 159 | supporting a large number of tasks. |
---|
[fd6dc8c8] | 160 | |
---|
| 161 | This scheduler is only aware of a single core. |
---|
| 162 | |
---|
[6c56401] | 163 | .. index:: earliest deadline first scheduling |
---|
| 164 | |
---|
[8010b6e] | 165 | .. _SchedulerEDF: |
---|
| 166 | |
---|
[fd6dc8c8] | 167 | Earliest Deadline First Scheduler |
---|
| 168 | --------------------------------- |
---|
| 169 | |
---|
[b8d3f6b] | 170 | This is an alternative scheduler in RTEMS for single core applications. The |
---|
| 171 | primary EDF advantage is high total CPU utilization (theoretically up to |
---|
| 172 | 100%). It assumes that tasks have priorities equal to deadlines. |
---|
[fd6dc8c8] | 173 | |
---|
| 174 | This EDF is initially preemptive, however, individual tasks may be declared |
---|
| 175 | not-preemptive. Deadlines are declared using only Rate Monotonic manager which |
---|
| 176 | goal is to handle periodic behavior. Period is always equal to deadline. All |
---|
| 177 | ready tasks reside in a single ready queue implemented using a red-black tree. |
---|
| 178 | |
---|
[b8d3f6b] | 179 | This implementation of EDF schedules two different types of task priority types |
---|
| 180 | while each task may switch between the two types within its execution. If a |
---|
| 181 | task does have a deadline declared using the Rate Monotonic manager, the task |
---|
| 182 | is deadline-driven and its priority is equal to deadline. On the contrary if a |
---|
| 183 | task does not have any deadline or the deadline is cancelled using the Rate |
---|
| 184 | Monotonic manager, the task is considered a background task with priority equal |
---|
| 185 | to that assigned upon initialization in the same manner as for priority |
---|
| 186 | scheduler. Each background task is of a lower importance than each |
---|
| 187 | deadline-driven one and is scheduled when no deadline-driven task and no higher |
---|
| 188 | priority background task is ready to run. |
---|
| 189 | |
---|
| 190 | Every deadline-driven scheduling algorithm requires means for tasks to claim a |
---|
| 191 | deadline. The Rate Monotonic Manager is responsible for handling periodic |
---|
| 192 | execution. In RTEMS periods are equal to deadlines, thus if a task announces a |
---|
| 193 | period, it has to be finished until the end of this period. The call of |
---|
| 194 | ``rtems_rate_monotonic_period`` passes the scheduler the length of oncoming |
---|
| 195 | deadline. Moreover, the ``rtems_rate_monotonic_cancel`` and |
---|
| 196 | ``rtems_rate_monotonic_delete`` calls clear the deadlines assigned to the task. |
---|
[fd6dc8c8] | 197 | |
---|
[6c56401] | 198 | .. index:: constant bandwidth server scheduling |
---|
| 199 | |
---|
[8010b6e] | 200 | .. _SchedulerCBS: |
---|
| 201 | |
---|
[fd6dc8c8] | 202 | Constant Bandwidth Server Scheduling (CBS) |
---|
| 203 | ------------------------------------------ |
---|
| 204 | |
---|
[b8d3f6b] | 205 | This is an alternative scheduler in RTEMS for single core applications. The |
---|
| 206 | CBS is a budget aware extension of EDF scheduler. The main goal of this |
---|
[d389819] | 207 | scheduler is to ensure temporal isolation of tasks meaning that a task's |
---|
[b8d3f6b] | 208 | execution in terms of meeting deadlines must not be influenced by other tasks |
---|
| 209 | as if they were run on multiple independent processors. |
---|
[fd6dc8c8] | 210 | |
---|
[b8d3f6b] | 211 | Each task can be assigned a server (current implementation supports only one |
---|
| 212 | task per server). The server is characterized by period (deadline) and |
---|
| 213 | computation time (budget). The ratio budget/period yields bandwidth, which is |
---|
| 214 | the fraction of CPU to be reserved by the scheduler for each subsequent period. |
---|
[fd6dc8c8] | 215 | |
---|
| 216 | The CBS is equipped with a set of rules applied to tasks attached to servers |
---|
[b8d3f6b] | 217 | ensuring that deadline miss because of another task cannot occur. In case a |
---|
| 218 | task breaks one of the rules, its priority is pulled to background until the |
---|
| 219 | end of its period and then restored again. The rules are: |
---|
[fd6dc8c8] | 220 | |
---|
| 221 | - Task cannot exceed its registered budget, |
---|
| 222 | |
---|
[b8d3f6b] | 223 | - Task cannot be unblocked when a ratio between remaining budget and remaining |
---|
| 224 | deadline is higher than declared bandwidth. |
---|
[fd6dc8c8] | 225 | |
---|
[b8d3f6b] | 226 | The CBS provides an extensive API. Unlike EDF, the |
---|
| 227 | ``rtems_rate_monotonic_period`` does not declare a deadline because it is |
---|
| 228 | carried out using CBS API. This call only announces next period. |
---|
[fd6dc8c8] | 229 | |
---|
[9037998] | 230 | SMP Schedulers |
---|
| 231 | ============== |
---|
| 232 | |
---|
| 233 | All SMP schedulers included in RTEMS are priority based. The processors |
---|
| 234 | managed by a scheduler instance are allocated to the highest priority tasks |
---|
| 235 | allowed to run. |
---|
| 236 | |
---|
[8010b6e] | 237 | .. _SchedulerSMPEDF: |
---|
| 238 | |
---|
[9037998] | 239 | Earliest Deadline First SMP Scheduler |
---|
| 240 | ------------------------------------- |
---|
| 241 | |
---|
| 242 | A job-level fixed-priority scheduler using the Earliest Deadline First (EDF) |
---|
| 243 | method. By convention, the maximum priority level is |
---|
[8010b6e] | 244 | :math:`min(INT\_MAX, 2^{62} - 1)` for background tasks. The tasks with an |
---|
[9037998] | 245 | active deadline have a higher priority than the background tasks. This |
---|
| 246 | scheduler supports task processor affinities of one-to-one and one-to-all, e.g. |
---|
| 247 | a task can execute on exactly one processor or all processors managed by the |
---|
| 248 | scheduler instance. This is the default scheduler in SMP configurations if |
---|
| 249 | more than one processor is configured. The processor affinity set of a task |
---|
| 250 | must contain all online processors to select the one-to-all affinity. This is |
---|
| 251 | to avoid pathological cases if processors are added/removed to/from the |
---|
| 252 | scheduler instance at run-time. In case the processor affinity set contains |
---|
| 253 | not all online processors, then a one-to-one affinity will be used selecting |
---|
[8010b6e] | 254 | the processor with the largest index within the set of processors currently |
---|
[9037998] | 255 | owned by the scheduler instance. |
---|
| 256 | |
---|
[8010b6e] | 257 | .. _SchedulerSMPPriority: |
---|
| 258 | |
---|
[9037998] | 259 | Deterministic Priority SMP Scheduler |
---|
| 260 | ------------------------------------ |
---|
| 261 | |
---|
| 262 | A fixed-priority scheduler which uses a table of chains with one chain per |
---|
| 263 | priority level for the ready tasks. The maximum priority level is |
---|
| 264 | configurable. By default, the maximum priority level is 255 (256 priority |
---|
| 265 | levels). |
---|
| 266 | |
---|
[8010b6e] | 267 | .. _SchedulerSMPPrioritySimple: |
---|
| 268 | |
---|
[9037998] | 269 | Simple Priority SMP Scheduler |
---|
| 270 | ----------------------------- |
---|
| 271 | |
---|
| 272 | A fixed-priority scheduler which uses a sorted chain for the ready tasks. By |
---|
| 273 | convention, the maximum priority level is 255. The implementation limit is |
---|
| 274 | actually :math:`2^{64} - 1`. |
---|
| 275 | |
---|
[8010b6e] | 276 | .. _SchedulerSMPPriorityAffinity: |
---|
| 277 | |
---|
[9037998] | 278 | Aribitary Processor Affinity Priority SMP Scheduler |
---|
| 279 | --------------------------------------------------- |
---|
| 280 | |
---|
| 281 | A fixed-priority scheduler which uses a table of chains with one chain per |
---|
| 282 | priority level for the ready tasks. The maximum priority level is |
---|
| 283 | configurable. By default, the maximum priority level is 255 (256 priority |
---|
| 284 | levels). This scheduler supports arbitrary task processor affinities. The |
---|
| 285 | worst-case run-time complexity of some scheduler operations exceeds |
---|
| 286 | :math:`O(n)` while :math:`n` is the count of ready tasks. |
---|
| 287 | |
---|
[6c56401] | 288 | .. index:: scheduling mechanisms |
---|
| 289 | |
---|
[fd6dc8c8] | 290 | Scheduling Modification Mechanisms |
---|
| 291 | ================================== |
---|
| 292 | |
---|
| 293 | RTEMS provides four mechanisms which allow the user to alter the task |
---|
| 294 | scheduling decisions: |
---|
| 295 | |
---|
| 296 | - user-selectable task priority level |
---|
| 297 | |
---|
| 298 | - task preemption control |
---|
| 299 | |
---|
| 300 | - task timeslicing control |
---|
| 301 | |
---|
| 302 | - manual round-robin selection |
---|
| 303 | |
---|
[b8d3f6b] | 304 | Each of these methods provides a powerful capability to customize sets of tasks |
---|
| 305 | to satisfy the unique and particular requirements encountered in custom |
---|
| 306 | real-time applications. Although each mechanism operates independently, there |
---|
| 307 | is a precedence relationship which governs the effects of scheduling |
---|
| 308 | modifications. The evaluation order for scheduling characteristics is always |
---|
| 309 | priority, preemption mode, and timeslicing. When reading the descriptions of |
---|
| 310 | timeslicing and manual round-robin it is important to keep in mind that |
---|
| 311 | preemption (if enabled) of a task by higher priority tasks will occur as |
---|
| 312 | required, overriding the other factors presented in the description. |
---|
[fd6dc8c8] | 313 | |
---|
[6c56401] | 314 | .. index:: task priority |
---|
| 315 | |
---|
[fd6dc8c8] | 316 | Task Priority and Scheduling |
---|
| 317 | ---------------------------- |
---|
| 318 | |
---|
[b8d3f6b] | 319 | The most significant task scheduling modification mechanism is the ability for |
---|
| 320 | the user to assign a priority level to each individual task when it is created |
---|
[9037998] | 321 | and to alter a task's priority at run-time. The maximum priority level depends |
---|
| 322 | on the configured scheduler. A lower priority level means higher priority |
---|
| 323 | (higher importance). The maximum priority level of the default uniprocessor |
---|
| 324 | scheduler is 255. |
---|
[fd6dc8c8] | 325 | |
---|
[6c56401] | 326 | .. index:: preemption |
---|
| 327 | |
---|
[fd6dc8c8] | 328 | Preemption |
---|
[b8d3f6b] | 329 | ---------- |
---|
[fd6dc8c8] | 330 | |
---|
| 331 | Another way the user can alter the basic scheduling algorithm is by |
---|
[b8d3f6b] | 332 | manipulating the preemption mode flag (``RTEMS_PREEMPT_MASK``) of individual |
---|
| 333 | tasks. If preemption is disabled for a task (``RTEMS_NO_PREEMPT``), then the |
---|
| 334 | task will not relinquish control of the processor until it terminates, blocks, |
---|
| 335 | or re-enables preemption. Even tasks which become ready to run and possess |
---|
| 336 | higher priority levels will not be allowed to execute. Note that the |
---|
| 337 | preemption setting has no effect on the manner in which a task is scheduled. |
---|
[fd6dc8c8] | 338 | It only applies once a task has control of the processor. |
---|
| 339 | |
---|
[b8d3f6b] | 340 | .. index:: timeslicing |
---|
[fd6dc8c8] | 341 | .. index:: round robin scheduling |
---|
| 342 | |
---|
[6c56401] | 343 | Timeslicing |
---|
| 344 | ----------- |
---|
| 345 | |
---|
[b8d3f6b] | 346 | Timeslicing or round-robin scheduling is an additional method which can be used |
---|
| 347 | to alter the basic scheduling algorithm. Like preemption, timeslicing is |
---|
| 348 | specified on a task by task basis using the timeslicing mode flag |
---|
| 349 | (``RTEMS_TIMESLICE_MASK``). If timeslicing is enabled for a task |
---|
| 350 | (``RTEMS_TIMESLICE``), then RTEMS will limit the amount of time the task can |
---|
| 351 | execute before the processor is allocated to another task. Each tick of the |
---|
| 352 | real-time clock reduces the currently running task's timeslice. When the |
---|
| 353 | execution time equals the timeslice, RTEMS will dispatch another task of the |
---|
| 354 | same priority to execute. If there are no other tasks of the same priority |
---|
| 355 | ready to execute, then the current task is allocated an additional timeslice |
---|
| 356 | and continues to run. Remember that a higher priority task will preempt the |
---|
| 357 | task (unless preemption is disabled) as soon as it is ready to run, even if the |
---|
| 358 | task has not used up its entire timeslice. |
---|
[fd6dc8c8] | 359 | |
---|
[6c56401] | 360 | .. index:: manual round robin |
---|
| 361 | |
---|
[fd6dc8c8] | 362 | Manual Round-Robin |
---|
[b8d3f6b] | 363 | ------------------ |
---|
[fd6dc8c8] | 364 | |
---|
[b8d3f6b] | 365 | The final mechanism for altering the RTEMS scheduling algorithm is called |
---|
| 366 | manual round-robin. Manual round-robin is invoked by using |
---|
| 367 | the ``rtems_task_wake_after`` directive with a time interval of |
---|
| 368 | ``RTEMS_YIELD_PROCESSOR``. This allows a task to give up the processor and be |
---|
| 369 | immediately returned to the ready chain at the end of its priority group. If |
---|
| 370 | no other tasks of the same priority are ready to run, then the task does not |
---|
| 371 | lose control of the processor. |
---|
[fd6dc8c8] | 372 | |
---|
[6c56401] | 373 | .. index:: dispatching |
---|
| 374 | |
---|
[fd6dc8c8] | 375 | Dispatching Tasks |
---|
[b8d3f6b] | 376 | ================= |
---|
| 377 | |
---|
| 378 | The dispatcher is the RTEMS component responsible for allocating the processor |
---|
| 379 | to a ready task. In order to allocate the processor to one task, it must be |
---|
| 380 | deallocated or retrieved from the task currently using it. This involves a |
---|
| 381 | concept called a context switch. To perform a context switch, the dispatcher |
---|
| 382 | saves the context of the current task and restores the context of the task |
---|
| 383 | which has been allocated to the processor. Saving and restoring a task's |
---|
| 384 | context is the storing/loading of all the essential information about a task to |
---|
| 385 | enable it to continue execution without any effects of the interruption. For |
---|
| 386 | example, the contents of a task's register set must be the same when it is |
---|
| 387 | given the processor as they were when it was taken away. All of the |
---|
| 388 | information that must be saved or restored for a context switch is located |
---|
| 389 | either in the TCB or on the task's stacks. |
---|
| 390 | |
---|
| 391 | Tasks that utilize a numeric coprocessor and are created with the |
---|
| 392 | ``RTEMS_FLOATING_POINT`` attribute require additional operations during a |
---|
| 393 | context switch. These additional operations are necessary to save and restore |
---|
| 394 | the floating point context of ``RTEMS_FLOATING_POINT`` tasks. To avoid |
---|
| 395 | unnecessary save and restore operations, the state of the numeric coprocessor |
---|
| 396 | is only saved when a ``RTEMS_FLOATING_POINT`` task is dispatched and that task |
---|
| 397 | was not the last task to utilize the coprocessor. |
---|
[fd6dc8c8] | 398 | |
---|
[6c56401] | 399 | .. index:: task state transitions |
---|
| 400 | |
---|
[fd6dc8c8] | 401 | Task State Transitions |
---|
[b8d3f6b] | 402 | ====================== |
---|
| 403 | |
---|
| 404 | Tasks in an RTEMS system must always be in one of the five allowable task |
---|
| 405 | states. These states are: executing, ready, blocked, dormant, and |
---|
| 406 | non-existent. |
---|
| 407 | |
---|
| 408 | A task occupies the non-existent state before a ``rtems_task_create`` has been |
---|
| 409 | issued on its behalf. A task enters the non-existent state from any other |
---|
| 410 | state in the system when it is deleted with the ``rtems_task_delete`` |
---|
| 411 | directive. While a task occupies this state it does not have a TCB or a task |
---|
| 412 | ID assigned to it; therefore, no other tasks in the system may reference this |
---|
| 413 | task. |
---|
| 414 | |
---|
| 415 | When a task is created via the ``rtems_task_create`` directive it enters the |
---|
| 416 | dormant state. This state is not entered through any other means. Although |
---|
| 417 | the task exists in the system, it cannot actively compete for system resources. |
---|
| 418 | It will remain in the dormant state until it is started via the |
---|
| 419 | ``rtems_task_start`` directive, at which time it enters the ready state. The |
---|
| 420 | task is now permitted to be scheduled for the processor and to compete for |
---|
| 421 | other system resources. |
---|
| 422 | |
---|
[170418a] | 423 | .. figure:: ../images/c_user/states.png |
---|
[b8d3f6b] | 424 | :width: 70% |
---|
| 425 | :align: center |
---|
| 426 | :alt: Task State Transitions |
---|
| 427 | |
---|
| 428 | A task occupies the blocked state whenever it is unable to be scheduled to run. |
---|
| 429 | A running task may block itself or be blocked by other tasks in the system. |
---|
| 430 | The running task blocks itself through voluntary operations that cause the task |
---|
| 431 | to wait. The only way a task can block a task other than itself is with the |
---|
| 432 | ``rtems_task_suspend`` directive. A task enters the blocked state due to any |
---|
| 433 | of the following conditions: |
---|
| 434 | |
---|
| 435 | - A task issues a ``rtems_task_suspend`` directive which blocks either itself |
---|
| 436 | or another task in the system. |
---|
| 437 | |
---|
| 438 | - The running task issues a ``rtems_barrier_wait`` directive. |
---|
| 439 | |
---|
| 440 | - The running task issues a ``rtems_message_queue_receive`` directive with the |
---|
| 441 | wait option and the message queue is empty. |
---|
| 442 | |
---|
| 443 | - The running task issues an ``rtems_event_receive`` directive with the wait |
---|
| 444 | option and the currently pending events do not satisfy the request. |
---|
| 445 | |
---|
| 446 | - The running task issues a ``rtems_semaphore_obtain`` directive with the wait |
---|
| 447 | option and the requested semaphore is unavailable. |
---|
| 448 | |
---|
| 449 | - The running task issues a ``rtems_task_wake_after`` directive which blocks |
---|
| 450 | the task for the given time interval. If the time interval specified is |
---|
| 451 | zero, the task yields the processor and remains in the ready state. |
---|
| 452 | |
---|
| 453 | - The running task issues a ``rtems_task_wake_when`` directive which blocks the |
---|
| 454 | task until the requested date and time arrives. |
---|
| 455 | |
---|
| 456 | - The running task issues a ``rtems_rate_monotonic_period`` directive and must |
---|
| 457 | wait for the specified rate monotonic period to conclude. |
---|
| 458 | |
---|
| 459 | - The running task issues a ``rtems_region_get_segment`` directive with the |
---|
| 460 | wait option and there is not an available segment large enough to satisfy the |
---|
| 461 | task's request. |
---|
| 462 | |
---|
| 463 | A blocked task may also be suspended. Therefore, both the suspension and the |
---|
| 464 | blocking condition must be removed before the task becomes ready to run again. |
---|
| 465 | |
---|
| 466 | A task occupies the ready state when it is able to be scheduled to run, but |
---|
| 467 | currently does not have control of the processor. Tasks of the same or higher |
---|
| 468 | priority will yield the processor by either becoming blocked, completing their |
---|
| 469 | timeslice, or being deleted. All tasks with the same priority will execute in |
---|
| 470 | FIFO order. A task enters the ready state due to any of the following |
---|
| 471 | conditions: |
---|
| 472 | |
---|
| 473 | - A running task issues a ``rtems_task_resume`` directive for a task that is |
---|
| 474 | suspended and the task is not blocked waiting on any resource. |
---|
| 475 | |
---|
| 476 | - A running task issues a ``rtems_message_queue_send``, |
---|
| 477 | ``rtems_message_queue_broadcast``, or a ``rtems_message_queue_urgent`` |
---|
| 478 | directive which posts a message to the queue on which the blocked task is |
---|
[fd6dc8c8] | 479 | waiting. |
---|
| 480 | |
---|
[b8d3f6b] | 481 | - A running task issues an ``rtems_event_send`` directive which sends an event |
---|
| 482 | condition to a task which is blocked waiting on that event condition. |
---|
[fd6dc8c8] | 483 | |
---|
[b8d3f6b] | 484 | - A running task issues a ``rtems_semaphore_release`` directive which releases |
---|
| 485 | the semaphore on which the blocked task is waiting. |
---|
[fd6dc8c8] | 486 | |
---|
[b8d3f6b] | 487 | - A timeout interval expires for a task which was blocked by a call to the |
---|
| 488 | ``rtems_task_wake_after`` directive. |
---|
[fd6dc8c8] | 489 | |
---|
[b8d3f6b] | 490 | - A timeout period expires for a task which blocked by a call to the |
---|
| 491 | ``rtems_task_wake_when`` directive. |
---|
[fd6dc8c8] | 492 | |
---|
[b8d3f6b] | 493 | - A running task issues a ``rtems_region_return_segment`` directive which |
---|
| 494 | releases a segment to the region on which the blocked task is waiting and a |
---|
| 495 | resulting segment is large enough to satisfy the task's request. |
---|
[fd6dc8c8] | 496 | |
---|
[b8d3f6b] | 497 | - A rate monotonic period expires for a task which blocked by a call to the |
---|
| 498 | ``rtems_rate_monotonic_period`` directive. |
---|
[fd6dc8c8] | 499 | |
---|
[b8d3f6b] | 500 | - A timeout interval expires for a task which was blocked waiting on a message, |
---|
| 501 | event, semaphore, or segment with a timeout specified. |
---|
[fd6dc8c8] | 502 | |
---|
[b8d3f6b] | 503 | - A running task issues a directive which deletes a message queue, a semaphore, |
---|
| 504 | or a region on which the blocked task is waiting. |
---|
[fd6dc8c8] | 505 | |
---|
[b8d3f6b] | 506 | - A running task issues a ``rtems_task_restart`` directive for the blocked |
---|
| 507 | task. |
---|
[fd6dc8c8] | 508 | |
---|
[b8d3f6b] | 509 | - The running task, with its preemption mode enabled, may be made ready by |
---|
| 510 | issuing any of the directives that may unblock a task with a higher priority. |
---|
| 511 | This directive may be issued from the running task itself or from an ISR. A |
---|
| 512 | ready task occupies the executing state when it has control of the CPU. A |
---|
| 513 | task enters the executing state due to any of the following conditions: |
---|
[fd6dc8c8] | 514 | |
---|
[b8d3f6b] | 515 | - The task is the highest priority ready task in the system. |
---|
[fd6dc8c8] | 516 | |
---|
[b8d3f6b] | 517 | - The running task blocks and the task is next in the scheduling queue. The |
---|
| 518 | task may be of equal priority as in round-robin scheduling or the task may |
---|
| 519 | possess the highest priority of the remaining ready tasks. |
---|
[fd6dc8c8] | 520 | |
---|
[b8d3f6b] | 521 | - The running task may reenable its preemption mode and a task exists in the |
---|
| 522 | ready queue that has a higher priority than the running task. |
---|
[fd6dc8c8] | 523 | |
---|
[b8d3f6b] | 524 | - The running task lowers its own priority and another task is of higher |
---|
| 525 | priority as a result. |
---|
[fd6dc8c8] | 526 | |
---|
[b8d3f6b] | 527 | - The running task raises the priority of a task above its own and the running |
---|
| 528 | task is in preemption mode. |
---|
[ba781f9] | 529 | |
---|
| 530 | Directives |
---|
| 531 | ========== |
---|
| 532 | |
---|
| 533 | This section details the scheduler manager. A subsection is dedicated to each |
---|
| 534 | of these services and describes the calling sequence, related constants, usage, |
---|
| 535 | and status codes. |
---|
| 536 | |
---|
| 537 | .. raw:: latex |
---|
| 538 | |
---|
| 539 | \clearpage |
---|
| 540 | |
---|
| 541 | .. _rtems_scheduler_ident: |
---|
| 542 | |
---|
| 543 | SCHEDULER_IDENT - Get ID of a scheduler |
---|
| 544 | --------------------------------------- |
---|
| 545 | |
---|
| 546 | CALLING SEQUENCE: |
---|
| 547 | .. code-block:: c |
---|
| 548 | |
---|
| 549 | rtems_status_code rtems_scheduler_ident( |
---|
| 550 | rtems_name name, |
---|
| 551 | rtems_id *id |
---|
| 552 | ); |
---|
| 553 | |
---|
| 554 | DIRECTIVE STATUS CODES: |
---|
| 555 | .. list-table:: |
---|
| 556 | :class: rtems-table |
---|
| 557 | |
---|
| 558 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 559 | - Successful operation. |
---|
| 560 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 561 | - The ``id`` parameter is ``NULL``. |
---|
| 562 | * - ``RTEMS_INVALID_NAME`` |
---|
| 563 | - Invalid scheduler name. |
---|
| 564 | |
---|
| 565 | DESCRIPTION: |
---|
| 566 | Identifies a scheduler by its name. The scheduler name is determined by |
---|
[c65aeed] | 567 | the scheduler configuration. See :ref:`ConfigurationSchedulerTable` |
---|
| 568 | and :ref:`CONFIGURE_SCHEDULER_NAME`. |
---|
[ba781f9] | 569 | |
---|
| 570 | NOTES: |
---|
| 571 | None. |
---|
| 572 | |
---|
| 573 | .. raw:: latex |
---|
| 574 | |
---|
| 575 | \clearpage |
---|
| 576 | |
---|
[a31dbcb] | 577 | .. _rtems_scheduler_ident_by_processor: |
---|
| 578 | |
---|
| 579 | SCHEDULER_IDENT_BY_PROCESSOR - Get ID of a scheduler by processor |
---|
| 580 | ----------------------------------------------------------------- |
---|
| 581 | |
---|
| 582 | CALLING SEQUENCE: |
---|
| 583 | .. code-block:: c |
---|
| 584 | |
---|
| 585 | rtems_status_code rtems_scheduler_ident_by_processor( |
---|
| 586 | uint32_t cpu_index, |
---|
| 587 | rtems_id *id |
---|
| 588 | ); |
---|
| 589 | |
---|
| 590 | DIRECTIVE STATUS CODES: |
---|
| 591 | .. list-table:: |
---|
| 592 | :class: rtems-table |
---|
| 593 | |
---|
| 594 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 595 | - Successful operation. |
---|
| 596 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 597 | - The ``id`` parameter is ``NULL``. |
---|
| 598 | * - ``RTEMS_INVALID_NAME`` |
---|
| 599 | - Invalid processor index. |
---|
| 600 | * - ``RTEMS_INCORRECT_STATE`` |
---|
| 601 | - The processor index is valid, however, this processor is not owned by |
---|
| 602 | a scheduler. |
---|
| 603 | |
---|
| 604 | DESCRIPTION: |
---|
| 605 | Identifies a scheduler by a processor. |
---|
| 606 | |
---|
| 607 | NOTES: |
---|
| 608 | None. |
---|
| 609 | |
---|
| 610 | .. raw:: latex |
---|
| 611 | |
---|
| 612 | \clearpage |
---|
| 613 | |
---|
| 614 | .. _rtems_scheduler_ident_by_processor_set: |
---|
| 615 | |
---|
| 616 | SCHEDULER_IDENT_BY_PROCESSOR_SET - Get ID of a scheduler by processor set |
---|
| 617 | ------------------------------------------------------------------------- |
---|
| 618 | |
---|
| 619 | CALLING SEQUENCE: |
---|
| 620 | .. code-block:: c |
---|
| 621 | |
---|
| 622 | rtems_status_code rtems_scheduler_ident_by_processor_set( |
---|
| 623 | size_t cpusetsize, |
---|
| 624 | const cpu_set_t *cpuset, |
---|
| 625 | rtems_id *id |
---|
| 626 | ); |
---|
| 627 | |
---|
| 628 | DIRECTIVE STATUS CODES: |
---|
| 629 | .. list-table:: |
---|
| 630 | :class: rtems-table |
---|
| 631 | |
---|
| 632 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 633 | - Successful operation. |
---|
| 634 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 635 | - The ``id`` parameter is ``NULL``. |
---|
| 636 | * - ``RTEMS_INVALID_SIZE`` |
---|
| 637 | - Invalid processor set size. |
---|
| 638 | * - ``RTEMS_INVALID_NAME`` |
---|
| 639 | - The processor set contains no online processor. |
---|
| 640 | * - ``RTEMS_INCORRECT_STATE`` |
---|
| 641 | - The processor set is valid, however, the highest numbered online |
---|
| 642 | processor in the specified processor set is not owned by a scheduler. |
---|
| 643 | |
---|
| 644 | DESCRIPTION: |
---|
| 645 | Identifies a scheduler by a processor set. The scheduler is selected |
---|
| 646 | according to the highest numbered online processor in the specified |
---|
| 647 | processor set. |
---|
| 648 | |
---|
| 649 | NOTES: |
---|
| 650 | None. |
---|
| 651 | |
---|
| 652 | .. raw:: latex |
---|
| 653 | |
---|
| 654 | \clearpage |
---|
| 655 | |
---|
[ba781f9] | 656 | .. _rtems_scheduler_get_processor_set: |
---|
| 657 | |
---|
| 658 | SCHEDULER_GET_PROCESSOR_SET - Get processor set of a scheduler |
---|
| 659 | -------------------------------------------------------------- |
---|
| 660 | |
---|
| 661 | CALLING SEQUENCE: |
---|
| 662 | .. code-block:: c |
---|
| 663 | |
---|
| 664 | rtems_status_code rtems_scheduler_get_processor_set( |
---|
| 665 | rtems_id scheduler_id, |
---|
| 666 | size_t cpusetsize, |
---|
| 667 | cpu_set_t *cpuset |
---|
| 668 | ); |
---|
| 669 | |
---|
| 670 | DIRECTIVE STATUS CODES: |
---|
| 671 | .. list-table:: |
---|
| 672 | :class: rtems-table |
---|
| 673 | |
---|
| 674 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 675 | - Successful operation. |
---|
| 676 | * - ``RTEMS_INVALID_ID`` |
---|
| 677 | - Invalid scheduler instance identifier. |
---|
| 678 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 679 | - The ``cpuset`` parameter is ``NULL``. |
---|
| 680 | * - ``RTEMS_INVALID_NUMBER`` |
---|
| 681 | - The processor set buffer is too small for the set of processors owned |
---|
| 682 | by the scheduler instance. |
---|
| 683 | |
---|
| 684 | DESCRIPTION: |
---|
| 685 | Returns the processor set owned by the scheduler instance in ``cpuset``. A |
---|
| 686 | set bit in the processor set means that this processor is owned by the |
---|
| 687 | scheduler instance and a cleared bit means the opposite. |
---|
| 688 | |
---|
| 689 | NOTES: |
---|
| 690 | None. |
---|
| 691 | |
---|
| 692 | .. raw:: latex |
---|
| 693 | |
---|
| 694 | \clearpage |
---|
| 695 | |
---|
| 696 | .. _rtems_scheduler_add_processor: |
---|
| 697 | |
---|
| 698 | SCHEDULER_ADD_PROCESSOR - Add processor to a scheduler |
---|
| 699 | ------------------------------------------------------ |
---|
| 700 | |
---|
| 701 | CALLING SEQUENCE: |
---|
| 702 | .. code-block:: c |
---|
| 703 | |
---|
| 704 | rtems_status_code rtems_scheduler_add_processor( |
---|
| 705 | rtems_id scheduler_id, |
---|
| 706 | uint32_t cpu_index |
---|
| 707 | ); |
---|
| 708 | |
---|
| 709 | DIRECTIVE STATUS CODES: |
---|
| 710 | .. list-table:: |
---|
| 711 | :class: rtems-table |
---|
| 712 | |
---|
| 713 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 714 | - Successful operation. |
---|
| 715 | * - ``RTEMS_INVALID_ID`` |
---|
| 716 | - Invalid scheduler instance identifier. |
---|
| 717 | * - ``RTEMS_NOT_CONFIGURED`` |
---|
| 718 | - The processor is not configured to be used by the application. |
---|
| 719 | * - ``RTEMS_INCORRECT_STATE`` |
---|
| 720 | - The processor is configured to be used by the application, however, it |
---|
| 721 | is not online. |
---|
| 722 | * - ``RTEMS_RESOURCE_IN_USE`` |
---|
| 723 | - The processor is already assigned to a scheduler instance. |
---|
| 724 | |
---|
| 725 | DESCRIPTION: |
---|
| 726 | Adds a processor to the set of processors owned by the specified scheduler |
---|
| 727 | instance. |
---|
| 728 | |
---|
| 729 | NOTES: |
---|
| 730 | Must be called from task context. This operation obtains and releases the |
---|
| 731 | objects allocator lock. |
---|
| 732 | |
---|
| 733 | .. raw:: latex |
---|
| 734 | |
---|
| 735 | \clearpage |
---|
| 736 | |
---|
| 737 | .. _rtems_scheduler_remove_processor: |
---|
| 738 | |
---|
| 739 | SCHEDULER_REMOVE_PROCESSOR - Remove processor from a scheduler |
---|
| 740 | -------------------------------------------------------------- |
---|
| 741 | |
---|
| 742 | CALLING SEQUENCE: |
---|
| 743 | .. code-block:: c |
---|
| 744 | |
---|
| 745 | rtems_status_code rtems_scheduler_remove_processor( |
---|
| 746 | rtems_id scheduler_id, |
---|
| 747 | uint32_t cpu_index |
---|
| 748 | ); |
---|
| 749 | |
---|
| 750 | DIRECTIVE STATUS CODES: |
---|
| 751 | .. list-table:: |
---|
| 752 | :class: rtems-table |
---|
| 753 | |
---|
| 754 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 755 | - Successful operation. |
---|
| 756 | * - ``RTEMS_INVALID_ID`` |
---|
| 757 | - Invalid scheduler instance identifier. |
---|
| 758 | * - ``RTEMS_INVALID_NUMBER`` |
---|
| 759 | - The processor is not owned by the specified scheduler instance. |
---|
| 760 | * - ``RTEMS_RESOURCE_IN_USE`` |
---|
| 761 | - The set of processors owned by the specified scheduler instance would |
---|
| 762 | be empty after the processor removal and there exists a non-idle task |
---|
| 763 | that uses this scheduler instance as its home scheduler instance. |
---|
[9037998] | 764 | * - ``RTEMS_RESOURCE_IN_USE`` |
---|
| 765 | - A task with a restricted processor affinity exists that uses this |
---|
| 766 | scheduler instance as its home scheduler instance and it would be no |
---|
| 767 | longer possible to allocate a processor for this task after the |
---|
| 768 | removal of this processor. |
---|
[ba781f9] | 769 | |
---|
| 770 | DESCRIPTION: |
---|
| 771 | Removes a processor from set of processors owned by the specified scheduler |
---|
| 772 | instance. |
---|
| 773 | |
---|
| 774 | NOTES: |
---|
| 775 | Must be called from task context. This operation obtains and releases the |
---|
| 776 | objects allocator lock. Removing a processor from a scheduler is a complex |
---|
| 777 | operation that involves all tasks of the system. |
---|