# Tasks
[RTOS]

The individual "programs" that make up your application. More...

## Functions
void | Sleep (int timems)
| Put a task to sleep for a given number of milliseconds.
void | TaskYield ()
| Give up the remaining time allotted to this task by the processor.
void * | TaskCreate (void(taskCode)(void *), char *name, int stackDepth, void *parameters, int priority)
| Create a new task.
void | TaskDelete (void *task)
| Delete an existing task.
void | TaskEnterCritical ()
| Specify that a task is entering a period during which it should not be interrupted.
void | TaskExitCritical ()
| Specify that a task is exiting a critical period, in response to TaskEnterCritical().
int | TaskGetRemainingStack (void *task)
| Check how much stack is available for a given task.
void * | getTaskByName (char *taskName)
| Get a pointer to a task by its name.
void * | getTaskByID (int taskID)
| Get a pointer to a task by its ID number.
int | TaskGetPriority (void *task)
| Get the priority of a task.
int | TaskGetIDNumber (void *task)
| Get the ID number of a task.
char * | TaskGetName (void *task)
| Get the name of a task.
int | TaskGetStackAllocated (void *task)
| Read the amount of stack initially allocated for a task.
void * | TaskGetCurrent ()
| Get a pointer to the task that's currently running.
int | TaskGetTopPriorityUsed ()
| Read the highest priority being used by any existing task.
void * | TaskGetNext (void *task)
| Get a pointer to the task whose ID comes after a given ID.
int | GetNumberOfTasks ()
| Get the total number of tasks that exist at a given moment.
void | TaskSetPriority (void *task, int priority)
| Update the priority of a task.
int | TaskGetTickCount (void)
| Returns the number of ticks since the scheduler started.

## Detailed Description

The individual "programs" that make up your application.

Tasks can all be written separately and the RTOS will take of switching between them, making sure they all get the processing time they need. Each task is implemented as a continuous loop, and all tasks have the same signature:

     void MyTask( void* parameters)

The void* parameters is a value that can be passed in at the time the task is created. Make sure that you put your task to sleep when it's not doing anything so that other tasks can get time as well. Otherwise, the Controller will lock up and none of the other tasks will run.

Example

        void MyTask( void* p )
        {
          // some initialization here
          int newVal = 0;

          // then just sit in our loop
          // we're going to turn an LED on whenever an AnalogIn is over a certain value
          while( 1 )
          {
            newVal = AnalogIn_GetValue( 1 );
            if( newVal < 512 )
              AppLed_SetState( 0, 1 );
            else
              AppLed_SetState( 0, 0 );
            Sleep( 100 ); // wait for 100 milliseconds, allowing other tasks to do their thing
          }
        }

Notice we don't need to include anything about Ethernet or USB communication, or anything else that might be going on. These are taken care of elsewhere by the RTOS, allowing us to focus on our LED blinking.

More info at http://www.freertos.org

## Function Documentation

int GetNumberOfTasks | ( | void |  | ) |

Get the total number of tasks that exist at a given moment.

Returns:
  An integer specifying the number of tasks.

Example

      int numberOfTasks = GetNumberOfTasks( );

Definition at line 412 of file rtos.c.

void* getTaskByID | ( | int | taskID | ) |

Get a pointer to a task by its ID number.

Each task is given a unique ID number by freeRTOS. If you know this number, but don't have a pointer to the task, use this function to get a pointer to the task itself. This is a costly function, as it shuts down the scheduler to search for the task, so it should really only be used in a debug setting.

Parameters:

  | taskID | An integer specifying the unique ID number given to the task by FreeRTOS

Returns:
  A pointer to the task, or NULL if the task was not found.

See also:
  TaskGetIDNumber( )

Definition at line 263 of file rtos.c.

void* getTaskByName | ( | char * | taskName | ) |

Get a pointer to a task by its name.

When a task is created, it is initialized with a name. If you don't have a pointer to the task itself but you know its name, you can still get a reference to the task. This is a costly function, as it shuts down the scheduler to search for the task, so it should really only be used in a debug setting.

Parameters:

  | taskName | A character string specifying the name of the task to find.

Returns:
  A pointer to the task, or NULL if the task was not found.

See also:
  getTaskByID()

Example

      TaskCreate( MyTask, "Mine", 1000, 0, 1 ); // a task has been created, but we don't have a pointer to it
      void *taskPtr = getTaskByName( "Mine" ); // but we can still get a pointer to it by its name

Definition at line 243 of file rtos.c.

void Sleep | ( | int | timems | ) |

Put a task to sleep for a given number of milliseconds.

This lets the processor give time to other tasks. You'll always want to include some amount of Sleep( ) in your tasks to avoid locking up the Controller.

Parameters:

  | timems | An integer specifying how long to sleep in milliseconds.

Example

      void MyTask( void *p) // in your task
      {
        while( 1 )
        {
          Led_SetState( 0 ); // turn the LED off
          Sleep( 900 ); // leave it off for 900 milliseconds
          Led_SetState( 1 ); // turn the LED on
          Sleep( 10 ); // leave it on for 10 milliseconds
        }
      }

Definition at line 107 of file rtos.c.

void* TaskCreate | ( | void(taskCode)(void *) | ,
|  | char * | name,
|  | int | stackDepth,
|  | void * | parameters,
|  | int | priority |
| ) |  |  |

Create a new task.

When creating a new task, be sure that you allocate it enough stack space. A task must have enough stack space to load any of the potential data structures it will be working with, otherwise it will die and the Controller will crash.

Since FreeRTOS is pre-emptive, higher priority tasks will get processor time before lower priority tasks. The priority level is a bit arbitrary, but choose something that makes sense in relation to the other tasks you have running. Always be sure to block a task when possible, in order to give processor time to other tasks.

Parameters:

  | taskCode | A pointer to the function that will run when the task starts.
  | name | A character string containing the name of the task.
  | stackDepth | An integer specifying in bytes the size of the task's stack.
  | parameters | A void* parameter which will be passed into the task at create time.
  | priority | An integer specifying the task's priority (0 lowest - 7 highest priority).

Returns:
  A pointer to the handle for the newly created task, or NULL if it didn't succeed.

See also:
  TaskDelete( )

Example

      // create the task MyTask, called "Me", with a stack of 1000 bytes, no parameters, at priority 1
      void *taskPtr = TaskCreate( MyTask, "Me", 1000, 0, 1 );

      void MyTask( void *p) // in your task
      {
        // set up any variables that you'll need
        int counter = 0;
        // then start your continuous loop
        while( 1 )
        {
          counter++;
          Sleep( 100 );
        }
      }

Definition at line 159 of file rtos.c.

void TaskDelete | ( | void * | task | ) |

Delete an existing task.

TaskCreate( ) returns a pointer to the newly created task. You'll need to hang onto this pointer in order to delete the task.

Parameters:

  | task | A pointer to the handle of the task to be deleted.

Example

      void *taskPtr = TaskCreate( MyTask, "Me", 1000, 0, 1 ); // create a new task
      // ... run the task ...
      TaskDelete( taskPtr ); // then delete it

Definition at line 180 of file rtos.c.

void TaskEnterCritical | ( | void |  | ) |

Specify that a task is entering a period during which it should not be interrupted.

Call this from within your task. Be sure to minimize use of this, and to call TaskExitCritical() as soon as the task has completed its critical stage. Other tasks can't get any processor time while in this state, and performance might be compromised.

See also:
  TaskExitCritical( )

Definition at line 192 of file rtos.c.

void TaskExitCritical | ( | void |  | ) |

Specify that a task is exiting a critical period, in response to TaskEnterCritical().

Once the task exits a critical period, FreeRTOS will resume switching this task as usual.

See also:
  TaskEnterCritical( )

Definition at line 202 of file rtos.c.

void* TaskGetCurrent | ( | void |  | ) |

Get a pointer to the task that's currently running.

Returns:
  A pointer to the task that's currently running.

Example

      void *currentTask = TaskGetCurrent( );

Definition at line 355 of file rtos.c.

int TaskGetIDNumber | ( | void * | task | ) |

Get the ID number of a task.

FreeRTOS assigns each task a unique ID number. Use this function to retrieve a particular task's ID number. Task ID numbers are not necessarily sequential.

Parameters:

  | task | A pointer to the task.

Returns:
  An integer specifying the task's unique ID within freeRTOS, or -1 on fail.

Example

      void *taskPtr = TaskCreate( MyTask, "Mine", 1000, 0, 1 );
      int id = TaskGetIDNumber( taskPtr );

Definition at line 305 of file rtos.c.

char* TaskGetName | ( | void * | task | ) |

Get the name of a task.

Read back the name a task was given when it was created.

Parameters:

  | task | A pointer to the task.

Returns:
  The task's name as a string

Example

      void *taskPtr = TaskCreate( MyTask, "Mine", 1000, 0, 1 );
      char* name = TaskGetName( taskPtr ); // will return "Mine"

Definition at line 322 of file rtos.c.

void* TaskGetNext | ( | void * | task | ) |

Get a pointer to the task whose ID comes after a given ID.

FreeRTOS assigns each task a unique ID number internally. This function will return a pointer to the task with the next ID. Note that this does not necessarily mean that this task will be given processor time next, just that its ID is the next one along in the list of all tasks.

This is an expensive function since it needs to stop the scheduler to search the lists of tasks. It should only really be used in a debug setting.

Parameters:

  | task | A pointer to the previous task.

Returns:
  A pointer to the task that's next in the ID list.

Example

      void *oneTask = TaskCreate( MyTask, "Mine", 1000, 0, 1 );
      void *nextTask = TaskGetNext( oneTask );

Definition at line 392 of file rtos.c.

int TaskGetPriority | ( | void * | task | ) |

Get the priority of a task.

When a task is created, it's given a priority from 1-7. Use this function to get the task's priority after it has been created.

Parameters:

  | task | A pointer to the task.

Returns:
  An integer specifying the task's priority

Example

      void *taskPtr = TaskCreate( MyTask, "Mine", 1000, 0, 1 );
      int priority = TaskGetPriority( taskPtr ); // will return 1

Definition at line 287 of file rtos.c.

int TaskGetRemainingStack | ( | void * | task | ) |

Check how much stack is available for a given task.

When a task is created, it is initialized with a stack depth. This function will return the numbers of bytes available from that initial allocation.

Returns:
  An integer specifying the available stack in bytes.

See also:
  TaskGetStackAllocated( )

Example

      void *taskPtr = TaskCreate( MyTask, "Mine", 1000, 0, 1 ); // create a new task
      int freeBytes = TaskGetRemainingStack( taskPtr ); // check how much of the task's stack has been used

Definition at line 220 of file rtos.c.

int TaskGetStackAllocated | ( | void * | task | ) |

Read the amount of stack initially allocated for a task.

Each task is allocated a certain amount of stack space when it's created. Use this function to determine how much stack space a task was originally given.

Parameters:

  | task | A pointer to the task.

Returns:
  An integer specifying the amount of stack, in bytes, that this task was allocated.

See also:
  TaskGetRemainingStack( )

Example

      void *taskPtr = TaskCreate( MyTask, "Mine", 1000, 0, 1 );
      int stack = TaskGetStackAllocated( taskPtr ); // will return 1000

Definition at line 341 of file rtos.c.

int TaskGetTickCount | ( | void |  | ) |

Returns the number of ticks since the scheduler started.

Returns:
  the number of ticks

Definition at line 439 of file rtos.c.

int TaskGetTopPriorityUsed | ( | void |  | ) |

Read the highest priority being used by any existing task.

Returns:
  An integer specifying the priority.

Example

      int highestPriority = TaskGetTopPriorityUsed( );

Definition at line 369 of file rtos.c.

void TaskSetPriority | ( | void * | task,
|  | int | priority |
| ) |  |  |

Update the priority of a task.

Higher numbers mean higher priority/more processor time.

Parameters:

  | task | A pointer to the task you want to update.
  | priority | An integer specifying the new priority.

Example

      void *task = TaskCreate( MyTask, "Mine", 1000, 0, 1 ); // create a task
      // ... now update the task's priority to 6
      TaskSetPriority( task, 6 );

Definition at line 430 of file rtos.c.

void TaskYield | ( | void |  | ) |

Give up the remaining time allotted to this task by the processor.

The presently running task immeidately gives up the remaining time it has in the current timeslice so that other tasks can run. While Sleep() will wait the specified number of milliseconds before continuing, TaskYield() will cause the task to take processor time again as soon as it's available.

Definition at line 119 of file rtos.c.