source: rtems/cpukit/rtems/include/rtems/rtems/tasks.h @ 7a4b2645

5
Last change on this file since 7a4b2645 was 7a4b2645, checked in by Joel Sherrill <joel@…>, on 01/11/17 at 15:43:06

Remove obsolete RTEMS_HAVE_SYS_CPUSET_H

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