task.h File Reference

Task management and scheduler API for SRTOS. More...

#include "fault.h"
#include "kernel_config.h"
#include "mcu_macros.h"
#include "system_funcs.h"
#include <stddef.h>
#include <stdint.h>
#include <stdlib.h>

Include dependency graph for task.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	TCB
	This struct is the Task Control Block (TCB), which is what stores a task's properties. More...
struct	TaskNode

Typedefs
typedef struct TaskNode	TaskNode
	This struct is used to represent a task in a linked list.

Enumerations
enum	STATUS { STATUS_SUCCESS = 0 , STATUS_FAILURE = 1 }
	This enum is used to indicate whether an operation was sucessful or not. More...

Functions
uint32_t *	initTaskStackFrame (uint32_t taskStack[], void(*taskFunc)(void))
	Initializes a task's stack frame.
STATUS	createTask (uint32_t taskStack[], void(*taskFunc)(void), unsigned int priority, TCB *userAllocatedTCB, TaskNode *userAllocatedTaskNode)
	Add a task to the scheduler's ready list.
void	SysTick_Handler ()
	This interrupt handler will be called every 1 ms, checking if any tasks need to be unblocked or blocked, and whether a context switch is needed.
void	PendSV_Handler ()
	This interrupt will be pended when a context switch is needed.
void	SVC_Handler ()
	This interrupt will be executed when the scheduler is started.
void	setPendSVPending ()
	This function will be called when a context-switch is needed.
void	startScheduler ()
	Start the scheduler.
void	taskDelay (uint32_t ticksToDelay)
	This function will delay a task's execution for ticksToDelay ms.
uint32_t	getCurTaskWordsAvailable ()
	This function will return the minimum number of words left on the stack.
void	handleStackOverflow ()
	This function will be called when a stack overflow is detected. This function will only be called if no other definitions are found. The user is recommended to define this themselves.

Variables
volatile uint32_t	msTicks
	msTicks contains the amount of ticks that have occured since the scheduler started.
TaskNode *	readyTasksList [MAX_PRIORITIES]
	This is a list of linked lists that contain the ready tasks.

Detailed Description

Task management and scheduler API for SRTOS.

This header files provides all task control functions for SRTOS users.

Provides user-level functions to manage tasks.

Definition in file task.h.

Typedef Documentation

TaskNode

typedef struct TaskNode TaskNode

This struct is used to represent a task in a linked list.

Definition at line 42 of file task.h.

Enumeration Type Documentation

STATUS

enum STATUS

This enum is used to indicate whether an operation was sucessful or not.

Enumerator
STATUS_SUCCESS
STATUS_FAILURE

Definition at line 21 of file task.h.

{
  STATUS_SUCCESS = 0,
  STATUS_FAILURE = 1
} STATUS;

Function Documentation

createTask()

STATUS createTask	(	uint32_t	taskStack[],
		void(*	taskFunc )(void),
		unsigned int	priority,
		TCB *	userAllocatedTCB,
		TaskNode *	userAllocatedTaskNode )

Add a task to the scheduler's ready list.

Parameters

taskStack	The user-defined array of size STACK_SIZE
taskAddress	The address of the task function
priority	The task's priority which must be between 0 and MAX_PRIORITIES - 1, inclusive
userAllocatedTCB	The address of the task's TCB allocated by the user
userAllocatedTaskNode	The address of the task's TaskNode allocated by the user

Returns

Returns either STATUS_SUCCESS or STATUS_FAILURE, depending on whether the task was successfully created or not.

Note

Must be called before the scheduler is started.

Definition at line 77 of file task.c.

{
  if (!taskFunc || !userAllocatedTCB || !userAllocatedTaskNode)
    return STATUS_FAILURE;
  if (priority >= MAX_PRIORITIES)
    return STATUS_FAILURE;
  if (STACK_SIZE < 18)
    return STATUS_FAILURE;
 
  userAllocatedTCB->sp = initTaskStackFrame (taskStack, taskFunc);
  userAllocatedTCB->priority = priority;
  userAllocatedTCB->id = prvCurTaskIDNum;
  prvCurTaskIDNum++;
  userAllocatedTCB->stackFrameLowerBoundAddr = &taskStack[0];
 
  /* Insert at end of tasks linked list */
  userAllocatedTaskNode->taskTCB = userAllocatedTCB;
  userAllocatedTaskNode->next = NULL;
 
  STATUS resStatus;
  systemENTER_CRITICAL ();
  {
    resStatus = prvAddTaskNodeToReadyList (userAllocatedTaskNode);
  }
  systemEXIT_CRITICAL ();
 
  return resStatus;
}

Here is the call graph for this function:

Here is the caller graph for this function:

getCurTaskWordsAvailable()

uint32_t getCurTaskWordsAvailable

(

)

This function will return the minimum number of words left on the stack.

Returns

This function returns the minimum amount of words left on the stack.

Note

A word is 32 bits in size on the ARM-Cortex M4/M4f.

Definition at line 503 of file task.c.

{
  uint32_t *curTaskStackFrameLowerBound;
  systemENTER_CRITICAL ();
  {
    curTaskStackFrameLowerBound = curTask->taskTCB->stackFrameLowerBoundAddr;
  }
  systemEXIT_CRITICAL ();
 
  curTaskStackFrameLowerBound
      += 2; /* Skip the 2 canary values (assumes no stack overflow) */
 
  uint32_t amtWordsAvailable = 0;
 
  while (*(curTaskStackFrameLowerBound) == STACK_USAGE_WATERMARK)
    {
      curTaskStackFrameLowerBound++;
      amtWordsAvailable++;
    }
 
  return amtWordsAvailable;
}

Here is the call graph for this function:

handleStackOverflow()

void handleStackOverflow

(

)

This function will be called when a stack overflow is detected. This function will only be called if no other definitions are found. The user is recommended to define this themselves.

initTaskStackFrame()

uint32_t * initTaskStackFrame	(	uint32_t	taskStack[],
		void(*	taskFunc )(void) )

Initializes a task's stack frame.

This will populate the stack with a dummy xPSR and LR value to allow the task to begin execution. These values will be overwritten once the task starts executing. Also, this will fill the bottom of the stack with canary values so that stack overflows can be detected. The stack is also populated with usage watermarks.

Parameters

taskStack	The array created by the user
taskFunc	The address of the task function

Warning

This function should not be called by user code.

Returns

Returns a pointer to the top of the stack.

Definition at line 46 of file task.c.

{
  for (int i = 0; i < STACK_SIZE; ++i)
    {
      taskStack[i] = STACK_USAGE_WATERMARK;
    }
 
  taskStack[0] = STACK_OVERFLOW_CANARY_VALUE;
  taskStack[1] = STACK_OVERFLOW_CANARY_VALUE;
 
  taskStack[STACK_SIZE - 1] = 0x01000000;                 /* xPSR */
  taskStack[STACK_SIZE - 2] = ((uint32_t)taskFunc) | 0x1; /* PC */
  taskStack[STACK_SIZE - 3] = 0xFFFFFFFD;                 /* LR */
  taskStack[STACK_SIZE - 4] = 0x00000000;                 /* R12 */
  taskStack[STACK_SIZE - 5] = 0x00000000;                 /* R3 */
  taskStack[STACK_SIZE - 6] = 0x00000000;                 /* R2 */
  taskStack[STACK_SIZE - 7] = 0x00000000;                 /* R1 */
  taskStack[STACK_SIZE - 8] = 0x00000000;                 /* R0 */
  taskStack[STACK_SIZE - 9] = 0x00000000;                 /* R11 */
  taskStack[STACK_SIZE - 10] = 0x00000000;                /* R10 */
  taskStack[STACK_SIZE - 11] = 0x00000000;                /* R9 */
  taskStack[STACK_SIZE - 12] = 0x00000000;                /* R8 */
  taskStack[STACK_SIZE - 13] = 0x00000000;                /* R7 */
  taskStack[STACK_SIZE - 14] = 0x00000000;                /* R6 */
  taskStack[STACK_SIZE - 15] = 0x00000000;                /* R5 */
  taskStack[STACK_SIZE - 16] = 0x00000000;                /* R4 */
 
  return &taskStack[STACK_SIZE - 16];
}

Here is the caller graph for this function:

PendSV_Handler()

void PendSV_Handler

(

)

This interrupt will be pended when a context switch is needed.

Note

This interrupt will run only after all other pending interupts have finished executing.

prvNextTask will be set when this interrupt is pended.

Warning

This function should never be called by user code.

Definition at line 166 of file task.c.

{
  prvCheckCurTaskForStackOverflow ();
 
  uint32_t spToSave;
  __asm volatile ("mrs r0, PSP\n"
                  "stmdb r0!, {r4-r11}\n"
                  "mov %[spToSave], r0\n"
                  : [spToSave] "=r"(spToSave));
 
  curTask->taskTCB->sp = (uint32_t *)spToSave;
 
  uint32_t nextSP;
  systemENTER_CRITICAL ();
  {
    nextSP = (uint32_t)prvNextTask->taskTCB->sp;
    curTask = prvNextTask;
  }
  systemEXIT_CRITICAL ();
 
  __asm volatile ("mov r2, %[nextSP]\n"
                  "ldmia r2!, {r4-r11}\n"
                  "msr PSP, r2\n"
                  :
                  : [nextSP] "r"(nextSP));
 
  __asm volatile ("ldr lr, =0xFFFFFFFD\n"
                  "bx lr\n");
}

Here is the call graph for this function:

setPendSVPending()

void setPendSVPending

(

)

This function will be called when a context-switch is needed.

Warning

This function should not be called from user code.

Definition at line 231 of file task.c.

{
  ICSR |= (1 << 28);
}

Here is the caller graph for this function:

startScheduler()

void startScheduler

(

)

Start the scheduler.

Note

No tasks should be created after this function is called.

There should be no code directly under this function call that is expected to execute. This function will initiate the transfer of execution to the first task.

Definition at line 218 of file task.c.

{
  prvIdleTask = createIdleTask ();
  curTask = prvGetHighestTaskReadyToExecute ();
  __asm volatile ("svc #0");
}

Here is the caller graph for this function:

SVC_Handler()

void SVC_Handler

(

)

This interrupt will be executed when the scheduler is started.

Note

This is where the first task is started.

Warning

This function should not be called from user code.

Definition at line 203 of file task.c.

{
  TCB *tcbToStart = curTask->taskTCB;
  uint32_t spToStart = (uint32_t)tcbToStart->sp;
 
  __asm volatile ("ldr r0, %[sp]\n"
                  "ldmia r0!, {r4-r11}\n"
                  "msr PSP, r0\n"
                  "ldr lr, =0xFFFFFFFD\n"
                  "bx lr\n"
                  :
                  : [sp] "m"(spToStart));
}

SysTick_Handler()

void SysTick_Handler

(

)

This interrupt handler will be called every 1 ms, checking if any tasks need to be unblocked or blocked, and whether a context switch is needed.

Warning

This function should not be called from user code.

Definition at line 115 of file task.c.

{
  msTicks++;
 
  prvUnblockDelayedTasksReadyToUnblock ();
 
  if (curTask == NULL)
    {
      return;
    }
 
  uint32_t curExecutingPriority = curTask->taskTCB->priority;
 
  TaskNode *highestPriorityPossibleExecute
      = prvGetHighestTaskReadyToExecute ();
 
  /* Check if a higher priority task is ready to execute */
  if (curExecutingPriority < highestPriorityPossibleExecute->taskTCB->priority)
    {
      prvNextTask = highestPriorityPossibleExecute;
      setPendSVPending ();
      return;
    }
 
  if (curTask->next == NULL)
    {
      if (highestPriorityPossibleExecute->taskTCB->id != curTask->taskTCB->id)
        {
          /* There is another task of equal priority, time to switch. */
          prvNextTask = highestPriorityPossibleExecute;
          setPendSVPending ();
          return;
        }
    }
  else
    {
      /* There is another task of equal priority, time to switch. */
      prvNextTask = curTask->next;
      setPendSVPending ();
      return;
    }
}

Here is the call graph for this function:

taskDelay()

void taskDelay

(

uint32_t

ticksToDelay

)

This function will delay a task's execution for ticksToDelay ms.

This function will move the current task to the blocked list for ticksToDelay ms. If there are no other tasks available to execute, the idleTask will execute.

Parameters

ticksToDelay

The number of milliseconds to delay a task's execution.

Definition at line 237 of file task.c.

{
  systemENTER_CRITICAL ();
  {
    uint32_t curTaskID = curTask->taskTCB->id;
    uint32_t curTaskPriority = curTask->taskTCB->priority;
 
    curTask->taskTCB->delayedUntil = msTicks + ticksToDelay;
 
    /* Remove the task from the ready list */
    TaskNode *cur = readyTasksList[curTaskPriority];
    TaskNode *prev = NULL;
 
    if (cur->next == NULL)
      {
        /* This is the only task for this priority, and it must be curTask */
        readyTasksList[curTaskPriority] = NULL;
        prvNextTask = prvGetHighestTaskReadyToExecute ();
        prvAddTaskToBlockedList (curTask);
        systemEXIT_CRITICAL ();
        setPendSVPending ();
        return;
      }
 
    /* Check if curTask is the head of the priority */
    if (cur->taskTCB->id == curTaskID)
      {
        readyTasksList[curTaskPriority] = curTask->next;
 
        prvNextTask = prvGetHighestTaskReadyToExecute ();
        prvAddTaskToBlockedList (curTask);
        systemEXIT_CRITICAL ();
        setPendSVPending ();
        return;
      }
 
    /* There is more than one task for the current priority */
    while (cur->taskTCB->id != curTaskID)
      {
        prev = cur;
        cur = cur->next;
      }
 
    TaskNode *afterCur = cur->next;
    prev->next = afterCur;
 
    prvNextTask = prvGetHighestTaskReadyToExecute ();
    prvAddTaskToBlockedList (curTask);
  }
  systemEXIT_CRITICAL ();
  setPendSVPending ();
}

Here is the call graph for this function:

Variable Documentation

msTicks

volatile uint32_t msTicks

extern

msTicks contains the amount of ticks that have occured since the scheduler started.

Warning

User code should rarely, if ever, access this variable.

Definition at line 10 of file task.c.

readyTasksList

TaskNode* readyTasksList[MAX_PRIORITIES]

extern

This is a list of linked lists that contain the ready tasks.

Note

Each index represents the linked list of ready tasks for that priority.

Warning

This variable should never be accessed in user code.

Definition at line 12 of file task.c.

{ NULL };