IPC@CHIP® RTOS-PPC – API Documentation

Header image

Main page

RtxTaskDefS Struct Reference
[RTX Data Structures and Type Definitions]

Task creation specification. More...

Detailed Description

This structure is used by RTX_NewTask() to create a new task.

typedef struct RtxTaskDefT
    char            tkdTag[4] ;
    RTX_TASK_PROC   tkdProc ;
    void           *tkdStackBase ;
    unsigned int    tkdStackSize ;
    long            tkdlParam ;
    short           tkdPriority ;
    unsigned short  tkdAttr ;
    unsigned int    tkdSlice ;
    unsigned int    tkdPeriod ;
    unsigned int    tkdPhase ;
    unsigned int    tkdPhaseRef ;
} RtxTaskDefS ;

Task Name

The four character task name is not strictly required. But it is helpful for diagnostic purposes. For example, the TASKS command lists the tasks' names with status information for all tasks running in the system.

Optional Task Input Parameter

The RTX_TASK_PROC type for the vectors to the task entry point specify one long input parameter. This input parameter is optional and the actual task procedure may be declared with void parameters, or any other type of the same size as long such as a pointer to an object. Then the task entry vector can be cast to RTX_TASK_PROC type when assigned to the tkdProc member.

The task's input parameter is specified in the tkdlParam member. A pointer to an object can be cast to long and set as this member's value for object oriented tasks.

Stack Space

A pointer to the bottom (lowest address) of the tasks stack space must be set in the tkdStackBase member. Note that unlike the task definition API in the SC1x, SC2x and SC1x3 systems, this pointer does not reference the high end of the stack space.

The system requires a miminum of 1024 bytes stack space for all tasks.

The user is responsible for allocating this stack space. This can be done either with a static allocation or from the program heap memory.

When deciding how large to make the task's stack, it may be wise during program development to make the stack larger than you think will be necessary. Then after the software is running, use the TASKS console command to check your task's stack space usage. You can then trim the stack down to some more reasonable size.

Task Priority

Some thought should be given to your task priority selection set in the tkdPriority member. For reference, the program's main() thread is launched by the system at priority 50. Priorities can be changed at run time with the RTX_Task_Priority() API.

Refer to the multitasking overview for a further discussion of task priorities.

Task Creation Attributes

Commonly, the tkdAttr member can be left at zero and all the remaining members of this data structure can be ignored since that is what the system is going to do with them when tkdAttr is zero.

The following features are available by setting flags in the tkdAttr bit field.

Time-Slice or Watchdog Time-Limit

The tkdSlice member can be set to the number of milliseconds that either a task time-slice period or watchdog time-limit shall be set to. Either the RTX_TA_TIME_SLICED or RTX_TA_TIME_LIMIT flags must be set in the tkdAttr bit field member (but not both) for the tkdSlice value to be applied. The time value will be limited by the @CHIP-RTOS-PPC to around 65 seconds if any value higher than this is specified, due to range limitations on the CPU's decrementer hardware register which is used to implement this timer.

Tasks are charged for time stolen by interrupt service procedures, but they are not charged for time spent within tasks which preempt them.

Refer to the multitasking overview for a further description of time-slicing.

This type is not available in the SC1x, SC2x and SC1x3 C-Library.
See also:
SC2x3 V1.00 - CLIB V1.00

Data Fields

char tkdTag [4]
void * tkdStackBase
unsigned int tkdStackSize
long tkdlParam
short tkdPriority
unsigned short tkdAttr
unsigned int tkdSlice
unsigned int tkdPeriod
unsigned int tkdPhase
unsigned int tkdPhaseRef

Top of page | Main page

Copyright © 2018 Beck IPC GmbH
Generated on Thu Nov 1 13:20:18 2018 by Doxygen 1.6.1