Detailed Description

Task module for the RTOS Porting Interface.

============================================================================

TaskP objects are RTOS threads backed by OS-specific thread or task objects. Task functions will run according to the rules of the underlying scheduler, with higher priority tasks executing first.

Tasks require a stack and a control struct to operate, which can either be allocated statically with TaskP_construct or dynamically with TaskP_create. The stack should be large enough to contain at least your deepest call stack plus an interrupt frame.

Task Functions: The void* argument will be NULL by default, but you can set a value using TaskP_Params. Task functions should never return, as the behaviour after a task has returned is implementation-dependent and TaskP does not provide a mechanism for OS-independent task deletion. See your OS documentation for

details.

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

Include dependency graph for TaskP.h:

Go to the source code of this file.

Data Structures
union	TaskP_Struct
	TaskP structure. More...

struct	TaskP_Params

Macros
#define	TaskP_DEFAULT_STACK_SIZE (512)
	Number of bytes greater than or equal to the size of any RTOS Task object. More...

Typedefs
typedef union TaskP_Struct	TaskP_Struct
	TaskP structure. More...

typedef TaskP_Struct *	TaskP_Handle
	Opaque client reference to an instance of a TaskP. More...

typedef void(*	TaskP_Function) (void *)
	Task function definition, passed to create and construct. More...

Enumerations
enum	TaskP_State { TaskP_State_RUNNING, TaskP_State_READY, TaskP_State_BLOCKED, TaskP_State_DELETED, TaskP_State_INACTIVE, TaskP_State_INVALID }
	Enum returned from TaskP_getState(). More...

Functions
TaskP_Handle	TaskP_create (TaskP_Function fxn, const TaskP_Params *params)
	Create a TaskP, allocating memory on the heap. More...

void	TaskP_delete (TaskP_Handle task)
	Delete a TaskP. More...

TaskP_Handle	TaskP_construct (TaskP_Struct obj, TaskP_Function fxn, const TaskP_Params params)
	Construct a TaskP from statically allocated memory. More...

void	TaskP_destruct (TaskP_Struct *obj)
	Destruct a TaskP. More...

TaskP_State	TaskP_getState (TaskP_Handle task)
	Get the current state of a task handle. More...

TaskP_Handle	TaskP_getCurrentTask (void)
	Get the currently executing task handle. More...

uintptr_t	TaskP_disableScheduler (void)
	Function to disable task scheduling. More...

void	TaskP_restoreScheduler (uintptr_t key)
	Function to re-enable task scheduling. More...

void	TaskP_yield (void)
	Create a scheduler point, yielding to equal priority tasks. More...

void	TaskP_Params_init (TaskP_Params *params)
	Initialize params structure to default values. More...

Macro Definition Documentation

§ TaskP_DEFAULT_STACK_SIZE

#define TaskP_DEFAULT_STACK_SIZE (512)

Number of bytes greater than or equal to the size of any RTOS Task object.

BIOS 6.x: 80 BIOS 7.x: 88 FreeRTOS: 104(llvm)/340(gcc)

Number of bytes for the default stack size of any RTOS Task object.

Typedef Documentation

§ TaskP_Struct

typedef union TaskP_Struct TaskP_Struct

TaskP structure.

Opaque structure that should be large enough to hold any of the RTOS specific TaskP objects.

§ TaskP_Handle

typedef TaskP_Struct* TaskP_Handle

Opaque client reference to an instance of a TaskP.

A TaskP_Handle returned from create or construct represents that instance.

§ TaskP_Function

typedef void(* TaskP_Function) (void *)

Task function definition, passed to create and construct.

This function should never return.

Enumeration Type Documentation

§ TaskP_State

enum TaskP_State

Enum returned from TaskP_getState().

Enumerator
TaskP_State_RUNNING	This task is actively running
TaskP_State_READY	The task is ready to run, but not currently running
TaskP_State_BLOCKED	The task is blocked
TaskP_State_DELETED	The task has been deleted
TaskP_State_INACTIVE	The task is inactive
TaskP_State_INVALID	The task is not found or in an otherwise invalid state

Function Documentation

§ TaskP_create()

TaskP_Handle TaskP_create	(	TaskP_Function	fxn,
		const TaskP_Params *	params
	)

Create a TaskP, allocating memory on the heap.

Creates a new TaskP and registers it with the OS scheduler. The task object and the entire stack will be allocated on the heap - make sure you have a sufficiently large heap. Stack allocation size is controlled by params.

If the program is already executing a task and the new task has a higher priority the new task will be scheduled immediately; in this case TaskP_create() will not return until the new task blocks. To avoid this (for example when creating interdependent tasks at once) use TaskP_disableScheduler() and TaskP_restoreScheduler() to prevent the context switch.

Note: This API cannot be called from interrupt contexts.

Return values

TaskP handle (NULL on failure)

§ TaskP_delete()

void TaskP_delete ( TaskP_Handle task )

Delete a TaskP.

Deletes a TaskP.

Note: This API cannot be called from interrupt contexts.

For FreeRTOS, INCLUDE_vTaskDelete has to be set to 1 in FreeRTOSConfig.h. See 'Configuration with FreeRTOS' in the Core SDK User's Guide for how to do this.

§ TaskP_construct()

TaskP_Handle TaskP_construct	(	TaskP_Struct *	obj,
		TaskP_Function	fxn,
		const TaskP_Params *	params
	)

Construct a TaskP from statically allocated memory.

TaskP_construct creates a new task object. TaskP_construct returns the handle of the new task object or NULL if the task could not be created.

To use TaskP_construct you must set both point params.stack to a valid preallocated memory location of at least params.stackSize.

Note: This API cannot be called from interrupt contexts.

For FreeRTOS, configSUPPORT_STATIC_ALLOCATION has to be set to 1 in FreeRTOSConfig.h. See 'Configuration with FreeRTOS' in the Core SDK User's Guide for how to do this.

Return values

TaskP handle (NULL on failure)

§ TaskP_destruct()

void TaskP_destruct ( TaskP_Struct * obj )

Destruct a TaskP.

TaskP_destruct destructs a task object.

Note: This API cannot be called from interrupt contexts.

§ TaskP_getState()

TaskP_State TaskP_getState ( TaskP_Handle task )

Get the current state of a task handle.

Returns the state of the referenced task at the time this function was called. The return value is not guaranteed to match the state of the task when the calling function tests the return value. For example, the referenced task might have unblocked as a result of an interrupt, but the value may still read TaskP_State_BLOCKED.

The conversion of task states between DPL, FreeRTOS and TI-RTOS is: DPL: FreeRTOS: TI-RTOS: TaskP_State_RUNNING - eRunning - Task_Mode_RUNNING TaskP_State_READY - eReady - Task_Mode_READY TaskP_State_BLOCKED - eBlocked - Task_Mode_BLOCKED TaskP_State_DELETED - eDeleted - Task_Mode_TERMINATED TaskP_State_INACTIVE - eSuspended - Task_Mode_INACTIVE TaskP_State_INVALID - eInvalid - N.A

For FreeRTOS, INCLUDE_eTaskGetState has to be set to 1 in FreeRTOSConfig.h. See 'Configuration with FreeRTOS' in the Core SDK User's Guide for how to do this.

Return values

Current state of the task pointed to by the task parameter

§ TaskP_getCurrentTask()

TaskP_Handle TaskP_getCurrentTask ( void )

Get the currently executing task handle.

Note: Must be called from task context.

For FreeRTOS, INCLUDE_xTaskGetCurrentTaskHandle has to be set to 1 in FreeRTOSConfig.h. See 'Configuration with FreeRTOS' in the Core SDK User's Guide for how to do this.

Return values

The	handle for the calling task

§ TaskP_disableScheduler()

uintptr_t TaskP_disableScheduler ( void )

Function to disable task scheduling.

This function can be called multiple times, but must unwound in the reverse order. For example

uintptr_t key1, key2;
key1 = TaskP_disableScheduler();
key2 = TaskP_disableScheduler();
TaskP_restoreScheduler(key2);
TaskP_restoreScheduler(key1);

Note: This API cannot be called from interrupt contexts.

For FreeRTOS the key value returned is always 0.

Returns: A key to pass to TaskP_restoreScheduler to re-enable the scheduler.

§ TaskP_restoreScheduler()

void TaskP_restoreScheduler ( uintptr_t key )

Function to re-enable task scheduling.

Note: This API cannot be called from interrupt contexts.

For FreeRTOS the key value is ignored.

Parameters

key	returned from TaskP_disableScheduler

§ TaskP_yield()

void TaskP_yield ( void )

Create a scheduler point, yielding to equal priority tasks.

Task_yield yields the processor to another task of equal priority. A task switch occurs when you call Task_yield if there is an equal priority task ready to run.

§ TaskP_Params_init()

void TaskP_Params_init ( TaskP_Params * params )

Initialize params structure to default values.

Initialize the parameter struct with default values.

Parameters

params pointer to the task parameter struct

Detailed Description

details.

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

§ TaskP_DEFAULT_STACK_SIZE

Typedef Documentation

§ TaskP_Struct

§ TaskP_Handle

§ TaskP_Function

Enumeration Type Documentation

§ TaskP_State

Function Documentation

§ TaskP_create()

§ TaskP_delete()

§ TaskP_construct()

§ TaskP_destruct()

§ TaskP_getState()

§ TaskP_getCurrentTask()

§ TaskP_disableScheduler()

§ TaskP_restoreScheduler()

§ TaskP_yield()

§ TaskP_Params_init()