KernelSoftware timers

Updated Mar 2025

xTimerChangePeriodFromISR

[Timer API]

timers.h

1 BaseType_t xTimerChangePeriodFromISR
2           (
3              TimerHandle_t xTimer,
4              TickType_t xNewPeriod,
5              BaseType_t *pxHigherPriorityTaskWoken
6           );

Copy

A version of xTimerChangePeriod() that can be called from an interrupt service routine.

Parameters:

• xTimer

  The handle of the software timer that is having its period changed.

• xNewPeriod

  The new period for xTimer. Timer periods are specified in tick periods, so the constant portTICK_PERIOD_MS can be used to convert a time that has been specified in milliseconds. For example, if the timer must expire after 100 ticks, then xNewPeriod should be set to 100. Alternatively, if the timer must expire after 500ms, then xNewPeriod can be set to ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or equal to 1000.

• pxHigherPriorityTaskWoken

  The timer service/daemon task spends most of its time in the Blocked state, waiting for messages to arrive on the timer command queue. Calling xTimerChangePeriodFromISR() writes a message to the timer command queue, so has the potential to transition the timer service/daemon task out of the Blocked state. If calling xTimerChangePeriodFromISR() causes the timer service/daemon task to leave the Blocked state, and the timer service/daemon task has a priority equal to or greater than the currently executing task (the task that was interrupted), then pxHigherPriorityTaskWoken will get set to pdTRUE internally within the xTimerChangePeriodFromISR() function. If xTimerChangePeriodFromISR() sets this value to pdTRUE, then a context switch should be performed before the interrupt exits.

Returns:

• pdFAIL will be returned if the command to change the timers period could not be sent to the timer command queue.

• pdPASS will be returned if the command was successfully sent to the timer command queue.

• When the command is actually processed will depend on the priority of the timer service/daemon task relative to other tasks in the system. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.

Example usage:

1/* This scenario assumes xTimer has already been created and started. When
2   an interrupt occurs, the period of xTimer should be changed to 500ms. */
3
4/* The interrupt service routine that changes the period of xTimer. */
5void vAnExampleInterruptServiceRoutine( void )
6{
7BaseType_t xHigherPriorityTaskWoken = pdFALSE;
8
9    /* The interrupt has occurred - change the period of xTimer to 500ms.
10       xHigherPriorityTaskWoken was set to pdFALSE where it was defined
11       (within this function). As this is an interrupt service routine, only
12       FreeRTOS API functions that end in "FromISR" can be used. */
13    if( xTimerChangePeriodFromISR( xTimer,
14                                   pdMS_TO_TICKS( 500 ),
15                                   &xHigherPriorityTaskWoken ) != pdPASS )
16    {
17        /* The command to change the timers period was not executed
18           successfully. Take appropriate action here. */
19    }
20
21    /* If xHigherPriorityTaskWoken equals pdTRUE, then a context switch
22       should be performed. The syntax required to perform a context switch
23       from inside an ISR varies from port to port, and from compiler to
24       compiler. Inspect the demos for the port you are using to find the
25       actual syntax required. */
26    if( xHigherPriorityTaskWoken != pdFALSE )
27    {
28        /* Call the interrupt safe yield function here (actual function
29           depends on the FreeRTOS port being used). */
30    }
31}

Copy