RTEMS 4.9.3 On-Line Library

Task Manager TASK_CREATE - Create a task

RTEMS Ada User's Guide

5.4.1: TASK_CREATE - Create a task

CALLING SEQUENCE:

procedure Task_Create (
   Name             : in     RTEMS.Name;
   Initial_Priority : in     RTEMS.Task_Priority;
   Stack_Size       : in     RTEMS.Unsigned32;
   Initial_Modes    : in     RTEMS.Mode;
   Attribute_Set    : in     RTEMS.Attribute;
   ID               :    out RTEMS.ID;
   Result           :    out RTEMS.Status_Codes
);

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 Ada User's Guide