[Study FreeRTOS-Task API] 2.10 vTaskDelayUntil()

#include "FreeRTOS.h"
#include "task.h"

void vTaskDelayUntil(TickType_t *pxPreviousWakeTime,TickType_t xTimeIncrement);

Summary
Places  the  task  that  calls  vTaskDelayUntil()  into  the  Blocked  state  until  an  absolute  time  is
reached.
Periodic tasks can use vTaskDelayUntil() to achieve a constant execution frequency.
Differences Between vTaskDelay() and  vTaskDelayUntil()
vTaskDelay()  results in  the calling task  entering into the Blocked state, and then remaining in
the  Blocked  state,  for the  specified  number  of ticks from the  time  vTaskDelay()  was  called.
The time at which the task  that called vTaskDelay()  exits the Blocked state is  relative  to when
vTaskDelay() was called.
vTaskDelayUntil()  results  in  the  calling  task  entering  into  the  Blocked  state,  and  then
remaining in the Blocked state, until an  absolute  time has been reached. The task that called
vTaskDelayUntil()  exits  the  Blocked state  exactly  at  the  specified  time, not  at  a  time that  is
relative to when vTaskDelayUntil() was called.

Parameters
pxPreviousWakeTime - This parameter is named on the assumption that vTaskDelayUntil() is
being used to implement a task that executes periodically and with a fixed frequency. In this case pxPreviousWakeTime holds the time at which the task last left the Blocked state (was ‘woken’ up). This time is used as a reference point to calculate the time at which t he task should next leave the
Blocked state.
The variable pointed to by pxPreviousWakeTime is updated automatically within the vTaskDelayUntil() function; it would not normally be modified by the application code, other than when the variable is first initialized.  The example in this section demonstrates
how the initialization is performed.
xTimeIncrement  This parameter is also named on the assumption that
vTaskDelayUntil() is being used to implement a task that executes
periodically and with a fixed frequency – the frequency being set by
the xTimeIncrement value.
xTimeIncrement is specified in ‘ticks’. The pdMS_TO_TICKS() macro
can be used to convert milliseconds to ticks.

Return Values
None.

Notes
INCLUDE_vTaskDelayUntil  must be set to 1 in FreeRTOSConfig.h for the vTaskDelay() API
function to be available.


Example 
/* Define a task that performs an action every 50 milliseconds. */
void vCyclicTaskFunction( void * pvParameters )
{
TickType_t xLastWakeTime;
const TickType_t xPeriod = pdMS_TO_TICKS( 50 );
/* The xLastWakeTime variable needs to be initialized with the current tick count. Note that this is the only time the variable is written to explicitly.After this assignment, xLastWakeTime is updated automatically internally within vTaskDelayUntil(). */
xLastWakeTime = xTaskGetTickCount();

/* Enter the loop that defines the task behavior. */
for( ;; )
{
/* This task should execute every 50 milliseconds. Time is measured in ticks. The pdMS_TO_TICKS macro is used to convert milliseconds into ticks. xLastWakeTime is automatically updated within vTaskDelayUntil() so is not explicitly updated by the task. */
vTaskDelayUntil( &xLastWakeTime, xPeriod );

/* Perform the periodic actions here. */
}
}