source: rtems/cpukit/include/rtems/rtems/tasks.h @ 2fa014db

Last change on this file since 2fa014db was 2fa014db, checked in by Sebastian Huber <sebastian.huber@…>, on Nov 8, 2018 at 11:05:44 AM

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