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

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

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