Task

Attention

This module is not applicable for NO RTOS environment

Features Supported

  • APIs to create and destroy tasks

  • APIs to yeild a task

  • Ability to specify task priority, task entry function, stack pointer, stack size

  • Ability to get task and CPU load

Features NOT Supported

NA

Important Usage Guidelines

  • On R5F, and M4F, make sure memory provided as stack is 32b aligned and size is also multiple of 32b

  • Stack and stack size MUST be provided by application and is not allocated internally

Example Usage

Include the below file to access the APIs,


//! [include]
#include <kernel/dpl/TaskP.h>
//! [include]
#include <kernel/dpl/DebugP.h>
#include <drivers/hw_include/csl_types.h>

//! [define]
/* Task priority, stack, stack size and task objects, these MUST be global's */
#define MY_TASK_PRI         (8U)

Example usage to define task objects and parameters:

uint8_t gMyTaskStack[MY_TASK_STACK_SIZE] __attribute__((aligned(32)));
TaskP_Object gMyTask;

/* Application specific task arguments */
typedef struct {
    uint32_t value;
} MyTask_Args;

MyTask_Args gMyTask_args;
//! [define]

//! [taskmain]
/* Task entry point or main function for this task */
void myTaskMain(void *args)

Example task main function:

    MyTask_Args *myArgs = (MyTask_Args*)args;
    DebugP_assert(myArgs != NULL);

    /* myArgs points to structure pointer passed during TaskP_construct */

    /* do something in the task */

    /* when done call below function, DO NOT 'return` from this function */
    TaskP_exit();
}
//! [taskmain]

void samples()
{

Example usage to create a task:

//! [create]
    int32_t status;
    TaskP_Params myTaskParams; /* this need not be global variable */

    TaskP_Params_init(&myTaskParams);
    myTaskParams.name = "MY_TASK";
    myTaskParams.stackSize = MY_TASK_STACK_SIZE;
    myTaskParams.stack = gMyTaskStack;
    myTaskParams.priority = MY_TASK_PRI;
    myTaskParams.args = &gMyTask_args;
    myTaskParams.taskMain = myTaskMain;

    status = TaskP_construct(&gMyTask, &myTaskParams);
    DebugP_assert(status == SystemP_SUCCESS);

Example usage to get task and CPU load:

}
}

void get_load()
{
{
//! [load]
    TaskP_Load taskLoad;
    uint32_t cpuLoad;

    cpuLoad = TaskP_loadGetTotalCpuLoad();
    DebugP_log(" LOAD: CPU  = %2d.%2d %%\r\n", cpuLoad/100, cpuLoad%100 );

    TaskP_loadGet(&gMyTask, &taskLoad);

API Reference

Defines

TaskP_PRIORITY_LOWEST

Value to be used for lowest priority task.

TaskP_PRIORITY_HIGHEST

Value to be used for highest priority task.

TaskP_LOAD_UPDATE_WINDOW_MSEC

The update rate at which TaskP_loadUpdateAll() is called.

TaskP_OBJECT_SIZE_MAX

Max size of task object across all OS’s.

Typedefs

typedef void (*TaskP_FxnMain)(void *args)

Entry point to the task.

Functions

void TaskP_Params_init(TaskP_Params *params)

Set default values to TaskP_Params.

Strongly recommended to be called before seting values in TaskP_Params

Parameters:

params – [out] parameter structure to set to default

int32_t TaskP_construct(TaskP_Object *obj, TaskP_Params *params)

Create a task object.

Parameters:

  • obj – [out] Created object

  • params – [in] Task create parameters

Returns:

SystemP_SUCCESS on success, SystemP_FAILURE on error

void TaskP_destruct(TaskP_Object *obj)

Cleanup, delete, destruct a task object.

Parameters:

obj – [in] task object

void *TaskP_getHndl(TaskP_Object *obj)

Return OS defined task handle.

Parameters:

obj – [in] task object

Returns:

OS specific task handle

void TaskP_yield(void)

Yield current task.

void TaskP_exit(void)

Exit current task.

In FreeRTOS, task cannot simply return from a function. It needs to call vTaskDelete(NULL) instead. To keep the task exit portable, call this function when a task wants to terminate itself.

void TaskP_loadGet(TaskP_Object *obj, TaskP_Load *taskLoad)

Get task load.

Parameters:

  • obj – [out] Created object

  • taskLoad – [out] Task load statistics

void TaskP_loadUpdateAll(void)

Updated task load statistics.

This updates task load statistics for all tasks created with TaskP_construct(). This also updates idle task load.

This function is called, every TaskP_LOAD_UPDATE_WINDOW_MSEC msecs within the IDLE task. It is important that idle task get to run atleast once every TaskP_LOAD_UPDATE_WINDOW_MSEC msecs for the load statistics to be correct

void TaskP_loadResetAll(void)

Reset task load statistics.

Until load statistics is reset the load statistics keep getting accumulated

uint32_t TaskP_loadGetTotalCpuLoad()

Get total CPU load including all task and ISR execution time.

Returns:

CPU load in units of percentage with 2 decimal point precision, i.e 1234 means 12.34%

uint32_t TaskP_disable(void)
void TaskP_restore(uint32_t key)
void TaskP_endScheduler()
struct TaskP_Load
#include <TaskP.h>

Task load statistics.

Public Members

const char *name

Name of the task

uint64_t runTime

Amount of time the task has run, units of usec

uint64_t totalTime

Amount of time that has elapsed so far, units of usec

uint32_t cpuLoad

CPU load in units of percentage with 2 decimal point precision, i.e 1234 means 12.34%

struct TaskP_Object
#include <TaskP.h>

Opaque task object used with the task APIs.

Public Members

uintptr_t rsv[TaskP_OBJECT_SIZE_MAX / sizeof(uint32_t)]

reserved, should NOT be modified by end users

struct TaskP_Params
#include <TaskP.h>

Parameters passed during TaskP_construct.

Public Members

const char *name

Pointer to task name

uint32_t stackSize

Size of stack in units of bytes

uint8_t *stack

Pointer to stack memory, MUST be aligned based on CPU architecture, typically atleast 32b on 32b systems

uint32_t priority

Task priority, MUST be between TaskP_PRIORITY_LOWEST and TaskP_PRIORITY_HIGHEST

void *args

User arguments that are passed back as parater to task main

TaskP_FxnMain taskMain

Entry point function to the task

uintptr_t coreAffinity

Core affinity for the task (Applicable in case of SMP only)

uint64_t taskPrivilege

Task Privilege (Appilcable only for R5F SAFERTOS)