source: rtems/cpukit/include/rtems/rtems/tasks.h @ b7af3e44

Last change on this file since b7af3e44 was b7af3e44, checked in by Sebastian Huber <sebastian.huber@…>, on Nov 8, 2018 at 9:57:21 AM

rtems: Move internal structures to tasksdata.h

Update #3598.

  • Property mode set to 100644
File size: 21.3 KB
Line 
1/**
2 * @file
3 *
4 * @ingroup ClassicTasks
5 *
6 * @brief Classic Task Manager API
7 */
8
9/*
10 * COPYRIGHT (c) 1989-2014.
11 * On-Line Applications Research Corporation (OAR).
12 *
13 * The license and distribution terms for this file may be
14 * found in the file LICENSE in this distribution or at
15 * http://www.rtems.org/license/LICENSE.
16 */
17
18#ifndef _RTEMS_RTEMS_TASKS_H
19#define _RTEMS_RTEMS_TASKS_H
20
21#include <rtems/score/scheduler.h>
22#include <rtems/score/thread.h>
23#include <rtems/rtems/attr.h>
24#include <rtems/rtems/status.h>
25#include <rtems/rtems/types.h>
26
27#ifdef __cplusplus
28extern "C" {
29#endif
30
31/**
32 *  @defgroup ClassicTasks Tasks
33 *
34 *  @ingroup ClassicRTEMS
35 *
36 *  This encapsulates the functionality of the Classic API Task Manager.
37 *  This functionality includes task services such as creation, deletion,
38 *  delays, suspend/resume, and manipulation of execution mode and priority.
39 */
40/**@{*/
41
42/**
43 *  Constant to be used as the ID of current task
44 */
45#define RTEMS_SELF                OBJECTS_ID_OF_SELF
46
47/**
48 *  This constant is passed to the rtems_task_wake_after directive as the
49 *  interval when a task wishes to yield the CPU.
50 */
51#define RTEMS_YIELD_PROCESSOR WATCHDOG_NO_TIMEOUT
52
53/**
54 *  Define the type for an RTEMS API task priority.
55 */
56typedef uint32_t rtems_task_priority;
57
58/**
59 *  This is the constant used with the rtems_task_set_priority
60 *  directive to indicate that the caller wants to obtain its
61 *  current priority rather than set it as the name of the
62 *  directive indicates.
63 */
64#define RTEMS_NO_PRIORITY           RTEMS_CURRENT_PRIORITY
65
66/**
67 *  This constant is the least valid value for a Classic API
68 *  task priority.
69 */
70#define RTEMS_MINIMUM_PRIORITY      (PRIORITY_MINIMUM + 1)
71
72/**
73 *  This constant is the maximum valid value for a Classic API
74 *  task priority.
75 *
76 *  @note This is actually the priority of the IDLE thread so
77 *        using this priority will result in having a task
78 *        which never executes.  This could be useful if you
79 *        want to ensure that a task does not executes during
80 *        certain operations such as a system mode change.
81 */
82#define RTEMS_MAXIMUM_PRIORITY      ((rtems_task_priority) PRIORITY_MAXIMUM)
83
84/**
85 *  The following constant is passed to rtems_task_set_priority when the
86 *  caller wants to obtain the current priority.
87 */
88#define RTEMS_CURRENT_PRIORITY      PRIORITY_MINIMUM
89
90/**
91 *  External API name for Thread_Control
92 */
93typedef Thread_Control rtems_tcb;
94
95/**
96 *  The following defines the "return type" of an RTEMS task.
97 */
98typedef void rtems_task;
99
100/**
101 *  The following defines the argument to an RTEMS task.
102 */
103typedef Thread_Entry_numeric_type rtems_task_argument;
104
105/**
106 *  The following defines the type for the entry point of an RTEMS task.
107 */
108typedef rtems_task ( *rtems_task_entry )(
109                      rtems_task_argument
110                   );
111
112/**
113 *  The following records define the Initialization Tasks Table.
114 *  Each entry contains the information required by RTEMS to
115 *  create and start a user task automatically at executive
116 *  initialization time.
117 */
118typedef struct {
119  /** This is the Initialization Task's name. */
120  rtems_name            name;
121  /** This is the Initialization Task's stack size. */
122  size_t                stack_size;
123  /** This is the Initialization Task's priority. */
124  rtems_task_priority   initial_priority;
125  /** This is the Initialization Task's attributes. */
126  rtems_attribute       attribute_set;
127  /** This is the Initialization Task's entry point. */
128  rtems_task_entry      entry_point;
129  /** This is the Initialization Task's initial mode. */
130  rtems_mode            mode_set;
131  /** This is the Initialization Task's argument. */
132  rtems_task_argument   argument;
133} rtems_initialization_tasks_table;
134
135/**
136 * @brief RTEMS Task Create
137 *
138 * This routine implements the rtems_task_create directive. The task
139 * will have the name name. The attribute_set can be used to indicate
140 * that the task will be globally accessible or utilize floating point.
141 * The task's stack will be stack_size bytes. The task will begin
142 * execution with initial_priority and initial_modes. It returns the
143 * id of the created task in ID.
144 *
145 * @param[in] name is the user defined thread name
146 * @param[in] initial_priority is the thread priority
147 * @param[in] stack_size is the stack size in bytes
148 * @param[in] initial_modes is the initial thread mode
149 * @param[in] attribute_set is the thread attributes
150 * @param[in] id is the pointer to thread id
151 *
152 * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
153 *              and *id thread id filled in
154 */
155rtems_status_code rtems_task_create(
156  rtems_name           name,
157  rtems_task_priority  initial_priority,
158  size_t               stack_size,
159  rtems_mode           initial_modes,
160  rtems_attribute      attribute_set,
161  rtems_id            *id
162);
163
164/**
165 * @brief RTEMS Task Name to Id
166 *
167 * This routine implements the rtems_task_ident directive.
168 * This directive returns the task ID associated with name.
169 * If more than one task is named name, then the task to
170 * which the ID belongs is arbitrary. node indicates the
171 * extent of the search for the ID of the task named name.
172 * The search can be limited to a particular node or allowed to
173 * encompass all nodes.
174 *
175 * @param[in] name is the user defined thread name
176 * @param[in] node is(are) the node(s) to be searched
177 * @param[in] id is the pointer to thread id
178 *
179 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
180 *         error. Otherwise, a status code is returned indicating the
181 *         source of the error. If successful, the id will
182 *         be filled in with the thread id.
183 */
184rtems_status_code rtems_task_ident(
185  rtems_name    name,
186  uint32_t      node,
187  rtems_id     *id
188);
189
190/**
191 * @brief RTEMS Delete Task
192 *
193 * This routine implements the rtems_task_delete directive. The
194 * task indicated by ID is deleted. The executive halts execution
195 * of the thread and frees the thread control block.
196 *
197 * @param[in] id is the thread id
198 *
199 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
200 *         error and id is not the requesting thread. Status code is
201 *         returned indicating the source of the error. Nothing
202 *         is returned if id is the requesting thread (always succeeds).
203 */
204rtems_status_code rtems_task_delete(
205  rtems_id   id
206);
207
208void rtems_task_exit( void ) RTEMS_NO_RETURN;
209
210/**
211 * @brief RTEMS Task Mode
212 *
213 * This routine implements the rtems_task_mode directive. The current
214 * values of the modes indicated by mask of the calling task are changed
215 * to that indicated in mode_set. The former mode of the task is
216 * returned in mode_set.
217 *
218 * @param[in] mode_set is the new mode
219 * @param[in] mask is the mask
220 * @param[in] previous_mode_set is the address of previous mode set
221 *
222 * @retval RTEMS_SUCCESSFUL and previous_mode_set filled in with the
223 * previous mode set
224 */
225rtems_status_code rtems_task_mode(
226  rtems_mode  mode_set,
227  rtems_mode  mask,
228  rtems_mode *previous_mode_set
229);
230
231/**
232 * @brief RTEMS Task Restart
233 *
234 * This routine implements the rtems_task_restart directive. The
235 * task associated with ID is restarted at its initial entry
236 * point with the new argument.
237 *
238 * @param[in] id is the thread id
239 * @param[in] arg is the thread argument
240 *
241 * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
242 */
243rtems_status_code rtems_task_restart(
244  rtems_id   id,
245  uint32_t   arg
246);
247
248/**
249 * @brief RTEMS Suspend Task
250 *
251 * This routine implements the rtems_task_suspend directive. The
252 * SUSPENDED state is set for task associated with ID. Note that the
253 * suspended state can be in addition to other waiting states.
254 *
255 * @param[in] id is the thread id
256 *
257 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
258 *         error. Otherwise, a status code is returned indicating the
259 *         source of the error.
260 */
261rtems_status_code rtems_task_suspend(
262  rtems_id   id
263);
264
265/**
266 * @brief RTEMS Resume Task
267 *
268 * This routine implements the rtems_task_resume Directive. The
269 * SUSPENDED state is cleared for task associated with ID.
270 *
271 * @param[in] id is the thread id
272 *
273 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
274 *         error. Otherwise, a status code is returned indicating the
275 *         source of the error.
276 */
277rtems_status_code rtems_task_resume(
278  rtems_id   id
279);
280
281/**
282 * @brief RTEMS Set Task Priority
283 *
284 * This routine implements the rtems_task_set_priority directive. The
285 * current priority of the task associated with ID is set to
286 * new_priority. The former priority of that task is returned
287 * in old_priority.
288 *
289 * @param[in] id is the thread to extract
290 * @param[in] new_priority is the thread to extract
291 * @param[in] old_priority is the thread to extract
292 *
293 * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
294 * and *old_priority filled in with the previous previous priority
295 */
296rtems_status_code rtems_task_set_priority(
297  rtems_id             id,
298  rtems_task_priority  new_priority,
299  rtems_task_priority *old_priority
300);
301
302/**
303 * @brief Gets the current priority of the specified task with respect to the
304 * specified scheduler instance.
305 *
306 * The current priority reflects temporary priority adjustments due to locking
307 * protocols, the rate-monotonic period objects on some schedulers and other
308 * mechanisms.
309 *
310 * @param[in] task_id Identifier of the task.  Use @ref RTEMS_SELF to select
311 *   the executing task.
312 * @param[in] scheduler_id Identifier of the scheduler instance.
313 * @param[out] priority Returns the current priority of the specified task with
314 *   respect to the specified scheduler instance.
315 *
316 * @retval RTEMS_SUCCESSFUL Successful operation.
317 * @retval RTEMS_ILLEGAL_ON_REMOTE_OBJECT Directive is illegal on remote tasks.
318 * @retval RTEMS_INVALID_ADDRESS The priority parameter is @c NULL.
319 * @retval RTEMS_INVALID_ID Invalid task or scheduler identifier.
320 * @retval RTEMS_NOT_DEFINED The task has no priority within the specified
321 *   scheduler instance.  This error is only possible on SMP configurations.
322 *
323 * @see rtems_scheduler_ident().
324 */
325rtems_status_code rtems_task_get_priority(
326  rtems_id             task_id,
327  rtems_id             scheduler_id,
328  rtems_task_priority *priority
329);
330
331/**
332 *  @brief RTEMS Start Task
333 *
334 *  RTEMS Task Manager
335 *
336 *  This routine implements the rtems_task_start directive.  The
337 *  starting execution point of the task associated with ID is
338 *  set to entry_point with the initial argument.
339 */
340rtems_status_code rtems_task_start(
341  rtems_id             id,
342  rtems_task_entry     entry_point,
343  rtems_task_argument  argument
344);
345
346/**
347 * @brief RTEMS Task Wake When
348 *
349 * This routine implements the rtems_task_wake_when directive. The
350 * calling task is blocked until the current time of day is
351 * equal to that indicated by time_buffer.
352 *
353 * @param[in] time_buffer is the pointer to the time and date structure
354 *
355 * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
356 */
357rtems_status_code rtems_task_wake_when(
358  rtems_time_of_day *time_buffer
359);
360
361/**
362 * @brief RTEMS Task Wake After
363 *
364 * This routine implements the rtems_task_wake_after directive. The
365 * calling task is blocked until the indicated number of clock
366 * ticks have occurred.
367 *
368 * @param[in] ticks is the number of ticks to wait
369 * @retval RTEMS_SUCCESSFUL
370 */
371rtems_status_code rtems_task_wake_after(
372  rtems_interval  ticks
373);
374
375/**
376 *  @brief rtems_task_is_suspended
377 *
378 *  This directive returns a status indicating whether or not
379 *  the specified task is suspended.
380 */
381rtems_status_code rtems_task_is_suspended(
382  rtems_id   id
383);
384
385/**
386 * @brief Gets the processor affinity set of a task.
387 *
388 * @param[in] id Identifier of the task.  Use @ref RTEMS_SELF to select the
389 * executing task.
390 * @param[in] cpusetsize Size of the specified affinity set buffer in
391 * bytes.  This value must be positive.
392 * @param[out] cpuset The current processor affinity set of the task.  A set
393 * bit in the affinity set means that the task can execute on this processor
394 * and a cleared bit means the opposite.
395 *
396 * @retval RTEMS_SUCCESSFUL Successful operation.
397 * @retval RTEMS_INVALID_ADDRESS The @a cpuset parameter is @c NULL.
398 * @retval RTEMS_INVALID_ID Invalid task identifier.
399 * @retval RTEMS_INVALID_NUMBER The affinity set buffer is too small for the
400 * current processor affinity set of the task.
401 */
402rtems_status_code rtems_task_get_affinity(
403  rtems_id             id,
404  size_t               cpusetsize,
405  cpu_set_t           *cpuset
406);
407
408/**
409 * @brief Sets the processor affinity set of a task.
410 *
411 * This function will not change the scheduler of the task.  The intersection
412 * of the processor affinity set and the set of processors owned by the
413 * scheduler of the task must be non-empty.  It is not an error if the
414 * processor affinity set contains processors that are not part of the set of
415 * processors owned by the scheduler instance of the task.  A task will simply
416 * not run under normal circumstances on these processors since the scheduler
417 * ignores them.  Some locking protocols may temporarily use processors that
418 * are not included in the processor affinity set of the task.  It is also not
419 * an error if the processor affinity set contains processors that are not part
420 * of the system.
421 *
422 * @param[in] id Identifier of the task.  Use @ref RTEMS_SELF to select the
423 * executing task.
424 * @param[in] cpusetsize Size of the specified affinity set buffer in
425 * bytes.  This value must be positive.
426 * @param[in] cpuset The new processor affinity set for the task.  A set bit in
427 * the affinity set means that the task can execute on this processor and a
428 * cleared bit means the opposite.
429 *
430 * @retval RTEMS_SUCCESSFUL Successful operation.
431 * @retval RTEMS_INVALID_ADDRESS The @a cpuset parameter is @c NULL.
432 * @retval RTEMS_INVALID_ID Invalid task identifier.
433 * @retval RTEMS_INVALID_NUMBER Invalid processor affinity set.
434 */
435rtems_status_code rtems_task_set_affinity(
436  rtems_id         id,
437  size_t           cpusetsize,
438  const cpu_set_t *cpuset
439);
440
441/**
442 * @brief Gets the scheduler of a task.
443 *
444 * @param[in] task_id Identifier of the task.  Use @ref RTEMS_SELF to select
445 * the executing task.
446 * @param[out] scheduler_id Identifier of the scheduler instance.
447 *
448 * @retval RTEMS_SUCCESSFUL Successful operation.
449 * @retval RTEMS_INVALID_ADDRESS The @a scheduler_id parameter is @c NULL.
450 * @retval RTEMS_INVALID_ID Invalid task identifier.
451 */
452rtems_status_code rtems_task_get_scheduler(
453  rtems_id  task_id,
454  rtems_id *scheduler_id
455);
456
457/**
458 * @brief Sets the scheduler instance of a task.
459 *
460 * Initially, the scheduler instance of a task is set to the scheduler instance
461 * of the task that created it.  This directive allows to move a task from its
462 * current scheduler instance to another specified by the scheduler identifier.
463 *
464 * @param[in] task_id Identifier of the task.  Use @ref RTEMS_SELF to select
465 *   the executing task.
466 * @param[in] scheduler_id Identifier of the scheduler instance.
467 * @param[in] priority The task priority with respect to the new scheduler
468 *   instance.  The real and initial priority of the task is set to this value.
469 *   The initial priority is used by rtems_task_restart() for example.
470 *
471 * @retval RTEMS_SUCCESSFUL Successful operation.
472 * @retval RTEMS_ILLEGAL_ON_REMOTE_OBJECT Directive is illegal on remote tasks.
473 * @retval RTEMS_INVALID_ID Invalid task or scheduler identifier.
474 * @retval RTEMS_INVALID_PRIORITY Invalid priority.
475 * @retval RTEMS_RESOURCE_IN_USE The task owns resources which deny a scheduler
476 *   change.
477 *
478 * @see rtems_scheduler_ident().
479 */
480rtems_status_code rtems_task_set_scheduler(
481  rtems_id            task_id,
482  rtems_id            scheduler_id,
483  rtems_task_priority priority
484);
485
486/**
487 *  @brief RTEMS Get Self Task Id
488 *
489 *  This directive returns the ID of the currently executing task.
490 */
491rtems_id rtems_task_self(void);
492
493/**
494 * @brief Task visitor.
495 *
496 * @param[in] tcb The task control block.
497 * @param[in] arg The visitor argument.
498 *
499 * @retval true Stop the iteration.
500 * @retval false Otherwise.
501 *
502 * @see rtems_task_iterate().
503 */
504typedef bool ( *rtems_task_visitor )( rtems_tcb *tcb, void *arg );
505
506/**
507 * @brief Iterates over all tasks in the system.
508 *
509 * This operation covers all tasks of all APIs.
510 *
511 * Must be called from task context.  This operation obtains and releases the
512 * objects allocator lock.  The task visitor is called while owning the objects
513 * allocator lock.  It is possible to perform blocking operations in the task
514 * visitor, however, take care that no deadlocks via the object allocator lock
515 * can occur.
516 *
517 * @param[in] visitor The task visitor.
518 * @param[in] arg The visitor argument.
519 */
520void rtems_task_iterate(
521  rtems_task_visitor  visitor,
522  void               *arg
523);
524
525/**
526 * @brief Identifies a scheduler by its name.
527 *
528 * The scheduler name is determined by the scheduler configuration.
529 *
530 * @param[in] name The scheduler name.
531 * @param[out] id The scheduler identifier associated with the name.
532 *
533 * @retval RTEMS_SUCCESSFUL Successful operation.
534 * @retval RTEMS_INVALID_ADDRESS The @a id parameter is @c NULL.
535 * @retval RTEMS_INVALID_NAME Invalid scheduler name.
536 */
537rtems_status_code rtems_scheduler_ident(
538  rtems_name  name,
539  rtems_id   *id
540);
541
542/**
543 * @brief Identifies a scheduler by a processor index.
544 *
545 * @param[in] cpu_index The processor index.
546 * @param[out] id The scheduler identifier associated with the processor index.
547 *
548 * @retval RTEMS_SUCCESSFUL Successful operation.
549 * @retval RTEMS_INVALID_ADDRESS The @a id parameter is @c NULL.
550 * @retval RTEMS_INVALID_NAME Invalid processor index.
551 * @retval RTEMS_INCORRECT_STATE The processor index is valid, however, this
552 *   processor is not owned by a scheduler.
553 */
554rtems_status_code rtems_scheduler_ident_by_processor(
555  uint32_t  cpu_index,
556  rtems_id *id
557);
558
559/**
560 * @brief Identifies a scheduler by a processor set.
561 *
562 * The scheduler is selected according to the highest numbered online processor
563 * in the specified processor set.
564 *
565 * @param[in] cpusetsize Size of the specified processor set buffer in
566 *   bytes.  This value must be positive.
567 * @param[out] cpuset The processor set to identify the scheduler.
568 * @param[out] id The scheduler identifier associated with the processor set.
569 *
570 * @retval RTEMS_SUCCESSFUL Successful operation.
571 * @retval RTEMS_INVALID_ADDRESS The @a id parameter is @c NULL.
572 * @retval RTEMS_INVALID_SIZE Invalid processor set size.
573 * @retval RTEMS_INVALID_NAME The processor set contains no online processor.
574 * @retval RTEMS_INCORRECT_STATE The processor set is valid, however, the
575 *   highest numbered online processor in the specified processor set is not
576 *   owned by a scheduler.
577 */
578rtems_status_code rtems_scheduler_ident_by_processor_set(
579  size_t           cpusetsize,
580  const cpu_set_t *cpuset,
581  rtems_id        *id
582);
583
584/**
585 * @brief Gets the set of processors owned by the specified scheduler instance.
586 *
587 * @param[in] scheduler_id Identifier of the scheduler instance.
588 * @param[in] cpusetsize Size of the specified processor set buffer in
589 * bytes.  This value must be positive.
590 * @param[out] cpuset The processor set owned by the scheduler.  A set bit in
591 * the processor set means that this processor is owned by the scheduler and a
592 * cleared bit means the opposite.
593 *
594 * @retval RTEMS_SUCCESSFUL Successful operation.
595 * @retval RTEMS_INVALID_ADDRESS The @a cpuset parameter is @c NULL.
596 * @retval RTEMS_INVALID_ID Invalid scheduler instance identifier.
597 * @retval RTEMS_INVALID_NUMBER The processor set buffer is too small for the
598 * set of processors owned by the scheduler.
599 */
600rtems_status_code rtems_scheduler_get_processor_set(
601  rtems_id   scheduler_id,
602  size_t     cpusetsize,
603  cpu_set_t *cpuset
604);
605
606/**
607 * @brief Adds a processor to the set of processors owned by the specified
608 * scheduler instance.
609 *
610 * Must be called from task context.  This operation obtains and releases the
611 * objects allocator lock.
612 *
613 * @param[in] scheduler_id Identifier of the scheduler instance.
614 * @param[in] cpu_index Index of the processor to add.
615 *
616 * @retval RTEMS_SUCCESSFUL Successful operation.
617 * @retval RTEMS_INVALID_ID Invalid scheduler instance identifier.
618 * @retval RTEMS_NOT_CONFIGURED The processor is not configured to be used by
619 *   the application.
620 * @retval RTEMS_INCORRECT_STATE The processor is configured to be used by
621 *   the application, however, it is not online.
622 * @retval RTEMS_RESOURCE_IN_USE The processor is already assigned to a
623 *   scheduler instance.
624 */
625rtems_status_code rtems_scheduler_add_processor(
626  rtems_id scheduler_id,
627  uint32_t cpu_index
628);
629
630/**
631 * @brief Removes a processor from set of processors owned by the specified
632 * scheduler instance.
633 *
634 * Must be called from task context.  This operation obtains and releases the
635 * objects allocator lock.  Removing a processor from a scheduler is a complex
636 * operation that involves all tasks of the system.
637 *
638 * @param[in] scheduler_id Identifier of the scheduler instance.
639 * @param[in] cpu_index Index of the processor to add.
640 *
641 * @retval RTEMS_SUCCESSFUL Successful operation.
642 * @retval RTEMS_INVALID_ID Invalid scheduler instance identifier.
643 * @retval RTEMS_INVALID_NUMBER The processor is not owned by the specified
644 *   scheduler instance.
645 * @retval RTEMS_RESOURCE_IN_USE The set of processors owned by the specified
646 *   scheduler instance would be empty after the processor removal and there
647 *   exists a non-idle task that uses this scheduler instance as its home
648 *   scheduler instance.
649 */
650rtems_status_code rtems_scheduler_remove_processor(
651  rtems_id scheduler_id,
652  uint32_t cpu_index
653);
654
655/**@}*/
656
657#ifdef __cplusplus
658}
659#endif
660
661#endif
662/* end of include file */
Note: See TracBrowser for help on using the repository browser.