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. | |
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)
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 } }
More info at http://www.freertos.org
| int GetNumberOfTasks | ( | void | ) |
Get the total number of tasks that exist at a given moment.
int numberOfTasks = GetNumberOfTasks( );
| 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.
| taskID | An integer specifying the unique ID number given to the task by FreeRTOS |
| 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.
| taskName | A character string specifying the name of the task to find. |
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
| 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.
| timems | An integer specifying how long to sleep in milliseconds. |
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 } }
| 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.
| 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). |
// 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 ); } }
| 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.
| task | A pointer to the handle of the task to be deleted. |
void *taskPtr = TaskCreate( MyTask, "Me", 1000, 0, 1 ); // create a new task // ... run the task ... TaskDelete( taskPtr ); // then delete it
| 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.
| 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.
| void* TaskGetCurrent | ( | void | ) |
Get a pointer to the task that's currently running.
void *currentTask = TaskGetCurrent( );
| 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.
| task | A pointer to the task. |
void *taskPtr = TaskCreate( MyTask, "Mine", 1000, 0, 1 ); int id = TaskGetIDNumber( taskPtr );
| char* TaskGetName | ( | void * | task | ) |
Get the name of a task.
Read back the name a task was given when it was created.
| task | A pointer to the task. |
void *taskPtr = TaskCreate( MyTask, "Mine", 1000, 0, 1 ); char* name = TaskGetName( taskPtr ); // will return "Mine"
| 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.
| task | A pointer to the previous task. |
void *oneTask = TaskCreate( MyTask, "Mine", 1000, 0, 1 ); void *nextTask = TaskGetNext( oneTask );
| 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.
| task | A pointer to the task. |
void *taskPtr = TaskCreate( MyTask, "Mine", 1000, 0, 1 ); int priority = TaskGetPriority( taskPtr ); // will return 1
| 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.
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
| 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.
| task | A pointer to the task. |
void *taskPtr = TaskCreate( MyTask, "Mine", 1000, 0, 1 ); int stack = TaskGetStackAllocated( taskPtr ); // will return 1000
| int TaskGetTickCount | ( | void | ) |
| int TaskGetTopPriorityUsed | ( | void | ) |
Read the highest priority being used by any existing task.
int highestPriority = TaskGetTopPriorityUsed( );
| void TaskSetPriority | ( | void * | task, | |
| int | priority | |||
| ) |
Update the priority of a task.
Higher numbers mean higher priority/more processor time.
| task | A pointer to the task you want to update. | |
| priority | An integer specifying the new priority. |
void *task = TaskCreate( MyTask, "Mine", 1000, 0, 1 ); // create a task // ... now update the task's priority to 6 TaskSetPriority( task, 6 );
| 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.