RTEMS 4.6.0pre5 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,
  rtems_unsigned32     stack_size,
  rtems_mode           initial_modes,
  rtems_attribute      attribute_set,
  rtems_id            *id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL - task created successfully
RTEMS_INVALID_NAME - invalid task name
RTEMS_INVALID_SIZE - stack too small
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.

The requested stack size should be at least RTEMS_MINIMUM_STACK_SIZE bytes. The value of RTEMS_MINIMUM_STACK_SIZE is processor dependent. 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