/* * FreeRTOS Kernel V10.5.1 * Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved. * * SPDX-License-Identifier: MIT * * */ #ifndef TIMERS_H #define TIMERS_H #ifndef INC_FREERTOS_H #error "include FreeRTOS.h must appear in source files before include timers.h" #endif /*lint -save -e537 This headers are only multiply included if the application code * happens to also be including task.h. */ #include "task.h" /*lint -restore */ /*----------------------------------------------------------- * MACROS AND DEFINITIONS *----------------------------------------------------------*/ /* IDs for commands that can be sent/received on the timer queue. These are to * be used solely through the macros that make up the public software timer API, * as defined below. The commands that are sent from interrupts must use the * highest numbers as tmrFIRST_FROM_ISR_COMMAND is used to determine if the task * or interrupt version of the queue send function should be used. */ #define tmrCOMMAND_EXECUTE_CALLBACK_FROM_ISR ( ( BaseType_t ) -2 ) #define tmrCOMMAND_EXECUTE_CALLBACK ( ( BaseType_t ) -1 ) #define tmrCOMMAND_START_DONT_TRACE ( ( BaseType_t ) 0 ) #define tmrCOMMAND_START ( ( BaseType_t ) 1 ) #define tmrCOMMAND_RESET ( ( BaseType_t ) 2 ) #define tmrCOMMAND_STOP ( ( BaseType_t ) 3 ) #define tmrCOMMAND_CHANGE_PERIOD ( ( BaseType_t ) 4 ) #define tmrCOMMAND_DELETE ( ( BaseType_t ) 5 ) #define tmrFIRST_FROM_ISR_COMMAND ( ( BaseType_t ) 6 ) #define tmrCOMMAND_START_FROM_ISR ( ( BaseType_t ) 6 ) #define tmrCOMMAND_RESET_FROM_ISR ( ( BaseType_t ) 7 ) #define tmrCOMMAND_STOP_FROM_ISR ( ( BaseType_t ) 8 ) #define tmrCOMMAND_CHANGE_PERIOD_FROM_ISR ( ( BaseType_t ) 9 ) /** * Type by which software timers are referenced. For example, a call to * xTimerCreate() returns an TimerHandle_t variable that can then be used to * reference the subject timer in calls to other software timer API functions * (for example, xTimerStart(), xTimerReset(), etc.). */ struct tmrTimerControl; /* The old naming convention is used to prevent breaking kernel aware debuggers. */ typedef struct tmrTimerControl * TimerHandle_t; /* * Defines the prototype to which timer callback functions must conform. */ typedef void (*TimerCallbackFunction_t)(TimerHandle_t xTimer); /* * Defines the prototype to which functions used with the * xTimerPendFunctionCallFromISR() function must conform. */ typedef void (* PendedFunction_t)(void *, uint32_t ); /** * TimerHandle_t xTimerCreate( const char * const pcTimerName, * TickType_t xTimerPeriodInTicks, * BaseType_t xAutoReload, * 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 * https://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. * * @param 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. * * @param 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. Time timer period must be greater than 0. * * @param xAutoReload If xAutoReload is set to pdTRUE then the timer will * expire repeatedly with a frequency set by the xTimerPeriodInTicks parameter. * If xAutoReload is set to pdFALSE then the timer will be a one-shot timer and * enter the dormant state after it expires. * * @param 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. * * @param 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 );". * * @return If the timer is successfully created then a handle to the newly * created timer is returned. If the timer cannot be created because there is * insufficient FreeRTOS heap remaining to allocate the timer * structures then NULL is returned. * */ TimerHandle_t xTimerCreate(const char * const pcTimerName, const TickType_t xTimerPeriodInTicks, const BaseType_t xAutoReload, void * const pvTimerID, TimerCallbackFunction_t pxCallbackFunction) PRIVILEGED_FUNCTION; /** * 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. * * @param xTimer The timer being queried. * * @return The ID assigned to the timer being queried. * * Example usage: * * See the xTimerCreate() API function example usage scenario. */ void * pvTimerGetTimerID(const TimerHandle_t xTimer) PRIVILEGED_FUNCTION; /** * 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. * * @param xTimer The timer being updated. * * @param pvNewID The ID to assign to the timer. * * Example usage: * * See the xTimerCreate() API function example usage scenario. */ void vTimerSetTimerID(TimerHandle_t xTimer, void * pvNewID) PRIVILEGED_FUNCTION; /** * 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. * * @param xTimer The timer being queried. * * @return pdFALSE will be returned if the timer is dormant. A value other than * pdFALSE will be returned if the timer is active. * */ BaseType_t xTimerIsTimerActive(TimerHandle_t xTimer) PRIVILEGED_FUNCTION; /** * 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. */ TaskHandle_t xTimerGetTimerDaemonTaskHandle(void) PRIVILEGED_FUNCTION; /** * 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. * * @param xTimer The handle of the timer being started/restarted. * * @param 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. * * @return 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. */ #define xTimerStart(xTimer, xTicksToWait) \ xTimerGenericCommand((xTimer), tmrCOMMAND_START, (xTaskGetTickCount()), 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. * * @param xTimer The handle of the timer being stopped. * * @param 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. * * @return 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. */ #define xTimerStop(xTimer, xTicksToWait) \ xTimerGenericCommand((xTimer), tmrCOMMAND_STOP, 0U, 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. * * @param xTimer The handle of the timer that is having its period changed. * * @param 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. * * @param 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. * * @return 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. * */ #define xTimerChangePeriod(xTimer, xNewPeriod, xTicksToWait) \ xTimerGenericCommand((xTimer), tmrCOMMAND_CHANGE_PERIOD, (xNewPeriod), 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. * * @param xTimer The handle of the timer being deleted. * * @param 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. * * @return 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 xTimerDelete(xTimer, xTicksToWait) \ xTimerGenericCommand((xTimer), tmrCOMMAND_DELETE, 0U, 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. * * @param xTimer The handle of the timer being reset/started/restarted. * * @param 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. * * @return 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. * */ #define xTimerReset(xTimer, xTicksToWait) \ xTimerGenericCommand((xTimer), tmrCOMMAND_RESET, (xTaskGetTickCount()), NULL, (xTicksToWait)) /** * BaseType_t xTimerStartFromISR( TimerHandle_t xTimer, * BaseType_t *pxHigherPriorityTaskWoken ); * * A version of xTimerStart() that can be called from an interrupt service * routine. * * @param xTimer The handle of the timer being started/restarted. * * @param 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. * * @return 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. * */ #define xTimerStartFromISR(xTimer, pxHigherPriorityTaskWoken) \ xTimerGenericCommand((xTimer), tmrCOMMAND_START_FROM_ISR, (xTaskGetTickCountFromISR()), (pxHigherPriorityTaskWoken), 0U) /** * BaseType_t xTimerStopFromISR( TimerHandle_t xTimer, * BaseType_t *pxHigherPriorityTaskWoken ); * * A version of xTimerStop() that can be called from an interrupt service * routine. * * @param xTimer The handle of the timer being stopped. * * @param 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. * * @return 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. * */ #define xTimerStopFromISR(xTimer, pxHigherPriorityTaskWoken) \ xTimerGenericCommand((xTimer), tmrCOMMAND_STOP_FROM_ISR, 0, (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. * * @param xTimer The handle of the timer that is having its period changed. * * @param 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. * * @param 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. * * @return 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. * */ #define xTimerChangePeriodFromISR(xTimer, xNewPeriod, pxHigherPriorityTaskWoken) \ xTimerGenericCommand((xTimer), tmrCOMMAND_CHANGE_PERIOD_FROM_ISR, (xNewPeriod), (pxHigherPriorityTaskWoken), 0U) /** * BaseType_t xTimerResetFromISR( TimerHandle_t xTimer, * BaseType_t *pxHigherPriorityTaskWoken ); * * A version of xTimerReset() that can be called from an interrupt service * routine. * * @param xTimer The handle of the timer that is to be started, reset, or * restarted. * * @param 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. * * @return 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. * */ #define xTimerResetFromISR(xTimer, pxHigherPriorityTaskWoken) \ xTimerGenericCommand((xTimer), tmrCOMMAND_RESET_FROM_ISR, (xTaskGetTickCountFromISR()), (pxHigherPriorityTaskWoken), 0U) /** * 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. * * @param xFunctionToPend The function to execute from the timer service/ * daemon task. The function must conform to the PendedFunction_t * prototype. * * @param 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. * * @param ulParameter2 The value of the callback function's second parameter. * * @param 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. * * @return pdPASS is returned if the message was successfully sent to the * timer daemon task, otherwise pdFALSE is returned. * */ BaseType_t xTimerPendFunctionCallFromISR(PendedFunction_t xFunctionToPend, void * pvParameter1, uint32_t ulParameter2, BaseType_t * pxHigherPriorityTaskWoken) PRIVILEGED_FUNCTION; /** * 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'). * * @param xFunctionToPend The function to execute from the timer service/ * daemon task. The function must conform to the PendedFunction_t * prototype. * * @param 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. * * @param ulParameter2 The value of the callback function's second parameter. * * @param 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. * * @return pdPASS is returned if the message was successfully sent to the * timer daemon task, otherwise pdFALSE is returned. * */ BaseType_t xTimerPendFunctionCall(PendedFunction_t xFunctionToPend, void * pvParameter1, uint32_t ulParameter2, TickType_t xTicksToWait) PRIVILEGED_FUNCTION; /** * const char * const pcTimerGetName( TimerHandle_t xTimer ); * * Returns the name that was assigned to a timer when the timer was created. * * @param xTimer The handle of the timer being queried. * * @return The name assigned to the timer specified by the xTimer parameter. */ const char * pcTimerGetName(TimerHandle_t xTimer) PRIVILEGED_FUNCTION; /** * void vTimerSetReloadMode( TimerHandle_t xTimer, const BaseType_t xAutoReload ); * * 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. * * @param xTimer The handle of the timer being updated. * * @param xAutoReload If xAutoReload 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 * xAutoReload is set to pdFALSE then the timer will be a one-shot timer and * enter the dormant state after it expires. */ void vTimerSetReloadMode(TimerHandle_t xTimer, const BaseType_t xAutoReload) PRIVILEGED_FUNCTION; /** * BaseType_t xTimerGetReloadMode( 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. * * @param xTimer The handle of the timer being queried. * * @return If the timer is an auto-reload timer then pdTRUE is returned, otherwise * pdFALSE is returned. */ BaseType_t xTimerGetReloadMode(TimerHandle_t xTimer) PRIVILEGED_FUNCTION; /** * 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. * * @param xTimer The handle of the timer being queried. * * @return If the timer is an auto-reload timer then pdTRUE is returned, otherwise * pdFALSE is returned. */ UBaseType_t uxTimerGetReloadMode(TimerHandle_t xTimer) PRIVILEGED_FUNCTION; /** * TickType_t xTimerGetPeriod( TimerHandle_t xTimer ); * * Returns the period of a timer. * * @param xTimer The handle of the timer being queried. * * @return The period of the timer in ticks. */ TickType_t xTimerGetPeriod(TimerHandle_t xTimer) PRIVILEGED_FUNCTION; /** * 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. * * @param xTimer The handle of the timer being queried. * * @return 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. */ TickType_t xTimerGetExpiryTime(TimerHandle_t xTimer) PRIVILEGED_FUNCTION; /* * Functions beyond this part are not part of the public API and are intended * for use by the kernel only. */ BaseType_t xTimerCreateTimerTask(void) PRIVILEGED_FUNCTION; BaseType_t xTimerGenericCommand(TimerHandle_t xTimer, const BaseType_t xCommandID, const TickType_t xOptionalValue, BaseType_t * const pxHigherPriorityTaskWoken, const TickType_t xTicksToWait) PRIVILEGED_FUNCTION; #if (configUSE_TRACE_FACILITY == 1) void vTimerSetTimerNumber(TimerHandle_t xTimer, UBaseType_t uxTimerNumber) PRIVILEGED_FUNCTION; UBaseType_t uxTimerGetTimerNumber(TimerHandle_t xTimer) PRIVILEGED_FUNCTION; #endif #endif /* TIMERS_H */