source: rtems-docs/c-user/scheduling_concepts.rst @ c2ee227

5am
Last change on this file since c2ee227 was c2ee227, checked in by Sebastian Huber <sebastian.huber@…>, on 03/07/18 at 13:06:48

c-user: Promote clustered scheduler configuration

Add own section for the clustered scheduler configuration.

  • Property mode set to 100644
File size: 30.0 KB
Line 
1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. COMMENT: COPYRIGHT (c) 1988-2008.
4.. COMMENT: On-Line Applications Research Corporation (OAR).
5.. COMMENT: All rights reserved.
6
7.. index:: scheduling
8.. index:: task scheduling
9
10.. _SchedulingConcepts:
11
12Scheduling Concepts
13*******************
14
15Introduction
16============
17
18The concept of scheduling in real-time systems dictates the ability to provide
19immediate response to specific external events, particularly the necessity of
20scheduling tasks to run within a specified time limit after the occurrence of
21an event.  For example, software embedded in life-support systems used to
22monitor hospital patients must take instant action if a change in the patient's
23status is detected.
24
25The component of RTEMS responsible for providing this capability is
26appropriately called the scheduler.  The scheduler's sole purpose is to
27allocate the all important resource of processor time to the various tasks
28competing for attention.
29
30The directives provided by the scheduler manager are:
31
32- rtems_scheduler_ident_ - Get ID of a scheduler
33
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
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
44.. index:: scheduling algorithms
45
46Scheduling Algorithms
47---------------------
48
49RTEMS provides a plugin framework which allows it to support multiple
50scheduling algorithms. RTEMS includes multiple scheduling algorithms and the
51user can select which of these they wish to use in their application at
52link-time.  In addition, the user can implement their own scheduling algorithm
53and configure RTEMS to use it.
54
55Supporting multiple scheduling algorithms gives the end user the option to
56select the algorithm which is most appropriate to their use case. Most
57real-time operating systems schedule tasks using a priority based algorithm,
58possibly with preemption control.  The classic RTEMS scheduling algorithm which
59was the only algorithm available in RTEMS 4.10 and earlier, is a fixed-priority
60scheduling algorithm.  This scheduling algoritm is suitable for uniprocessor
61(e.g. non-SMP) systems and is known as the *Deterministic Priority
62Scheduler*.  Unless the user configures another scheduling algorithm, RTEMS
63will use this on uniprocessor systems.
64
65.. index:: priority scheduling
66
67Priority Scheduling
68-------------------
69
70When using priority based scheduling, RTEMS allocates the processor using a
71priority-based, preemptive algorithm augmented to provide round-robin
72characteristics within individual priority groups.  The goal of this algorithm
73is to guarantee that the task which is executing on the processor at any point
74in time is the one with the highest priority among all tasks in the ready
75state.
76
77When a task is added to the ready chain, it is placed behind all other tasks of
78the same priority.  This rule provides a round-robin within priority group
79scheduling characteristic.  This means that in a group of equal priority tasks,
80tasks will execute in the order they become ready or FIFO order.  Even though
81there are ways to manipulate and adjust task priorities, the most important
82rule 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
89Priority scheduling is the most commonly used scheduling algorithm.  It should
90be used by applications in which multiple tasks contend for CPU time or other
91resources and there is a need to ensure certain tasks are given priority over
92other tasks.
93
94There are a few common methods of accomplishing the mechanics of this
95algorithm.  These ways involve a list or chain of tasks in the ready state.
96
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.
100
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.
105
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
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.
116
117RTEMS currently includes multiple priority based scheduling algorithms as well
118as other algorithms which incorporate deadline.  Each algorithm is discussed in
119the following sections.
120
121Uniprocessor Schedulers
122=======================
123
124All uniprocessor schedulers included in RTEMS are priority based.  The
125processor is allocated to the highest priority task allowed to run.
126
127.. _SchedulerPriority:
128
129Deterministic Priority Scheduler
130--------------------------------
131
132This is the scheduler implementation which has always been in RTEMS.  After the
1334.10 release series, it was factored into pluggable scheduler selection.  It
134schedules tasks using a priority based algorithm which takes into account
135preemption.  It is implemented using an array of FIFOs with a FIFO per
136priority.  It maintains a bitmap which is used to track which priorities have
137ready tasks.
138
139This algorithm is deterministic (e.g. predictable and fixed) in execution time.
140This comes at the cost of using slightly over three (3) kilobytes of RAM on a
141system configured to support 256 priority levels.
142
143This scheduler is only aware of a single core.
144
145.. _SchedulerPrioritySimple:
146
147Simple Priority Scheduler
148-------------------------
149
150This scheduler implementation has the same behaviour as the Deterministic
151Priority Scheduler but uses only one linked list to manage all ready tasks.
152When a task is readied, a linear search of that linked list is performed to
153determine where to insert the newly readied task.
154
155This algorithm uses much less RAM than the Deterministic Priority Scheduler but
156is *O(n)* where *n* is the number of ready tasks.  In a small system with a
157small number of tasks, this will not be a performance issue.  Reducing RAM
158consumption is often critical in small systems which are incapable of
159supporting a large number of tasks.
160
161This scheduler is only aware of a single core.
162
163.. index:: earliest deadline first scheduling
164
165.. _SchedulerEDF:
166
167Earliest Deadline First Scheduler
168---------------------------------
169
170This is an alternative scheduler in RTEMS for single core applications.  The
171primary EDF advantage is high total CPU utilization (theoretically up to
172100%). It assumes that tasks have priorities equal to deadlines.
173
174This EDF is initially preemptive, however, individual tasks may be declared
175not-preemptive. Deadlines are declared using only Rate Monotonic manager which
176goal is to handle periodic behavior. Period is always equal to deadline. All
177ready tasks reside in a single ready queue implemented using a red-black tree.
178
179This implementation of EDF schedules two different types of task priority types
180while each task may switch between the two types within its execution. If a
181task does have a deadline declared using the Rate Monotonic manager, the task
182is deadline-driven and its priority is equal to deadline.  On the contrary if a
183task does not have any deadline or the deadline is cancelled using the Rate
184Monotonic manager, the task is considered a background task with priority equal
185to that assigned upon initialization in the same manner as for priority
186scheduler. Each background task is of a lower importance than each
187deadline-driven one and is scheduled when no deadline-driven task and no higher
188priority background task is ready to run.
189
190Every deadline-driven scheduling algorithm requires means for tasks to claim a
191deadline.  The Rate Monotonic Manager is responsible for handling periodic
192execution. In RTEMS periods are equal to deadlines, thus if a task announces a
193period, 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
195deadline. Moreover, the ``rtems_rate_monotonic_cancel`` and
196``rtems_rate_monotonic_delete`` calls clear the deadlines assigned to the task.
197
198.. index:: constant bandwidth server scheduling
199
200.. _SchedulerCBS:
201
202Constant Bandwidth Server Scheduling (CBS)
203------------------------------------------
204
205This is an alternative scheduler in RTEMS for single core applications.  The
206CBS is a budget aware extension of EDF scheduler. The main goal of this
207scheduler is to ensure temporal isolation of tasks meaning that a task's
208execution in terms of meeting deadlines must not be influenced by other tasks
209as if they were run on multiple independent processors.
210
211Each task can be assigned a server (current implementation supports only one
212task per server). The server is characterized by period (deadline) and
213computation time (budget). The ratio budget/period yields bandwidth, which is
214the fraction of CPU to be reserved by the scheduler for each subsequent period.
215
216The CBS is equipped with a set of rules applied to tasks attached to servers
217ensuring that deadline miss because of another task cannot occur.  In case a
218task breaks one of the rules, its priority is pulled to background until the
219end of its period and then restored again. The rules are:
220
221- Task cannot exceed its registered budget,
222
223- Task cannot be unblocked when a ratio between remaining budget and remaining
224  deadline is higher than declared bandwidth.
225
226The CBS provides an extensive API. Unlike EDF, the
227``rtems_rate_monotonic_period`` does not declare a deadline because it is
228carried out using CBS API. This call only announces next period.
229
230SMP Schedulers
231==============
232
233All SMP schedulers included in RTEMS are priority based.  The processors
234managed by a scheduler instance are allocated to the highest priority tasks
235allowed to run.
236
237.. _SchedulerSMPEDF:
238
239Earliest Deadline First SMP Scheduler
240-------------------------------------
241
242A job-level fixed-priority scheduler using the Earliest Deadline First (EDF)
243method.  By convention, the maximum priority level is
244:math:`min(INT\_MAX, 2^{62} - 1)` for background tasks.  The tasks with an
245active deadline have a higher priority than the background tasks.  This
246scheduler supports task processor affinities of one-to-one and one-to-all, e.g.
247a task can execute on exactly one processor or all processors managed by the
248scheduler instance.  This is the default scheduler in SMP configurations if
249more than one processor is configured.  The processor affinity set of a task
250must contain all online processors to select the one-to-all affinity.  This is
251to avoid pathological cases if processors are added/removed to/from the
252scheduler instance at run-time.  In case the processor affinity set contains
253not all online processors, then a one-to-one affinity will be used selecting
254the processor with the largest index within the set of processors currently
255owned by the scheduler instance.
256
257.. _SchedulerSMPPriority:
258
259Deterministic Priority SMP Scheduler
260------------------------------------
261
262A fixed-priority scheduler which uses a table of chains with one chain per
263priority level for the ready tasks.  The maximum priority level is
264configurable.  By default, the maximum priority level is 255 (256 priority
265levels).
266
267.. _SchedulerSMPPrioritySimple:
268
269Simple Priority SMP Scheduler
270-----------------------------
271
272A fixed-priority scheduler which uses a sorted chain for the ready tasks.  By
273convention, the maximum priority level is 255.  The implementation limit is
274actually :math:`2^{64} - 1`.
275
276.. _SchedulerSMPPriorityAffinity:
277
278Aribitary Processor Affinity Priority SMP Scheduler
279---------------------------------------------------
280
281A fixed-priority scheduler which uses a table of chains with one chain per
282priority level for the ready tasks.  The maximum priority level is
283configurable.  By default, the maximum priority level is 255 (256 priority
284levels).  This scheduler supports arbitrary task processor affinities.  The
285worst-case run-time complexity of some scheduler operations exceeds
286:math:`O(n)` while :math:`n` is the count of ready tasks.
287
288.. index:: scheduling mechanisms
289
290Scheduling Modification Mechanisms
291==================================
292
293RTEMS provides four mechanisms which allow the user to alter the task
294scheduling 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
304Each of these methods provides a powerful capability to customize sets of tasks
305to satisfy the unique and particular requirements encountered in custom
306real-time applications.  Although each mechanism operates independently, there
307is a precedence relationship which governs the effects of scheduling
308modifications.  The evaluation order for scheduling characteristics is always
309priority, preemption mode, and timeslicing.  When reading the descriptions of
310timeslicing and manual round-robin it is important to keep in mind that
311preemption (if enabled) of a task by higher priority tasks will occur as
312required, overriding the other factors presented in the description.
313
314.. index:: task priority
315
316Task Priority and Scheduling
317----------------------------
318
319The most significant task scheduling modification mechanism is the ability for
320the user to assign a priority level to each individual task when it is created
321and to alter a task's priority at run-time.  The maximum priority level depends
322on the configured scheduler.  A lower priority level means higher priority
323(higher importance).  The maximum priority level of the default uniprocessor
324scheduler is 255.
325
326.. index:: preemption
327
328Preemption
329----------
330
331Another way the user can alter the basic scheduling algorithm is by
332manipulating the preemption mode flag (``RTEMS_PREEMPT_MASK``) of individual
333tasks.  If preemption is disabled for a task (``RTEMS_NO_PREEMPT``), then the
334task will not relinquish control of the processor until it terminates, blocks,
335or re-enables preemption.  Even tasks which become ready to run and possess
336higher priority levels will not be allowed to execute.  Note that the
337preemption setting has no effect on the manner in which a task is scheduled.
338It only applies once a task has control of the processor.
339
340.. index:: timeslicing
341.. index:: round robin scheduling
342
343Timeslicing
344-----------
345
346Timeslicing or round-robin scheduling is an additional method which can be used
347to alter the basic scheduling algorithm.  Like preemption, timeslicing is
348specified 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
351execute before the processor is allocated to another task.  Each tick of the
352real-time clock reduces the currently running task's timeslice.  When the
353execution time equals the timeslice, RTEMS will dispatch another task of the
354same priority to execute.  If there are no other tasks of the same priority
355ready to execute, then the current task is allocated an additional timeslice
356and continues to run.  Remember that a higher priority task will preempt the
357task (unless preemption is disabled) as soon as it is ready to run, even if the
358task has not used up its entire timeslice.
359
360.. index:: manual round robin
361
362Manual Round-Robin
363------------------
364
365The final mechanism for altering the RTEMS scheduling algorithm is called
366manual round-robin.  Manual round-robin is invoked by using
367the ``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
369immediately returned to the ready chain at the end of its priority group.  If
370no other tasks of the same priority are ready to run, then the task does not
371lose control of the processor.
372
373.. index:: dispatching
374
375Dispatching Tasks
376=================
377
378The dispatcher is the RTEMS component responsible for allocating the processor
379to a ready task.  In order to allocate the processor to one task, it must be
380deallocated or retrieved from the task currently using it.  This involves a
381concept called a context switch.  To perform a context switch, the dispatcher
382saves the context of the current task and restores the context of the task
383which has been allocated to the processor.  Saving and restoring a task's
384context is the storing/loading of all the essential information about a task to
385enable it to continue execution without any effects of the interruption.  For
386example, the contents of a task's register set must be the same when it is
387given the processor as they were when it was taken away.  All of the
388information that must be saved or restored for a context switch is located
389either in the TCB or on the task's stacks.
390
391Tasks that utilize a numeric coprocessor and are created with the
392``RTEMS_FLOATING_POINT`` attribute require additional operations during a
393context switch.  These additional operations are necessary to save and restore
394the floating point context of ``RTEMS_FLOATING_POINT`` tasks.  To avoid
395unnecessary save and restore operations, the state of the numeric coprocessor
396is only saved when a ``RTEMS_FLOATING_POINT`` task is dispatched and that task
397was not the last task to utilize the coprocessor.
398
399.. index:: task state transitions
400
401Task State Transitions
402======================
403
404Tasks in an RTEMS system must always be in one of the five allowable task
405states.  These states are: executing, ready, blocked, dormant, and
406non-existent.
407
408A task occupies the non-existent state before a ``rtems_task_create`` has been
409issued on its behalf.  A task enters the non-existent state from any other
410state in the system when it is deleted with the ``rtems_task_delete``
411directive.  While a task occupies this state it does not have a TCB or a task
412ID assigned to it; therefore, no other tasks in the system may reference this
413task.
414
415When a task is created via the ``rtems_task_create`` directive it enters the
416dormant state.  This state is not entered through any other means.  Although
417the task exists in the system, it cannot actively compete for system resources.
418It 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
420task is now permitted to be scheduled for the processor and to compete for
421other system resources.
422
423.. figure:: ../images/c_user/states.png
424         :width: 70%
425         :align: center
426         :alt: Task State Transitions
427
428A task occupies the blocked state whenever it is unable to be scheduled to run.
429A running task may block itself or be blocked by other tasks in the system.
430The running task blocks itself through voluntary operations that cause the task
431to 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
433of 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
463A blocked task may also be suspended.  Therefore, both the suspension and the
464blocking condition must be removed before the task becomes ready to run again.
465
466A task occupies the ready state when it is able to be scheduled to run, but
467currently does not have control of the processor.  Tasks of the same or higher
468priority will yield the processor by either becoming blocked, completing their
469timeslice, or being deleted.  All tasks with the same priority will execute in
470FIFO order.  A task enters the ready state due to any of the following
471conditions:
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
479  waiting.
480
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.
483
484- A running task issues a ``rtems_semaphore_release`` directive which releases
485  the semaphore on which the blocked task is waiting.
486
487- A timeout interval expires for a task which was blocked by a call to the
488  ``rtems_task_wake_after`` directive.
489
490- A timeout period expires for a task which blocked by a call to the
491  ``rtems_task_wake_when`` directive.
492
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.
496
497- A rate monotonic period expires for a task which blocked by a call to the
498  ``rtems_rate_monotonic_period`` directive.
499
500- A timeout interval expires for a task which was blocked waiting on a message,
501  event, semaphore, or segment with a timeout specified.
502
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.
505
506- A running task issues a ``rtems_task_restart`` directive for the blocked
507  task.
508
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:
514
515- The task is the highest priority ready task in the system.
516
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.
520
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.
523
524- The running task lowers its own priority and another task is of higher
525  priority as a result.
526
527- The running task raises the priority of a task above its own and the running
528  task is in preemption mode.
529
530Directives
531==========
532
533This section details the scheduler manager.  A subsection is dedicated to each
534of these services and describes the calling sequence, related constants, usage,
535and status codes.
536
537.. raw:: latex
538
539   \clearpage
540
541.. _rtems_scheduler_ident:
542
543SCHEDULER_IDENT - Get ID of a scheduler
544---------------------------------------
545
546CALLING SEQUENCE:
547    .. code-block:: c
548
549        rtems_status_code rtems_scheduler_ident(
550            rtems_name  name,
551            rtems_id   *id
552        );
553
554DIRECTIVE 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
565DESCRIPTION:
566    Identifies a scheduler by its name.  The scheduler name is determined by
567    the scheduler configuration.  See :ref:`ConfigurationSchedulersClustered`
568    and :ref:`Configuring a Scheduler Name`.
569
570NOTES:
571    None.
572
573.. raw:: latex
574
575   \clearpage
576
577.. _rtems_scheduler_ident_by_processor:
578
579SCHEDULER_IDENT_BY_PROCESSOR - Get ID of a scheduler by processor
580-----------------------------------------------------------------
581
582CALLING 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
590DIRECTIVE 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
604DESCRIPTION:
605    Identifies a scheduler by a processor.
606
607NOTES:
608    None.
609
610.. raw:: latex
611
612   \clearpage
613
614.. _rtems_scheduler_ident_by_processor_set:
615
616SCHEDULER_IDENT_BY_PROCESSOR_SET - Get ID of a scheduler by processor set
617-------------------------------------------------------------------------
618
619CALLING 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
628DIRECTIVE 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
644DESCRIPTION:
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
649NOTES:
650    None.
651
652.. raw:: latex
653
654   \clearpage
655
656.. _rtems_scheduler_get_processor_set:
657
658SCHEDULER_GET_PROCESSOR_SET - Get processor set of a scheduler
659--------------------------------------------------------------
660
661CALLING 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
670DIRECTIVE 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
684DESCRIPTION:
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
689NOTES:
690    None.
691
692.. raw:: latex
693
694   \clearpage
695
696.. _rtems_scheduler_add_processor:
697
698SCHEDULER_ADD_PROCESSOR - Add processor to a scheduler
699------------------------------------------------------
700
701CALLING 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
709DIRECTIVE 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
725DESCRIPTION:
726    Adds a processor to the set of processors owned by the specified scheduler
727    instance.
728
729NOTES:
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
739SCHEDULER_REMOVE_PROCESSOR - Remove processor from a scheduler
740--------------------------------------------------------------
741
742CALLING 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
750DIRECTIVE 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.
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.
769
770DESCRIPTION:
771    Removes a processor from set of processors owned by the specified scheduler
772    instance.
773
774NOTES:
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.
Note: See TracBrowser for help on using the repository browser.