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 |
---|
74 | extern "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 | */ |
---|
122 | typedef 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 | */ |
---|
132 | typedef 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 | */ |
---|
252 | typedef 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 | */ |
---|
261 | typedef 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 | */ |
---|
271 | typedef 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 | */ |
---|
403 | typedef 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 | */ |
---|
413 | typedef 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 | */ |
---|
431 | rtems_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 object identifier variable. When the |
---|
453 | * directive call is successful, the identifier of the scheduler will be |
---|
454 | * stored in this variable. |
---|
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 | */ |
---|
483 | rtems_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 object identifier variable. When the |
---|
495 | * directive call is successful, the identifier of the scheduler will be |
---|
496 | * stored in this variable. |
---|
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 | */ |
---|
516 | rtems_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 referenced processor set variable in |
---|
529 | * bytes. This value shall be positive. |
---|
530 | * |
---|
531 | * @param cpuset is the pointer to a processor set variable. The referenced |
---|
532 | * processor set will be used to identify the scheduler. |
---|
533 | * |
---|
534 | * @param[out] id is the pointer to an object identifier variable. When the |
---|
535 | * directive call is successful, the identifier of the scheduler will be |
---|
536 | * stored in this variable. |
---|
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 | */ |
---|
565 | rtems_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 a task priority variable. The |
---|
581 | * maximum priority of the scheduler will be stored in this variable, if the |
---|
582 | * operation is successful. |
---|
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 | */ |
---|
600 | rtems_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 a POSIX thread priority |
---|
618 | * variable. When the directive call is successful, the POSIX thread |
---|
619 | * priority value corresponding to the specified Classic API task priority |
---|
620 | * value will be stored in this variable. |
---|
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 | */ |
---|
640 | rtems_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 a Classic API task priority variable. |
---|
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 variable. |
---|
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 | */ |
---|
681 | rtems_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 | */ |
---|
719 | uint32_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 | */ |
---|
753 | uint32_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 referenced processor set variable in |
---|
768 | * bytes. |
---|
769 | * |
---|
770 | * @param[out] cpuset is the pointer to a processor set variable. When the |
---|
771 | * directive call is successful, the processor set of the scheduler will be |
---|
772 | * stored in this variable. A set bit in the processor set means that the |
---|
773 | * corresponding processor is owned by the scheduler, otherwise the bit is |
---|
774 | * cleared. |
---|
775 | * |
---|
776 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
777 | * |
---|
778 | * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL. |
---|
779 | * |
---|
780 | * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the |
---|
781 | * identifier specified by ``scheduler_id``. |
---|
782 | * |
---|
783 | * @retval ::RTEMS_INVALID_SIZE The provided processor set was too small for |
---|
784 | * the set of processors owned by the scheduler. |
---|
785 | * |
---|
786 | * @par Constraints |
---|
787 | * @parblock |
---|
788 | * The following constraints apply to this directive: |
---|
789 | * |
---|
790 | * * The directive may be called from within any runtime context. |
---|
791 | * |
---|
792 | * * The directive will not cause the calling task to be preempted. |
---|
793 | * @endparblock |
---|
794 | */ |
---|
795 | rtems_status_code rtems_scheduler_get_processor_set( |
---|
796 | rtems_id scheduler_id, |
---|
797 | size_t cpusetsize, |
---|
798 | cpu_set_t *cpuset |
---|
799 | ); |
---|
800 | |
---|
801 | /* Generated from spec:/rtems/scheduler/if/add-processor */ |
---|
802 | |
---|
803 | /** |
---|
804 | * @ingroup RTEMSAPIClassicScheduler |
---|
805 | * |
---|
806 | * @brief Adds the processor to the set of processors owned by the scheduler. |
---|
807 | * |
---|
808 | * @param scheduler_id is the scheduler identifier. |
---|
809 | * |
---|
810 | * @param cpu_index is the index of the processor to add. |
---|
811 | * |
---|
812 | * This directive adds the processor specified by the ``cpu_index`` to the |
---|
813 | * scheduler specified by ``scheduler_id``. |
---|
814 | * |
---|
815 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
816 | * |
---|
817 | * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the |
---|
818 | * identifier specified by ``scheduler_id``. |
---|
819 | * |
---|
820 | * @retval ::RTEMS_NOT_CONFIGURED The processor was not configured to be used |
---|
821 | * by the application. |
---|
822 | * |
---|
823 | * @retval ::RTEMS_INCORRECT_STATE The processor was configured to be used by |
---|
824 | * the application, however, it was not online. |
---|
825 | * |
---|
826 | * @retval ::RTEMS_RESOURCE_IN_USE The processor was already assigned to a |
---|
827 | * scheduler. |
---|
828 | * |
---|
829 | * @par Constraints |
---|
830 | * @parblock |
---|
831 | * The following constraints apply to this directive: |
---|
832 | * |
---|
833 | * * The directive may be called from within device driver initialization |
---|
834 | * context. |
---|
835 | * |
---|
836 | * * The directive may be called from within task context. |
---|
837 | * |
---|
838 | * * The directive may obtain and release the object allocator mutex. This may |
---|
839 | * cause the calling task to be preempted. |
---|
840 | * @endparblock |
---|
841 | */ |
---|
842 | rtems_status_code rtems_scheduler_add_processor( |
---|
843 | rtems_id scheduler_id, |
---|
844 | uint32_t cpu_index |
---|
845 | ); |
---|
846 | |
---|
847 | /* Generated from spec:/rtems/scheduler/if/remove-processor */ |
---|
848 | |
---|
849 | /** |
---|
850 | * @ingroup RTEMSAPIClassicScheduler |
---|
851 | * |
---|
852 | * @brief Removes the processor from the set of processors owned by the |
---|
853 | * scheduler. |
---|
854 | * |
---|
855 | * @param scheduler_id is the scheduler identifier. |
---|
856 | * |
---|
857 | * @param cpu_index is the index of the processor to remove. |
---|
858 | * |
---|
859 | * This directive removes the processor specified by the ``cpu_index`` from the |
---|
860 | * scheduler specified by ``scheduler_id``. |
---|
861 | * |
---|
862 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
863 | * |
---|
864 | * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the |
---|
865 | * identifier specified by ``scheduler_id``. |
---|
866 | * |
---|
867 | * @retval ::RTEMS_INVALID_NUMBER The processor was not owned by the scheduler. |
---|
868 | * |
---|
869 | * @retval ::RTEMS_RESOURCE_IN_USE The set of processors owned by the scheduler |
---|
870 | * would have been empty after the processor removal and there was at least |
---|
871 | * one non-idle task that used this scheduler as its home scheduler. |
---|
872 | * |
---|
873 | * @par Notes |
---|
874 | * Removing a processor from a scheduler is a complex operation that involves |
---|
875 | * all tasks of the system. |
---|
876 | * |
---|
877 | * @par Constraints |
---|
878 | * @parblock |
---|
879 | * The following constraints apply to this directive: |
---|
880 | * |
---|
881 | * * The directive may be called from within device driver initialization |
---|
882 | * context. |
---|
883 | * |
---|
884 | * * The directive may be called from within task context. |
---|
885 | * |
---|
886 | * * The directive may obtain and release the object allocator mutex. This may |
---|
887 | * cause the calling task to be preempted. |
---|
888 | * @endparblock |
---|
889 | */ |
---|
890 | rtems_status_code rtems_scheduler_remove_processor( |
---|
891 | rtems_id scheduler_id, |
---|
892 | uint32_t cpu_index |
---|
893 | ); |
---|
894 | |
---|
895 | /* Generated from spec:/rtems/task/if/create */ |
---|
896 | |
---|
897 | /** |
---|
898 | * @ingroup RTEMSAPIClassicTasks |
---|
899 | * |
---|
900 | * @brief Creates a task. |
---|
901 | * |
---|
902 | * @param name is the object name of the task. |
---|
903 | * |
---|
904 | * @param initial_priority is the initial task priority. |
---|
905 | * |
---|
906 | * @param stack_size is the task stack size in bytes. |
---|
907 | * |
---|
908 | * @param initial_modes is the initial mode set of the task. |
---|
909 | * |
---|
910 | * @param attribute_set is the attribute set of the task. |
---|
911 | * |
---|
912 | * @param[out] id is the pointer to an object identifier variable. When the |
---|
913 | * directive call is successful, the identifier of the created task will be |
---|
914 | * stored in this variable. |
---|
915 | * |
---|
916 | * This directive creates a task which resides on the local node. The task has |
---|
917 | * the user-defined object name specified in ``name``. The assigned object |
---|
918 | * identifier is returned in ``id``. This identifier is used to access the |
---|
919 | * task with other task related directives. |
---|
920 | * |
---|
921 | * The **initial priority** of the task is specified in ``initial_priority``. |
---|
922 | * The scheduler of the created task is the scheduler of the calling task at |
---|
923 | * some point during the task creation. The initial task priority specified in |
---|
924 | * ``initial_priority`` shall be valid for this scheduler. |
---|
925 | * |
---|
926 | * The **stack size** of the task is specified in ``stack_size``. If the |
---|
927 | * requested stack size is less than the configured minimum stack size, then |
---|
928 | * RTEMS will use the configured minimum as the stack size for this task. The |
---|
929 | * configured minimum stack size is defined by the |
---|
930 | * #CONFIGURE_MINIMUM_TASK_STACK_SIZE application configuration option. In |
---|
931 | * addition to being able to specify the task stack size as a integer, there |
---|
932 | * are two constants which may be specified: |
---|
933 | * |
---|
934 | * * The #RTEMS_MINIMUM_STACK_SIZE constant can be specified to use the |
---|
935 | * **recommended minimum stack size** for the target processor. This value |
---|
936 | * is selected by the RTEMS maintainers conservatively to minimize the risk |
---|
937 | * of blown stacks for most user applications. Using this constant when |
---|
938 | * specifying the task stack size, indicates that the stack size will be at |
---|
939 | * least #RTEMS_MINIMUM_STACK_SIZE bytes in size. If the user configured |
---|
940 | * minimum stack size is larger than the recommended minimum, then it will be |
---|
941 | * used. |
---|
942 | * |
---|
943 | * * The #RTEMS_CONFIGURED_MINIMUM_STACK_SIZE constant can be specified to use |
---|
944 | * the minimum stack size that was configured by the application. If not |
---|
945 | * explicitly configured by the application, the default configured minimum |
---|
946 | * stack size is the target processor dependent value |
---|
947 | * #RTEMS_MINIMUM_STACK_SIZE. Since this uses the configured minimum stack |
---|
948 | * size value, you may get a stack size that is smaller or larger than the |
---|
949 | * recommended minimum. This can be used to provide large stacks for all |
---|
950 | * tasks on complex applications or small stacks on applications that are |
---|
951 | * trying to conserve memory. |
---|
952 | * |
---|
953 | * The **initial mode set** specified in ``initial_modes`` is built through a |
---|
954 | * *bitwise or* of the mode constants described below. Not all combinations of |
---|
955 | * modes are allowed. Some modes are mutually exclusive. If mutually |
---|
956 | * exclusive modes are combined, the behaviour is undefined. Default task |
---|
957 | * modes can be selected by using the #RTEMS_DEFAULT_MODES constant. The task |
---|
958 | * mode set defines |
---|
959 | * |
---|
960 | * * the preemption mode of the task: #RTEMS_PREEMPT (default) or |
---|
961 | * #RTEMS_NO_PREEMPT, |
---|
962 | * |
---|
963 | * * the timeslicing mode of the task: #RTEMS_TIMESLICE or #RTEMS_NO_TIMESLICE |
---|
964 | * (default), |
---|
965 | * |
---|
966 | * * the ASR processing mode of the task: #RTEMS_ASR (default) or |
---|
967 | * #RTEMS_NO_ASR, |
---|
968 | * |
---|
969 | * * the interrupt level of the task: RTEMS_INTERRUPT_LEVEL() with a default of |
---|
970 | * ``RTEMS_INTERRUPT_LEVEL( 0 )`` which is associated with enabled |
---|
971 | * interrupts. |
---|
972 | * |
---|
973 | * The **initial preemption mode** of the task is enabled or disabled. |
---|
974 | * |
---|
975 | * * An **enabled preemption** is the default and can be emphasized through the |
---|
976 | * use of the #RTEMS_PREEMPT mode constant. |
---|
977 | * |
---|
978 | * * A **disabled preemption** is set by the #RTEMS_NO_PREEMPT mode constant. |
---|
979 | * |
---|
980 | * The **initial timeslicing mode** of the task is enabled or disabled. |
---|
981 | * |
---|
982 | * * A **disabled timeslicing** is the default and can be emphasized through |
---|
983 | * the use of the #RTEMS_NO_TIMESLICE mode constant. |
---|
984 | * |
---|
985 | * * An **enabled timeslicing** is set by the #RTEMS_TIMESLICE mode constant. |
---|
986 | * |
---|
987 | * The **initial ASR processing mode** of the task is enabled or disabled. |
---|
988 | * |
---|
989 | * * An **enabled ASR processing** is the default and can be emphasized through |
---|
990 | * the use of the #RTEMS_ASR mode constant. |
---|
991 | * |
---|
992 | * * A **disabled ASR processing** is set by the #RTEMS_NO_ASR mode constant. |
---|
993 | * |
---|
994 | * The **initial interrupt level mode** of the task is defined by |
---|
995 | * RTEMS_INTERRUPT_LEVEL(). |
---|
996 | * |
---|
997 | * * Task execution with **interrupts enabled** the default and can be |
---|
998 | * emphasized through the use of the RTEMS_INTERRUPT_LEVEL() mode macro with |
---|
999 | * a value of zero (0) for the parameter. An interrupt level of zero is |
---|
1000 | * associated with enabled interrupts on all target processors. |
---|
1001 | * |
---|
1002 | * * Task execution at a **non-zero interrupt level** can be specified by the |
---|
1003 | * RTEMS_INTERRUPT_LEVEL() mode macro with a non-zero value for the |
---|
1004 | * parameter. The interrupt level portion of the task mode supports a |
---|
1005 | * maximum of 256 interrupt levels. These levels are mapped onto the |
---|
1006 | * interrupt levels actually supported by the target processor in a processor |
---|
1007 | * dependent fashion. |
---|
1008 | * |
---|
1009 | * The **attribute set** specified in ``attribute_set`` is built through a |
---|
1010 | * *bitwise or* of the attribute constants described below. Not all |
---|
1011 | * combinations of attributes are allowed. Some attributes are mutually |
---|
1012 | * exclusive. If mutually exclusive attributes are combined, the behaviour is |
---|
1013 | * undefined. Attributes not mentioned below are not evaluated by this |
---|
1014 | * directive and have no effect. Default attributes can be selected by using |
---|
1015 | * the #RTEMS_DEFAULT_ATTRIBUTES constant. The attribute set defines |
---|
1016 | * |
---|
1017 | * * the scope of the task: #RTEMS_LOCAL (default) or #RTEMS_GLOBAL and |
---|
1018 | * |
---|
1019 | * * the floating-point unit use of the task: #RTEMS_FLOATING_POINT or |
---|
1020 | * #RTEMS_NO_FLOATING_POINT (default). |
---|
1021 | * |
---|
1022 | * The task has a local or global **scope** in a multiprocessing network (this |
---|
1023 | * attribute does not refer to SMP systems). The scope is selected by the |
---|
1024 | * mutually exclusive #RTEMS_LOCAL and #RTEMS_GLOBAL attributes. |
---|
1025 | * |
---|
1026 | * * A **local scope** is the default and can be emphasized through the use of |
---|
1027 | * the #RTEMS_LOCAL attribute. A local task can be only used by the node |
---|
1028 | * which created it. |
---|
1029 | * |
---|
1030 | * * A **global scope** is established if the #RTEMS_GLOBAL attribute is set. |
---|
1031 | * Setting the global attribute in a single node system has no effect.the |
---|
1032 | * |
---|
1033 | * The **use of the floating-point unit** is selected by the mutually exclusive |
---|
1034 | * #RTEMS_FLOATING_POINT and #RTEMS_NO_FLOATING_POINT attributes. On some |
---|
1035 | * target processors, the use of the floating-point unit can be enabled or |
---|
1036 | * disabled for each task. Other target processors may have no hardware |
---|
1037 | * floating-point unit or enable the use of the floating-point unit for all |
---|
1038 | * tasks. Consult the *RTEMS CPU Architecture Supplement* for the details. |
---|
1039 | * |
---|
1040 | * * A **disabled floating-point unit** is the default and can be emphasized |
---|
1041 | * through use of the #RTEMS_NO_FLOATING_POINT attribute. For performance |
---|
1042 | * reasons, it is recommended that tasks not using the floating-point unit |
---|
1043 | * should specify this attribute. |
---|
1044 | * |
---|
1045 | * * An **enabled floating-point unit** is selected by the |
---|
1046 | * #RTEMS_FLOATING_POINT attribute. |
---|
1047 | * |
---|
1048 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
1049 | * |
---|
1050 | * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was invalid. |
---|
1051 | * |
---|
1052 | * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. |
---|
1053 | * |
---|
1054 | * @retval ::RTEMS_INVALID_PRIORITY The ``initial_priority`` was invalid. |
---|
1055 | * |
---|
1056 | * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a |
---|
1057 | * task. The number of tasks available to the application is configured |
---|
1058 | * through the #CONFIGURE_MAXIMUM_TASKS application configuration option. |
---|
1059 | * |
---|
1060 | * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no |
---|
1061 | * inactive global object available to create a global task. The number of |
---|
1062 | * global objects available to the application is configured through the |
---|
1063 | * #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option. |
---|
1064 | * |
---|
1065 | * @retval ::RTEMS_UNSATISFIED There was not enough memory to allocate the task |
---|
1066 | * storage area. The task storage area contains the task stack, the |
---|
1067 | * thread-local storage, and the floating point context. |
---|
1068 | * |
---|
1069 | * @retval ::RTEMS_UNSATISFIED One of the task create extensions failed to |
---|
1070 | * create the task. |
---|
1071 | * |
---|
1072 | * @retval ::RTEMS_UNSATISFIED In SMP configurations, the non-preemption mode |
---|
1073 | * was not supported. |
---|
1074 | * |
---|
1075 | * @retval ::RTEMS_UNSATISFIED In SMP configurations, the interrupt level mode |
---|
1076 | * was not supported. |
---|
1077 | * |
---|
1078 | * @par Notes |
---|
1079 | * @parblock |
---|
1080 | * The task processor affinity is initialized to the set of online processors. |
---|
1081 | * |
---|
1082 | * When created, a task is placed in the dormant state and can only be made |
---|
1083 | * ready to execute using the directive rtems_task_start(). |
---|
1084 | * |
---|
1085 | * Application developers should consider the stack usage of the device drivers |
---|
1086 | * when calculating the stack size required for tasks which utilize the driver. |
---|
1087 | * The task stack size shall account for an target processor dependent |
---|
1088 | * interrupt stack frame which may be placed on the stack of the interrupted |
---|
1089 | * task while servicing an interrupt. The stack checker may be used to monitor |
---|
1090 | * the stack usage, see #CONFIGURE_STACK_CHECKER_ENABLED. |
---|
1091 | * |
---|
1092 | * For control and maintenance of the task, RTEMS allocates a TCB from the |
---|
1093 | * local TCB free pool and initializes it. |
---|
1094 | * |
---|
1095 | * The TCB for a global task is allocated on the local node. Task should not |
---|
1096 | * be made global unless remote tasks must interact with the task. This is to |
---|
1097 | * avoid the system overhead incurred by the creation of a global task. When a |
---|
1098 | * global task is created, the task's name and identifier must be transmitted |
---|
1099 | * to every node in the system for insertion in the local copy of the global |
---|
1100 | * object table. |
---|
1101 | * @endparblock |
---|
1102 | * |
---|
1103 | * @par Constraints |
---|
1104 | * @parblock |
---|
1105 | * The following constraints apply to this directive: |
---|
1106 | * |
---|
1107 | * * The directive may be called from within device driver initialization |
---|
1108 | * context. |
---|
1109 | * |
---|
1110 | * * The directive may be called from within task context. |
---|
1111 | * |
---|
1112 | * * The directive may obtain and release the object allocator mutex. This may |
---|
1113 | * cause the calling task to be preempted. |
---|
1114 | * |
---|
1115 | * * When the directive operates on a global object, the directive sends a |
---|
1116 | * message to remote nodes. This may preempt the calling task. |
---|
1117 | * |
---|
1118 | * * The number of tasks available to the application is configured through the |
---|
1119 | * #CONFIGURE_MAXIMUM_TASKS application configuration option. |
---|
1120 | * |
---|
1121 | * * Where the object class corresponding to the directive is configured to use |
---|
1122 | * unlimited objects, the directive may allocate memory from the RTEMS |
---|
1123 | * Workspace. |
---|
1124 | * |
---|
1125 | * * The number of global objects available to the application is configured |
---|
1126 | * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration |
---|
1127 | * option. |
---|
1128 | * @endparblock |
---|
1129 | */ |
---|
1130 | rtems_status_code rtems_task_create( |
---|
1131 | rtems_name name, |
---|
1132 | rtems_task_priority initial_priority, |
---|
1133 | size_t stack_size, |
---|
1134 | rtems_mode initial_modes, |
---|
1135 | rtems_attribute attribute_set, |
---|
1136 | rtems_id *id |
---|
1137 | ); |
---|
1138 | |
---|
1139 | /* Generated from spec:/rtems/task/if/construct */ |
---|
1140 | |
---|
1141 | /** |
---|
1142 | * @ingroup RTEMSAPIClassicTasks |
---|
1143 | * |
---|
1144 | * @brief Constructs a task from the specified task configuration. |
---|
1145 | * |
---|
1146 | * @param config is the task configuration. |
---|
1147 | * |
---|
1148 | * @param[out] id is the pointer to an object identifier variable. When the |
---|
1149 | * directive call is successful, the identifier of the constructed task will |
---|
1150 | * be stored in this variable. |
---|
1151 | * |
---|
1152 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
1153 | * |
---|
1154 | * @retval ::RTEMS_INVALID_ADDRESS The ``config`` parameter was NULL. |
---|
1155 | * |
---|
1156 | * @retval ::RTEMS_INVALID_NAME The task name was invalid. |
---|
1157 | * |
---|
1158 | * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. |
---|
1159 | * |
---|
1160 | * @retval ::RTEMS_INVALID_PRIORITY The initial task priority was invalid. |
---|
1161 | * |
---|
1162 | * @retval ::RTEMS_INVALID_SIZE The thread-local storage size is greater than |
---|
1163 | * the maximum thread-local storage size specified in the task configuration. |
---|
1164 | * The thread-local storage size is determined by the thread-local variables |
---|
1165 | * used by the application and #CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE. |
---|
1166 | * |
---|
1167 | * @retval ::RTEMS_INVALID_SIZE The task storage area was too small to provide |
---|
1168 | * a task stack of the configured minimum size, see |
---|
1169 | * #CONFIGURE_MINIMUM_TASK_STACK_SIZE. The task storage area contains the |
---|
1170 | * task stack, the thread-local storage, and the floating-point context on |
---|
1171 | * architectures with a separate floating-point context. |
---|
1172 | * |
---|
1173 | * @retval ::RTEMS_TOO_MANY There was no inactive task object available to |
---|
1174 | * construct a task. |
---|
1175 | * |
---|
1176 | * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no |
---|
1177 | * inactive global object available to construct a global task. |
---|
1178 | * |
---|
1179 | * @retval ::RTEMS_UNSATISFIED One of the task create extensions failed during |
---|
1180 | * the task construction. |
---|
1181 | * |
---|
1182 | * @retval ::RTEMS_UNSATISFIED In SMP configurations, the non-preemption mode |
---|
1183 | * was not supported. |
---|
1184 | * |
---|
1185 | * @retval ::RTEMS_UNSATISFIED In SMP configurations, the interrupt level mode |
---|
1186 | * was not supported. |
---|
1187 | * |
---|
1188 | * @par Notes |
---|
1189 | * @parblock |
---|
1190 | * In contrast to tasks created by rtems_task_create(), the tasks constructed |
---|
1191 | * by this directive use a user-provided task storage area. The task storage |
---|
1192 | * area contains the task stack, the thread-local storage, and the |
---|
1193 | * floating-point context on architectures with a separate floating-point |
---|
1194 | * context. |
---|
1195 | * |
---|
1196 | * This directive is intended for applications which do not want to use the |
---|
1197 | * RTEMS Workspace and instead statically allocate all operating system |
---|
1198 | * resources. It is not recommended to use rtems_task_create() and |
---|
1199 | * rtems_task_construct() together in an application. It is also not |
---|
1200 | * recommended to use rtems_task_construct() for drivers or general purpose |
---|
1201 | * libraries. The reason for these recommendations is that the task |
---|
1202 | * configuration needs settings which can be only given with a through |
---|
1203 | * knowledge of the application resources. |
---|
1204 | * |
---|
1205 | * An application based solely on static allocation can avoid any runtime |
---|
1206 | * memory allocators. This can simplify the application architecture as well |
---|
1207 | * as any analysis that may be required. |
---|
1208 | * |
---|
1209 | * The stack space estimate done by <rtems/confdefs.h> assumes that all tasks |
---|
1210 | * are created by rtems_task_create(). The estimate can be adjusted to take |
---|
1211 | * user-provided task storage areas into account through the |
---|
1212 | * #CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE application |
---|
1213 | * configuration option. |
---|
1214 | * |
---|
1215 | * The #CONFIGURE_MAXIMUM_TASKS should include tasks constructed by |
---|
1216 | * rtems_task_construct(). |
---|
1217 | * @endparblock |
---|
1218 | * |
---|
1219 | * @par Constraints |
---|
1220 | * @parblock |
---|
1221 | * The following constraints apply to this directive: |
---|
1222 | * |
---|
1223 | * * The directive may be called from within device driver initialization |
---|
1224 | * context. |
---|
1225 | * |
---|
1226 | * * The directive may be called from within task context. |
---|
1227 | * |
---|
1228 | * * The directive may obtain and release the object allocator mutex. This may |
---|
1229 | * cause the calling task to be preempted. |
---|
1230 | * |
---|
1231 | * * When the directive operates on a global object, the directive sends a |
---|
1232 | * message to remote nodes. This may preempt the calling task. |
---|
1233 | * |
---|
1234 | * * The number of tasks available to the application is configured through the |
---|
1235 | * #CONFIGURE_MAXIMUM_TASKS application configuration option. |
---|
1236 | * |
---|
1237 | * * Where the object class corresponding to the directive is configured to use |
---|
1238 | * unlimited objects, the directive may allocate memory from the RTEMS |
---|
1239 | * Workspace. |
---|
1240 | * |
---|
1241 | * * The number of global objects available to the application is configured |
---|
1242 | * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration |
---|
1243 | * option. |
---|
1244 | * @endparblock |
---|
1245 | */ |
---|
1246 | rtems_status_code rtems_task_construct( |
---|
1247 | const rtems_task_config *config, |
---|
1248 | rtems_id *id |
---|
1249 | ); |
---|
1250 | |
---|
1251 | /* Generated from spec:/rtems/task/if/ident */ |
---|
1252 | |
---|
1253 | /** |
---|
1254 | * @ingroup RTEMSAPIClassicTasks |
---|
1255 | * |
---|
1256 | * @brief Identifies a task by the object name. |
---|
1257 | * |
---|
1258 | * @param name is the object name to look up. |
---|
1259 | * |
---|
1260 | * @param node is the node or node set to search for a matching object. |
---|
1261 | * |
---|
1262 | * @param[out] id is the pointer to an object identifier variable. When the |
---|
1263 | * directive call is successful, the object identifier of an object with the |
---|
1264 | * specified name will be stored in this variable. |
---|
1265 | * |
---|
1266 | * This directive obtains a task identifier associated with the task name |
---|
1267 | * specified in ``name``. |
---|
1268 | * |
---|
1269 | * A task may obtain its own identifier by specifying #RTEMS_SELF for the name. |
---|
1270 | * |
---|
1271 | * The node to search is specified in ``node``. It shall be |
---|
1272 | * |
---|
1273 | * * a valid node number, |
---|
1274 | * |
---|
1275 | * * the constant #RTEMS_SEARCH_ALL_NODES to search in all nodes, |
---|
1276 | * |
---|
1277 | * * the constant #RTEMS_SEARCH_LOCAL_NODE to search in the local node only, or |
---|
1278 | * |
---|
1279 | * * the constant #RTEMS_SEARCH_OTHER_NODES to search in all nodes except the |
---|
1280 | * local node. |
---|
1281 | * |
---|
1282 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
1283 | * |
---|
1284 | * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. |
---|
1285 | * |
---|
1286 | * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on |
---|
1287 | * the specified nodes. |
---|
1288 | * |
---|
1289 | * @retval ::RTEMS_INVALID_NODE In multiprocessing configurations, the |
---|
1290 | * specified node was invalid. |
---|
1291 | * |
---|
1292 | * @par Notes |
---|
1293 | * @parblock |
---|
1294 | * If the task name is not unique, then the task identifier will match the |
---|
1295 | * first task with that name in the search order. However, this task |
---|
1296 | * identifier is not guaranteed to correspond to the desired task. |
---|
1297 | * |
---|
1298 | * The objects are searched from lowest to the highest index. If ``node`` is |
---|
1299 | * #RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local node being |
---|
1300 | * searched first. All other nodes are searched from lowest to the highest |
---|
1301 | * node number. |
---|
1302 | * |
---|
1303 | * If node is a valid node number which does not represent the local node, then |
---|
1304 | * only the tasks exported by the designated node are searched. |
---|
1305 | * |
---|
1306 | * This directive does not generate activity on remote nodes. It accesses only |
---|
1307 | * the local copy of the global object table. |
---|
1308 | * |
---|
1309 | * The task identifier is used with other task related directives to access the |
---|
1310 | * task. |
---|
1311 | * @endparblock |
---|
1312 | * |
---|
1313 | * @par Constraints |
---|
1314 | * @parblock |
---|
1315 | * The following constraints apply to this directive: |
---|
1316 | * |
---|
1317 | * * The directive may be called from within any runtime context. |
---|
1318 | * |
---|
1319 | * * The directive will not cause the calling task to be preempted. |
---|
1320 | * @endparblock |
---|
1321 | */ |
---|
1322 | rtems_status_code rtems_task_ident( |
---|
1323 | rtems_name name, |
---|
1324 | uint32_t node, |
---|
1325 | rtems_id *id |
---|
1326 | ); |
---|
1327 | |
---|
1328 | /* Generated from spec:/rtems/task/if/self */ |
---|
1329 | |
---|
1330 | /** |
---|
1331 | * @ingroup RTEMSAPIClassicTasks |
---|
1332 | * |
---|
1333 | * @brief Gets the task identifier of the calling task. |
---|
1334 | * |
---|
1335 | * This directive returns the task identifier of the calling task. |
---|
1336 | * |
---|
1337 | * @return Returns the task identifier of the calling task. |
---|
1338 | * |
---|
1339 | * @par Constraints |
---|
1340 | * @parblock |
---|
1341 | * The following constraints apply to this directive: |
---|
1342 | * |
---|
1343 | * * The directive may be called from within device driver initialization |
---|
1344 | * context. |
---|
1345 | * |
---|
1346 | * * The directive may be called from within task context. |
---|
1347 | * |
---|
1348 | * * The directive will not cause the calling task to be preempted. |
---|
1349 | * @endparblock |
---|
1350 | */ |
---|
1351 | rtems_id rtems_task_self( void ); |
---|
1352 | |
---|
1353 | /* Generated from spec:/rtems/task/if/start */ |
---|
1354 | |
---|
1355 | /** |
---|
1356 | * @ingroup RTEMSAPIClassicTasks |
---|
1357 | * |
---|
1358 | * @brief Starts the task. |
---|
1359 | * |
---|
1360 | * @param id is the task identifier. The constant #RTEMS_SELF may be used to |
---|
1361 | * specify the calling task. |
---|
1362 | * |
---|
1363 | * @param entry_point is the task entry point. |
---|
1364 | * |
---|
1365 | * @param argument is the task entry point argument. |
---|
1366 | * |
---|
1367 | * This directive readies the task, specified by ``id``, for execution based on |
---|
1368 | * the priority and execution mode specified when the task was created. The |
---|
1369 | * entry point of the task is given in ``entry_point``. The task's entry point |
---|
1370 | * argument is contained in ``argument``. |
---|
1371 | * |
---|
1372 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
1373 | * |
---|
1374 | * @retval ::RTEMS_INVALID_ADDRESS The ``entry_point`` parameter was NULL. |
---|
1375 | * |
---|
1376 | * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier |
---|
1377 | * specified by ``id``. |
---|
1378 | * |
---|
1379 | * @retval ::RTEMS_INCORRECT_STATE The task was not in the dormant state. |
---|
1380 | * |
---|
1381 | * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. |
---|
1382 | * |
---|
1383 | * @par Notes |
---|
1384 | * @parblock |
---|
1385 | * The type of the entry point argument is an unsigned integer type. However, |
---|
1386 | * the integer type has the property that any valid pointer to ``void`` can be |
---|
1387 | * converted to this type and then converted back to a pointer to ``void``. |
---|
1388 | * The result will compare equal to the original pointer. The type can |
---|
1389 | * represent at least 32 bits. Some applications use the entry point argument |
---|
1390 | * as an index into a parameter table to get task-specific parameters. |
---|
1391 | * |
---|
1392 | * Any actions performed on a dormant task such as suspension or change of |
---|
1393 | * priority are nullified when the task is initiated via the rtems_task_start() |
---|
1394 | * directive. |
---|
1395 | * @endparblock |
---|
1396 | * |
---|
1397 | * @par Constraints |
---|
1398 | * @parblock |
---|
1399 | * The following constraints apply to this directive: |
---|
1400 | * |
---|
1401 | * * The directive may be called from within interrupt context. |
---|
1402 | * |
---|
1403 | * * The directive may be called from within device driver initialization |
---|
1404 | * context. |
---|
1405 | * |
---|
1406 | * * The directive may be called from within task context. |
---|
1407 | * |
---|
1408 | * * The directive may unblock a task. This may cause the calling task to be |
---|
1409 | * preempted. |
---|
1410 | * @endparblock |
---|
1411 | */ |
---|
1412 | rtems_status_code rtems_task_start( |
---|
1413 | rtems_id id, |
---|
1414 | rtems_task_entry entry_point, |
---|
1415 | rtems_task_argument argument |
---|
1416 | ); |
---|
1417 | |
---|
1418 | /* Generated from spec:/rtems/task/if/restart */ |
---|
1419 | |
---|
1420 | /** |
---|
1421 | * @ingroup RTEMSAPIClassicTasks |
---|
1422 | * |
---|
1423 | * @brief Restarts the task. |
---|
1424 | * |
---|
1425 | * @param id is the task identifier. The constant #RTEMS_SELF may be used to |
---|
1426 | * specify the calling task. |
---|
1427 | * |
---|
1428 | * @param argument is the task entry point argument. |
---|
1429 | * |
---|
1430 | * This directive resets the task specified by ``id`` to begin execution at its |
---|
1431 | * original entry point. The task's priority and execution mode are set to the |
---|
1432 | * original creation values. If the task is currently blocked, RTEMS |
---|
1433 | * automatically makes the task ready. A task can be restarted from any state, |
---|
1434 | * except the dormant state. The task's entry point argument is contained in |
---|
1435 | * ``argument``. |
---|
1436 | * |
---|
1437 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
1438 | * |
---|
1439 | * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier |
---|
1440 | * specified by ``id``. |
---|
1441 | * |
---|
1442 | * @retval ::RTEMS_INCORRECT_STATE The task never started. |
---|
1443 | * |
---|
1444 | * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. |
---|
1445 | * |
---|
1446 | * @par Notes |
---|
1447 | * @parblock |
---|
1448 | * The type of the entry point argument is an unsigned integer type. However, |
---|
1449 | * the integer type has the property that any valid pointer to ``void`` can be |
---|
1450 | * converted to this type and then converted back to a pointer to ``void``. |
---|
1451 | * The result will compare equal to the original pointer. The type can |
---|
1452 | * represent at least 32 bits. Some applications use the entry point argument |
---|
1453 | * as an index into a parameter table to get task-specific parameters. |
---|
1454 | * |
---|
1455 | * A new entry point argument may be used to distinguish between the initial |
---|
1456 | * rtems_task_start() of the task and any ensuing calls to rtems_task_restart() |
---|
1457 | * of the task. This can be beneficial in deleting a task. Instead of |
---|
1458 | * deleting a task using the rtems_task_delete() directive, a task can delete |
---|
1459 | * another task by restarting that task, and allowing that task to release |
---|
1460 | * resources back to RTEMS and then delete itself. |
---|
1461 | * @endparblock |
---|
1462 | * |
---|
1463 | * @par Constraints |
---|
1464 | * @parblock |
---|
1465 | * The following constraints apply to this directive: |
---|
1466 | * |
---|
1467 | * * The directive may be called from within interrupt context. |
---|
1468 | * |
---|
1469 | * * The directive may be called from within device driver initialization |
---|
1470 | * context. |
---|
1471 | * |
---|
1472 | * * The directive may be called from within task context. |
---|
1473 | * |
---|
1474 | * * The directive may change the priority of a task. This may cause the |
---|
1475 | * calling task to be preempted. |
---|
1476 | * |
---|
1477 | * * The directive may unblock a task. This may cause the calling task to be |
---|
1478 | * preempted. |
---|
1479 | * @endparblock |
---|
1480 | */ |
---|
1481 | rtems_status_code rtems_task_restart( |
---|
1482 | rtems_id id, |
---|
1483 | rtems_task_argument argument |
---|
1484 | ); |
---|
1485 | |
---|
1486 | /* Generated from spec:/rtems/task/if/delete */ |
---|
1487 | |
---|
1488 | /** |
---|
1489 | * @ingroup RTEMSAPIClassicTasks |
---|
1490 | * |
---|
1491 | * @brief Deletes the task. |
---|
1492 | * |
---|
1493 | * @param id is the task identifier. The constant #RTEMS_SELF may be used to |
---|
1494 | * specify the calling task. |
---|
1495 | * |
---|
1496 | * This directive deletes the task, either the calling task or another task, as |
---|
1497 | * specified by ``id``. |
---|
1498 | * |
---|
1499 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
1500 | * |
---|
1501 | * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier |
---|
1502 | * specified by ``id``. |
---|
1503 | * |
---|
1504 | * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within |
---|
1505 | * interrupt context. |
---|
1506 | * |
---|
1507 | * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. |
---|
1508 | * |
---|
1509 | * @par Notes |
---|
1510 | * @parblock |
---|
1511 | * RTEMS stops the execution of the task and reclaims the stack memory, any |
---|
1512 | * allocated delay or timeout timers, the TCB, and, if the task is |
---|
1513 | * #RTEMS_FLOATING_POINT, its floating point context area. RTEMS explicitly |
---|
1514 | * does not reclaim the following resources: region segments, partition |
---|
1515 | * buffers, semaphores, timers, or rate monotonic periods. |
---|
1516 | * |
---|
1517 | * A task is responsible for releasing its resources back to RTEMS before |
---|
1518 | * deletion. To insure proper deallocation of resources, a task should not be |
---|
1519 | * deleted unless it is unable to execute or does not hold any RTEMS resources. |
---|
1520 | * If a task holds RTEMS resources, the task should be allowed to deallocate |
---|
1521 | * its resources before deletion. A task can be directed to release its |
---|
1522 | * resources and delete itself by restarting it with a special argument or by |
---|
1523 | * sending it a message, an event, or a signal. |
---|
1524 | * |
---|
1525 | * Deletion of the current task (#RTEMS_SELF) will force RTEMS to select |
---|
1526 | * another task to execute. |
---|
1527 | * |
---|
1528 | * The TCB for the deleted task is reclaimed by RTEMS. |
---|
1529 | * |
---|
1530 | * When a global task is deleted, the task identifier must be transmitted to |
---|
1531 | * every node in the system for deletion from the local copy of the global |
---|
1532 | * object table. |
---|
1533 | * |
---|
1534 | * The task must reside on the local node, even if the task was created with |
---|
1535 | * the #RTEMS_GLOBAL attribute. |
---|
1536 | * @endparblock |
---|
1537 | * |
---|
1538 | * @par Constraints |
---|
1539 | * @parblock |
---|
1540 | * The following constraints apply to this directive: |
---|
1541 | * |
---|
1542 | * * The directive may be called from within device driver initialization |
---|
1543 | * context. |
---|
1544 | * |
---|
1545 | * * The directive may be called from within task context. |
---|
1546 | * |
---|
1547 | * * The directive may obtain and release the object allocator mutex. This may |
---|
1548 | * cause the calling task to be preempted. |
---|
1549 | * |
---|
1550 | * * When the directive operates on a global object, the directive sends a |
---|
1551 | * message to remote nodes. This may preempt the calling task. |
---|
1552 | * |
---|
1553 | * * The calling task does not have to be the task that created the object. |
---|
1554 | * Any local task that knows the object identifier can delete the object. |
---|
1555 | * |
---|
1556 | * * Where the object class corresponding to the directive is configured to use |
---|
1557 | * unlimited objects, the directive may free memory to the RTEMS Workspace. |
---|
1558 | * @endparblock |
---|
1559 | */ |
---|
1560 | rtems_status_code rtems_task_delete( rtems_id id ); |
---|
1561 | |
---|
1562 | /* Generated from spec:/rtems/task/if/exit */ |
---|
1563 | |
---|
1564 | /** |
---|
1565 | * @ingroup RTEMSAPIClassicTasks |
---|
1566 | * |
---|
1567 | * @brief Deletes the calling task. |
---|
1568 | * |
---|
1569 | * This directive deletes the calling task. |
---|
1570 | * |
---|
1571 | * @par Notes |
---|
1572 | * @parblock |
---|
1573 | * The directive is an optimized variant of the following code sequences, see |
---|
1574 | * also rtems_task_delete(): |
---|
1575 | * |
---|
1576 | * @code |
---|
1577 | * #include <pthread.h> |
---|
1578 | * #include <rtems.h> |
---|
1579 | * |
---|
1580 | * void classic_delete_self( void ) |
---|
1581 | * { |
---|
1582 | * (void) rtems_task_delete( RTEMS_SELF ); |
---|
1583 | * } |
---|
1584 | * |
---|
1585 | * void posix_delete_self( void ) |
---|
1586 | * { |
---|
1587 | * (void) pthread_detach( pthread_self() ); |
---|
1588 | * (void) pthread_exit( NULL); |
---|
1589 | * } |
---|
1590 | * @endcode |
---|
1591 | * @endparblock |
---|
1592 | * |
---|
1593 | * @par Constraints |
---|
1594 | * @parblock |
---|
1595 | * The following constraints apply to this directive: |
---|
1596 | * |
---|
1597 | * * The directive may be called from within task context. |
---|
1598 | * |
---|
1599 | * * The directive will not return to the caller. |
---|
1600 | * |
---|
1601 | * * While thread dispatching is disabled, if the directive performs a thread |
---|
1602 | * dispatch, then the fatal error with the fatal source INTERNAL_ERROR_CORE |
---|
1603 | * and the fatal code INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL will |
---|
1604 | * occur. |
---|
1605 | * @endparblock |
---|
1606 | */ |
---|
1607 | RTEMS_NO_RETURN void rtems_task_exit( void ); |
---|
1608 | |
---|
1609 | /* Generated from spec:/rtems/task/if/suspend */ |
---|
1610 | |
---|
1611 | /** |
---|
1612 | * @ingroup RTEMSAPIClassicTasks |
---|
1613 | * |
---|
1614 | * @brief Suspends the task. |
---|
1615 | * |
---|
1616 | * @param id is the task identifier. The constant #RTEMS_SELF may be used to |
---|
1617 | * specify the calling task. |
---|
1618 | * |
---|
1619 | * This directive suspends the task specified by ``id`` from further execution |
---|
1620 | * by placing it in the suspended state. This state is additive to any other |
---|
1621 | * blocked state that the task may already be in. The task will not execute |
---|
1622 | * again until another task issues the rtems_task_resume() directive for this |
---|
1623 | * task and any blocked state has been removed. The rtems_task_restart() |
---|
1624 | * directive will also remove the suspended state. |
---|
1625 | * |
---|
1626 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
1627 | * |
---|
1628 | * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier |
---|
1629 | * specified by ``id``. |
---|
1630 | * |
---|
1631 | * @retval ::RTEMS_ALREADY_SUSPENDED The task was already suspended. |
---|
1632 | * |
---|
1633 | * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. |
---|
1634 | * |
---|
1635 | * @par Notes |
---|
1636 | * The requesting task can suspend itself for example by specifying #RTEMS_SELF |
---|
1637 | * as ``id``. In this case, the task will be suspended and a successful return |
---|
1638 | * code will be returned when the task is resumed. |
---|
1639 | * |
---|
1640 | * @par Constraints |
---|
1641 | * @parblock |
---|
1642 | * The following constraints apply to this directive: |
---|
1643 | * |
---|
1644 | * * The directive may be called from within interrupt context. |
---|
1645 | * |
---|
1646 | * * The directive may be called from within device driver initialization |
---|
1647 | * context. |
---|
1648 | * |
---|
1649 | * * The directive may be called from within task context. |
---|
1650 | * |
---|
1651 | * * When the directive operates on a remote object, the directive sends a |
---|
1652 | * message to the remote node and waits for a reply. This will preempt the |
---|
1653 | * calling task. |
---|
1654 | * @endparblock |
---|
1655 | */ |
---|
1656 | rtems_status_code rtems_task_suspend( rtems_id id ); |
---|
1657 | |
---|
1658 | /* Generated from spec:/rtems/task/if/resume */ |
---|
1659 | |
---|
1660 | /** |
---|
1661 | * @ingroup RTEMSAPIClassicTasks |
---|
1662 | * |
---|
1663 | * @brief Resumes the task. |
---|
1664 | * |
---|
1665 | * @param id is the task identifier. |
---|
1666 | * |
---|
1667 | * This directive removes the task specified by ``id`` from the suspended |
---|
1668 | * state. If the task is in the ready state after the suspension is removed, |
---|
1669 | * then it will be scheduled to run. If the task is still in a blocked state |
---|
1670 | * after the suspension is removed, then it will remain in that blocked state. |
---|
1671 | * |
---|
1672 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
1673 | * |
---|
1674 | * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier |
---|
1675 | * specified by ``id``. |
---|
1676 | * |
---|
1677 | * @retval ::RTEMS_INCORRECT_STATE The task was not suspended. |
---|
1678 | * |
---|
1679 | * @par Constraints |
---|
1680 | * @parblock |
---|
1681 | * The following constraints apply to this directive: |
---|
1682 | * |
---|
1683 | * * The directive may be called from within interrupt context. |
---|
1684 | * |
---|
1685 | * * The directive may be called from within device driver initialization |
---|
1686 | * context. |
---|
1687 | * |
---|
1688 | * * The directive may be called from within task context. |
---|
1689 | * |
---|
1690 | * * The directive may unblock a task. This may cause the calling task to be |
---|
1691 | * preempted. |
---|
1692 | * |
---|
1693 | * * When the directive operates on a remote object, the directive sends a |
---|
1694 | * message to the remote node and waits for a reply. This will preempt the |
---|
1695 | * calling task. |
---|
1696 | * @endparblock |
---|
1697 | */ |
---|
1698 | rtems_status_code rtems_task_resume( rtems_id id ); |
---|
1699 | |
---|
1700 | /* Generated from spec:/rtems/task/if/is-suspended */ |
---|
1701 | |
---|
1702 | /** |
---|
1703 | * @ingroup RTEMSAPIClassicTasks |
---|
1704 | * |
---|
1705 | * @brief Checks if the task is suspended. |
---|
1706 | * |
---|
1707 | * @param id is the task identifier. The constant #RTEMS_SELF may be used to |
---|
1708 | * specify the calling task. |
---|
1709 | * |
---|
1710 | * This directive returns a status code indicating whether or not the task |
---|
1711 | * specified by ``id`` is currently suspended. |
---|
1712 | * |
---|
1713 | * @retval ::RTEMS_SUCCESSFUL The task was **not** suspended. |
---|
1714 | * |
---|
1715 | * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier |
---|
1716 | * specified by ``id``. |
---|
1717 | * |
---|
1718 | * @retval ::RTEMS_ALREADY_SUSPENDED The task was suspended. |
---|
1719 | * |
---|
1720 | * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. |
---|
1721 | * |
---|
1722 | * @par Constraints |
---|
1723 | * @parblock |
---|
1724 | * The following constraints apply to this directive: |
---|
1725 | * |
---|
1726 | * * The directive may be called from within interrupt context. |
---|
1727 | * |
---|
1728 | * * The directive may be called from within device driver initialization |
---|
1729 | * context. |
---|
1730 | * |
---|
1731 | * * The directive may be called from within task context. |
---|
1732 | * |
---|
1733 | * * The directive will not cause the calling task to be preempted. |
---|
1734 | * @endparblock |
---|
1735 | */ |
---|
1736 | rtems_status_code rtems_task_is_suspended( rtems_id id ); |
---|
1737 | |
---|
1738 | /* Generated from spec:/rtems/task/if/set-priority */ |
---|
1739 | |
---|
1740 | /** |
---|
1741 | * @ingroup RTEMSAPIClassicTasks |
---|
1742 | * |
---|
1743 | * @brief Sets the real priority or gets the current priority of the task. |
---|
1744 | * |
---|
1745 | * @param id is the task identifier. The constant #RTEMS_SELF may be used to |
---|
1746 | * specify the calling task. |
---|
1747 | * |
---|
1748 | * @param new_priority is the new real priority or #RTEMS_CURRENT_PRIORITY to |
---|
1749 | * get the current priority. |
---|
1750 | * |
---|
1751 | * @param[out] old_priority is the pointer to an ::rtems_task_priority |
---|
1752 | * variable. When the directive call is successful, the current or previous |
---|
1753 | * priority of the task with respect to its home scheduler will be stored in |
---|
1754 | * this variable. |
---|
1755 | * |
---|
1756 | * This directive manipulates the priority of the task specified by ``id``. |
---|
1757 | * When ``new_priority`` is not equal to #RTEMS_CURRENT_PRIORITY, the specified |
---|
1758 | * task's previous priority is returned in ``old_priority``. When |
---|
1759 | * ``new_priority`` is #RTEMS_CURRENT_PRIORITY, the specified task's current |
---|
1760 | * priority is returned in ``old_priority``. |
---|
1761 | * |
---|
1762 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
1763 | * |
---|
1764 | * @retval ::RTEMS_INVALID_ADDRESS The ``old_priority`` parameter was NULL. |
---|
1765 | * |
---|
1766 | * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier |
---|
1767 | * specified by ``id``. |
---|
1768 | * |
---|
1769 | * @retval ::RTEMS_INVALID_PRIORITY The task priority specified in |
---|
1770 | * ``new_priority`` was invalid with respect to the home scheduler of the |
---|
1771 | * task. |
---|
1772 | * |
---|
1773 | * @par Notes |
---|
1774 | * @parblock |
---|
1775 | * Valid priorities range from one to a maximum value which depends on the |
---|
1776 | * configured scheduler. The lower the priority value the higher is the |
---|
1777 | * importance of the task. |
---|
1778 | * |
---|
1779 | * If the task is currently holding any binary semaphores which use a locking |
---|
1780 | * protocol, then the task's priority cannot be lowered immediately. If the |
---|
1781 | * task's priority were lowered immediately, then this could violate properties |
---|
1782 | * of the locking protocol and may result in priority inversion. The requested |
---|
1783 | * lowering of the task's priority will occur when the task has released all |
---|
1784 | * binary semaphores which make the task more important. The task's priority |
---|
1785 | * can be increased regardless of the task's use of binary semaphores with |
---|
1786 | * locking protocols. |
---|
1787 | * @endparblock |
---|
1788 | * |
---|
1789 | * @par Constraints |
---|
1790 | * @parblock |
---|
1791 | * The following constraints apply to this directive: |
---|
1792 | * |
---|
1793 | * * The directive may be called from within interrupt context. |
---|
1794 | * |
---|
1795 | * * The directive may be called from within device driver initialization |
---|
1796 | * context. |
---|
1797 | * |
---|
1798 | * * The directive may be called from within task context. |
---|
1799 | * |
---|
1800 | * * The directive may change the priority of a task. This may cause the |
---|
1801 | * calling task to be preempted. |
---|
1802 | * |
---|
1803 | * * When the directive operates on a remote object, the directive sends a |
---|
1804 | * message to the remote node and waits for a reply. This will preempt the |
---|
1805 | * calling task. |
---|
1806 | * @endparblock |
---|
1807 | */ |
---|
1808 | rtems_status_code rtems_task_set_priority( |
---|
1809 | rtems_id id, |
---|
1810 | rtems_task_priority new_priority, |
---|
1811 | rtems_task_priority *old_priority |
---|
1812 | ); |
---|
1813 | |
---|
1814 | /* Generated from spec:/rtems/task/if/get-priority */ |
---|
1815 | |
---|
1816 | /** |
---|
1817 | * @ingroup RTEMSAPIClassicTasks |
---|
1818 | * |
---|
1819 | * @brief Gets the current priority of the task with respect to the scheduler. |
---|
1820 | * |
---|
1821 | * @param task_id is the task identifier. The constant #RTEMS_SELF may be used |
---|
1822 | * to specify the calling task. |
---|
1823 | * |
---|
1824 | * @param scheduler_id is the scheduler identifier. |
---|
1825 | * |
---|
1826 | * @param[out] priority is the pointer to an ::rtems_task_priority variable. |
---|
1827 | * When the directive call is successful, the current priority of the task |
---|
1828 | * with respect to the specified scheduler will be stored in this variable. |
---|
1829 | * |
---|
1830 | * This directive returns the current priority in ``priority`` of the task |
---|
1831 | * specified by ``task_id`` with respect to the scheduler specified by |
---|
1832 | * ``scheduler_id``. |
---|
1833 | * |
---|
1834 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
1835 | * |
---|
1836 | * @retval ::RTEMS_INVALID_ADDRESS The ``priority`` parameter was NULL. |
---|
1837 | * |
---|
1838 | * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier |
---|
1839 | * specified by ``task_id``. |
---|
1840 | * |
---|
1841 | * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the |
---|
1842 | * identifier specified by ``scheduler_id``. |
---|
1843 | * |
---|
1844 | * @retval ::RTEMS_NOT_DEFINED The task had no priority with respect to the |
---|
1845 | * scheduler. |
---|
1846 | * |
---|
1847 | * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. |
---|
1848 | * |
---|
1849 | * @par Notes |
---|
1850 | * The current priority reflects temporary priority adjustments due to locking |
---|
1851 | * protocols, the rate-monotonic period objects on some schedulers such as EDF, |
---|
1852 | * and the POSIX sporadic server. |
---|
1853 | * |
---|
1854 | * @par Constraints |
---|
1855 | * @parblock |
---|
1856 | * The following constraints apply to this directive: |
---|
1857 | * |
---|
1858 | * * The directive may be called from within interrupt context. |
---|
1859 | * |
---|
1860 | * * The directive may be called from within device driver initialization |
---|
1861 | * context. |
---|
1862 | * |
---|
1863 | * * The directive may be called from within task context. |
---|
1864 | * |
---|
1865 | * * The directive will not cause the calling task to be preempted. |
---|
1866 | * @endparblock |
---|
1867 | */ |
---|
1868 | rtems_status_code rtems_task_get_priority( |
---|
1869 | rtems_id task_id, |
---|
1870 | rtems_id scheduler_id, |
---|
1871 | rtems_task_priority *priority |
---|
1872 | ); |
---|
1873 | |
---|
1874 | /* Generated from spec:/rtems/task/if/mode */ |
---|
1875 | |
---|
1876 | /** |
---|
1877 | * @ingroup RTEMSAPIClassicTasks |
---|
1878 | * |
---|
1879 | * @brief Gets and optionally sets the mode of the calling task. |
---|
1880 | * |
---|
1881 | * @param mode_set is the mode set to apply to the calling task. When ``mask`` |
---|
1882 | * is set to #RTEMS_CURRENT_MODE, the value of this parameter is ignored. |
---|
1883 | * Only modes requested by ``mask`` are applied to the calling task. |
---|
1884 | * |
---|
1885 | * @param mask is the mode mask which specifies which modes in ``mode_set`` are |
---|
1886 | * applied to the calling task. When the value is #RTEMS_CURRENT_MODE, the |
---|
1887 | * mode of the calling task is not changed. |
---|
1888 | * |
---|
1889 | * @param previous_mode_set is the pointer to a mode variable. When the |
---|
1890 | * directive call is successful, the mode of the task before any mode changes |
---|
1891 | * done by the directive call will be stored in this variable. |
---|
1892 | * |
---|
1893 | * This directive queries and optionally manipulates the execution mode of the |
---|
1894 | * calling task. A task's execution mode enables and disables preemption, |
---|
1895 | * timeslicing, asynchronous signal processing, as well as specifying the |
---|
1896 | * interrupt level. To modify an execution mode, the mode class(es) to be |
---|
1897 | * changed must be specified in the ``mask`` parameter and the desired mode(s) |
---|
1898 | * must be specified in the ``mode_set`` parameter. |
---|
1899 | * |
---|
1900 | * A task can obtain its current execution mode, without modifying it, by |
---|
1901 | * calling this directive with a ``mask`` value of #RTEMS_CURRENT_MODE. |
---|
1902 | * |
---|
1903 | * The **mode set** specified in ``mode_set`` is built through a *bitwise or* |
---|
1904 | * of the mode constants described below. Not all combinations of modes are |
---|
1905 | * allowed. Some modes are mutually exclusive. If mutually exclusive modes |
---|
1906 | * are combined, the behaviour is undefined. Default task modes can be |
---|
1907 | * selected by using the #RTEMS_DEFAULT_MODES constant. The task mode set |
---|
1908 | * defines |
---|
1909 | * |
---|
1910 | * * the preemption mode of the task: #RTEMS_PREEMPT (default) or |
---|
1911 | * #RTEMS_NO_PREEMPT, |
---|
1912 | * |
---|
1913 | * * the timeslicing mode of the task: #RTEMS_TIMESLICE or #RTEMS_NO_TIMESLICE |
---|
1914 | * (default), |
---|
1915 | * |
---|
1916 | * * the ASR processing mode of the task: #RTEMS_ASR (default) or |
---|
1917 | * #RTEMS_NO_ASR, |
---|
1918 | * |
---|
1919 | * * the interrupt level of the task: RTEMS_INTERRUPT_LEVEL() with a default of |
---|
1920 | * ``RTEMS_INTERRUPT_LEVEL( 0 )`` which is associated with enabled |
---|
1921 | * interrupts. |
---|
1922 | * |
---|
1923 | * The **mode mask** specified in ``mask`` is built through a *bitwise or* of |
---|
1924 | * the mode mask constants described below. |
---|
1925 | * |
---|
1926 | * When the #RTEMS_PREEMPT_MASK is set in ``mask``, the **preemption mode** of |
---|
1927 | * the calling task is |
---|
1928 | * |
---|
1929 | * * enabled by using the #RTEMS_PREEMPT mode constant in ``mode_set`` and |
---|
1930 | * |
---|
1931 | * * disabled by using the #RTEMS_NO_PREEMPT mode constant in ``mode_set``. |
---|
1932 | * |
---|
1933 | * When the #RTEMS_TIMESLICE_MASK is set in ``mask``, the **timeslicing mode** |
---|
1934 | * of the calling task is |
---|
1935 | * |
---|
1936 | * * enabled by using the #RTEMS_TIMESLICE mode constant in ``mode_set`` and |
---|
1937 | * |
---|
1938 | * * disabled by using the #RTEMS_NO_TIMESLICE mode constant in ``mode_set``. |
---|
1939 | * |
---|
1940 | * Enabling timeslicing has no effect if preemption is disabled. For a task to |
---|
1941 | * be timesliced, that task must have both preemption and timeslicing enabled. |
---|
1942 | * |
---|
1943 | * When the #RTEMS_ASR_MASK is set in ``mask``, the **ASR processing mode** of |
---|
1944 | * the calling task is |
---|
1945 | * |
---|
1946 | * * enabled by using the #RTEMS_ASR mode constant in ``mode_set`` and |
---|
1947 | * |
---|
1948 | * * disabled by using the #RTEMS_NO_ASR mode constant in ``mode_set``. |
---|
1949 | * |
---|
1950 | * When the #RTEMS_INTERRUPT_MASK is set in ``mask``, **interrupts** of the |
---|
1951 | * calling task are |
---|
1952 | * |
---|
1953 | * * enabled by using the RTEMS_INTERRUPT_LEVEL() mode macro with a value of |
---|
1954 | * zero (0) in ``mode_set`` and |
---|
1955 | * |
---|
1956 | * * disabled up to the specified level by using the RTEMS_INTERRUPT_LEVEL() |
---|
1957 | * mode macro with a positive value in ``mode_set``. |
---|
1958 | * |
---|
1959 | * An interrupt level of zero is associated with enabled interrupts on all |
---|
1960 | * target processors. The interrupt level portion of the task mode supports a |
---|
1961 | * maximum of 256 interrupt levels. These levels are mapped onto the interrupt |
---|
1962 | * levels actually supported by the target processor in a processor dependent |
---|
1963 | * fashion. |
---|
1964 | * |
---|
1965 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
1966 | * |
---|
1967 | * @retval ::RTEMS_NOT_IMPLEMENTED The #RTEMS_NO_PREEMPT was set in |
---|
1968 | * ``mode_set`` and setting the preemption mode was requested by |
---|
1969 | * #RTEMS_PREEMPT_MASK in ``mask`` and the system configuration had no |
---|
1970 | * implementation for this mode. |
---|
1971 | * |
---|
1972 | * @retval ::RTEMS_NOT_IMPLEMENTED The RTEMS_INTERRUPT_LEVEL() was set to a |
---|
1973 | * positive level in ``mode_set`` and setting the interrupt level was |
---|
1974 | * requested by #RTEMS_INTERRUPT_MASK in ``mask`` and the system |
---|
1975 | * configuration had no implementation for this mode. |
---|
1976 | * |
---|
1977 | * @par Constraints |
---|
1978 | * @parblock |
---|
1979 | * The following constraints apply to this directive: |
---|
1980 | * |
---|
1981 | * * The directive may be called from within task context. |
---|
1982 | * |
---|
1983 | * * When the directive enables preemption for the calling task, another task |
---|
1984 | * may preempt the calling task. |
---|
1985 | * |
---|
1986 | * * While thread dispatching is disabled, if the directive performs a thread |
---|
1987 | * dispatch, then the fatal error with the fatal source INTERNAL_ERROR_CORE |
---|
1988 | * and the fatal code INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL will |
---|
1989 | * occur. |
---|
1990 | * @endparblock |
---|
1991 | */ |
---|
1992 | rtems_status_code rtems_task_mode( |
---|
1993 | rtems_mode mode_set, |
---|
1994 | rtems_mode mask, |
---|
1995 | rtems_mode *previous_mode_set |
---|
1996 | ); |
---|
1997 | |
---|
1998 | /* Generated from spec:/rtems/task/if/wake-after */ |
---|
1999 | |
---|
2000 | /** |
---|
2001 | * @ingroup RTEMSAPIClassicTasks |
---|
2002 | * |
---|
2003 | * @brief Wakes up after an interval in clock ticks or yields the processor. |
---|
2004 | * |
---|
2005 | * @param ticks is the interval in clock ticks to delay the task or |
---|
2006 | * #RTEMS_YIELD_PROCESSOR to yield the processor. |
---|
2007 | * |
---|
2008 | * This directive blocks the calling task for the specified ``ticks`` of clock |
---|
2009 | * ticks if the value is not equal to #RTEMS_YIELD_PROCESSOR. When the |
---|
2010 | * requested interval has elapsed, the task is made ready. The clock tick |
---|
2011 | * directives automatically updates the delay period. The calling task may |
---|
2012 | * give up the processor and remain in the ready state by specifying a value of |
---|
2013 | * #RTEMS_YIELD_PROCESSOR in ``ticks``. |
---|
2014 | * |
---|
2015 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
2016 | * |
---|
2017 | * @par Notes |
---|
2018 | * Setting the system date and time with the rtems_clock_set() directive and |
---|
2019 | * similar directives which set CLOCK_REALTIME have no effect on a |
---|
2020 | * rtems_task_wake_after() blocked task. |
---|
2021 | * |
---|
2022 | * @par Constraints |
---|
2023 | * @parblock |
---|
2024 | * The following constraints apply to this directive: |
---|
2025 | * |
---|
2026 | * * The directive may be called from within task context. |
---|
2027 | * |
---|
2028 | * * The directive requires a Clock Driver. |
---|
2029 | * |
---|
2030 | * * While thread dispatching is disabled, if the directive performs a thread |
---|
2031 | * dispatch, then the fatal error with the fatal source INTERNAL_ERROR_CORE |
---|
2032 | * and the fatal code INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL will |
---|
2033 | * occur. |
---|
2034 | * @endparblock |
---|
2035 | */ |
---|
2036 | rtems_status_code rtems_task_wake_after( rtems_interval ticks ); |
---|
2037 | |
---|
2038 | /* Generated from spec:/rtems/task/if/wake-when */ |
---|
2039 | |
---|
2040 | /** |
---|
2041 | * @ingroup RTEMSAPIClassicTasks |
---|
2042 | * |
---|
2043 | * @brief Wakes up when specified. |
---|
2044 | * |
---|
2045 | * @param time_buffer is the date and time to wake up. |
---|
2046 | * |
---|
2047 | * This directive blocks a task until the date and time specified in |
---|
2048 | * ``time_buffer``. At the requested date and time, the calling task will be |
---|
2049 | * unblocked and made ready to execute. |
---|
2050 | * |
---|
2051 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
2052 | * |
---|
2053 | * @retval ::RTEMS_NOT_DEFINED The system date and time was not set. |
---|
2054 | * |
---|
2055 | * @retval ::RTEMS_INVALID_ADDRESS The ``time_buffer`` parameter was NULL. |
---|
2056 | * |
---|
2057 | * @retval ::RTEMS_INVALID_CLOCK The time of day was invalid. |
---|
2058 | * |
---|
2059 | * @par Notes |
---|
2060 | * The ticks portion of ``time_buffer`` structure is ignored. The timing |
---|
2061 | * granularity of this directive is a second. |
---|
2062 | * |
---|
2063 | * @par Constraints |
---|
2064 | * @parblock |
---|
2065 | * The following constraints apply to this directive: |
---|
2066 | * |
---|
2067 | * * The directive may be called from within task context. |
---|
2068 | * |
---|
2069 | * * The directive requires a Clock Driver. |
---|
2070 | * |
---|
2071 | * * While thread dispatching is disabled, if the directive performs a thread |
---|
2072 | * dispatch, then the fatal error with the fatal source INTERNAL_ERROR_CORE |
---|
2073 | * and the fatal code INTERNAL_ERROR_BAD_THREAD_DISPATCH_DISABLE_LEVEL will |
---|
2074 | * occur. |
---|
2075 | * @endparblock |
---|
2076 | */ |
---|
2077 | rtems_status_code rtems_task_wake_when( const rtems_time_of_day *time_buffer ); |
---|
2078 | |
---|
2079 | /* Generated from spec:/rtems/task/if/get-scheduler */ |
---|
2080 | |
---|
2081 | /** |
---|
2082 | * @ingroup RTEMSAPIClassicTasks |
---|
2083 | * |
---|
2084 | * @brief Gets the home scheduler of the task. |
---|
2085 | * |
---|
2086 | * @param task_id is the task identifier. The constant #RTEMS_SELF may be used |
---|
2087 | * to specify the calling task. |
---|
2088 | * |
---|
2089 | * @param[out] scheduler_id is the pointer to an ::rtems_id variable. When the |
---|
2090 | * directive call is successful, the identifier of the home scheduler of the |
---|
2091 | * task will be stored in this variable. |
---|
2092 | * |
---|
2093 | * This directive returns the identifier of the home scheduler of the task |
---|
2094 | * specified by ``task_id`` in ``scheduler_id``. |
---|
2095 | * |
---|
2096 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
2097 | * |
---|
2098 | * @retval ::RTEMS_INVALID_ADDRESS The ``scheduler_id`` parameter was NULL. |
---|
2099 | * |
---|
2100 | * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier |
---|
2101 | * specified by ``task_id``. |
---|
2102 | * |
---|
2103 | * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. |
---|
2104 | * |
---|
2105 | * @par Constraints |
---|
2106 | * @parblock |
---|
2107 | * The following constraints apply to this directive: |
---|
2108 | * |
---|
2109 | * * The directive may be called from within interrupt context. |
---|
2110 | * |
---|
2111 | * * The directive may be called from within device driver initialization |
---|
2112 | * context. |
---|
2113 | * |
---|
2114 | * * The directive may be called from within task context. |
---|
2115 | * |
---|
2116 | * * The directive will not cause the calling task to be preempted. |
---|
2117 | * @endparblock |
---|
2118 | */ |
---|
2119 | rtems_status_code rtems_task_get_scheduler( |
---|
2120 | rtems_id task_id, |
---|
2121 | rtems_id *scheduler_id |
---|
2122 | ); |
---|
2123 | |
---|
2124 | /* Generated from spec:/rtems/task/if/set-scheduler */ |
---|
2125 | |
---|
2126 | /** |
---|
2127 | * @ingroup RTEMSAPIClassicTasks |
---|
2128 | * |
---|
2129 | * @brief Sets the home scheduler for the task. |
---|
2130 | * |
---|
2131 | * @param task_id is the task identifier. The constant #RTEMS_SELF may be used |
---|
2132 | * to specify the calling task. |
---|
2133 | * |
---|
2134 | * @param scheduler_id is the scheduler identifier of the new home scheduler |
---|
2135 | * for the task specified by ``task_id``. |
---|
2136 | * |
---|
2137 | * @param priority is the new real priority for the task with respect to the |
---|
2138 | * scheduler specified by ``scheduler_id``. |
---|
2139 | * |
---|
2140 | * This directive sets the home scheduler to the scheduler specified by |
---|
2141 | * ``scheduler_id`` for the task specified by ``task_id``. |
---|
2142 | * |
---|
2143 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
2144 | * |
---|
2145 | * @retval ::RTEMS_INVALID_ID There was no scheduler associated with the |
---|
2146 | * identifier specified by ``scheduler_id``. |
---|
2147 | * |
---|
2148 | * @retval ::RTEMS_INVALID_PRIORITY The task priority specified by ``priority`` |
---|
2149 | * was invalid with respect to the scheduler specified by ``scheduler_id``. |
---|
2150 | * |
---|
2151 | * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier |
---|
2152 | * specified by ``task_id``. |
---|
2153 | * |
---|
2154 | * @retval ::RTEMS_RESOURCE_IN_USE The task specified by ``task_id`` was |
---|
2155 | * enqueued on a wait queue. |
---|
2156 | * |
---|
2157 | * @retval ::RTEMS_RESOURCE_IN_USE The task specified by ``task_id`` had a |
---|
2158 | * current priority which consisted of more than the real priority. |
---|
2159 | * |
---|
2160 | * @retval ::RTEMS_RESOURCE_IN_USE The task specified by ``task_id`` had a |
---|
2161 | * helping scheduler. |
---|
2162 | * |
---|
2163 | * @retval ::RTEMS_RESOURCE_IN_USE The task specified by ``task_id`` was |
---|
2164 | * pinned. |
---|
2165 | * |
---|
2166 | * @retval ::RTEMS_UNSATISFIED The scheduler specified by ``scheduler_id`` |
---|
2167 | * owned no processor. |
---|
2168 | * |
---|
2169 | * @retval ::RTEMS_UNSATISFIED The scheduler specified by ``scheduler_id`` did |
---|
2170 | * not support the affinity set of the task specified by ``task_id``. |
---|
2171 | * |
---|
2172 | * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. |
---|
2173 | * |
---|
2174 | * @par Constraints |
---|
2175 | * @parblock |
---|
2176 | * The following constraints apply to this directive: |
---|
2177 | * |
---|
2178 | * * The directive may be called from within interrupt context. |
---|
2179 | * |
---|
2180 | * * The directive may be called from within device driver initialization |
---|
2181 | * context. |
---|
2182 | * |
---|
2183 | * * The directive may be called from within task context. |
---|
2184 | * |
---|
2185 | * * The directive may change the priority of a task. This may cause the |
---|
2186 | * calling task to be preempted. |
---|
2187 | * @endparblock |
---|
2188 | */ |
---|
2189 | rtems_status_code rtems_task_set_scheduler( |
---|
2190 | rtems_id task_id, |
---|
2191 | rtems_id scheduler_id, |
---|
2192 | rtems_task_priority priority |
---|
2193 | ); |
---|
2194 | |
---|
2195 | /* Generated from spec:/rtems/task/if/get-affinity */ |
---|
2196 | |
---|
2197 | /** |
---|
2198 | * @ingroup RTEMSAPIClassicTasks |
---|
2199 | * |
---|
2200 | * @brief Gets the processor affinity of the task. |
---|
2201 | * |
---|
2202 | * @param id is the task identifier. The constant #RTEMS_SELF may be used to |
---|
2203 | * specify the calling task. |
---|
2204 | * |
---|
2205 | * @param cpusetsize is the size of the referenced processor set variable in |
---|
2206 | * bytes. |
---|
2207 | * |
---|
2208 | * @param[out] cpuset is the pointer to a processor set variable. When the |
---|
2209 | * directive call is successful, the processor affinity set of the task will |
---|
2210 | * be stored in this variable. A set bit in the processor set means that the |
---|
2211 | * corresponding processor is in the processor affinity set of the task, |
---|
2212 | * otherwise the bit is cleared. |
---|
2213 | * |
---|
2214 | * This directive returns the processor affinity of the task in ``cpuset`` of |
---|
2215 | * the task specified by ``id``. |
---|
2216 | * |
---|
2217 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
2218 | * |
---|
2219 | * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL. |
---|
2220 | * |
---|
2221 | * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier |
---|
2222 | * specified by ``id``. |
---|
2223 | * |
---|
2224 | * @retval ::RTEMS_INVALID_SIZE The provided processor set was too small for |
---|
2225 | * the processor affinity set of the task. |
---|
2226 | * |
---|
2227 | * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. |
---|
2228 | * |
---|
2229 | * @par Constraints |
---|
2230 | * @parblock |
---|
2231 | * The following constraints apply to this directive: |
---|
2232 | * |
---|
2233 | * * The directive may be called from within interrupt context. |
---|
2234 | * |
---|
2235 | * * The directive may be called from within device driver initialization |
---|
2236 | * context. |
---|
2237 | * |
---|
2238 | * * The directive may be called from within task context. |
---|
2239 | * |
---|
2240 | * * The directive will not cause the calling task to be preempted. |
---|
2241 | * @endparblock |
---|
2242 | */ |
---|
2243 | rtems_status_code rtems_task_get_affinity( |
---|
2244 | rtems_id id, |
---|
2245 | size_t cpusetsize, |
---|
2246 | cpu_set_t *cpuset |
---|
2247 | ); |
---|
2248 | |
---|
2249 | /* Generated from spec:/rtems/task/if/set-affinity */ |
---|
2250 | |
---|
2251 | /** |
---|
2252 | * @ingroup RTEMSAPIClassicTasks |
---|
2253 | * |
---|
2254 | * @brief Sets the processor affinity of the task. |
---|
2255 | * |
---|
2256 | * @param id is the task identifier. The constant #RTEMS_SELF may be used to |
---|
2257 | * specify the calling task. |
---|
2258 | * |
---|
2259 | * @param cpusetsize is the size of the referenced processor set variable in |
---|
2260 | * bytes. |
---|
2261 | * |
---|
2262 | * @param cpuset is the pointer to a processor set variable. The processor set |
---|
2263 | * defines the new processor affinity set of the task. A set bit in the |
---|
2264 | * processor set means that the corresponding processor shall be in the |
---|
2265 | * processor affinity set of the task, otherwise the bit shall be cleared. |
---|
2266 | * |
---|
2267 | * This directive sets the processor affinity of the task specified by ``id``. |
---|
2268 | * |
---|
2269 | * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. |
---|
2270 | * |
---|
2271 | * @retval ::RTEMS_INVALID_ADDRESS The ``cpuset`` parameter was NULL. |
---|
2272 | * |
---|
2273 | * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier |
---|
2274 | * specified by ``id``. |
---|
2275 | * |
---|
2276 | * @retval ::RTEMS_INVALID_NUMBER The referenced processor set was not a valid |
---|
2277 | * new processor affinity set for the task. |
---|
2278 | * |
---|
2279 | * @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node. |
---|
2280 | * |
---|
2281 | * @par Constraints |
---|
2282 | * @parblock |
---|
2283 | * The following constraints apply to this directive: |
---|
2284 | * |
---|
2285 | * * The directive may be called from within interrupt context. |
---|
2286 | * |
---|
2287 | * * The directive may be called from within device driver initialization |
---|
2288 | * context. |
---|
2289 | * |
---|
2290 | * * The directive may be called from within task context. |
---|
2291 | * |
---|
2292 | * * The directive may change the processor affinity of a task. This may cause |
---|
2293 | * the calling task to be preempted. |
---|
2294 | * @endparblock |
---|
2295 | */ |
---|
2296 | rtems_status_code rtems_task_set_affinity( |
---|
2297 | rtems_id id, |
---|
2298 | size_t cpusetsize, |
---|
2299 | const cpu_set_t *cpuset |
---|
2300 | ); |
---|
2301 | |
---|
2302 | /* Generated from spec:/rtems/task/if/iterate */ |
---|
2303 | |
---|
2304 | /** |
---|
2305 | * @ingroup RTEMSAPIClassicTasks |
---|
2306 | * |
---|
2307 | * @brief Iterates over all tasks and invokes the visitor routine for each |
---|
2308 | * task. |
---|
2309 | * |
---|
2310 | * @param visitor is the visitor routine invoked for each task. |
---|
2311 | * |
---|
2312 | * @param arg is the argument passed to each visitor routine invocation during |
---|
2313 | * the iteration. |
---|
2314 | * |
---|
2315 | * This directive iterates over all tasks in the system. This operation covers |
---|
2316 | * all tasks of all APIs. The user should be careful in accessing the contents |
---|
2317 | * of the TCB. The visitor argument ``arg`` is passed to all invocations of |
---|
2318 | * ``visitor`` in addition to the TCB. The iteration stops immediately in case |
---|
2319 | * the visitor routine returns true. |
---|
2320 | * |
---|
2321 | * @par Notes |
---|
2322 | * The visitor routine is invoked while owning the objects allocator lock. It |
---|
2323 | * is allowed to perform blocking operations in the visitor routine, however, |
---|
2324 | * care must be taken so that no deadlocks via the object allocator lock can |
---|
2325 | * occur. |
---|
2326 | * |
---|
2327 | * @par Constraints |
---|
2328 | * @parblock |
---|
2329 | * The following constraints apply to this directive: |
---|
2330 | * |
---|
2331 | * * The directive may be called from within device driver initialization |
---|
2332 | * context. |
---|
2333 | * |
---|
2334 | * * The directive may be called from within task context. |
---|
2335 | * |
---|
2336 | * * The directive may obtain and release the object allocator mutex. This may |
---|
2337 | * cause the calling task to be preempted. |
---|
2338 | * @endparblock |
---|
2339 | */ |
---|
2340 | void rtems_task_iterate( rtems_task_visitor visitor, void *arg ); |
---|
2341 | |
---|
2342 | #ifdef __cplusplus |
---|
2343 | } |
---|
2344 | #endif |
---|
2345 | |
---|
2346 | #endif /* _RTEMS_RTEMS_TASKS_H */ |
---|