Skip to content

File timers.h

FileList > FreeRTOS > include > timers.h

Go to the source code of this file.

  • #include "task.h"

Public Types

Type Name
typedef void(* PendedFunction_t
typedef void(* TimerCallbackFunction_t
typedef struct tmrTimerControl * TimerHandle_t

Public Functions

Type Name
const char * pcTimerGetName (TimerHandle_t xTimer)
void * pvTimerGetTimerID (const TimerHandle_t xTimer)
UBaseType_t uxTimerGetReloadMode (TimerHandle_t xTimer)
void vTimerSetReloadMode (TimerHandle_t xTimer, const UBaseType_t uxAutoReload)
void vTimerSetTimerID (TimerHandle_t xTimer, void * pvNewID)
BaseType_t xTimerCreateTimerTask (void)
BaseType_t xTimerGenericCommand (TimerHandle_t xTimer, const BaseType_t xCommandID, const TickType_t xOptionalValue, BaseType_t *const pxHigherPriorityTaskWoken, const TickType_t xTicksToWait)
TickType_t xTimerGetExpiryTime (TimerHandle_t xTimer)
TickType_t xTimerGetPeriod (TimerHandle_t xTimer)
TaskHandle_t xTimerGetTimerDaemonTaskHandle (void)
BaseType_t xTimerIsTimerActive (TimerHandle_t xTimer)
BaseType_t xTimerPendFunctionCall (PendedFunction_t xFunctionToPend, void * pvParameter1, uint32_t ulParameter2, TickType_t xTicksToWait)
BaseType_t xTimerPendFunctionCallFromISR (PendedFunction_t xFunctionToPend, void * pvParameter1, uint32_t ulParameter2, BaseType_t * pxHigherPriorityTaskWoken)

Macros

Type Name
define tmrCOMMAND_CHANGE_PERIOD ( ( BaseType_t ) 4 )
define tmrCOMMAND_CHANGE_PERIOD_FROM_ISR ( ( BaseType_t ) 9 )
define tmrCOMMAND_DELETE ( ( BaseType_t ) 5 )
define tmrCOMMAND_EXECUTE_CALLBACK ( ( BaseType_t ) -1 )
define tmrCOMMAND_EXECUTE_CALLBACK_FROM_ISR ( ( BaseType_t ) -2 )
define tmrCOMMAND_RESET ( ( BaseType_t ) 2 )
define tmrCOMMAND_RESET_FROM_ISR ( ( BaseType_t ) 7 )
define tmrCOMMAND_START ( ( BaseType_t ) 1 )
define tmrCOMMAND_START_DONT_TRACE ( ( BaseType_t ) 0 )
define tmrCOMMAND_START_FROM_ISR ( ( BaseType_t ) 6 )
define tmrCOMMAND_STOP ( ( BaseType_t ) 3 )
define tmrCOMMAND_STOP_FROM_ISR ( ( BaseType_t ) 8 )
define tmrFIRST_FROM_ISR_COMMAND ( ( BaseType_t ) 6 )
define xTimerChangePeriod (xTimer, xNewPeriod, xTicksToWait) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD, ( xNewPeriod ), NULL, ( xTicksToWait ) )
define xTimerChangePeriodFromISR (xTimer, xNewPeriod, pxHigherPriorityTaskWoken) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD_FROM_ISR, ( xNewPeriod ), ( pxHigherPriorityTaskWoken ), 0U )
define xTimerDelete (xTimer, xTicksToWait) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_DELETE, 0U, NULL, ( xTicksToWait ) )
define xTimerReset (xTimer, xTicksToWait) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_RESET, ( xTaskGetTickCount() ), NULL, ( xTicksToWait ) )
define xTimerResetFromISR (xTimer, pxHigherPriorityTaskWoken) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_RESET_FROM_ISR, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U )
define xTimerStart (xTimer, xTicksToWait) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START, ( xTaskGetTickCount() ), NULL, ( xTicksToWait ) )
define xTimerStartFromISR (xTimer, pxHigherPriorityTaskWoken) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START_FROM_ISR, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U )
define xTimerStop (xTimer, xTicksToWait) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP, 0U, NULL, ( xTicksToWait ) )
define xTimerStopFromISR (xTimer, pxHigherPriorityTaskWoken) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP_FROM_ISR, 0, ( pxHigherPriorityTaskWoken ), 0U )

Public Types Documentation

typedef PendedFunction_t

typedef void(* PendedFunction_t) (void *, uint32_t);

typedef TimerCallbackFunction_t

typedef void(* TimerCallbackFunction_t) (TimerHandle_t xTimer);

typedef TimerHandle_t

typedef struct tmrTimerControl* TimerHandle_t;

Public Functions Documentation

function pcTimerGetName

const char * pcTimerGetName (
    TimerHandle_t xTimer
)

const char * const pcTimerGetName( TimerHandle_t xTimer );

Returns the name that was assigned to a timer when the timer was created.

Parameters:

  • xTimer The handle of the timer being queried.

Returns:

The name assigned to the timer specified by the xTimer parameter.

function pvTimerGetTimerID

void * pvTimerGetTimerID (
    const TimerHandle_t xTimer
)

TimerHandle_t xTimerCreate( const char * const pcTimerName, TickType_t xTimerPeriodInTicks, UBaseType_t uxAutoReload, void * pvTimerID, TimerCallbackFunction_t pxCallbackFunction );

Creates a new software timer instance, and returns a handle by which the created software timer can be referenced.

Internally, within the FreeRTOS implementation, software timers use a block of memory, in which the timer data structure is stored. If a software timer is created using xTimerCreate() then the required memory is automatically dynamically allocated inside the xTimerCreate() function. (see http://www.freertos.org/a00111.html). If a software timer is created using xTimerCreateStatic() then the application writer must provide the memory that will get used by the software timer. xTimerCreateStatic() therefore allows a software timer to be created without using any dynamic memory allocation.

Timers are created in the dormant state. The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and xTimerChangePeriodFromISR() API functions can all be used to transition a timer into the active state.

Parameters:

  • pcTimerName A text name that is assigned to the timer. This is done purely to assist debugging. The kernel itself only ever references a timer by its handle, and never by its name.
  • xTimerPeriodInTicks The timer period. The time is defined 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 xTimerPeriodInTicks should be set to 100. Alternatively, if the timer must expire after 500ms, then xPeriod can be set to ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or equal to 1000.
  • uxAutoReload If uxAutoReload is set to pdTRUE then the timer will expire repeatedly with a frequency set by the xTimerPeriodInTicks parameter. If uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and enter the dormant state after it expires.
  • pvTimerID An identifier that is assigned to the timer being created. Typically this would be used in the timer callback function to identify which timer expired when the same callback function is assigned to more than one timer.
  • pxCallbackFunction The function to call when the timer expires. Callback functions must have the prototype defined by TimerCallbackFunction_t, which is "void vCallbackFunction( TimerHandle_t xTimer );".

Returns:

If the timer is successfully created then a handle to the newly created timer is returned. If the timer cannot be created (because either there is insufficient FreeRTOS heap remaining to allocate the timer structures, or the timer period was set to 0) then NULL is returned.

Example usage: TimerHandle_t xTimerCreateStatic(const char * const pcTimerName, TickType_t xTimerPeriodInTicks, UBaseType_t uxAutoReload, void * pvTimerID, TimerCallbackFunction_t pxCallbackFunction, StaticTimer_t *pxTimerBuffer );

Creates a new software timer instance, and returns a handle by which the created software timer can be referenced.

Internally, within the FreeRTOS implementation, software timers use a block of memory, in which the timer data structure is stored. If a software timer is created using xTimerCreate() then the required memory is automatically dynamically allocated inside the xTimerCreate() function. (see http://www.freertos.org/a00111.html). If a software timer is created using xTimerCreateStatic() then the application writer must provide the memory that will get used by the software timer. xTimerCreateStatic() therefore allows a software timer to be created without using any dynamic memory allocation.

Timers are created in the dormant state. The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and xTimerChangePeriodFromISR() API functions can all be used to transition a timer into the active state.

Parameters:

  • pcTimerName A text name that is assigned to the timer. This is done purely to assist debugging. The kernel itself only ever references a timer by its handle, and never by its name.
  • xTimerPeriodInTicks The timer period. The time is defined 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 xTimerPeriodInTicks should be set to 100. Alternatively, if the timer must expire after 500ms, then xPeriod can be set to ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or equal to 1000.
  • uxAutoReload If uxAutoReload is set to pdTRUE then the timer will expire repeatedly with a frequency set by the xTimerPeriodInTicks parameter. If uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and enter the dormant state after it expires.
  • pvTimerID An identifier that is assigned to the timer being created. Typically this would be used in the timer callback function to identify which timer expired when the same callback function is assigned to more than one timer.
  • pxCallbackFunction The function to call when the timer expires. Callback functions must have the prototype defined by TimerCallbackFunction_t, which is "void vCallbackFunction( TimerHandle_t xTimer );".
  • pxTimerBuffer Must point to a variable of type StaticTimer_t, which will be then be used to hold the software timer's data structures, removing the need for the memory to be allocated dynamically.

Returns:

If the timer is created then a handle to the created timer is returned. If pxTimerBuffer was NULL then NULL is returned.

Example usage: void *pvTimerGetTimerID( TimerHandle_t xTimer );

Returns the ID assigned to the timer.

IDs are assigned to timers using the pvTimerID parameter of the call to xTimerCreated() that was used to create the timer, and by calling the vTimerSetTimerID() API function.

If the same callback function is assigned to multiple timers then the timer ID can be used as time specific (timer local) storage.

Parameters:

  • xTimer The timer being queried.

Returns:

The ID assigned to the timer being queried.

Example usage:

See the xTimerCreate() API function example usage scenario.

function uxTimerGetReloadMode

UBaseType_t uxTimerGetReloadMode (
    TimerHandle_t xTimer
)

UBaseType_t uxTimerGetReloadMode( TimerHandle_t xTimer );

Queries a timer to determine if it is an auto-reload timer, in which case the timer automatically resets itself each time it expires, or a one-shot timer, in which case the timer will only expire once unless it is manually restarted.

Parameters:

  • xTimer The handle of the timer being queried.

Returns:

If the timer is an auto-reload timer then pdTRUE is returned, otherwise pdFALSE is returned.

function vTimerSetReloadMode

void vTimerSetReloadMode (
    TimerHandle_t xTimer,
    const UBaseType_t uxAutoReload
)

void vTimerSetReloadMode( TimerHandle_t xTimer, const UBaseType_t uxAutoReload );

Updates a timer to be either an auto-reload timer, in which case the timer automatically resets itself each time it expires, or a one-shot timer, in which case the timer will only expire once unless it is manually restarted.

Parameters:

  • xTimer The handle of the timer being updated.
  • uxAutoReload If uxAutoReload is set to pdTRUE then the timer will expire repeatedly with a frequency set by the timer's period (see the xTimerPeriodInTicks parameter of the xTimerCreate() API function). If uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and enter the dormant state after it expires.

function vTimerSetTimerID

void vTimerSetTimerID (
    TimerHandle_t xTimer,
    void * pvNewID
)

void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID );

Sets the ID assigned to the timer.

IDs are assigned to timers using the pvTimerID parameter of the call to xTimerCreated() that was used to create the timer.

If the same callback function is assigned to multiple timers then the timer ID can be used as time specific (timer local) storage.

Parameters:

  • xTimer The timer being updated.
  • pvNewID The ID to assign to the timer.

Example usage:

See the xTimerCreate() API function example usage scenario.

function xTimerCreateTimerTask

BaseType_t xTimerCreateTimerTask (
    void
)

function xTimerGenericCommand

BaseType_t xTimerGenericCommand (
    TimerHandle_t xTimer,
    const BaseType_t xCommandID,
    const TickType_t xOptionalValue,
    BaseType_t *const pxHigherPriorityTaskWoken,
    const TickType_t xTicksToWait
)

function xTimerGetExpiryTime

TickType_t xTimerGetExpiryTime (
    TimerHandle_t xTimer
)

TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer );

Returns the time in ticks at which the timer will expire. If this is less than the current tick count then the expiry time has overflowed from the current time.

Parameters:

  • xTimer The handle of the timer being queried.

Returns:

If the timer is running then the time in ticks at which the timer will next expire is returned. If the timer is not running then the return value is undefined.

function xTimerGetPeriod

TickType_t xTimerGetPeriod (
    TimerHandle_t xTimer
)

TickType_t xTimerGetPeriod( TimerHandle_t xTimer );

Returns the period of a timer.

Parameters:

  • xTimer The handle of the timer being queried.

Returns:

The period of the timer in ticks.

function xTimerGetTimerDaemonTaskHandle

TaskHandle_t xTimerGetTimerDaemonTaskHandle (
    void
)

TaskHandle_t xTimerGetTimerDaemonTaskHandle( void );

Simply returns the handle of the timer service/daemon task. It it not valid to call xTimerGetTimerDaemonTaskHandle() before the scheduler has been started.

function xTimerIsTimerActive

BaseType_t xTimerIsTimerActive (
    TimerHandle_t xTimer
)

BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer );

Queries a timer to see if it is active or dormant.

A timer will be dormant if: 1) It has been created but not started, or 2) It is an expired one-shot timer that has not been restarted.

Timers are created in the dormant state. The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and xTimerChangePeriodFromISR() API functions can all be used to transition a timer into the active state.

Parameters:

  • xTimer The timer being queried.

Returns:

pdFALSE will be returned if the timer is dormant. A value other than pdFALSE will be returned if the timer is active.

Example usage:

function xTimerPendFunctionCall

BaseType_t xTimerPendFunctionCall (
    PendedFunction_t xFunctionToPend,
    void * pvParameter1,
    uint32_t ulParameter2,
    TickType_t xTicksToWait
)

BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend, void *pvParameter1, uint32_t ulParameter2, TickType_t xTicksToWait );

Used to defer the execution of a function to the RTOS daemon task (the timer service task, hence this function is implemented in timers.c and is prefixed with 'Timer').

Parameters:

  • xFunctionToPend The function to execute from the timer service/ daemon task. The function must conform to the PendedFunction_t prototype.
  • pvParameter1 The value of the callback function's first parameter. The parameter has a void * type to allow it to be used to pass any type. For example, unsigned longs can be cast to a void *, or the void * can be used to point to a structure.
  • ulParameter2 The value of the callback function's second parameter.
  • xTicksToWait Calling this function will result in a message being sent to the timer daemon task on a queue. xTicksToWait is the amount of time the calling task should remain in the Blocked state (so not using any processing time) for space to become available on the timer queue if the queue is found to be full.

Returns:

pdPASS is returned if the message was successfully sent to the timer daemon task, otherwise pdFALSE is returned.

function xTimerPendFunctionCallFromISR

BaseType_t xTimerPendFunctionCallFromISR (
    PendedFunction_t xFunctionToPend,
    void * pvParameter1,
    uint32_t ulParameter2,
    BaseType_t * pxHigherPriorityTaskWoken
)

BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend, void *pvParameter1, uint32_t ulParameter2, BaseType_t *pxHigherPriorityTaskWoken );

Used from application interrupt service routines to defer the execution of a function to the RTOS daemon task (the timer service task, hence this function is implemented in timers.c and is prefixed with 'Timer').

Ideally an interrupt service routine (ISR) is kept as short as possible, but sometimes an ISR either has a lot of processing to do, or needs to perform processing that is not deterministic. In these cases xTimerPendFunctionCallFromISR() can be used to defer processing of a function to the RTOS daemon task.

A mechanism is provided that allows the interrupt to return directly to the task that will subsequently execute the pended callback function. This allows the callback function to execute contiguously in time with the interrupt - just as if the callback had executed in the interrupt itself.

Parameters:

  • xFunctionToPend The function to execute from the timer service/ daemon task. The function must conform to the PendedFunction_t prototype.
  • pvParameter1 The value of the callback function's first parameter. The parameter has a void * type to allow it to be used to pass any type. For example, unsigned longs can be cast to a void *, or the void * can be used to point to a structure.
  • ulParameter2 The value of the callback function's second parameter.
  • pxHigherPriorityTaskWoken As mentioned above, calling this function will result in a message being sent to the timer daemon task. If the priority of the timer daemon task (which is set using configTIMER_TASK_PRIORITY in FreeRTOSConfig.h) is higher than the priority of the currently running task (the task the interrupt interrupted) then *pxHigherPriorityTaskWoken will be set to pdTRUE within xTimerPendFunctionCallFromISR(), indicating that a context switch should be requested before the interrupt exits. For that reason *pxHigherPriorityTaskWoken must be initialised to pdFALSE. See the example code below.

Returns:

pdPASS is returned if the message was successfully sent to the timer daemon task, otherwise pdFALSE is returned.

Example usage:

Macro Definition Documentation

define tmrCOMMAND_CHANGE_PERIOD

#define tmrCOMMAND_CHANGE_PERIOD ( ( BaseType_t ) 4 )

define tmrCOMMAND_CHANGE_PERIOD_FROM_ISR

#define tmrCOMMAND_CHANGE_PERIOD_FROM_ISR ( ( BaseType_t ) 9 )

define tmrCOMMAND_DELETE

#define tmrCOMMAND_DELETE ( ( BaseType_t ) 5 )

define tmrCOMMAND_EXECUTE_CALLBACK

#define tmrCOMMAND_EXECUTE_CALLBACK ( ( BaseType_t ) -1 )

define tmrCOMMAND_EXECUTE_CALLBACK_FROM_ISR

#define tmrCOMMAND_EXECUTE_CALLBACK_FROM_ISR ( ( BaseType_t ) -2 )

define tmrCOMMAND_RESET

#define tmrCOMMAND_RESET ( ( BaseType_t ) 2 )

define tmrCOMMAND_RESET_FROM_ISR

#define tmrCOMMAND_RESET_FROM_ISR ( ( BaseType_t ) 7 )

define tmrCOMMAND_START

#define tmrCOMMAND_START ( ( BaseType_t ) 1 )

define tmrCOMMAND_START_DONT_TRACE

#define tmrCOMMAND_START_DONT_TRACE ( ( BaseType_t ) 0 )

define tmrCOMMAND_START_FROM_ISR

#define tmrCOMMAND_START_FROM_ISR ( ( BaseType_t ) 6 )

define tmrCOMMAND_STOP

#define tmrCOMMAND_STOP ( ( BaseType_t ) 3 )

define tmrCOMMAND_STOP_FROM_ISR

#define tmrCOMMAND_STOP_FROM_ISR ( ( BaseType_t ) 8 )

define tmrFIRST_FROM_ISR_COMMAND

#define tmrFIRST_FROM_ISR_COMMAND ( ( BaseType_t ) 6 )

define xTimerChangePeriod

#define xTimerChangePeriod (
    xTimer,
    xNewPeriod,
    xTicksToWait
) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD, ( xNewPeriod ), NULL, ( xTicksToWait ) )

BaseType_t xTimerChangePeriod( TimerHandle_t xTimer, TickType_t xNewPeriod, TickType_t xTicksToWait );

Timer functionality is provided by a timer service/daemon task. Many of the public FreeRTOS timer API functions send commands to the timer service task through a queue called the timer command queue. The timer command queue is private to the kernel itself and is not directly accessible to application code. The length of the timer command queue is set by the configTIMER_QUEUE_LENGTH configuration constant.

xTimerChangePeriod() changes the period of a timer that was previously created using the xTimerCreate() API function.

xTimerChangePeriod() can be called to change the period of an active or dormant state timer.

The configUSE_TIMERS configuration constant must be set to 1 for xTimerChangePeriod() to be available.

Parameters:

  • xTimer The handle of the 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.
  • xTicksToWait Specifies the time, in ticks, that the calling task should be held in the Blocked state to wait for the change period command to be successfully sent to the timer command queue, should the queue already be full when xTimerChangePeriod() was called. xTicksToWait is ignored if xTimerChangePeriod() is called before the scheduler is started.

Returns:

pdFAIL will be returned if the change period command could not be sent to the timer command queue even after xTicksToWait ticks had passed. 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:

define xTimerChangePeriodFromISR

#define xTimerChangePeriodFromISR (
    xTimer,
    xNewPeriod,
    pxHigherPriorityTaskWoken
) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD_FROM_ISR, ( xNewPeriod ), ( pxHigherPriorityTaskWoken ), 0U )

BaseType_t xTimerChangePeriodFromISR( TimerHandle_t xTimer, TickType_t xNewPeriod, BaseType_t *pxHigherPriorityTaskWoken );

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

Parameters:

  • xTimer The handle of the 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:

define xTimerDelete

#define xTimerDelete (
    xTimer,
    xTicksToWait
) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_DELETE, 0U, NULL, ( xTicksToWait ) )

BaseType_t xTimerDelete( TimerHandle_t xTimer, TickType_t xTicksToWait );

Timer functionality is provided by a timer service/daemon task. Many of the public FreeRTOS timer API functions send commands to the timer service task through a queue called the timer command queue. The timer command queue is private to the kernel itself and is not directly accessible to application code. The length of the timer command queue is set by the configTIMER_QUEUE_LENGTH configuration constant.

xTimerDelete() deletes a timer that was previously created using the xTimerCreate() API function.

The configUSE_TIMERS configuration constant must be set to 1 for xTimerDelete() to be available.

Parameters:

  • xTimer The handle of the timer being deleted.
  • xTicksToWait Specifies the time, in ticks, that the calling task should be held in the Blocked state to wait for the delete command to be successfully sent to the timer command queue, should the queue already be full when xTimerDelete() was called. xTicksToWait is ignored if xTimerDelete() is called before the scheduler is started.

Returns:

pdFAIL will be returned if the delete command could not be sent to the timer command queue even after xTicksToWait ticks had passed. 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:

See the xTimerChangePeriod() API function example usage scenario.

define xTimerReset

#define xTimerReset (
    xTimer,
    xTicksToWait
) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_RESET, ( xTaskGetTickCount() ), NULL, ( xTicksToWait ) )

BaseType_t xTimerReset( TimerHandle_t xTimer, TickType_t xTicksToWait );

Timer functionality is provided by a timer service/daemon task. Many of the public FreeRTOS timer API functions send commands to the timer service task through a queue called the timer command queue. The timer command queue is private to the kernel itself and is not directly accessible to application code. The length of the timer command queue is set by the configTIMER_QUEUE_LENGTH configuration constant.

xTimerReset() re-starts a timer that was previously created using the xTimerCreate() API function. If the timer had already been started and was already in the active state, then xTimerReset() will cause the timer to re-evaluate its expiry time so that it is relative to when xTimerReset() was called. If the timer was in the dormant state then xTimerReset() has equivalent functionality to the xTimerStart() API function.

Resetting a timer ensures the timer is in the active state. If the timer is not stopped, deleted, or reset in the mean time, the callback function associated with the timer will get called 'n' ticks after xTimerReset() was called, where 'n' is the timers defined period.

It is valid to call xTimerReset() before the scheduler has been started, but when this is done the timer will not actually start until the scheduler is started, and the timers expiry time will be relative to when the scheduler is started, not relative to when xTimerReset() was called.

The configUSE_TIMERS configuration constant must be set to 1 for xTimerReset() to be available.

Parameters:

  • xTimer The handle of the timer being reset/started/restarted.
  • xTicksToWait Specifies the time, in ticks, that the calling task should be held in the Blocked state to wait for the reset command to be successfully sent to the timer command queue, should the queue already be full when xTimerReset() was called. xTicksToWait is ignored if xTimerReset() is called before the scheduler is started.

Returns:

pdFAIL will be returned if the reset command could not be sent to the timer command queue even after xTicksToWait ticks had passed. 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, although the timers expiry time is relative to when xTimerStart() is actually called. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.

Example usage:

define xTimerResetFromISR

#define xTimerResetFromISR (
    xTimer,
    pxHigherPriorityTaskWoken
) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_RESET_FROM_ISR, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U )

BaseType_t xTimerResetFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken );

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

Parameters:

  • xTimer The handle of the timer that is to be started, reset, or restarted.
  • 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 xTimerResetFromISR() 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 xTimerResetFromISR() 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 xTimerResetFromISR() function. If xTimerResetFromISR() sets this value to pdTRUE then a context switch should be performed before the interrupt exits.

Returns:

pdFAIL will be returned if the reset command 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, although the timers expiry time is relative to when xTimerResetFromISR() is actually called. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.

Example usage:

define xTimerStart

#define xTimerStart (
    xTimer,
    xTicksToWait
) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START, ( xTaskGetTickCount() ), NULL, ( xTicksToWait ) )

BaseType_t xTimerStart( TimerHandle_t xTimer, TickType_t xTicksToWait );

Timer functionality is provided by a timer service/daemon task. Many of the public FreeRTOS timer API functions send commands to the timer service task through a queue called the timer command queue. The timer command queue is private to the kernel itself and is not directly accessible to application code. The length of the timer command queue is set by the configTIMER_QUEUE_LENGTH configuration constant.

xTimerStart() starts a timer that was previously created using the xTimerCreate() API function. If the timer had already been started and was already in the active state, then xTimerStart() has equivalent functionality to the xTimerReset() API function.

Starting a timer ensures the timer is in the active state. If the timer is not stopped, deleted, or reset in the mean time, the callback function associated with the timer will get called 'n' ticks after xTimerStart() was called, where 'n' is the timers defined period.

It is valid to call xTimerStart() before the scheduler has been started, but when this is done the timer will not actually start until the scheduler is started, and the timers expiry time will be relative to when the scheduler is started, not relative to when xTimerStart() was called.

The configUSE_TIMERS configuration constant must be set to 1 for xTimerStart() to be available.

Parameters:

  • xTimer The handle of the timer being started/restarted.
  • xTicksToWait Specifies the time, in ticks, that the calling task should be held in the Blocked state to wait for the start command to be successfully sent to the timer command queue, should the queue already be full when xTimerStart() was called. xTicksToWait is ignored if xTimerStart() is called before the scheduler is started.

Returns:

pdFAIL will be returned if the start command could not be sent to the timer command queue even after xTicksToWait ticks had passed. 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, although the timers expiry time is relative to when xTimerStart() is actually called. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.

Example usage:

See the xTimerCreate() API function example usage scenario.

define xTimerStartFromISR

#define xTimerStartFromISR (
    xTimer,
    pxHigherPriorityTaskWoken
) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START_FROM_ISR, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U )

BaseType_t xTimerStartFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken );

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

Parameters:

  • xTimer The handle of the timer being started/restarted.
  • 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 xTimerStartFromISR() 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 xTimerStartFromISR() 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 xTimerStartFromISR() function. If xTimerStartFromISR() sets this value to pdTRUE then a context switch should be performed before the interrupt exits.

Returns:

pdFAIL will be returned if the start command 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, although the timers expiry time is relative to when xTimerStartFromISR() is actually called. The timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY configuration constant.

Example usage:

define xTimerStop

#define xTimerStop (
    xTimer,
    xTicksToWait
) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP, 0U, NULL, ( xTicksToWait ) )

BaseType_t xTimerStop( TimerHandle_t xTimer, TickType_t xTicksToWait );

Timer functionality is provided by a timer service/daemon task. Many of the public FreeRTOS timer API functions send commands to the timer service task through a queue called the timer command queue. The timer command queue is private to the kernel itself and is not directly accessible to application code. The length of the timer command queue is set by the configTIMER_QUEUE_LENGTH configuration constant.

xTimerStop() stops a timer that was previously started using either of the The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() or xTimerChangePeriodFromISR() API functions.

Stopping a timer ensures the timer is not in the active state.

The configUSE_TIMERS configuration constant must be set to 1 for xTimerStop() to be available.

Parameters:

  • xTimer The handle of the timer being stopped.
  • xTicksToWait Specifies the time, in ticks, that the calling task should be held in the Blocked state to wait for the stop command to be successfully sent to the timer command queue, should the queue already be full when xTimerStop() was called. xTicksToWait is ignored if xTimerStop() is called before the scheduler is started.

Returns:

pdFAIL will be returned if the stop command could not be sent to the timer command queue even after xTicksToWait ticks had passed. 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:

See the xTimerCreate() API function example usage scenario.

define xTimerStopFromISR

#define xTimerStopFromISR (
    xTimer,
    pxHigherPriorityTaskWoken
) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP_FROM_ISR, 0, ( pxHigherPriorityTaskWoken ), 0U )

BaseType_t xTimerStopFromISR( TimerHandle_t xTimer, BaseType_t *pxHigherPriorityTaskWoken );

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

Parameters:

  • xTimer The handle of the timer being stopped.
  • 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 xTimerStopFromISR() 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 xTimerStopFromISR() 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 xTimerStopFromISR() function. If xTimerStopFromISR() sets this value to pdTRUE then a context switch should be performed before the interrupt exits.

Returns:

pdFAIL will be returned if the stop command 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:

The documentation for this class was generated from the following file fw/rbcx-coprocessor/lib/FreeRTOS/include/timers.h