|
FreeRTOS API Reference 7.0.0 r0
|
|
FreeRTOS API Reference 7.0.0 r0
|
task. h
void vTaskDelay( portTickType xTicksToDelay );
Delay a task for a given number of ticks. The actual time that the task remains blocked depends on the tick rate. The constant portTICK_RATE_MS can be used to calculate real time from the tick rate - with the resolution of one tick period.
INCLUDE_vTaskDelay must be defined as 1 for this function to be available. See the configuration section for more information.
vTaskDelay() specifies a time at which the task wishes to unblock relative to the time at which vTaskDelay() is called. For example, specifying a block period of 100 ticks will cause the task to unblock 100 ticks after vTaskDelay() is called. vTaskDelay() does not therefore provide a good method of controlling the frequency of a cyclical task as the path taken through the code, as well as other task and interrupt activity, will effect the frequency at which vTaskDelay() gets called and therefore the time at which the task next executes. See vTaskDelayUntil() for an alternative API function designed to facilitate fixed frequency execution. It does this by specifying an absolute time (rather than a relative time) at which the calling task should unblock.
| xTicksToDelay | The amount of time, in tick periods, that the calling task should block. |
Example usage:
void vTaskFunction( void * pvParameters ) { // Block for 500ms. const portTickType xDelay = 500 / portTICK_RATE_MS; for( ;; ) { // Simply toggle the LED every 500ms, blocking between each toggle. vToggleLED(); vTaskDelay( xDelay ); } }
task. h
void vTaskDelayUntil( portTickType *pxPreviousWakeTime, portTickType xTimeIncrement );
INCLUDE_vTaskDelayUntil must be defined as 1 for this function to be available. See the configuration section for more information.
Delay a task until a specified time. This function can be used by cyclical tasks to ensure a constant execution frequency.
This function differs from vTaskDelay () in one important aspect: vTaskDelay () will cause a task to block for the specified number of ticks from the time vTaskDelay () is called. It is therefore difficult to use vTaskDelay () by itself to generate a fixed execution frequency as the time between a task starting to execute and that task calling vTaskDelay () may not be fixed [the task may take a different path though the code between calls, or may get interrupted or preempted a different number of times each time it executes].
Whereas vTaskDelay () specifies a wake time relative to the time at which the function is called, vTaskDelayUntil () specifies the absolute (exact) time at which it wishes to unblock.
The constant portTICK_RATE_MS can be used to calculate real time from the tick rate - with the resolution of one tick period.
| pxPreviousWakeTime | Pointer to a variable that holds the time at which the task was last unblocked. The variable must be initialised with the current time prior to its first use (see the example below). Following this the variable is automatically updated within vTaskDelayUntil (). |
| xTimeIncrement | The cycle time period. The task will be unblocked at time *pxPreviousWakeTime + xTimeIncrement. Calling vTaskDelayUntil with the same xTimeIncrement parameter value will cause the task to execute with a fixed interface period. |
Example usage:
// Perform an action every 10 ticks. void vTaskFunction( void * pvParameters ) { portTickType xLastWakeTime; const portTickType xFrequency = 10; // Initialise the xLastWakeTime variable with the current time. xLastWakeTime = xTaskGetTickCount (); for( ;; ) { // Wait for the next cycle. vTaskDelayUntil( &xLastWakeTime, xFrequency ); // Perform action here. } }
task. h
unsigned portBASE_TYPE uxTaskPriorityGet( xTaskHandle pxTask );
INCLUDE_xTaskPriorityGet must be defined as 1 for this function to be available. See the configuration section for more information.
Obtain the priority of any task.
| pxTask | Handle of the task to be queried. Passing a NULL handle results in the priority of the calling task being returned. |
Example usage:
void vAFunction( void ) { xTaskHandle xHandle; // Create a task, storing the handle. xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); // ... // Use the handle to obtain the priority of the created task. // It was created with tskIDLE_PRIORITY, but may have changed // it itself. if( uxTaskPriorityGet( xHandle ) != tskIDLE_PRIORITY ) { // The task has changed it's priority. } // ... // Is our priority higher than the created task? if( uxTaskPriorityGet( xHandle ) < uxTaskPriorityGet( NULL ) ) { // Our priority (obtained using NULL handle) is higher. } }
task. h
void vTaskPrioritySet( xTaskHandle pxTask, unsigned portBASE_TYPE uxNewPriority );
INCLUDE_vTaskPrioritySet must be defined as 1 for this function to be available. See the configuration section for more information.
Set the priority of any task.
A context switch will occur before the function returns if the priority being set is higher than the currently executing task.
| pxTask | Handle to the task for which the priority is being set. Passing a NULL handle results in the priority of the calling task being set. |
| uxNewPriority | The priority to which the task will be set. |
Example usage:
void vAFunction( void ) { xTaskHandle xHandle; // Create a task, storing the handle. xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); // ... // Use the handle to raise the priority of the created task. vTaskPrioritySet( xHandle, tskIDLE_PRIORITY + 1 ); // ... // Use a NULL handle to raise our priority to the same value. vTaskPrioritySet( NULL, tskIDLE_PRIORITY + 1 ); }
task. h
void vTaskSuspend( xTaskHandle pxTaskToSuspend );
INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. See the configuration section for more information.
Suspend any task. When suspended a task will never get any microcontroller processing time, no matter what its priority.
Calls to vTaskSuspend are not accumulative - i.e. calling vTaskSuspend () twice on the same task still only requires one call to vTaskResume () to ready the suspended task.
| pxTaskToSuspend | Handle to the task being suspended. Passing a NULL handle will cause the calling task to be suspended. |
Example usage:
void vAFunction( void ) { xTaskHandle xHandle; // Create a task, storing the handle. xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); // ... // Use the handle to suspend the created task. vTaskSuspend( xHandle ); // ... // The created task will not run during this period, unless // another task calls vTaskResume( xHandle ). //... // Suspend ourselves. vTaskSuspend( NULL ); // We cannot get here unless another task calls vTaskResume // with our handle as the parameter. }
task. h
void vTaskResume( xTaskHandle pxTaskToResume );
INCLUDE_vTaskSuspend must be defined as 1 for this function to be available. See the configuration section for more information.
Resumes a suspended task.
A task that has been suspended by one of more calls to vTaskSuspend () will be made available for running again by a single call to vTaskResume ().
| pxTaskToResume | Handle to the task being readied. |
Example usage:
void vAFunction( void ) { xTaskHandle xHandle; // Create a task, storing the handle. xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, &xHandle ); // ... // Use the handle to suspend the created task. vTaskSuspend( xHandle ); // ... // The created task will not run during this period, unless // another task calls vTaskResume( xHandle ). //... // Resume the suspended task ourselves. vTaskResume( xHandle ); // The created task will once again get microcontroller processing // time in accordance with it priority within the system. }
task. h
void xTaskResumeFromISR( xTaskHandle pxTaskToResume );
INCLUDE_xTaskResumeFromISR must be defined as 1 for this function to be available. See the configuration section for more information.
An implementation of vTaskResume() that can be called from within an ISR.
A task that has been suspended by one of more calls to vTaskSuspend () will be made available for running again by a single call to xTaskResumeFromISR ().
| pxTaskToResume | Handle to the task being readied. |
1.7.3