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