source: rtems/cpukit/include/rtems/rtems/tasks.h @ 6abdd89

Last change on this file since 6abdd89 was 6abdd89, checked in by Sebastian Huber <sebastian.huber@…>, on Jun 14, 2021 at 7:57:51 AM

Use a common phrase for pointer parameters

Mention the type of the pointer in the parameter description. Use the
more general term "object" instead of "variable".

Update #3993.

  • Property mode set to 100644
File size: 81.5 KB
Line 
1/* SPDX-License-Identifier: BSD-2-Clause */
2
3/**
4 * @file
5 *
6 * @brief This header file defines the main parts of the Tasks Manager API.
7 */
8
9/*
10 * Copyright (C) 2013, 2021 embedded brains GmbH (http://www.embedded-brains.de)
11 * Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR)
12 *
13 * Redistribution and use in source and binary forms, with or without
14 * modification, are permitted provided that the following conditions
15 * are met:
16 * 1. Redistributions of source code must retain the above copyright
17 *    notice, this list of conditions and the following disclaimer.
18 * 2. Redistributions in binary form must reproduce the above copyright
19 *    notice, this list of conditions and the following disclaimer in the
20 *    documentation and/or other materials provided with the distribution.
21 *
22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
23 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
26 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
27 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
28 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
29 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
30 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
31 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32 * POSSIBILITY OF SUCH DAMAGE.
33 */
34
35/*
36 * This file is part of the RTEMS quality process and was automatically
37 * generated.  If you find something that needs to be fixed or
38 * worded better please post a report or patch to an RTEMS mailing list
39 * or raise a bug report:
40 *
41 * https://www.rtems.org/bugs.html
42 *
43 * For information on updating and regenerating please refer to the How-To
44 * section in the Software Requirements Engineering chapter of the
45 * RTEMS Software Engineering manual.  The manual is provided as a part of
46 * a release.  For development sources please refer to the online
47 * documentation at:
48 *
49 * https://docs.rtems.org
50 */
51
52/* Generated from spec:/rtems/task/if/header */
53
54#ifndef _RTEMS_RTEMS_TASKS_H
55#define _RTEMS_RTEMS_TASKS_H
56
57#include <stdbool.h>
58#include <stddef.h>
59#include <stdint.h>
60#include <sys/cpuset.h>
61#include <rtems/rtems/attr.h>
62#include <rtems/rtems/modes.h>
63#include <rtems/rtems/status.h>
64#include <rtems/rtems/types.h>
65#include <rtems/score/basedefs.h>
66#include <rtems/score/context.h>
67#include <rtems/score/cpu.h>
68#include <rtems/score/object.h>
69#include <rtems/score/smp.h>
70#include <rtems/score/stack.h>
71#include <rtems/score/watchdogticks.h>
72
73#ifdef __cplusplus
74extern "C" {
75#endif
76
77/* Generated from spec:/rtems/scheduler/if/group */
78
79/**
80 * @defgroup RTEMSAPIClassicScheduler Scheduler Manager
81 *
82 * @ingroup RTEMSAPIClassic
83 *
84 * @brief The scheduling concepts relate to the allocation of processing time
85 *   for tasks.
86 *
87 * The concept of scheduling in real-time systems dictates the ability to
88 * provide an immediate response to specific external events, particularly the
89 * necessity of scheduling tasks to run within a specified time limit after the
90 * occurrence of an event. For example, software embedded in life-support
91 * systems used to monitor hospital patients must take instant action if a
92 * change in the patient’s status is detected.
93 *
94 * The component of RTEMS responsible for providing this capability is
95 * appropriately called the scheduler. The scheduler’s sole purpose is to
96 * allocate the all important resource of processor time to the various tasks
97 * competing for attention.
98 */
99
100/* Generated from spec:/rtems/task/if/group */
101
102/**
103 * @defgroup RTEMSAPIClassicTasks Task Manager
104 *
105 * @ingroup RTEMSAPIClassic
106 *
107 * @brief The Task Manager provides a comprehensive set of directives to
108 *   create, delete, and administer tasks.
109 */
110
111/* Generated from spec:/rtems/task/if/argument */
112
113/**
114 * @ingroup RTEMSAPIClassicTasks
115 *
116 * @brief This integer type represents task argument values.
117 *
118 * @par Notes
119 * The type is an architecture-specific unsigned integer type which is large
120 * enough to represent pointer values and 32-bit unsigned integers.
121 */
122typedef CPU_Uint32ptr rtems_task_argument;
123
124/* Generated from spec:/rtems/task/if/config */
125
126/**
127 * @ingroup RTEMSAPIClassicTasks
128 *
129 * @brief This structure defines the configuration of a task constructed by
130 *   rtems_task_construct().
131 */
132typedef struct {
133  /**
134   * @brief This member defines the name of the task.
135   */
136  rtems_name name;
137
138  /**
139   * @brief This member defines the initial priority of the task.
140   */
141  rtems_task_priority initial_priority;
142
143  /**
144   * @brief This member shall point to the task storage area begin.
145   *
146   * The task storage area will contain the task stack, the thread-local storage,
147   * and the floating-point context on architectures with a separate
148   * floating-point context.
149   *
150   * The task storage area begin address and size should be aligned by
151   * #RTEMS_TASK_STORAGE_ALIGNMENT.  To avoid memory waste, use RTEMS_ALIGNED()
152   * and #RTEMS_TASK_STORAGE_ALIGNMENT to enforce the recommended alignment of a
153   * statically allocated task storage area.
154   */
155  void *storage_area;
156
157  /**
158   * @brief This member defines size of the task storage area in bytes.
159   *
160   * Use the RTEMS_TASK_STORAGE_SIZE() macro to determine the recommended task
161   * storage area size.
162   */
163  size_t storage_size;
164
165  /**
166   * @brief This member defines the maximum thread-local storage size supported
167   *   by the task storage area.
168   *
169   * Use RTEMS_ALIGN_UP() and #RTEMS_TASK_STORAGE_ALIGNMENT to adjust the size to
170   * meet the minimum alignment requirement of a thread-local storage area used
171   * to construct a task.
172   *
173   * If the value is less than the actual thread-local storage size, then the
174   * task construction by rtems_task_construct() fails.
175   *
176   * If the is less than the task storage area size, then the task construction
177   * by rtems_task_construct() fails.
178   *
179   * The actual thread-local storage size is determined when the application
180   * executable is linked.  The ``rtems-exeinfo`` command line tool included in
181   * the RTEMS Tools can be used to obtain the thread-local storage size and
182   * alignment of an application executable.
183   *
184   * The application may configure the maximum thread-local storage size for all
185   * threads explicitly through the #CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE
186   * configuration option.
187   */
188  size_t maximum_thread_local_storage_size;
189
190  /**
191   * @brief This member defines the optional handler to free the task storage
192   *   area.
193   *
194   * It is called on exactly two mutually exclusive occasions.  Firstly, when the
195   * task construction aborts due to a failed task create extension, or secondly,
196   * when the task is deleted.  It is called from task context under protection
197   * of the object allocator lock.  It is allowed to call free() in this handler.
198   * If handler is NULL, then no action will be performed.
199   */
200  void ( *storage_free )( void * );
201
202  /**
203   * @brief This member defines the initial modes of the task.
204   */
205  rtems_mode initial_modes;
206
207  /**
208   * @brief This member defines the attributes of the task.
209   */
210  rtems_attribute attributes;
211} rtems_task_config;
212
213/* Generated from spec:/rtems/task/if/configured-minimum-stack-size */
214
215/**
216 * @ingroup RTEMSAPIClassicTasks
217 *
218 * @brief This constant can be used to indicate that the task should be created
219 *   with the configured minimum stack size.
220 *
221 * Using this constant when specifying the task stack size indicates that this
222 * task is to be created with a stack size of the minimum stack size that was
223 * configured by the application. If not explicitly configured by the
224 * application, the default configured minimum stack size is
225 * #RTEMS_MINIMUM_STACK_SIZE which depends on the target architecture. Since
226 * this uses the configured minimum stack size value, you may get a stack size
227 * that is smaller or larger than the recommended minimum. This can be used to
228 * provide large stacks for all tasks on complex applications or small stacks
229 * on applications that are trying to conserve memory.
230 */
231#define RTEMS_CONFIGURED_MINIMUM_STACK_SIZE 0
232
233/* Generated from spec:/rtems/task/if/current-priority */
234
235/**
236 * @ingroup RTEMSAPIClassicTasks
237 *
238 * @brief This constant is passed to {set-priority:/name} when the caller wants
239 *   to obtain the current priority.
240 */
241#define RTEMS_CURRENT_PRIORITY 0
242
243/* Generated from spec:/rtems/task/if/task */
244
245/**
246 * @ingroup RTEMSAPIClassicTasks
247 *
248 * @brief This type defines the return type of task entry points.
249 *
250 * This type can be used to document task entry points in the source code.
251 */
252typedef void rtems_task;
253
254/* Generated from spec:/rtems/task/if/entry */
255
256/**
257 * @ingroup RTEMSAPIClassicTasks
258 *
259 * @brief This type defines the entry point of an RTEMS task.
260 */
261typedef rtems_task ( *rtems_task_entry )( rtems_task_argument );
262
263/* Generated from spec:/rtems/task/if/initialization-table */
264
265/**
266 * @ingroup RTEMSAPIClassicTasks
267 *
268 * @brief This structure defines the properties of the Classic API user
269 *   initialization task.
270 */
271typedef struct {
272  /**
273   * @brief This member defines the task name.
274   */
275  rtems_name name;
276
277  /**
278   * @brief This member defines the task stack size in bytes.
279   */
280  size_t stack_size;
281
282  /**
283   * @brief This member defines the initial task priority.
284   */
285  rtems_task_priority initial_priority;
286
287  /**
288   * @brief This member defines the attribute set of the task.
289   */
290  rtems_attribute attribute_set;
291
292  /**
293   * @brief This member defines the entry point of the task.
294   */
295  rtems_task_entry entry_point;
296
297  /**
298   * @brief This member defines the initial modes of the task.
299   */
300  rtems_mode mode_set;
301
302  /**
303   * @brief This member defines the entry point argument of the task.
304   */
305  rtems_task_argument argument;
306} rtems_initialization_tasks_table;
307
308/* Generated from spec:/rtems/task/if/minimum-priority */
309
310/**
311 * @ingroup RTEMSAPIClassicTasks
312 *
313 * @brief This compile time constant provides the highest (most important) task
314 *   priority settable by the API.
315 */
316#define RTEMS_MINIMUM_PRIORITY 1
317
318/* Generated from spec:/rtems/task/if/minimum-stack-size */
319
320/**
321 * @ingroup RTEMSAPIClassicTasks
322 *
323 * @brief This compile time constant provides the minimum task stack size
324 *   recommended for the target architecture.
325 *
326 * It is the minimum stack size recommended for use on this processor.  This
327 * value is selected by the RTEMS maintainers conservatively to minimize the
328 * risk of blown stacks for most user applications.  Using this constant when
329 * specifying the task stack size, indicates that the stack size will be at
330 * least RTEMS_MINIMUM_STACK_SIZE bytes in size.  If the user configured
331 * minimum stack size (see #CONFIGURE_MINIMUM_TASK_STACK_SIZE) is larger than
332 * the recommended minimum, then it will be used.
333 */
334#define RTEMS_MINIMUM_STACK_SIZE STACK_MINIMUM_SIZE
335
336/* Generated from spec:/rtems/task/if/no-priority */
337
338/**
339 * @ingroup RTEMSAPIClassicTasks
340 *
341 * @brief This compile time constant may be used for the
342 *   rtems_task_set_priority() directive to get the current task priority.
343 */
344#define RTEMS_NO_PRIORITY RTEMS_CURRENT_PRIORITY
345
346/* Generated from spec:/rtems/task/if/self-define */
347
348/**
349 * @ingroup RTEMSAPIClassicTasks
350 *
351 * @brief This compile time constant may be used to identify the calling task
352 *   in task related directives.
353 */
354#define RTEMS_SELF OBJECTS_ID_OF_SELF
355
356/* Generated from spec:/rtems/task/if/storage-alignment */
357
358/**
359 * @ingroup RTEMSAPIClassicTasks
360 *
361 * @brief This compile time constant defines the recommended alignment of a
362 *   task storage area in bytes.
363 *
364 * @par Notes
365 * Use it with RTEMS_ALIGNED() to define the alignment of a statically
366 * allocated task storage area.
367 */
368#define RTEMS_TASK_STORAGE_ALIGNMENT CPU_STACK_ALIGNMENT
369
370/* Generated from spec:/rtems/task/if/storage-size */
371
372/**
373 * @ingroup RTEMSAPIClassicTasks
374 *
375 * @brief Gets the recommended task storage area size for the size and task
376 *   attributes.
377 *
378 * @param _size is the size dedicated to the task stack and thread-local
379 *   storage in bytes.
380 *
381 * @param _attributes is the attribute set of the task using the storage area.
382 *
383 * @return Returns the recommended task storage area size calculated from the
384 *   input parameters.
385 */
386#if CPU_ALL_TASKS_ARE_FP == TRUE
387  #define RTEMS_TASK_STORAGE_SIZE( _size, _attributes ) \
388    ( ( _size ) + CONTEXT_FP_SIZE )
389#else
390  #define RTEMS_TASK_STORAGE_SIZE( _size, _attributes ) \
391    ( ( _size ) + \
392      ( ( ( _attributes ) & RTEMS_FLOATING_POINT ) != 0 ? \
393        CONTEXT_FP_SIZE : 0 ) )
394#endif
395
396/* Generated from spec:/rtems/task/if/tcb */
397
398/**
399 * @ingroup RTEMSAPIClassicTasks
400 *
401 * @brief This structure represents the TCB.
402 */
403typedef struct _Thread_Control rtems_tcb;
404
405/* Generated from spec:/rtems/task/if/visitor */
406
407/**
408 * @ingroup RTEMSAPIClassicTasks
409 *
410 * @brief Visitor routines invoked by rtems_task_iterate() shall have this
411 *   type.
412 */
413typedef bool( *rtems_task_visitor )( rtems_tcb *, void * );
414
415/* Generated from spec:/rtems/task/if/yield-processor */
416
417/**
418 * @ingroup RTEMSAPIClassicTasks
419 *
420 * @brief This compile time constant may be passed to the
421 *   rtems_task_wake_after() directive as the interval when a task wishes to
422 *   yield the processor.
423 */
424#define RTEMS_YIELD_PROCESSOR WATCHDOG_NO_TIMEOUT
425
426/* Generated from spec:/score/if/maximum-priority */
427
428/**
429 * @brief Returns the maximum priority of the scheduler with index zero.
430 */
431rtems_task_priority _RTEMS_Maximum_priority( void );
432
433/* Generated from spec:/rtems/task/if/maximum-priority */
434
435/**
436 * @ingroup RTEMSAPIClassicTasks
437 *
438 * @brief This constant variable provides the lowest (least important) task
439 *   priority of the first configured scheduler.
440 */
441#define RTEMS_MAXIMUM_PRIORITY _RTEMS_Maximum_priority()
442
443/* Generated from spec:/rtems/scheduler/if/ident */
444
445/**
446 * @ingroup RTEMSAPIClassicScheduler
447 *
448 * @brief Identifies a scheduler by the object name.
449 *
450 * @param name is the scheduler name to look up.
451 *
452 * @param[out] id is the pointer to an ::rtems_id object.  When the directive
453 *   call is successful, the identifier of the scheduler will be stored in this
454 *   object.
455 *
456 * This directive obtains a scheduler identifier associated with the scheduler
457 * name specified in ``name``.
458 *
459 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
460 *
461 * @retval ::RTEMS_INVALID_NAME There was no scheduler associated with the
462 *   name.
463 *
464 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
465 *
466 * @par Notes
467 * @parblock
468 * The scheduler name is determined by the scheduler configuration.
469 *
470 * The scheduler identifier is used with other scheduler related directives to
471 * access the scheduler.
472 * @endparblock
473 *
474 * @par Constraints
475 * @parblock
476 * The following constraints apply to this directive:
477 *
478 * * The directive may be called from within any runtime context.
479 *
480 * * The directive will not cause the calling task to be preempted.
481 * @endparblock
482 */
483rtems_status_code rtems_scheduler_ident( rtems_name name, rtems_id *id );
484
485/* Generated from spec:/rtems/scheduler/if/ident-by-processor */
486
487/**
488 * @ingroup RTEMSAPIClassicScheduler
489 *
490 * @brief Identifies a scheduler by the processor index.
491 *
492 * @param cpu_index is the processor index to identify the scheduler.
493 *
494 * @param[out] id is the pointer to an ::rtems_id object.  When the directive
495 *   call is successful, the identifier of the scheduler will be stored in this
496 *   object.
497 *
498 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
499 *
500 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
501 *
502 * @retval ::RTEMS_INVALID_NAME The processor index was invalid.
503 *
504 * @retval ::RTEMS_INCORRECT_STATE The processor index was valid, however, the
505 *   corresponding processor was not owned by a scheduler.
506 *
507 * @par Constraints
508 * @parblock
509 * The following constraints apply to this directive:
510 *
511 * * The directive may be called from within any runtime context.
512 *
513 * * The directive will not cause the calling task to be preempted.
514 * @endparblock
515 */
516rtems_status_code rtems_scheduler_ident_by_processor(
517  uint32_t  cpu_index,
518  rtems_id *id
519);
520
521/* Generated from spec:/rtems/scheduler/if/ident-by-processor-set */
522
523/**
524 * @ingroup RTEMSAPIClassicScheduler
525 *
526 * @brief Identifies a scheduler by the processor set.
527 *
528 * @param cpusetsize is the size of the processor set referenced by ``cpuset``
529 *   in bytes.  The size shall be positive.
530 *
531 * @param cpuset is the pointer to a cpu_set_t.  The referenced processor set
532 *   will be used to identify the scheduler.
533 *
534 * @param[out] id is the pointer to an ::rtems_id object.  When the directive
535 *   call is successful, the identifier of the scheduler will be stored in this
536 *   object.
537 *
538 * The scheduler is selected according to the highest numbered online processor
539 * in the specified processor set.
540 *
541 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
542 *
543 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
544 *
545 * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL.
546 *
547 * @retval ::RTEMS_INVALID_SIZE The processor set size was invalid.
548 *
549 * @retval ::RTEMS_INVALID_NAME The processor set contained no online
550 *   processor.
551 *
552 * @retval ::RTEMS_INCORRECT_STATE The processor set was valid, however, the
553 *   highest numbered online processor in the processor set was not owned by a
554 *   scheduler.
555 *
556 * @par Constraints
557 * @parblock
558 * The following constraints apply to this directive:
559 *
560 * * The directive may be called from within any runtime context.
561 *
562 * * The directive will not cause the calling task to be preempted.
563 * @endparblock
564 */
565rtems_status_code rtems_scheduler_ident_by_processor_set(
566  size_t           cpusetsize,
567  const cpu_set_t *cpuset,
568  rtems_id        *id
569);
570
571/* Generated from spec:/rtems/scheduler/if/get-maximum-priority */
572
573/**
574 * @ingroup RTEMSAPIClassicScheduler
575 *
576 * @brief Gets the maximum task priority of the scheduler.
577 *
578 * @param scheduler_id is the scheduler identifier.
579 *
580 * @param[out] priority is the pointer to an ::rtems_task_priority object.
581 *   When the directive the maximum priority of the scheduler will be stored in
582 *   this object.
583 *
584 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
585 *
586 * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the
587 *   identifier specified by ``scheduler_id``.
588 *
589 * @retval ::RTEMS_INVALID_ADDRESS The ``priority`` parameter was NULL.
590 *
591 * @par Constraints
592 * @parblock
593 * The following constraints apply to this directive:
594 *
595 * * The directive may be called from within any runtime context.
596 *
597 * * The directive will not cause the calling task to be preempted.
598 * @endparblock
599 */
600rtems_status_code rtems_scheduler_get_maximum_priority(
601  rtems_id             scheduler_id,
602  rtems_task_priority *priority
603);
604
605/* Generated from spec:/rtems/scheduler/if/map-priority-to-posix */
606
607/**
608 * @ingroup RTEMSAPIClassicScheduler
609 *
610 * @brief Maps a Classic API task priority to the corresponding POSIX thread
611 *   priority.
612 *
613 * @param scheduler_id is the scheduler identifier.
614 *
615 * @param priority is the Classic API task priority to map.
616 *
617 * @param[out] posix_priority is the pointer to an ``int`` object.  When the
618 *   directive call is successful, the POSIX thread priority value
619 *   corresponding to the specified Classic API task priority value will be
620 *   stored in this object.
621 *
622 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
623 *
624 * @retval ::RTEMS_INVALID_ADDRESS The ``posix_priority`` parameter was NULL.
625 *
626 * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the
627 *   identifier specified by ``scheduler_id``.
628 *
629 * @retval ::RTEMS_INVALID_PRIORITY The Classic API task priority was invalid.
630 *
631 * @par Constraints
632 * @parblock
633 * The following constraints apply to this directive:
634 *
635 * * The directive may be called from within any runtime context.
636 *
637 * * The directive will not cause the calling task to be preempted.
638 * @endparblock
639 */
640rtems_status_code rtems_scheduler_map_priority_to_posix(
641  rtems_id            scheduler_id,
642  rtems_task_priority priority,
643  int                *posix_priority
644);
645
646/* Generated from spec:/rtems/scheduler/if/map-priority-from-posix */
647
648/**
649 * @ingroup RTEMSAPIClassicScheduler
650 *
651 * @brief Maps a POSIX thread priority to the corresponding Classic API task
652 *   priority.
653 *
654 * @param scheduler_id is the scheduler identifier.
655 *
656 * @param posix_priority is the POSIX thread priority to map.
657 *
658 * @param[out] priority is the pointer to an ::rtems_task_priority object.
659 *   When the directive call is successful, the Classic API task priority value
660 *   corresponding to the specified POSIX thread priority value will be stored
661 *   in this object.
662 *
663 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
664 *
665 * @retval ::RTEMS_INVALID_ADDRESS The ``priority`` parameter was NULL.
666 *
667 * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the
668 *   identifier specified by ``scheduler_id``.
669 *
670 * @retval ::RTEMS_INVALID_PRIORITY The POSIX thread priority was invalid.
671 *
672 * @par Constraints
673 * @parblock
674 * The following constraints apply to this directive:
675 *
676 * * The directive may be called from within any runtime context.
677 *
678 * * The directive will not cause the calling task to be preempted.
679 * @endparblock
680 */
681rtems_status_code rtems_scheduler_map_priority_from_posix(
682  rtems_id             scheduler_id,
683  int                  posix_priority,
684  rtems_task_priority *priority
685);
686
687/* Generated from spec:/rtems/scheduler/if/get-processor */
688
689/**
690 * @ingroup RTEMSAPIClassicScheduler
691 *
692 * @brief Returns the index of the current processor.
693 *
694 * Where the system was built with SMP support disabled, this directive
695 * evaluates to a compile time constant of zero.
696 *
697 * Where the system was built with SMP support enabled, this directive returns
698 * the index of the current processor.  The set of processor indices is the
699 * range of integers starting with zero up to
700 * rtems_scheduler_get_processor_maximum() minus one.
701 *
702 * @return Returns the index of the current processor.
703 *
704 * @par Notes
705 * Outside of sections with disabled thread dispatching the current processor
706 * index may change after every instruction since the thread may migrate from
707 * one processor to another.  Sections with disabled interrupts are sections
708 * with thread dispatching disabled.
709 *
710 * @par Constraints
711 * @parblock
712 * The following constraints apply to this directive:
713 *
714 * * The directive may be called from within any runtime context.
715 *
716 * * The directive will not cause the calling task to be preempted.
717 * @endparblock
718 */
719uint32_t rtems_scheduler_get_processor( void );
720
721/* Generated from spec:/rtems/scheduler/if/get-processor-macro */
722#define rtems_scheduler_get_processor() _SMP_Get_current_processor()
723
724/* Generated from spec:/rtems/scheduler/if/get-processor-maximum */
725
726/**
727 * @ingroup RTEMSAPIClassicScheduler
728 *
729 * @brief Returns the processor maximum supported by the system.
730 *
731 * Where the system was built with SMP support disabled, this directive
732 * evaluates to a compile time constant of one.
733 *
734 * Where the system was built with SMP support enabled, this directive returns
735 * the minimum of the processors (physically or virtually) available at the
736 * target and the configured processor maximum (see
737 * #CONFIGURE_MAXIMUM_PROCESSORS).  Not all processors in the range from
738 * processor index zero to the last processor index (which is the processor
739 * maximum minus one) may be configured to be used by a scheduler or may be
740 * online (online processors have a scheduler assigned).
741 *
742 * @return Returns the processor maximum supported by the system.
743 *
744 * @par Constraints
745 * @parblock
746 * The following constraints apply to this directive:
747 *
748 * * The directive may be called from within any runtime context.
749 *
750 * * The directive will not cause the calling task to be preempted.
751 * @endparblock
752 */
753uint32_t rtems_scheduler_get_processor_maximum( void );
754
755/* Generated from spec:/rtems/scheduler/if/get-processor-maximum-macro */
756#define rtems_scheduler_get_processor_maximum() _SMP_Get_processor_maximum()
757
758/* Generated from spec:/rtems/scheduler/if/get-processor-set */
759
760/**
761 * @ingroup RTEMSAPIClassicScheduler
762 *
763 * @brief Gets the set of processors owned by the scheduler.
764 *
765 * @param scheduler_id is the scheduler identifier.
766 *
767 * @param cpusetsize is the size of the processor set referenced by ``cpuset``
768 *   in bytes.
769 *
770 * @param[out] cpuset is the pointer to a cpu_set_t object.  When the directive
771 *   call is successful, the processor set of the scheduler will be stored in
772 *   this object.  A set bit in the processor set means that the corresponding
773 *   processor is owned by the scheduler, otherwise the bit is cleared.
774 *
775 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
776 *
777 * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL.
778 *
779 * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the
780 *   identifier specified by ``scheduler_id``.
781 *
782 * @retval ::RTEMS_INVALID_SIZE The provided processor set was too small for
783 *   the set of processors owned by the scheduler.
784 *
785 * @par Constraints
786 * @parblock
787 * The following constraints apply to this directive:
788 *
789 * * The directive may be called from within any runtime context.
790 *
791 * * The directive will not cause the calling task to be preempted.
792 * @endparblock
793 */
794rtems_status_code rtems_scheduler_get_processor_set(
795  rtems_id   scheduler_id,
796  size_t     cpusetsize,
797  cpu_set_t *cpuset
798);
799
800/* Generated from spec:/rtems/scheduler/if/add-processor */
801
802/**
803 * @ingroup RTEMSAPIClassicScheduler
804 *
805 * @brief Adds the processor to the set of processors owned by the scheduler.
806 *
807 * @param scheduler_id is the scheduler identifier.
808 *
809 * @param cpu_index is the index of the processor to add.
810 *
811 * This directive adds the processor specified by the ``cpu_index`` to the
812 * scheduler specified by ``scheduler_id``.
813 *
814 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
815 *
816 * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the
817 *   identifier specified by ``scheduler_id``.
818 *
819 * @retval ::RTEMS_NOT_CONFIGURED The processor was not configured to be used
820 *   by the application.
821 *
822 * @retval ::RTEMS_INCORRECT_STATE The processor was configured to be used by
823 *   the application, however, it was not online.
824 *
825 * @retval ::RTEMS_RESOURCE_IN_USE The processor was already assigned to a
826 *   scheduler.
827 *
828 * @par Constraints
829 * @parblock
830 * The following constraints apply to this directive:
831 *
832 * * The directive may be called from within device driver initialization
833 *   context.
834 *
835 * * The directive may be called from within task context.
836 *
837 * * The directive may obtain and release the object allocator mutex.  This may
838 *   cause the calling task to be preempted.
839 * @endparblock
840 */
841rtems_status_code rtems_scheduler_add_processor(
842  rtems_id scheduler_id,
843  uint32_t cpu_index
844);
845
846/* Generated from spec:/rtems/scheduler/if/remove-processor */
847
848/**
849 * @ingroup RTEMSAPIClassicScheduler
850 *
851 * @brief Removes the processor from the set of processors owned by the
852 *   scheduler.
853 *
854 * @param scheduler_id is the scheduler identifier.
855 *
856 * @param cpu_index is the index of the processor to remove.
857 *
858 * This directive removes the processor specified by the ``cpu_index`` from the
859 * scheduler specified by ``scheduler_id``.
860 *
861 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
862 *
863 * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the
864 *   identifier specified by ``scheduler_id``.
865 *
866 * @retval ::RTEMS_INVALID_NUMBER The processor was not owned by the scheduler.
867 *
868 * @retval ::RTEMS_RESOURCE_IN_USE The set of processors owned by the scheduler
869 *   would have been empty after the processor removal and there was at least
870 *   one non-idle task that used this scheduler as its home scheduler.
871 *
872 * @par Notes
873 * Removing a processor from a scheduler is a complex operation that involves
874 * all tasks of the system.
875 *
876 * @par Constraints
877 * @parblock
878 * The following constraints apply to this directive:
879 *
880 * * The directive may be called from within device driver initialization
881 *   context.
882 *
883 * * The directive may be called from within task context.
884 *
885 * * The directive may obtain and release the object allocator mutex.  This may
886 *   cause the calling task to be preempted.
887 * @endparblock
888 */
889rtems_status_code rtems_scheduler_remove_processor(
890  rtems_id scheduler_id,
891  uint32_t cpu_index
892);
893
894/* Generated from spec:/rtems/task/if/create */
895
896/**
897 * @ingroup RTEMSAPIClassicTasks
898 *
899 * @brief Creates a task.
900 *
901 * @param name is the object name of the task.
902 *
903 * @param initial_priority is the initial task priority.
904 *
905 * @param stack_size is the task stack size in bytes.
906 *
907 * @param initial_modes is the initial mode set of the task.
908 *
909 * @param attribute_set is the attribute set of the task.
910 *
911 * @param[out] id is the pointer to an ::rtems_id object.  When the directive
912 *   call is successful, the identifier of the created task will be stored in
913 *   this object.
914 *
915 * This directive creates a task which resides on the local node.  The task has
916 * the user-defined object name specified in ``name``.  The assigned object
917 * identifier is returned in ``id``.  This identifier is used to access the
918 * task with other task related directives.
919 *
920 * The **initial priority** of the task is specified in ``initial_priority``.
921 * The scheduler of the created task is the scheduler of the calling task at
922 * some point during the task creation.  The initial task priority specified in
923 * ``initial_priority`` shall be valid for this scheduler.
924 *
925 * The **stack size** of the task is specified in ``stack_size``.  If the
926 * requested stack size is less than the configured minimum stack size, then
927 * RTEMS will use the configured minimum as the stack size for this task.  The
928 * configured minimum stack size is defined by the
929 * #CONFIGURE_MINIMUM_TASK_STACK_SIZE application configuration option.  In
930 * addition to being able to specify the task stack size as a integer, there
931 * are two constants which may be specified:
932 *
933 * * The #RTEMS_MINIMUM_STACK_SIZE constant can be specified to use the
934 *   **recommended minimum stack size** for the target processor.  This value
935 *   is selected by the RTEMS maintainers conservatively to minimize the risk
936 *   of blown stacks for most user applications.  Using this constant when
937 *   specifying the task stack size, indicates that the stack size will be at
938 *   least #RTEMS_MINIMUM_STACK_SIZE bytes in size.  If the user configured
939 *   minimum stack size is larger than the recommended minimum, then it will be
940 *   used.
941 *
942 * * The #RTEMS_CONFIGURED_MINIMUM_STACK_SIZE constant can be specified to use
943 *   the minimum stack size that was configured by the application.  If not
944 *   explicitly configured by the application, the default configured minimum
945 *   stack size is the target processor dependent value
946 *   #RTEMS_MINIMUM_STACK_SIZE.  Since this uses the configured minimum stack
947 *   size value, you may get a stack size that is smaller or larger than the
948 *   recommended minimum.  This can be used to provide large stacks for all
949 *   tasks on complex applications or small stacks on applications that are
950 *   trying to conserve memory.
951 *
952 * The **initial mode set** specified in ``initial_modes`` is built through a
953 * *bitwise or* of the mode constants described below.  Not all combinations of
954 * modes are allowed.  Some modes are mutually exclusive.  If mutually
955 * exclusive modes are combined, the behaviour is undefined.  Default task
956 * modes can be selected by using the #RTEMS_DEFAULT_MODES constant.  The task
957 * mode set defines
958 *
959 * * the preemption mode of the task: #RTEMS_PREEMPT (default) or
960 *   #RTEMS_NO_PREEMPT,
961 *
962 * * the timeslicing mode of the task: #RTEMS_TIMESLICE or #RTEMS_NO_TIMESLICE
963 *   (default),
964 *
965 * * the ASR processing mode of the task: #RTEMS_ASR (default) or
966 *   #RTEMS_NO_ASR,
967 *
968 * * the interrupt level of the task: RTEMS_INTERRUPT_LEVEL() with a default of
969 *   ``RTEMS_INTERRUPT_LEVEL( 0 )`` which is associated with enabled
970 *   interrupts.
971 *
972 * The **initial preemption mode** of the task is enabled or disabled.
973 *
974 * * An **enabled preemption** is the default and can be emphasized through the
975 *   use of the #RTEMS_PREEMPT mode constant.
976 *
977 * * A **disabled preemption** is set by the #RTEMS_NO_PREEMPT mode constant.
978 *
979 * The **initial timeslicing mode** of the task is enabled or disabled.
980 *
981 * * A **disabled timeslicing** is the default and can be emphasized through
982 *   the use of the #RTEMS_NO_TIMESLICE mode constant.
983 *
984 * * An **enabled timeslicing** is set by the #RTEMS_TIMESLICE mode constant.
985 *
986 * The **initial ASR processing mode** of the task is enabled or disabled.
987 *
988 * * An **enabled ASR processing** is the default and can be emphasized through
989 *   the use of the #RTEMS_ASR mode constant.
990 *
991 * * A **disabled ASR processing** is set by the #RTEMS_NO_ASR mode constant.
992 *
993 * The **initial interrupt level mode** of the task is defined by
994 * RTEMS_INTERRUPT_LEVEL().
995 *
996 * * Task execution with **interrupts enabled** the default and can be
997 *   emphasized through the use of the RTEMS_INTERRUPT_LEVEL() mode macro with
998 *   a value of zero (0) for the parameter.  An interrupt level of zero is
999 *   associated with enabled interrupts on all target processors.
1000 *
1001 * * Task execution at a **non-zero interrupt level** can be specified by the
1002 *   RTEMS_INTERRUPT_LEVEL() mode macro with a non-zero value for the
1003 *   parameter.  The interrupt level portion of the task mode supports a
1004 *   maximum of 256 interrupt levels.  These levels are mapped onto the
1005 *   interrupt levels actually supported by the target processor in a processor
1006 *   dependent fashion.
1007 *
1008 * The **attribute set** specified in ``attribute_set`` is built through a
1009 * *bitwise or* of the attribute constants described below.  Not all
1010 * combinations of attributes are allowed.  Some attributes are mutually
1011 * exclusive.  If mutually exclusive attributes are combined, the behaviour is
1012 * undefined.  Attributes not mentioned below are not evaluated by this
1013 * directive and have no effect.  Default attributes can be selected by using
1014 * the #RTEMS_DEFAULT_ATTRIBUTES constant.  The attribute set defines
1015 *
1016 * * the scope of the task: #RTEMS_LOCAL (default) or #RTEMS_GLOBAL and
1017 *
1018 * * the floating-point unit use of the task: #RTEMS_FLOATING_POINT or
1019 *   #RTEMS_NO_FLOATING_POINT (default).
1020 *
1021 * The task has a local or global **scope** in a multiprocessing network (this
1022 * attribute does not refer to SMP systems).  The scope is selected by the
1023 * mutually exclusive #RTEMS_LOCAL and #RTEMS_GLOBAL attributes.
1024 *
1025 * * A **local scope** is the default and can be emphasized through the use of
1026 *   the #RTEMS_LOCAL attribute.  A local task can be only used by the node
1027 *   which created it.
1028 *
1029 * * A **global scope** is established if the #RTEMS_GLOBAL attribute is set.
1030 *   Setting the global attribute in a single node system has no effect.the
1031 *
1032 * The **use of the floating-point unit** is selected by the mutually exclusive
1033 * #RTEMS_FLOATING_POINT and #RTEMS_NO_FLOATING_POINT attributes.  On some
1034 * target processors, the use of the floating-point unit can be enabled or
1035 * disabled for each task.  Other target processors may have no hardware
1036 * floating-point unit or enable the use of the floating-point unit for all
1037 * tasks.  Consult the *RTEMS CPU Architecture Supplement* for the details.
1038 *
1039 * * A **disabled floating-point unit** is the default and can be emphasized
1040 *   through use of the #RTEMS_NO_FLOATING_POINT attribute.  For performance
1041 *   reasons, it is recommended that tasks not using the floating-point unit
1042 *   should specify this attribute.
1043 *
1044 * * An **enabled floating-point unit** is selected by the
1045 *   #RTEMS_FLOATING_POINT attribute.
1046 *
1047 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1048 *
1049 * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was invalid.
1050 *
1051 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
1052 *
1053 * @retval ::RTEMS_INVALID_PRIORITY The ``initial_priority`` was invalid.
1054 *
1055 * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a
1056 *   task.  The number of tasks available to the application is configured
1057 *   through the #CONFIGURE_MAXIMUM_TASKS application configuration option.
1058 *
1059 * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no
1060 *   inactive global object available to create a global task.  The number of
1061 *   global objects available to the application is configured through the
1062 *   #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option.
1063 *
1064 * @retval ::RTEMS_UNSATISFIED There was not enough memory to allocate the task
1065 *   storage area.  The task storage area contains the task stack, the
1066 *   thread-local storage, and the floating point context.
1067 *
1068 * @retval ::RTEMS_UNSATISFIED One of the task create extensions failed to
1069 *   create the task.
1070 *
1071 * @retval ::RTEMS_UNSATISFIED In SMP configurations, the non-preemption mode
1072 *   was not supported.
1073 *
1074 * @retval ::RTEMS_UNSATISFIED In SMP configurations, the interrupt level mode
1075 *   was not supported.
1076 *
1077 * @par Notes
1078 * @parblock
1079 * The task processor affinity is initialized to the set of online processors.
1080 *
1081 * When created, a task is placed in the dormant state and can only be made
1082 * ready to execute using the directive rtems_task_start().
1083 *
1084 * Application developers should consider the stack usage of the device drivers
1085 * when calculating the stack size required for tasks which utilize the driver.
1086 * The task stack size shall account for an target processor dependent
1087 * interrupt stack frame which may be placed on the stack of the interrupted
1088 * task while servicing an interrupt.  The stack checker may be used to monitor
1089 * the stack usage, see #CONFIGURE_STACK_CHECKER_ENABLED.
1090 *
1091 * For control and maintenance of the task, RTEMS allocates a TCB from the
1092 * local TCB free pool and initializes it.
1093 *
1094 * The TCB for a global task is allocated on the local node.  Task should not
1095 * be made global unless remote tasks must interact with the task.  This is to
1096 * avoid the system overhead incurred by the creation of a global task.  When a
1097 * global task is created, the task's name and identifier must be transmitted
1098 * to every node in the system for insertion in the local copy of the global
1099 * object table.
1100 * @endparblock
1101 *
1102 * @par Constraints
1103 * @parblock
1104 * The following constraints apply to this directive:
1105 *
1106 * * The directive may be called from within device driver initialization
1107 *   context.
1108 *
1109 * * The directive may be called from within task context.
1110 *
1111 * * The directive may obtain and release the object allocator mutex.  This may
1112 *   cause the calling task to be preempted.
1113 *
1114 * * When the directive operates on a global object, the directive sends a
1115 *   message to remote nodes.  This may preempt the calling task.
1116 *
1117 * * The number of tasks available to the application is configured through the
1118 *   #CONFIGURE_MAXIMUM_TASKS application configuration option.
1119 *
1120 * * Where the object class corresponding to the directive is configured to use
1121 *   unlimited objects, the directive may allocate memory from the RTEMS
1122 *   Workspace.
1123 *
1124 * * The number of global objects available to the application is configured
1125 *   through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration
1126 *   option.
1127 * @endparblock
1128 */
1129rtems_status_code rtems_task_create(
1130  rtems_name          name,
1131  rtems_task_priority initial_priority,
1132  size_t              stack_size,
1133  rtems_mode          initial_modes,
1134  rtems_attribute     attribute_set,
1135  rtems_id           *id
1136);
1137
1138/* Generated from spec:/rtems/task/if/construct */
1139
1140/**
1141 * @ingroup RTEMSAPIClassicTasks
1142 *
1143 * @brief Constructs a task from the specified task configuration.
1144 *
1145 * @param config is the task configuration.
1146 *
1147 * @param[out] id is the pointer to an ::rtems_id object.  When the directive
1148 *   call is successful, the identifier of the constructed task will be stored
1149 *   in this object.
1150 *
1151 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1152 *
1153 * @retval ::RTEMS_INVALID_ADDRESS The ``config`` parameter was NULL.
1154 *
1155 * @retval ::RTEMS_INVALID_NAME The task name was invalid.
1156 *
1157 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
1158 *
1159 * @retval ::RTEMS_INVALID_PRIORITY The initial task priority was invalid.
1160 *
1161 * @retval ::RTEMS_INVALID_SIZE The thread-local storage size is greater than
1162 *   the maximum thread-local storage size specified in the task configuration.
1163 *   The thread-local storage size is determined by the thread-local variables
1164 *   used by the application and #CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE.
1165 *
1166 * @retval ::RTEMS_INVALID_SIZE The task storage area was too small to provide
1167 *   a task stack of the configured minimum size, see
1168 *   #CONFIGURE_MINIMUM_TASK_STACK_SIZE. The task storage area contains the
1169 *   task stack, the thread-local storage, and the floating-point context on
1170 *   architectures with a separate floating-point context.
1171 *
1172 * @retval ::RTEMS_TOO_MANY There was no inactive task object available to
1173 *   construct a task.
1174 *
1175 * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no
1176 *   inactive global object available to construct a global task.
1177 *
1178 * @retval ::RTEMS_UNSATISFIED One of the task create extensions failed during
1179 *   the task construction.
1180 *
1181 * @retval ::RTEMS_UNSATISFIED In SMP configurations, the non-preemption mode
1182 *   was not supported.
1183 *
1184 * @retval ::RTEMS_UNSATISFIED In SMP configurations, the interrupt level mode
1185 *   was not supported.
1186 *
1187 * @par Notes
1188 * @parblock
1189 * In contrast to tasks created by rtems_task_create(), the tasks constructed
1190 * by this directive use a user-provided task storage area.  The task storage
1191 * area contains the task stack, the thread-local storage, and the
1192 * floating-point context on architectures with a separate floating-point
1193 * context.
1194 *
1195 * This directive is intended for applications which do not want to use the
1196 * RTEMS Workspace and instead statically allocate all operating system
1197 * resources.  It is not recommended to use rtems_task_create() and
1198 * rtems_task_construct() together in an application.  It is also not
1199 * recommended to use rtems_task_construct() for drivers or general purpose
1200 * libraries.  The reason for these recommendations is that the task
1201 * configuration needs settings which can be only given with a through
1202 * knowledge of the application resources.
1203 *
1204 * An application based solely on static allocation can avoid any runtime
1205 * memory allocators.  This can simplify the application architecture as well
1206 * as any analysis that may be required.
1207 *
1208 * The stack space estimate done by <rtems/confdefs.h> assumes that all tasks
1209 * are created by rtems_task_create().  The estimate can be adjusted to take
1210 * user-provided task storage areas into account through the
1211 * #CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE application
1212 * configuration option.
1213 *
1214 * The #CONFIGURE_MAXIMUM_TASKS should include tasks constructed by
1215 * rtems_task_construct().
1216 * @endparblock
1217 *
1218 * @par Constraints
1219 * @parblock
1220 * The following constraints apply to this directive:
1221 *
1222 * * The directive may be called from within device driver initialization
1223 *   context.
1224 *
1225 * * The directive may be called from within task context.
1226 *
1227 * * The directive may obtain and release the object allocator mutex.  This may
1228 *   cause the calling task to be preempted.
1229 *
1230 * * When the directive operates on a global object, the directive sends a
1231 *   message to remote nodes.  This may preempt the calling task.
1232 *
1233 * * The number of tasks available to the application is configured through the
1234 *   #CONFIGURE_MAXIMUM_TASKS application configuration option.
1235 *
1236 * * Where the object class corresponding to the directive is configured to use
1237 *   unlimited objects, the directive may allocate memory from the RTEMS
1238 *   Workspace.
1239 *
1240 * * The number of global objects available to the application is configured
1241 *   through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration
1242 *   option.
1243 * @endparblock
1244 */
1245rtems_status_code rtems_task_construct(
1246  const rtems_task_config *config,
1247  rtems_id                *id
1248);
1249
1250/* Generated from spec:/rtems/task/if/ident */
1251
1252/**
1253 * @ingroup RTEMSAPIClassicTasks
1254 *
1255 * @brief Identifies a task by the object name.
1256 *
1257 * @param name is the object name to look up.
1258 *
1259 * @param node is the node or node set to search for a matching object.
1260 *
1261 * @param[out] id is the pointer to an ::rtems_id object.  When the directive
1262 *   call is successful, the object identifier of an object with the specified
1263 *   name will be stored in this object.
1264 *
1265 * This directive obtains a task identifier associated with the task name
1266 * specified in ``name``.
1267 *
1268 * A task may obtain its own identifier by specifying #RTEMS_SELF for the name.
1269 *
1270 * The node to search is specified in ``node``.  It shall be
1271 *
1272 * * a valid node number,
1273 *
1274 * * the constant #RTEMS_SEARCH_ALL_NODES to search in all nodes,
1275 *
1276 * * the constant #RTEMS_SEARCH_LOCAL_NODE to search in the local node only, or
1277 *
1278 * * the constant #RTEMS_SEARCH_OTHER_NODES to search in all nodes except the
1279 *   local node.
1280 *
1281 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1282 *
1283 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
1284 *
1285 * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
1286 *   the specified nodes.
1287 *
1288 * @retval ::RTEMS_INVALID_NODE In multiprocessing configurations, the
1289 *   specified node was invalid.
1290 *
1291 * @par Notes
1292 * @parblock
1293 * If the task name is not unique, then the task identifier will match the
1294 * first task with that name in the search order.  However, this task
1295 * identifier is not guaranteed to correspond to the desired task.
1296 *
1297 * The objects are searched from lowest to the highest index.  If ``node`` is
1298 * #RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local node being
1299 * searched first.  All other nodes are searched from lowest to the highest
1300 * node number.
1301 *
1302 * If node is a valid node number which does not represent the local node, then
1303 * only the tasks exported by the designated node are searched.
1304 *
1305 * This directive does not generate activity on remote nodes.  It accesses only
1306 * the local copy of the global object table.
1307 *
1308 * The task identifier is used with other task related directives to access the
1309 * task.
1310 * @endparblock
1311 *
1312 * @par Constraints
1313 * @parblock
1314 * The following constraints apply to this directive:
1315 *
1316 * * The directive may be called from within any runtime context.
1317 *
1318 * * The directive will not cause the calling task to be preempted.
1319 * @endparblock
1320 */
1321rtems_status_code rtems_task_ident(
1322  rtems_name name,
1323  uint32_t   node,
1324  rtems_id  *id
1325);
1326
1327/* Generated from spec:/rtems/task/if/self */
1328
1329/**
1330 * @ingroup RTEMSAPIClassicTasks
1331 *
1332 * @brief Gets the task identifier of the calling task.
1333 *
1334 * This directive returns the task identifier of the calling task.
1335 *
1336 * @return Returns the task identifier of the calling task.
1337 *
1338 * @par Constraints
1339 * @parblock
1340 * The following constraints apply to this directive:
1341 *
1342 * * The directive may be called from within device driver initialization
1343 *   context.
1344 *
1345 * * The directive may be called from within task context.
1346 *
1347 * * The directive will not cause the calling task to be preempted.
1348 * @endparblock
1349 */
1350rtems_id rtems_task_self( void );
1351
1352/* Generated from spec:/rtems/task/if/start */
1353
1354/**
1355 * @ingroup RTEMSAPIClassicTasks
1356 *
1357 * @brief Starts the task.
1358 *
1359 * @param id is the task identifier.  The constant #RTEMS_SELF may be used to
1360 *   specify the calling task.
1361 *
1362 * @param entry_point is the task entry point.
1363 *
1364 * @param argument is the task entry point argument.
1365 *
1366 * This directive readies the task, specified by ``id``, for execution based on
1367 * the priority and execution mode specified when the task was created.  The
1368 * entry point of the task is given in ``entry_point``. The task's entry point
1369 * argument is contained in ``argument``.
1370 *
1371 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1372 *
1373 * @retval ::RTEMS_INVALID_ADDRESS The ``entry_point`` parameter was NULL.
1374 *
1375 * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier
1376 *   specified by ``id``.
1377 *
1378 * @retval ::RTEMS_INCORRECT_STATE The task was not in the dormant state.
1379 *
1380 * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node.
1381 *
1382 * @par Notes
1383 * @parblock
1384 * The type of the entry point argument is an unsigned integer type.  However,
1385 * the integer type has the property that any valid pointer to ``void`` can be
1386 * converted to this type and then converted back to a pointer to ``void``.
1387 * The result will compare equal to the original pointer.  The type can
1388 * represent at least 32 bits.  Some applications use the entry point argument
1389 * as an index into a parameter table to get task-specific parameters.
1390 *
1391 * Any actions performed on a dormant task such as suspension or change of
1392 * priority are nullified when the task is initiated via the rtems_task_start()
1393 * directive.
1394 * @endparblock
1395 *
1396 * @par Constraints
1397 * @parblock
1398 * The following constraints apply to this directive:
1399 *
1400 * * The directive may be called from within interrupt context.
1401 *
1402 * * The directive may be called from within device driver initialization
1403 *   context.
1404 *
1405 * * The directive may be called from within task context.
1406 *
1407 * * The directive may unblock a task.  This may cause the calling task to be
1408 *   preempted.
1409 * @endparblock
1410 */
1411rtems_status_code rtems_task_start(
1412  rtems_id            id,
1413  rtems_task_entry    entry_point,
1414  rtems_task_argument argument
1415);
1416
1417/* Generated from spec:/rtems/task/if/restart */
1418
1419/**
1420 * @ingroup RTEMSAPIClassicTasks
1421 *
1422 * @brief Restarts the task.
1423 *
1424 * @param id is the task identifier.  The constant #RTEMS_SELF may be used to
1425 *   specify the calling task.
1426 *
1427 * @param argument is the task entry point argument.
1428 *
1429 * This directive resets the task specified by ``id`` to begin execution at its
1430 * original entry point.  The task's priority and execution mode are set to the
1431 * original creation values.  If the task is currently blocked, RTEMS
1432 * automatically makes the task ready.  A task can be restarted from any state,
1433 * except the dormant state.  The task's entry point argument is contained in
1434 * ``argument``.
1435 *
1436 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1437 *
1438 * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier
1439 *   specified by ``id``.
1440 *
1441 * @retval ::RTEMS_INCORRECT_STATE The task never started.
1442 *
1443 * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node.
1444 *
1445 * @par Notes
1446 * @parblock
1447 * The type of the entry point argument is an unsigned integer type.  However,
1448 * the integer type has the property that any valid pointer to ``void`` can be
1449 * converted to this type and then converted back to a pointer to ``void``.
1450 * The result will compare equal to the original pointer.  The type can
1451 * represent at least 32 bits.  Some applications use the entry point argument
1452 * as an index into a parameter table to get task-specific parameters.
1453 *
1454 * A new entry point argument may be used to distinguish between the initial
1455 * rtems_task_start() of the task and any ensuing calls to rtems_task_restart()
1456 * of the task.  This can be beneficial in deleting a task.  Instead of
1457 * deleting a task using the rtems_task_delete() directive, a task can delete
1458 * another task by restarting that task, and allowing that task to release
1459 * resources back to RTEMS and then delete itself.
1460 * @endparblock
1461 *
1462 * @par Constraints
1463 * @parblock
1464 * The following constraints apply to this directive:
1465 *
1466 * * The directive may be called from within interrupt context.
1467 *
1468 * * The directive may be called from within device driver initialization
1469 *   context.
1470 *
1471 * * The directive may be called from within task context.
1472 *
1473 * * The directive may change the priority of a task.  This may cause the
1474 *   calling task to be preempted.
1475 *
1476 * * The directive may unblock a task.  This may cause the calling task to be
1477 *   preempted.
1478 * @endparblock
1479 */
1480rtems_status_code rtems_task_restart(
1481  rtems_id            id,
1482  rtems_task_argument argument
1483);
1484
1485/* Generated from spec:/rtems/task/if/delete */
1486
1487/**
1488 * @ingroup RTEMSAPIClassicTasks
1489 *
1490 * @brief Deletes the task.
1491 *
1492 * @param id is the task identifier.  The constant #RTEMS_SELF may be used to
1493 *   specify the calling task.
1494 *
1495 * This directive deletes the task, either the calling task or another task, as
1496 * specified by ``id``.
1497 *
1498 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1499 *
1500 * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier
1501 *   specified by ``id``.
1502 *
1503 * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within
1504 *   interrupt context.
1505 *
1506 * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node.
1507 *
1508 * @par Notes
1509 * @parblock
1510 * RTEMS stops the execution of the task and reclaims the stack memory, any
1511 * allocated delay or timeout timers, the TCB, and, if the task is
1512 * #RTEMS_FLOATING_POINT, its floating point context area. RTEMS explicitly
1513 * does not reclaim the following resources: region segments, partition
1514 * buffers, semaphores, timers, or rate monotonic periods.
1515 *
1516 * A task is responsible for releasing its resources back to RTEMS before
1517 * deletion.  To insure proper deallocation of resources, a task should not be
1518 * deleted unless it is unable to execute or does not hold any RTEMS resources.
1519 * If a task holds RTEMS resources, the task should be allowed to deallocate
1520 * its resources before deletion.  A task can be directed to release its
1521 * resources and delete itself by restarting it with a special argument or by
1522 * sending it a message, an event, or a signal.
1523 *
1524 * Deletion of the current task (#RTEMS_SELF) will force RTEMS to select
1525 * another task to execute.
1526 *
1527 * The TCB for the deleted task is reclaimed by RTEMS.
1528 *
1529 * When a global task is deleted, the task identifier must be transmitted to
1530 * every node in the system for deletion from the local copy of the global
1531 * object table.
1532 *
1533 * The task must reside on the local node, even if the task was created with
1534 * the #RTEMS_GLOBAL attribute.
1535 * @endparblock
1536 *
1537 * @par Constraints
1538 * @parblock
1539 * The following constraints apply to this directive:
1540 *
1541 * * The directive may be called from within device driver initialization
1542 *   context.
1543 *
1544 * * The directive may be called from within task context.
1545 *
1546 * * The directive may obtain and release the object allocator mutex.  This may
1547 *   cause the calling task to be preempted.
1548 *
1549 * * When the directive operates on a global object, the directive sends a
1550 *   message to remote nodes.  This may preempt the calling task.
1551 *
1552 * * The calling task does not have to be the task that created the object.
1553 *   Any local task that knows the object identifier can delete the object.
1554 *
1555 * * Where the object class corresponding to the directive is configured to use
1556 *   unlimited objects, the directive may free memory to the RTEMS Workspace.
1557 * @endparblock
1558 */
1559rtems_status_code rtems_task_delete( rtems_id id );
1560
1561/* Generated from spec:/rtems/task/if/exit */
1562
1563/**
1564 * @ingroup RTEMSAPIClassicTasks
1565 *
1566 * @brief Deletes the calling task.
1567 *
1568 * This directive deletes the calling task.
1569 *
1570 * @par Notes
1571 * @parblock
1572 * The directive is an optimized variant of the following code sequences, see
1573 * also rtems_task_delete():
1574 *
1575 * @code
1576 * #include <pthread.h>
1577 * #include <rtems.h>
1578 *
1579 * void classic_delete_self( void )
1580 * {
1581 *   (void) rtems_task_delete( RTEMS_SELF );
1582 * }
1583 *
1584 * void posix_delete_self( void )
1585 * {
1586 *   (void) pthread_detach( pthread_self() );
1587 *   (void) pthread_exit( NULL);
1588 * }
1589 * @endcode
1590 * @endparblock
1591 *
1592 * @par Constraints
1593 * @parblock
1594 * The following constraints apply to this directive:
1595 *
1596 * * The directive may be called from within task context.
1597 *
1598 * * The directive will not return to the caller.
1599 *
1600 * * While thread dispatching is disabled, if the directive performs a thread
1601 *   dispatch, then the fatal error with the fatal source INTERNAL_ERROR_CORE
1602 *   and the fatal code INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL will
1603 *   occur.
1604 * @endparblock
1605 */
1606RTEMS_NO_RETURN void rtems_task_exit( void );
1607
1608/* Generated from spec:/rtems/task/if/suspend */
1609
1610/**
1611 * @ingroup RTEMSAPIClassicTasks
1612 *
1613 * @brief Suspends the task.
1614 *
1615 * @param id is the task identifier.  The constant #RTEMS_SELF may be used to
1616 *   specify the calling task.
1617 *
1618 * This directive suspends the task specified by ``id`` from further execution
1619 * by placing it in the suspended state.  This state is additive to any other
1620 * blocked state that the task may already be in.  The task will not execute
1621 * again until another task issues the rtems_task_resume() directive for this
1622 * task and any blocked state has been removed.  The rtems_task_restart()
1623 * directive will also remove the suspended state.
1624 *
1625 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1626 *
1627 * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier
1628 *   specified by ``id``.
1629 *
1630 * @retval ::RTEMS_ALREADY_SUSPENDED The task was already suspended.
1631 *
1632 * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node.
1633 *
1634 * @par Notes
1635 * The requesting task can suspend itself for example by specifying #RTEMS_SELF
1636 * as ``id``.  In this case, the task will be suspended and a successful return
1637 * code will be returned when the task is resumed.
1638 *
1639 * @par Constraints
1640 * @parblock
1641 * The following constraints apply to this directive:
1642 *
1643 * * The directive may be called from within interrupt context.
1644 *
1645 * * The directive may be called from within device driver initialization
1646 *   context.
1647 *
1648 * * The directive may be called from within task context.
1649 *
1650 * * When the directive operates on a remote object, the directive sends a
1651 *   message to the remote node and waits for a reply.  This will preempt the
1652 *   calling task.
1653 * @endparblock
1654 */
1655rtems_status_code rtems_task_suspend( rtems_id id );
1656
1657/* Generated from spec:/rtems/task/if/resume */
1658
1659/**
1660 * @ingroup RTEMSAPIClassicTasks
1661 *
1662 * @brief Resumes the task.
1663 *
1664 * @param id is the task identifier.
1665 *
1666 * This directive removes the task specified by ``id`` from the suspended
1667 * state.  If the task is in the ready state after the suspension is removed,
1668 * then it will be scheduled to run.  If the task is still in a blocked state
1669 * after the suspension is removed, then it will remain in that blocked state.
1670 *
1671 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1672 *
1673 * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier
1674 *   specified by ``id``.
1675 *
1676 * @retval ::RTEMS_INCORRECT_STATE The task was not suspended.
1677 *
1678 * @par Constraints
1679 * @parblock
1680 * The following constraints apply to this directive:
1681 *
1682 * * The directive may be called from within interrupt context.
1683 *
1684 * * The directive may be called from within device driver initialization
1685 *   context.
1686 *
1687 * * The directive may be called from within task context.
1688 *
1689 * * The directive may unblock a task.  This may cause the calling task to be
1690 *   preempted.
1691 *
1692 * * When the directive operates on a remote object, the directive sends a
1693 *   message to the remote node and waits for a reply.  This will preempt the
1694 *   calling task.
1695 * @endparblock
1696 */
1697rtems_status_code rtems_task_resume( rtems_id id );
1698
1699/* Generated from spec:/rtems/task/if/is-suspended */
1700
1701/**
1702 * @ingroup RTEMSAPIClassicTasks
1703 *
1704 * @brief Checks if the task is suspended.
1705 *
1706 * @param id is the task identifier.  The constant #RTEMS_SELF may be used to
1707 *   specify the calling task.
1708 *
1709 * This directive returns a status code indicating whether or not the task
1710 * specified by ``id`` is currently suspended.
1711 *
1712 * @retval ::RTEMS_SUCCESSFUL The task was **not** suspended.
1713 *
1714 * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier
1715 *   specified by ``id``.
1716 *
1717 * @retval ::RTEMS_ALREADY_SUSPENDED The task was suspended.
1718 *
1719 * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node.
1720 *
1721 * @par Constraints
1722 * @parblock
1723 * The following constraints apply to this directive:
1724 *
1725 * * The directive may be called from within interrupt context.
1726 *
1727 * * The directive may be called from within device driver initialization
1728 *   context.
1729 *
1730 * * The directive may be called from within task context.
1731 *
1732 * * The directive will not cause the calling task to be preempted.
1733 * @endparblock
1734 */
1735rtems_status_code rtems_task_is_suspended( rtems_id id );
1736
1737/* Generated from spec:/rtems/task/if/set-priority */
1738
1739/**
1740 * @ingroup RTEMSAPIClassicTasks
1741 *
1742 * @brief Sets the real priority or gets the current priority of the task.
1743 *
1744 * @param id is the task identifier.  The constant #RTEMS_SELF may be used to
1745 *   specify the calling task.
1746 *
1747 * @param new_priority is the new real priority or #RTEMS_CURRENT_PRIORITY to
1748 *   get the current priority.
1749 *
1750 * @param[out] old_priority is the pointer to an ::rtems_task_priority object.
1751 *   When the directive call is successful, the current or previous priority of
1752 *   the task with respect to its home scheduler will be stored in this object.
1753 *
1754 * This directive manipulates the priority of the task specified by ``id``.
1755 * When ``new_priority`` is not equal to #RTEMS_CURRENT_PRIORITY, the specified
1756 * task's previous priority is returned in ``old_priority``.  When
1757 * ``new_priority`` is #RTEMS_CURRENT_PRIORITY, the specified task's current
1758 * priority is returned in ``old_priority``.
1759 *
1760 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1761 *
1762 * @retval ::RTEMS_INVALID_ADDRESS The ``old_priority`` parameter was NULL.
1763 *
1764 * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier
1765 *   specified by ``id``.
1766 *
1767 * @retval ::RTEMS_INVALID_PRIORITY The task priority specified in
1768 *   ``new_priority`` was invalid with respect to the home scheduler of the
1769 *   task.
1770 *
1771 * @par Notes
1772 * @parblock
1773 * Valid priorities range from one to a maximum value which depends on the
1774 * configured scheduler.  The lower the priority value the higher is the
1775 * importance of the task.
1776 *
1777 * If the task is currently holding any binary semaphores which use a locking
1778 * protocol, then the task's priority cannot be lowered immediately.  If the
1779 * task's priority were lowered immediately, then this could violate properties
1780 * of the locking protocol and may result in priority inversion.  The requested
1781 * lowering of the task's priority will occur when the task has released all
1782 * binary semaphores which make the task more important.  The task's priority
1783 * can be increased regardless of the task's use of binary semaphores with
1784 * locking protocols.
1785 * @endparblock
1786 *
1787 * @par Constraints
1788 * @parblock
1789 * The following constraints apply to this directive:
1790 *
1791 * * The directive may be called from within interrupt context.
1792 *
1793 * * The directive may be called from within device driver initialization
1794 *   context.
1795 *
1796 * * The directive may be called from within task context.
1797 *
1798 * * The directive may change the priority of a task.  This may cause the
1799 *   calling task to be preempted.
1800 *
1801 * * When the directive operates on a remote object, the directive sends a
1802 *   message to the remote node and waits for a reply.  This will preempt the
1803 *   calling task.
1804 * @endparblock
1805 */
1806rtems_status_code rtems_task_set_priority(
1807  rtems_id             id,
1808  rtems_task_priority  new_priority,
1809  rtems_task_priority *old_priority
1810);
1811
1812/* Generated from spec:/rtems/task/if/get-priority */
1813
1814/**
1815 * @ingroup RTEMSAPIClassicTasks
1816 *
1817 * @brief Gets the current priority of the task with respect to the scheduler.
1818 *
1819 * @param task_id is the task identifier.  The constant #RTEMS_SELF may be used
1820 *   to specify the calling task.
1821 *
1822 * @param scheduler_id is the scheduler identifier.
1823 *
1824 * @param[out] priority is the pointer to an ::rtems_task_priority object.
1825 *   When the directive call is successful, the current priority of the task
1826 *   with respect to the specified scheduler will be stored in this object.
1827 *
1828 * This directive returns the current priority in ``priority`` of the task
1829 * specified by ``task_id`` with respect to the scheduler specified by
1830 * ``scheduler_id``.
1831 *
1832 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1833 *
1834 * @retval ::RTEMS_INVALID_ADDRESS The ``priority`` parameter was NULL.
1835 *
1836 * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier
1837 *   specified by ``task_id``.
1838 *
1839 * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the
1840 *   identifier specified by ``scheduler_id``.
1841 *
1842 * @retval ::RTEMS_NOT_DEFINED The task had no priority with respect to the
1843 *   scheduler.
1844 *
1845 * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node.
1846 *
1847 * @par Notes
1848 * The current priority reflects temporary priority adjustments due to locking
1849 * protocols, the rate-monotonic period objects on some schedulers such as EDF,
1850 * and the POSIX sporadic server.
1851 *
1852 * @par Constraints
1853 * @parblock
1854 * The following constraints apply to this directive:
1855 *
1856 * * The directive may be called from within interrupt context.
1857 *
1858 * * The directive may be called from within device driver initialization
1859 *   context.
1860 *
1861 * * The directive may be called from within task context.
1862 *
1863 * * The directive will not cause the calling task to be preempted.
1864 * @endparblock
1865 */
1866rtems_status_code rtems_task_get_priority(
1867  rtems_id             task_id,
1868  rtems_id             scheduler_id,
1869  rtems_task_priority *priority
1870);
1871
1872/* Generated from spec:/rtems/task/if/mode */
1873
1874/**
1875 * @ingroup RTEMSAPIClassicTasks
1876 *
1877 * @brief Gets and optionally sets the mode of the calling task.
1878 *
1879 * @param mode_set is the mode set to apply to the calling task.  When ``mask``
1880 *   is set to #RTEMS_CURRENT_MODE, the value of this parameter is ignored.
1881 *   Only modes requested by ``mask`` are applied to the calling task.
1882 *
1883 * @param mask is the mode mask which specifies which modes in ``mode_set`` are
1884 *   applied to the calling task.  When the value is #RTEMS_CURRENT_MODE, the
1885 *   mode of the calling task is not changed.
1886 *
1887 * @param previous_mode_set is the pointer to an ::rtems_mode object.  When the
1888 *   directive call is successful, the mode of the task before any mode changes
1889 *   done by the directive call will be stored in this object.
1890 *
1891 * This directive queries and optionally manipulates the execution mode of the
1892 * calling task.  A task's execution mode enables and disables preemption,
1893 * timeslicing, asynchronous signal processing, as well as specifying the
1894 * interrupt level.  To modify an execution mode, the mode class(es) to be
1895 * changed must be specified in the ``mask`` parameter and the desired mode(s)
1896 * must be specified in the ``mode_set`` parameter.
1897 *
1898 * A task can obtain its current execution mode, without modifying it, by
1899 * calling this directive with a ``mask`` value of #RTEMS_CURRENT_MODE.
1900 *
1901 * The **mode set** specified in ``mode_set`` is built through a *bitwise or*
1902 * of the mode constants described below.  Not all combinations of modes are
1903 * allowed.  Some modes are mutually exclusive.  If mutually exclusive modes
1904 * are combined, the behaviour is undefined.  Default task modes can be
1905 * selected by using the #RTEMS_DEFAULT_MODES constant.  The task mode set
1906 * defines
1907 *
1908 * * the preemption mode of the task: #RTEMS_PREEMPT (default) or
1909 *   #RTEMS_NO_PREEMPT,
1910 *
1911 * * the timeslicing mode of the task: #RTEMS_TIMESLICE or #RTEMS_NO_TIMESLICE
1912 *   (default),
1913 *
1914 * * the ASR processing mode of the task: #RTEMS_ASR (default) or
1915 *   #RTEMS_NO_ASR,
1916 *
1917 * * the interrupt level of the task: RTEMS_INTERRUPT_LEVEL() with a default of
1918 *   ``RTEMS_INTERRUPT_LEVEL( 0 )`` which is associated with enabled
1919 *   interrupts.
1920 *
1921 * The **mode mask** specified in ``mask`` is built through a *bitwise or* of
1922 * the mode mask constants described below.
1923 *
1924 * When the #RTEMS_PREEMPT_MASK is set in ``mask``, the **preemption mode** of
1925 * the calling task is
1926 *
1927 * * enabled by using the #RTEMS_PREEMPT mode constant in ``mode_set`` and
1928 *
1929 * * disabled by using the #RTEMS_NO_PREEMPT mode constant in ``mode_set``.
1930 *
1931 * When the #RTEMS_TIMESLICE_MASK is set in ``mask``, the **timeslicing mode**
1932 * of the calling task is
1933 *
1934 * * enabled by using the #RTEMS_TIMESLICE mode constant in ``mode_set`` and
1935 *
1936 * * disabled by using the #RTEMS_NO_TIMESLICE mode constant in ``mode_set``.
1937 *
1938 * Enabling timeslicing has no effect if preemption is disabled.  For a task to
1939 * be timesliced, that task must have both preemption and timeslicing enabled.
1940 *
1941 * When the #RTEMS_ASR_MASK is set in ``mask``, the **ASR processing mode** of
1942 * the calling task is
1943 *
1944 * * enabled by using the #RTEMS_ASR mode constant in ``mode_set`` and
1945 *
1946 * * disabled by using the #RTEMS_NO_ASR mode constant in ``mode_set``.
1947 *
1948 * When the #RTEMS_INTERRUPT_MASK is set in ``mask``, **interrupts** of the
1949 * calling task are
1950 *
1951 * * enabled by using the RTEMS_INTERRUPT_LEVEL() mode macro with a value of
1952 *   zero (0) in ``mode_set`` and
1953 *
1954 * * disabled up to the specified level by using the RTEMS_INTERRUPT_LEVEL()
1955 *   mode macro with a positive value in ``mode_set``.
1956 *
1957 * An interrupt level of zero is associated with enabled interrupts on all
1958 * target processors.  The interrupt level portion of the task mode supports a
1959 * maximum of 256 interrupt levels.  These levels are mapped onto the interrupt
1960 * levels actually supported by the target processor in a processor dependent
1961 * fashion.
1962 *
1963 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1964 *
1965 * @retval ::RTEMS_NOT_IMPLEMENTED The #RTEMS_NO_PREEMPT was set in
1966 *   ``mode_set`` and setting the preemption mode was requested by
1967 *   #RTEMS_PREEMPT_MASK in ``mask`` and the system configuration had no
1968 *   implementation for this mode.
1969 *
1970 * @retval ::RTEMS_NOT_IMPLEMENTED The RTEMS_INTERRUPT_LEVEL() was set to a
1971 *   positive level in ``mode_set`` and setting the interrupt level was
1972 *   requested by #RTEMS_INTERRUPT_MASK in ``mask`` and the system
1973 *   configuration had no implementation for this mode.
1974 *
1975 * @par Constraints
1976 * @parblock
1977 * The following constraints apply to this directive:
1978 *
1979 * * The directive may be called from within task context.
1980 *
1981 * * When the directive enables preemption for the calling task, another task
1982 *   may preempt the calling task.
1983 *
1984 * * While thread dispatching is disabled, if the directive performs a thread
1985 *   dispatch, then the fatal error with the fatal source INTERNAL_ERROR_CORE
1986 *   and the fatal code INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL will
1987 *   occur.
1988 * @endparblock
1989 */
1990rtems_status_code rtems_task_mode(
1991  rtems_mode  mode_set,
1992  rtems_mode  mask,
1993  rtems_mode *previous_mode_set
1994);
1995
1996/* Generated from spec:/rtems/task/if/wake-after */
1997
1998/**
1999 * @ingroup RTEMSAPIClassicTasks
2000 *
2001 * @brief Wakes up after an interval in clock ticks or yields the processor.
2002 *
2003 * @param ticks is the interval in clock ticks to delay the task or
2004 *   #RTEMS_YIELD_PROCESSOR to yield the processor.
2005 *
2006 * This directive blocks the calling task for the specified ``ticks`` of clock
2007 * ticks if the value is not equal to #RTEMS_YIELD_PROCESSOR.  When the
2008 * requested interval has elapsed, the task is made ready.  The clock tick
2009 * directives automatically updates the delay period.  The calling task may
2010 * give up the processor and remain in the ready state by specifying a value of
2011 * #RTEMS_YIELD_PROCESSOR in ``ticks``.
2012 *
2013 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2014 *
2015 * @par Notes
2016 * Setting the system date and time with the rtems_clock_set() directive and
2017 * similar directives which set CLOCK_REALTIME have no effect on a
2018 * rtems_task_wake_after() blocked task.
2019 *
2020 * @par Constraints
2021 * @parblock
2022 * The following constraints apply to this directive:
2023 *
2024 * * The directive may be called from within task context.
2025 *
2026 * * The directive requires a Clock Driver.
2027 *
2028 * * While thread dispatching is disabled, if the directive performs a thread
2029 *   dispatch, then the fatal error with the fatal source INTERNAL_ERROR_CORE
2030 *   and the fatal code INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL will
2031 *   occur.
2032 * @endparblock
2033 */
2034rtems_status_code rtems_task_wake_after( rtems_interval ticks );
2035
2036/* Generated from spec:/rtems/task/if/wake-when */
2037
2038/**
2039 * @ingroup RTEMSAPIClassicTasks
2040 *
2041 * @brief Wakes up when specified.
2042 *
2043 * @param time_buffer is the date and time to wake up.
2044 *
2045 * This directive blocks a task until the date and time specified in
2046 * ``time_buffer``.  At the requested date and time, the calling task will be
2047 * unblocked and made ready to execute.
2048 *
2049 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2050 *
2051 * @retval ::RTEMS_NOT_DEFINED The system date and time was not set.
2052 *
2053 * @retval ::RTEMS_INVALID_ADDRESS The ``time_buffer`` parameter was NULL.
2054 *
2055 * @retval ::RTEMS_INVALID_CLOCK The time of day was invalid.
2056 *
2057 * @par Notes
2058 * The ticks portion of ``time_buffer`` structure is ignored.  The timing
2059 * granularity of this directive is a second.
2060 *
2061 * @par Constraints
2062 * @parblock
2063 * The following constraints apply to this directive:
2064 *
2065 * * The directive may be called from within task context.
2066 *
2067 * * The directive requires a Clock Driver.
2068 *
2069 * * While thread dispatching is disabled, if the directive performs a thread
2070 *   dispatch, then the fatal error with the fatal source INTERNAL_ERROR_CORE
2071 *   and the fatal code INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL will
2072 *   occur.
2073 * @endparblock
2074 */
2075rtems_status_code rtems_task_wake_when( const rtems_time_of_day *time_buffer );
2076
2077/* Generated from spec:/rtems/task/if/get-scheduler */
2078
2079/**
2080 * @ingroup RTEMSAPIClassicTasks
2081 *
2082 * @brief Gets the home scheduler of the task.
2083 *
2084 * @param task_id is the task identifier.  The constant #RTEMS_SELF may be used
2085 *   to specify the calling task.
2086 *
2087 * @param[out] scheduler_id is the pointer to an ::rtems_id object.  When the
2088 *   directive call is successful, the identifier of the home scheduler of the
2089 *   task will be stored in this object.
2090 *
2091 * This directive returns the identifier of the home scheduler of the task
2092 * specified by ``task_id`` in ``scheduler_id``.
2093 *
2094 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2095 *
2096 * @retval ::RTEMS_INVALID_ADDRESS The ``scheduler_id`` parameter was NULL.
2097 *
2098 * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier
2099 *   specified by ``task_id``.
2100 *
2101 * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node.
2102 *
2103 * @par Constraints
2104 * @parblock
2105 * The following constraints apply to this directive:
2106 *
2107 * * The directive may be called from within interrupt context.
2108 *
2109 * * The directive may be called from within device driver initialization
2110 *   context.
2111 *
2112 * * The directive may be called from within task context.
2113 *
2114 * * The directive will not cause the calling task to be preempted.
2115 * @endparblock
2116 */
2117rtems_status_code rtems_task_get_scheduler(
2118  rtems_id  task_id,
2119  rtems_id *scheduler_id
2120);
2121
2122/* Generated from spec:/rtems/task/if/set-scheduler */
2123
2124/**
2125 * @ingroup RTEMSAPIClassicTasks
2126 *
2127 * @brief Sets the home scheduler for the task.
2128 *
2129 * @param task_id is the task identifier.  The constant #RTEMS_SELF may be used
2130 *   to specify the calling task.
2131 *
2132 * @param scheduler_id is the scheduler identifier of the new home scheduler
2133 *   for the task specified by ``task_id``.
2134 *
2135 * @param priority is the new real priority for the task with respect to the
2136 *   scheduler specified by ``scheduler_id``.
2137 *
2138 * This directive sets the home scheduler to the scheduler specified by
2139 * ``scheduler_id`` for the task specified by ``task_id``.
2140 *
2141 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2142 *
2143 * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the
2144 *   identifier specified by ``scheduler_id``.
2145 *
2146 * @retval ::RTEMS_INVALID_PRIORITY The task priority specified by ``priority``
2147 *   was invalid with respect to the scheduler specified by ``scheduler_id``.
2148 *
2149 * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier
2150 *   specified by ``task_id``.
2151 *
2152 * @retval ::RTEMS_RESOURCE_IN_USE The task specified by ``task_id`` was
2153 *   enqueued on a wait queue.
2154 *
2155 * @retval ::RTEMS_RESOURCE_IN_USE The task specified by ``task_id`` had a
2156 *   current priority which consisted of more than the real priority.
2157 *
2158 * @retval ::RTEMS_RESOURCE_IN_USE The task specified by ``task_id`` had a
2159 *   helping scheduler.
2160 *
2161 * @retval ::RTEMS_RESOURCE_IN_USE The task specified by ``task_id`` was
2162 *   pinned.
2163 *
2164 * @retval ::RTEMS_UNSATISFIED The scheduler specified by ``scheduler_id``
2165 *   owned no processor.
2166 *
2167 * @retval ::RTEMS_UNSATISFIED The scheduler specified by ``scheduler_id`` did
2168 *   not support the affinity set of the task specified by ``task_id``.
2169 *
2170 * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node.
2171 *
2172 * @par Constraints
2173 * @parblock
2174 * The following constraints apply to this directive:
2175 *
2176 * * The directive may be called from within interrupt context.
2177 *
2178 * * The directive may be called from within device driver initialization
2179 *   context.
2180 *
2181 * * The directive may be called from within task context.
2182 *
2183 * * The directive may change the priority of a task.  This may cause the
2184 *   calling task to be preempted.
2185 * @endparblock
2186 */
2187rtems_status_code rtems_task_set_scheduler(
2188  rtems_id            task_id,
2189  rtems_id            scheduler_id,
2190  rtems_task_priority priority
2191);
2192
2193/* Generated from spec:/rtems/task/if/get-affinity */
2194
2195/**
2196 * @ingroup RTEMSAPIClassicTasks
2197 *
2198 * @brief Gets the processor affinity of the task.
2199 *
2200 * @param id is the task identifier.  The constant #RTEMS_SELF may be used to
2201 *   specify the calling task.
2202 *
2203 * @param cpusetsize is the size of the processor set referenced by ``cpuset``
2204 *   in bytes.
2205 *
2206 * @param[out] cpuset is the pointer to a cpu_set_t object.  When the directive
2207 *   call is successful, the processor affinity set of the task will be stored
2208 *   in this object.  A set bit in the processor set means that the
2209 *   corresponding processor is in the processor affinity set of the task,
2210 *   otherwise the bit is cleared.
2211 *
2212 * This directive returns the processor affinity of the task in ``cpuset`` of
2213 * the task specified by ``id``.
2214 *
2215 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2216 *
2217 * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL.
2218 *
2219 * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier
2220 *   specified by ``id``.
2221 *
2222 * @retval ::RTEMS_INVALID_SIZE The size specified by ``cpusetsize`` of the
2223 *   processor set was too small for the processor affinity set of the task.
2224 *
2225 * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node.
2226 *
2227 * @par Constraints
2228 * @parblock
2229 * The following constraints apply to this directive:
2230 *
2231 * * The directive may be called from within interrupt context.
2232 *
2233 * * The directive may be called from within device driver initialization
2234 *   context.
2235 *
2236 * * The directive may be called from within task context.
2237 *
2238 * * The directive will not cause the calling task to be preempted.
2239 * @endparblock
2240 */
2241rtems_status_code rtems_task_get_affinity(
2242  rtems_id   id,
2243  size_t     cpusetsize,
2244  cpu_set_t *cpuset
2245);
2246
2247/* Generated from spec:/rtems/task/if/set-affinity */
2248
2249/**
2250 * @ingroup RTEMSAPIClassicTasks
2251 *
2252 * @brief Sets the processor affinity of the task.
2253 *
2254 * @param id is the task identifier.  The constant #RTEMS_SELF may be used to
2255 *   specify the calling task.
2256 *
2257 * @param cpusetsize is the size of the processor set referenced by ``cpuset``
2258 *   in bytes.
2259 *
2260 * @param[out] cpuset is the pointer to a cpu_set_t object.  The processor set
2261 *   defines the new processor affinity set of the task.  A set bit in the
2262 *   processor set means that the corresponding processor shall be in the
2263 *   processor affinity set of the task, otherwise the bit shall be cleared.
2264 *
2265 * This directive sets the processor affinity of the task specified by ``id``.
2266 *
2267 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2268 *
2269 * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL.
2270 *
2271 * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier
2272 *   specified by ``id``.
2273 *
2274 * @retval ::RTEMS_INVALID_NUMBER The referenced processor set was not a valid
2275 *   new processor affinity set for the task.
2276 *
2277 * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node.
2278 *
2279 * @par Constraints
2280 * @parblock
2281 * The following constraints apply to this directive:
2282 *
2283 * * The directive may be called from within interrupt context.
2284 *
2285 * * The directive may be called from within device driver initialization
2286 *   context.
2287 *
2288 * * The directive may be called from within task context.
2289 *
2290 * * The directive may change the processor affinity of a task.  This may cause
2291 *   the calling task to be preempted.
2292 * @endparblock
2293 */
2294rtems_status_code rtems_task_set_affinity(
2295  rtems_id         id,
2296  size_t           cpusetsize,
2297  const cpu_set_t *cpuset
2298);
2299
2300/* Generated from spec:/rtems/task/if/iterate */
2301
2302/**
2303 * @ingroup RTEMSAPIClassicTasks
2304 *
2305 * @brief Iterates over all tasks and invokes the visitor routine for each
2306 *   task.
2307 *
2308 * @param visitor is the visitor routine invoked for each task.
2309 *
2310 * @param arg is the argument passed to each visitor routine invocation during
2311 *   the iteration.
2312 *
2313 * This directive iterates over all tasks in the system.  This operation covers
2314 * all tasks of all APIs.  The user should be careful in accessing the contents
2315 * of the TCB.  The visitor argument ``arg`` is passed to all invocations of
2316 * ``visitor`` in addition to the TCB. The iteration stops immediately in case
2317 * the visitor routine returns true.
2318 *
2319 * @par Notes
2320 * The visitor routine is invoked while owning the objects allocator lock.  It
2321 * is allowed to perform blocking operations in the visitor routine, however,
2322 * care must be taken so that no deadlocks via the object allocator lock can
2323 * occur.
2324 *
2325 * @par Constraints
2326 * @parblock
2327 * The following constraints apply to this directive:
2328 *
2329 * * The directive may be called from within device driver initialization
2330 *   context.
2331 *
2332 * * The directive may be called from within task context.
2333 *
2334 * * The directive may obtain and release the object allocator mutex.  This may
2335 *   cause the calling task to be preempted.
2336 * @endparblock
2337 */
2338void rtems_task_iterate( rtems_task_visitor visitor, void *arg );
2339
2340#ifdef __cplusplus
2341}
2342#endif
2343
2344#endif /* _RTEMS_RTEMS_TASKS_H */
Note: See TracBrowser for help on using the repository browser.