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