RTEMS 4.9.2 On-Line Library

Task Manager TASK_CREATE - Create a task

RTEMS C User's Guide

5.4.1: TASK_CREATE - Create a task

CALLING SEQUENCE:

rtems_status_code rtems_task_create(
  rtems_name           name,
  rtems_task_priority  initial_priority,
  size_t               stack_size,
  rtems_mode           initial_modes,
  rtems_attribute      attribute_set,
  rtems_id            *id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL - task created successfully
RTEMS_INVALID_ADDRESS - id is NULL
RTEMS_INVALID_NAME - invalid task name
RTEMS_INVALID_PRIORITY - invalid task priority
RTEMS_MP_NOT_CONFIGURED - multiprocessing not configured
RTEMS_TOO_MANY - too many tasks created
RTEMS_UNSATISFIED - not enough memory for stack/FP context
RTEMS_TOO_MANY - too many global objects

DESCRIPTION:

This directive creates a task which resides on the local node. It allocates and initializes a TCB, a stack, and an optional floating point context area. The mode parameter contains values which sets the task's initial execution mode. The RTEMS_FLOATING_POINT attribute should be specified if the created task is to use a numeric coprocessor. For performance reasons, it is recommended that tasks not using the numeric coprocessor should specify the RTEMS_NO_FLOATING_POINT attribute. If the RTEMS_GLOBAL attribute is specified, the task can be accessed from remote nodes. The task id, returned in id, is used in other task related directives to access the task. When created, a task is placed in the dormant state and can only be made ready to execute using the directive rtems_task_start.

NOTES:

This directive will not cause the calling task to be preempted.

Valid task priorities range from a high of 1 to a low of 255.

If the requested stack size is less than the configured minimum stack size, then RTEMS will use the configured minimum as the stack size for this task. In addition to being able to specify the task stack size as a integer, there are two constants which may be specified:

RTEMS_MINIMUM_STACK_SIZE is the minimum stack size RECOMMENDED for use on this processor. This value is selected by the RTEMS developers conservatively to minimize the risk of blown stacks for most user applications. Using this constant when specifying the task stack size, indicates that the stack size will be at least RTEMS_MINIMUM_STACK_SIZE bytes in size. If the user configured minimum stack size is larger than the recommended minimum, then it will be used.
RTEMS_CONFIGURED_MINIMUM_STACK_SIZE indicates that this task is to be created with a stack size of the minimum stack size that was configured by the application. If not explicitly configured by the application, the default configured minimum stack size is the processor dependent value RTEMS_MINIMUM_STACK_SIZE. Since this uses the configured minimum stack size value, you may get a stack size that is smaller or larger than the recommended minimum. This can be used to provide large stacks for all tasks on complex applications or small stacks on applications that are trying to conserve memory.

Application developers should consider the stack usage of the device drivers when calculating the stack size required for tasks which utilize the driver.

The following task attribute constants are defined by RTEMS:

RTEMS_NO_FLOATING_POINT - does not use coprocessor (default)
RTEMS_FLOATING_POINT - uses numeric coprocessor
RTEMS_LOCAL - local task (default)
RTEMS_GLOBAL - global task

The following task mode constants are defined by RTEMS:

RTEMS_PREEMPT - enable preemption (default)
RTEMS_NO_PREEMPT - disable preemption
RTEMS_NO_TIMESLICE - disable timeslicing (default)
RTEMS_TIMESLICE - enable timeslicing
RTEMS_ASR - enable ASR processing (default)
RTEMS_NO_ASR - disable ASR processing
RTEMS_INTERRUPT_LEVEL(0) - enable all interrupts (default)
RTEMS_INTERRUPT_LEVEL(n) - execute at interrupt level n

The interrupt level portion of the task execution mode supports a maximum of 256 interrupt levels. These levels are mapped onto the interrupt levels actually supported by the target processor in a processor dependent fashion.

Tasks should not be made global unless remote tasks must interact with them. This avoids the system overhead incurred by the creation of a global task. When a global task is created, the task's name and id must be transmitted to every node in the system for insertion in the local copy of the global object table.

The total number of global objects, including tasks, is limited by the maximum_global_objects field in the Configuration Table.

RTEMS C User's Guide