Francisco Paez / freertos

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   frdm_k64f_freertos_lib

src/include/timers.h@0:62cd296ba2a7, 2017-05-31 (annotated)

Committer:
fep
Date:
Wed May 31 02:27:10 2017 +0000
Revision:
0:62cd296ba2a7
FreeRTOS v9.0.0 for Cortex-M4F (FRDM-K64F and others...)

Who changed what in which revision?

UserRevisionLine numberNew contents of line
fep 0:62cd296ba2a7 1 /*
fep 0:62cd296ba2a7 2 FreeRTOS V9.0.0 - Copyright (C) 2016 Real Time Engineers Ltd.
fep 0:62cd296ba2a7 3 All rights reserved
fep 0:62cd296ba2a7 4
fep 0:62cd296ba2a7 5 VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.
fep 0:62cd296ba2a7 6
fep 0:62cd296ba2a7 7 This file is part of the FreeRTOS distribution.
fep 0:62cd296ba2a7 8
fep 0:62cd296ba2a7 9 FreeRTOS is free software; you can redistribute it and/or modify it under
fep 0:62cd296ba2a7 10 the terms of the GNU General Public License (version 2) as published by the
fep 0:62cd296ba2a7 11 Free Software Foundation >>>> AND MODIFIED BY <<<< the FreeRTOS exception.
fep 0:62cd296ba2a7 12
fep 0:62cd296ba2a7 13 ***************************************************************************
fep 0:62cd296ba2a7 14 >>! NOTE: The modification to the GPL is included to allow you to !<<
fep 0:62cd296ba2a7 15 >>! distribute a combined work that includes FreeRTOS without being !<<
fep 0:62cd296ba2a7 16 >>! obliged to provide the source code for proprietary components !<<
fep 0:62cd296ba2a7 17 >>! outside of the FreeRTOS kernel. !<<
fep 0:62cd296ba2a7 18 ***************************************************************************
fep 0:62cd296ba2a7 19
fep 0:62cd296ba2a7 20 FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY
fep 0:62cd296ba2a7 21 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
fep 0:62cd296ba2a7 22 FOR A PARTICULAR PURPOSE. Full license text is available on the following
fep 0:62cd296ba2a7 23 link: http://www.freertos.org/a00114.html
fep 0:62cd296ba2a7 24
fep 0:62cd296ba2a7 25 ***************************************************************************
fep 0:62cd296ba2a7 26 * *
fep 0:62cd296ba2a7 27 * FreeRTOS provides completely free yet professionally developed, *
fep 0:62cd296ba2a7 28 * robust, strictly quality controlled, supported, and cross *
fep 0:62cd296ba2a7 29 * platform software that is more than just the market leader, it *
fep 0:62cd296ba2a7 30 * is the industry's de facto standard. *
fep 0:62cd296ba2a7 31 * *
fep 0:62cd296ba2a7 32 * Help yourself get started quickly while simultaneously helping *
fep 0:62cd296ba2a7 33 * to support the FreeRTOS project by purchasing a FreeRTOS *
fep 0:62cd296ba2a7 34 * tutorial book, reference manual, or both: *
fep 0:62cd296ba2a7 35 * http://www.FreeRTOS.org/Documentation *
fep 0:62cd296ba2a7 36 * *
fep 0:62cd296ba2a7 37 ***************************************************************************
fep 0:62cd296ba2a7 38
fep 0:62cd296ba2a7 39 http://www.FreeRTOS.org/FAQHelp.html - Having a problem? Start by reading
fep 0:62cd296ba2a7 40 the FAQ page "My application does not run, what could be wrong?". Have you
fep 0:62cd296ba2a7 41 defined configASSERT()?
fep 0:62cd296ba2a7 42
fep 0:62cd296ba2a7 43 http://www.FreeRTOS.org/support - In return for receiving this top quality
fep 0:62cd296ba2a7 44 embedded software for free we request you assist our global community by
fep 0:62cd296ba2a7 45 participating in the support forum.
fep 0:62cd296ba2a7 46
fep 0:62cd296ba2a7 47 http://www.FreeRTOS.org/training - Investing in training allows your team to
fep 0:62cd296ba2a7 48 be as productive as possible as early as possible. Now you can receive
fep 0:62cd296ba2a7 49 FreeRTOS training directly from Richard Barry, CEO of Real Time Engineers
fep 0:62cd296ba2a7 50 Ltd, and the world's leading authority on the world's leading RTOS.
fep 0:62cd296ba2a7 51
fep 0:62cd296ba2a7 52 http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products,
fep 0:62cd296ba2a7 53 including FreeRTOS+Trace - an indispensable productivity tool, a DOS
fep 0:62cd296ba2a7 54 compatible FAT file system, and our tiny thread aware UDP/IP stack.
fep 0:62cd296ba2a7 55
fep 0:62cd296ba2a7 56 http://www.FreeRTOS.org/labs - Where new FreeRTOS products go to incubate.
fep 0:62cd296ba2a7 57 Come and try FreeRTOS+TCP, our new open source TCP/IP stack for FreeRTOS.
fep 0:62cd296ba2a7 58
fep 0:62cd296ba2a7 59 http://www.OpenRTOS.com - Real Time Engineers ltd. license FreeRTOS to High
fep 0:62cd296ba2a7 60 Integrity Systems ltd. to sell under the OpenRTOS brand. Low cost OpenRTOS
fep 0:62cd296ba2a7 61 licenses offer ticketed support, indemnification and commercial middleware.
fep 0:62cd296ba2a7 62
fep 0:62cd296ba2a7 63 http://www.SafeRTOS.com - High Integrity Systems also provide a safety
fep 0:62cd296ba2a7 64 engineered and independently SIL3 certified version for use in safety and
fep 0:62cd296ba2a7 65 mission critical applications that require provable dependability.
fep 0:62cd296ba2a7 66
fep 0:62cd296ba2a7 67 1 tab == 4 spaces!
fep 0:62cd296ba2a7 68 */
fep 0:62cd296ba2a7 69
fep 0:62cd296ba2a7 70
fep 0:62cd296ba2a7 71 #ifndef TIMERS_H
fep 0:62cd296ba2a7 72 #define TIMERS_H
fep 0:62cd296ba2a7 73
fep 0:62cd296ba2a7 74 #ifndef INC_FREERTOS_H
fep 0:62cd296ba2a7 75 #error "include FreeRTOS.h must appear in source files before include timers.h"
fep 0:62cd296ba2a7 76 #endif
fep 0:62cd296ba2a7 77
fep 0:62cd296ba2a7 78 /*lint -e537 This headers are only multiply included if the application code
fep 0:62cd296ba2a7 79 happens to also be including task.h. */
fep 0:62cd296ba2a7 80 #include "task.h"
fep 0:62cd296ba2a7 81 /*lint +e537 */
fep 0:62cd296ba2a7 82
fep 0:62cd296ba2a7 83 #ifdef __cplusplus
fep 0:62cd296ba2a7 84 extern "C" {
fep 0:62cd296ba2a7 85 #endif
fep 0:62cd296ba2a7 86
fep 0:62cd296ba2a7 87 /*-----------------------------------------------------------
fep 0:62cd296ba2a7 88 * MACROS AND DEFINITIONS
fep 0:62cd296ba2a7 89 *----------------------------------------------------------*/
fep 0:62cd296ba2a7 90
fep 0:62cd296ba2a7 91 /* IDs for commands that can be sent/received on the timer queue. These are to
fep 0:62cd296ba2a7 92 be used solely through the macros that make up the public software timer API,
fep 0:62cd296ba2a7 93 as defined below. The commands that are sent from interrupts must use the
fep 0:62cd296ba2a7 94 highest numbers as tmrFIRST_FROM_ISR_COMMAND is used to determine if the task
fep 0:62cd296ba2a7 95 or interrupt version of the queue send function should be used. */
fep 0:62cd296ba2a7 96 #define tmrCOMMAND_EXECUTE_CALLBACK_FROM_ISR ( ( BaseType_t ) -2 )
fep 0:62cd296ba2a7 97 #define tmrCOMMAND_EXECUTE_CALLBACK ( ( BaseType_t ) -1 )
fep 0:62cd296ba2a7 98 #define tmrCOMMAND_START_DONT_TRACE ( ( BaseType_t ) 0 )
fep 0:62cd296ba2a7 99 #define tmrCOMMAND_START ( ( BaseType_t ) 1 )
fep 0:62cd296ba2a7 100 #define tmrCOMMAND_RESET ( ( BaseType_t ) 2 )
fep 0:62cd296ba2a7 101 #define tmrCOMMAND_STOP ( ( BaseType_t ) 3 )
fep 0:62cd296ba2a7 102 #define tmrCOMMAND_CHANGE_PERIOD ( ( BaseType_t ) 4 )
fep 0:62cd296ba2a7 103 #define tmrCOMMAND_DELETE ( ( BaseType_t ) 5 )
fep 0:62cd296ba2a7 104
fep 0:62cd296ba2a7 105 #define tmrFIRST_FROM_ISR_COMMAND ( ( BaseType_t ) 6 )
fep 0:62cd296ba2a7 106 #define tmrCOMMAND_START_FROM_ISR ( ( BaseType_t ) 6 )
fep 0:62cd296ba2a7 107 #define tmrCOMMAND_RESET_FROM_ISR ( ( BaseType_t ) 7 )
fep 0:62cd296ba2a7 108 #define tmrCOMMAND_STOP_FROM_ISR ( ( BaseType_t ) 8 )
fep 0:62cd296ba2a7 109 #define tmrCOMMAND_CHANGE_PERIOD_FROM_ISR ( ( BaseType_t ) 9 )
fep 0:62cd296ba2a7 110
fep 0:62cd296ba2a7 111
fep 0:62cd296ba2a7 112 /**
fep 0:62cd296ba2a7 113 * Type by which software timers are referenced. For example, a call to
fep 0:62cd296ba2a7 114 * xTimerCreate() returns an TimerHandle_t variable that can then be used to
fep 0:62cd296ba2a7 115 * reference the subject timer in calls to other software timer API functions
fep 0:62cd296ba2a7 116 * (for example, xTimerStart(), xTimerReset(), etc.).
fep 0:62cd296ba2a7 117 */
fep 0:62cd296ba2a7 118 typedef void * TimerHandle_t;
fep 0:62cd296ba2a7 119
fep 0:62cd296ba2a7 120 /*
fep 0:62cd296ba2a7 121 * Defines the prototype to which timer callback functions must conform.
fep 0:62cd296ba2a7 122 */
fep 0:62cd296ba2a7 123 typedef void (*TimerCallbackFunction_t)( TimerHandle_t xTimer );
fep 0:62cd296ba2a7 124
fep 0:62cd296ba2a7 125 /*
fep 0:62cd296ba2a7 126 * Defines the prototype to which functions used with the
fep 0:62cd296ba2a7 127 * xTimerPendFunctionCallFromISR() function must conform.
fep 0:62cd296ba2a7 128 */
fep 0:62cd296ba2a7 129 typedef void (*PendedFunction_t)( void *, uint32_t );
fep 0:62cd296ba2a7 130
fep 0:62cd296ba2a7 131 /**
fep 0:62cd296ba2a7 132 * TimerHandle_t xTimerCreate( const char * const pcTimerName,
fep 0:62cd296ba2a7 133 * TickType_t xTimerPeriodInTicks,
fep 0:62cd296ba2a7 134 * UBaseType_t uxAutoReload,
fep 0:62cd296ba2a7 135 * void * pvTimerID,
fep 0:62cd296ba2a7 136 * TimerCallbackFunction_t pxCallbackFunction );
fep 0:62cd296ba2a7 137 *
fep 0:62cd296ba2a7 138 * Creates a new software timer instance, and returns a handle by which the
fep 0:62cd296ba2a7 139 * created software timer can be referenced.
fep 0:62cd296ba2a7 140 *
fep 0:62cd296ba2a7 141 * Internally, within the FreeRTOS implementation, software timers use a block
fep 0:62cd296ba2a7 142 * of memory, in which the timer data structure is stored. If a software timer
fep 0:62cd296ba2a7 143 * is created using xTimerCreate() then the required memory is automatically
fep 0:62cd296ba2a7 144 * dynamically allocated inside the xTimerCreate() function. (see
fep 0:62cd296ba2a7 145 * http://www.freertos.org/a00111.html). If a software timer is created using
fep 0:62cd296ba2a7 146 * xTimerCreateStatic() then the application writer must provide the memory that
fep 0:62cd296ba2a7 147 * will get used by the software timer. xTimerCreateStatic() therefore allows a
fep 0:62cd296ba2a7 148 * software timer to be created without using any dynamic memory allocation.
fep 0:62cd296ba2a7 149 *
fep 0:62cd296ba2a7 150 * Timers are created in the dormant state. The xTimerStart(), xTimerReset(),
fep 0:62cd296ba2a7 151 * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and
fep 0:62cd296ba2a7 152 * xTimerChangePeriodFromISR() API functions can all be used to transition a
fep 0:62cd296ba2a7 153 * timer into the active state.
fep 0:62cd296ba2a7 154 *
fep 0:62cd296ba2a7 155 * @param pcTimerName A text name that is assigned to the timer. This is done
fep 0:62cd296ba2a7 156 * purely to assist debugging. The kernel itself only ever references a timer
fep 0:62cd296ba2a7 157 * by its handle, and never by its name.
fep 0:62cd296ba2a7 158 *
fep 0:62cd296ba2a7 159 * @param xTimerPeriodInTicks The timer period. The time is defined in tick
fep 0:62cd296ba2a7 160 * periods so the constant portTICK_PERIOD_MS can be used to convert a time that
fep 0:62cd296ba2a7 161 * has been specified in milliseconds. For example, if the timer must expire
fep 0:62cd296ba2a7 162 * after 100 ticks, then xTimerPeriodInTicks should be set to 100.
fep 0:62cd296ba2a7 163 * Alternatively, if the timer must expire after 500ms, then xPeriod can be set
fep 0:62cd296ba2a7 164 * to ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or
fep 0:62cd296ba2a7 165 * equal to 1000.
fep 0:62cd296ba2a7 166 *
fep 0:62cd296ba2a7 167 * @param uxAutoReload If uxAutoReload is set to pdTRUE then the timer will
fep 0:62cd296ba2a7 168 * expire repeatedly with a frequency set by the xTimerPeriodInTicks parameter.
fep 0:62cd296ba2a7 169 * If uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and
fep 0:62cd296ba2a7 170 * enter the dormant state after it expires.
fep 0:62cd296ba2a7 171 *
fep 0:62cd296ba2a7 172 * @param pvTimerID An identifier that is assigned to the timer being created.
fep 0:62cd296ba2a7 173 * Typically this would be used in the timer callback function to identify which
fep 0:62cd296ba2a7 174 * timer expired when the same callback function is assigned to more than one
fep 0:62cd296ba2a7 175 * timer.
fep 0:62cd296ba2a7 176 *
fep 0:62cd296ba2a7 177 * @param pxCallbackFunction The function to call when the timer expires.
fep 0:62cd296ba2a7 178 * Callback functions must have the prototype defined by TimerCallbackFunction_t,
fep 0:62cd296ba2a7 179 * which is "void vCallbackFunction( TimerHandle_t xTimer );".
fep 0:62cd296ba2a7 180 *
fep 0:62cd296ba2a7 181 * @return If the timer is successfully created then a handle to the newly
fep 0:62cd296ba2a7 182 * created timer is returned. If the timer cannot be created (because either
fep 0:62cd296ba2a7 183 * there is insufficient FreeRTOS heap remaining to allocate the timer
fep 0:62cd296ba2a7 184 * structures, or the timer period was set to 0) then NULL is returned.
fep 0:62cd296ba2a7 185 *
fep 0:62cd296ba2a7 186 * Example usage:
fep 0:62cd296ba2a7 187 * @verbatim
fep 0:62cd296ba2a7 188 * #define NUM_TIMERS 5
fep 0:62cd296ba2a7 189 *
fep 0:62cd296ba2a7 190 * // An array to hold handles to the created timers.
fep 0:62cd296ba2a7 191 * TimerHandle_t xTimers[ NUM_TIMERS ];
fep 0:62cd296ba2a7 192 *
fep 0:62cd296ba2a7 193 * // An array to hold a count of the number of times each timer expires.
fep 0:62cd296ba2a7 194 * int32_t lExpireCounters[ NUM_TIMERS ] = { 0 };
fep 0:62cd296ba2a7 195 *
fep 0:62cd296ba2a7 196 * // Define a callback function that will be used by multiple timer instances.
fep 0:62cd296ba2a7 197 * // The callback function does nothing but count the number of times the
fep 0:62cd296ba2a7 198 * // associated timer expires, and stop the timer once the timer has expired
fep 0:62cd296ba2a7 199 * // 10 times.
fep 0:62cd296ba2a7 200 * void vTimerCallback( TimerHandle_t pxTimer )
fep 0:62cd296ba2a7 201 * {
fep 0:62cd296ba2a7 202 * int32_t lArrayIndex;
fep 0:62cd296ba2a7 203 * const int32_t xMaxExpiryCountBeforeStopping = 10;
fep 0:62cd296ba2a7 204 *
fep 0:62cd296ba2a7 205 * // Optionally do something if the pxTimer parameter is NULL.
fep 0:62cd296ba2a7 206 * configASSERT( pxTimer );
fep 0:62cd296ba2a7 207 *
fep 0:62cd296ba2a7 208 * // Which timer expired?
fep 0:62cd296ba2a7 209 * lArrayIndex = ( int32_t ) pvTimerGetTimerID( pxTimer );
fep 0:62cd296ba2a7 210 *
fep 0:62cd296ba2a7 211 * // Increment the number of times that pxTimer has expired.
fep 0:62cd296ba2a7 212 * lExpireCounters[ lArrayIndex ] += 1;
fep 0:62cd296ba2a7 213 *
fep 0:62cd296ba2a7 214 * // If the timer has expired 10 times then stop it from running.
fep 0:62cd296ba2a7 215 * if( lExpireCounters[ lArrayIndex ] == xMaxExpiryCountBeforeStopping )
fep 0:62cd296ba2a7 216 * {
fep 0:62cd296ba2a7 217 * // Do not use a block time if calling a timer API function from a
fep 0:62cd296ba2a7 218 * // timer callback function, as doing so could cause a deadlock!
fep 0:62cd296ba2a7 219 * xTimerStop( pxTimer, 0 );
fep 0:62cd296ba2a7 220 * }
fep 0:62cd296ba2a7 221 * }
fep 0:62cd296ba2a7 222 *
fep 0:62cd296ba2a7 223 * void main( void )
fep 0:62cd296ba2a7 224 * {
fep 0:62cd296ba2a7 225 * int32_t x;
fep 0:62cd296ba2a7 226 *
fep 0:62cd296ba2a7 227 * // Create then start some timers. Starting the timers before the scheduler
fep 0:62cd296ba2a7 228 * // has been started means the timers will start running immediately that
fep 0:62cd296ba2a7 229 * // the scheduler starts.
fep 0:62cd296ba2a7 230 * for( x = 0; x < NUM_TIMERS; x++ )
fep 0:62cd296ba2a7 231 * {
fep 0:62cd296ba2a7 232 * xTimers[ x ] = xTimerCreate( "Timer", // Just a text name, not used by the kernel.
fep 0:62cd296ba2a7 233 * ( 100 * x ), // The timer period in ticks.
fep 0:62cd296ba2a7 234 * pdTRUE, // The timers will auto-reload themselves when they expire.
fep 0:62cd296ba2a7 235 * ( void * ) x, // Assign each timer a unique id equal to its array index.
fep 0:62cd296ba2a7 236 * vTimerCallback // Each timer calls the same callback when it expires.
fep 0:62cd296ba2a7 237 * );
fep 0:62cd296ba2a7 238 *
fep 0:62cd296ba2a7 239 * if( xTimers[ x ] == NULL )
fep 0:62cd296ba2a7 240 * {
fep 0:62cd296ba2a7 241 * // The timer was not created.
fep 0:62cd296ba2a7 242 * }
fep 0:62cd296ba2a7 243 * else
fep 0:62cd296ba2a7 244 * {
fep 0:62cd296ba2a7 245 * // Start the timer. No block time is specified, and even if one was
fep 0:62cd296ba2a7 246 * // it would be ignored because the scheduler has not yet been
fep 0:62cd296ba2a7 247 * // started.
fep 0:62cd296ba2a7 248 * if( xTimerStart( xTimers[ x ], 0 ) != pdPASS )
fep 0:62cd296ba2a7 249 * {
fep 0:62cd296ba2a7 250 * // The timer could not be set into the Active state.
fep 0:62cd296ba2a7 251 * }
fep 0:62cd296ba2a7 252 * }
fep 0:62cd296ba2a7 253 * }
fep 0:62cd296ba2a7 254 *
fep 0:62cd296ba2a7 255 * // ...
fep 0:62cd296ba2a7 256 * // Create tasks here.
fep 0:62cd296ba2a7 257 * // ...
fep 0:62cd296ba2a7 258 *
fep 0:62cd296ba2a7 259 * // Starting the scheduler will start the timers running as they have already
fep 0:62cd296ba2a7 260 * // been set into the active state.
fep 0:62cd296ba2a7 261 * vTaskStartScheduler();
fep 0:62cd296ba2a7 262 *
fep 0:62cd296ba2a7 263 * // Should not reach here.
fep 0:62cd296ba2a7 264 * for( ;; );
fep 0:62cd296ba2a7 265 * }
fep 0:62cd296ba2a7 266 * @endverbatim
fep 0:62cd296ba2a7 267 */
fep 0:62cd296ba2a7 268 #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
fep 0:62cd296ba2a7 269 TimerHandle_t xTimerCreate( const char * const pcTimerName,
fep 0:62cd296ba2a7 270 const TickType_t xTimerPeriodInTicks,
fep 0:62cd296ba2a7 271 const UBaseType_t uxAutoReload,
fep 0:62cd296ba2a7 272 void * const pvTimerID,
fep 0:62cd296ba2a7 273 TimerCallbackFunction_t pxCallbackFunction ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
fep 0:62cd296ba2a7 274 #endif
fep 0:62cd296ba2a7 275
fep 0:62cd296ba2a7 276 /**
fep 0:62cd296ba2a7 277 * TimerHandle_t xTimerCreateStatic(const char * const pcTimerName,
fep 0:62cd296ba2a7 278 * TickType_t xTimerPeriodInTicks,
fep 0:62cd296ba2a7 279 * UBaseType_t uxAutoReload,
fep 0:62cd296ba2a7 280 * void * pvTimerID,
fep 0:62cd296ba2a7 281 * TimerCallbackFunction_t pxCallbackFunction,
fep 0:62cd296ba2a7 282 * StaticTimer_t *pxTimerBuffer );
fep 0:62cd296ba2a7 283 *
fep 0:62cd296ba2a7 284 * Creates a new software timer instance, and returns a handle by which the
fep 0:62cd296ba2a7 285 * created software timer can be referenced.
fep 0:62cd296ba2a7 286 *
fep 0:62cd296ba2a7 287 * Internally, within the FreeRTOS implementation, software timers use a block
fep 0:62cd296ba2a7 288 * of memory, in which the timer data structure is stored. If a software timer
fep 0:62cd296ba2a7 289 * is created using xTimerCreate() then the required memory is automatically
fep 0:62cd296ba2a7 290 * dynamically allocated inside the xTimerCreate() function. (see
fep 0:62cd296ba2a7 291 * http://www.freertos.org/a00111.html). If a software timer is created using
fep 0:62cd296ba2a7 292 * xTimerCreateStatic() then the application writer must provide the memory that
fep 0:62cd296ba2a7 293 * will get used by the software timer. xTimerCreateStatic() therefore allows a
fep 0:62cd296ba2a7 294 * software timer to be created without using any dynamic memory allocation.
fep 0:62cd296ba2a7 295 *
fep 0:62cd296ba2a7 296 * Timers are created in the dormant state. The xTimerStart(), xTimerReset(),
fep 0:62cd296ba2a7 297 * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and
fep 0:62cd296ba2a7 298 * xTimerChangePeriodFromISR() API functions can all be used to transition a
fep 0:62cd296ba2a7 299 * timer into the active state.
fep 0:62cd296ba2a7 300 *
fep 0:62cd296ba2a7 301 * @param pcTimerName A text name that is assigned to the timer. This is done
fep 0:62cd296ba2a7 302 * purely to assist debugging. The kernel itself only ever references a timer
fep 0:62cd296ba2a7 303 * by its handle, and never by its name.
fep 0:62cd296ba2a7 304 *
fep 0:62cd296ba2a7 305 * @param xTimerPeriodInTicks The timer period. The time is defined in tick
fep 0:62cd296ba2a7 306 * periods so the constant portTICK_PERIOD_MS can be used to convert a time that
fep 0:62cd296ba2a7 307 * has been specified in milliseconds. For example, if the timer must expire
fep 0:62cd296ba2a7 308 * after 100 ticks, then xTimerPeriodInTicks should be set to 100.
fep 0:62cd296ba2a7 309 * Alternatively, if the timer must expire after 500ms, then xPeriod can be set
fep 0:62cd296ba2a7 310 * to ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than or
fep 0:62cd296ba2a7 311 * equal to 1000.
fep 0:62cd296ba2a7 312 *
fep 0:62cd296ba2a7 313 * @param uxAutoReload If uxAutoReload is set to pdTRUE then the timer will
fep 0:62cd296ba2a7 314 * expire repeatedly with a frequency set by the xTimerPeriodInTicks parameter.
fep 0:62cd296ba2a7 315 * If uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and
fep 0:62cd296ba2a7 316 * enter the dormant state after it expires.
fep 0:62cd296ba2a7 317 *
fep 0:62cd296ba2a7 318 * @param pvTimerID An identifier that is assigned to the timer being created.
fep 0:62cd296ba2a7 319 * Typically this would be used in the timer callback function to identify which
fep 0:62cd296ba2a7 320 * timer expired when the same callback function is assigned to more than one
fep 0:62cd296ba2a7 321 * timer.
fep 0:62cd296ba2a7 322 *
fep 0:62cd296ba2a7 323 * @param pxCallbackFunction The function to call when the timer expires.
fep 0:62cd296ba2a7 324 * Callback functions must have the prototype defined by TimerCallbackFunction_t,
fep 0:62cd296ba2a7 325 * which is "void vCallbackFunction( TimerHandle_t xTimer );".
fep 0:62cd296ba2a7 326 *
fep 0:62cd296ba2a7 327 * @param pxTimerBuffer Must point to a variable of type StaticTimer_t, which
fep 0:62cd296ba2a7 328 * will be then be used to hold the software timer's data structures, removing
fep 0:62cd296ba2a7 329 * the need for the memory to be allocated dynamically.
fep 0:62cd296ba2a7 330 *
fep 0:62cd296ba2a7 331 * @return If the timer is created then a handle to the created timer is
fep 0:62cd296ba2a7 332 * returned. If pxTimerBuffer was NULL then NULL is returned.
fep 0:62cd296ba2a7 333 *
fep 0:62cd296ba2a7 334 * Example usage:
fep 0:62cd296ba2a7 335 * @verbatim
fep 0:62cd296ba2a7 336 *
fep 0:62cd296ba2a7 337 * // The buffer used to hold the software timer's data structure.
fep 0:62cd296ba2a7 338 * static StaticTimer_t xTimerBuffer;
fep 0:62cd296ba2a7 339 *
fep 0:62cd296ba2a7 340 * // A variable that will be incremented by the software timer's callback
fep 0:62cd296ba2a7 341 * // function.
fep 0:62cd296ba2a7 342 * UBaseType_t uxVariableToIncrement = 0;
fep 0:62cd296ba2a7 343 *
fep 0:62cd296ba2a7 344 * // A software timer callback function that increments a variable passed to
fep 0:62cd296ba2a7 345 * // it when the software timer was created. After the 5th increment the
fep 0:62cd296ba2a7 346 * // callback function stops the software timer.
fep 0:62cd296ba2a7 347 * static void prvTimerCallback( TimerHandle_t xExpiredTimer )
fep 0:62cd296ba2a7 348 * {
fep 0:62cd296ba2a7 349 * UBaseType_t *puxVariableToIncrement;
fep 0:62cd296ba2a7 350 * BaseType_t xReturned;
fep 0:62cd296ba2a7 351 *
fep 0:62cd296ba2a7 352 * // Obtain the address of the variable to increment from the timer ID.
fep 0:62cd296ba2a7 353 * puxVariableToIncrement = ( UBaseType_t * ) pvTimerGetTimerID( xExpiredTimer );
fep 0:62cd296ba2a7 354 *
fep 0:62cd296ba2a7 355 * // Increment the variable to show the timer callback has executed.
fep 0:62cd296ba2a7 356 * ( *puxVariableToIncrement )++;
fep 0:62cd296ba2a7 357 *
fep 0:62cd296ba2a7 358 * // If this callback has executed the required number of times, stop the
fep 0:62cd296ba2a7 359 * // timer.
fep 0:62cd296ba2a7 360 * if( *puxVariableToIncrement == 5 )
fep 0:62cd296ba2a7 361 * {
fep 0:62cd296ba2a7 362 * // This is called from a timer callback so must not block.
fep 0:62cd296ba2a7 363 * xTimerStop( xExpiredTimer, staticDONT_BLOCK );
fep 0:62cd296ba2a7 364 * }
fep 0:62cd296ba2a7 365 * }
fep 0:62cd296ba2a7 366 *
fep 0:62cd296ba2a7 367 *
fep 0:62cd296ba2a7 368 * void main( void )
fep 0:62cd296ba2a7 369 * {
fep 0:62cd296ba2a7 370 * // Create the software time. xTimerCreateStatic() has an extra parameter
fep 0:62cd296ba2a7 371 * // than the normal xTimerCreate() API function. The parameter is a pointer
fep 0:62cd296ba2a7 372 * // to the StaticTimer_t structure that will hold the software timer
fep 0:62cd296ba2a7 373 * // structure. If the parameter is passed as NULL then the structure will be
fep 0:62cd296ba2a7 374 * // allocated dynamically, just as if xTimerCreate() had been called.
fep 0:62cd296ba2a7 375 * xTimer = xTimerCreateStatic( "T1", // Text name for the task. Helps debugging only. Not used by FreeRTOS.
fep 0:62cd296ba2a7 376 * xTimerPeriod, // The period of the timer in ticks.
fep 0:62cd296ba2a7 377 * pdTRUE, // This is an auto-reload timer.
fep 0:62cd296ba2a7 378 * ( void * ) &uxVariableToIncrement, // A variable incremented by the software timer's callback function
fep 0:62cd296ba2a7 379 * prvTimerCallback, // The function to execute when the timer expires.
fep 0:62cd296ba2a7 380 * &xTimerBuffer ); // The buffer that will hold the software timer structure.
fep 0:62cd296ba2a7 381 *
fep 0:62cd296ba2a7 382 * // The scheduler has not started yet so a block time is not used.
fep 0:62cd296ba2a7 383 * xReturned = xTimerStart( xTimer, 0 );
fep 0:62cd296ba2a7 384 *
fep 0:62cd296ba2a7 385 * // ...
fep 0:62cd296ba2a7 386 * // Create tasks here.
fep 0:62cd296ba2a7 387 * // ...
fep 0:62cd296ba2a7 388 *
fep 0:62cd296ba2a7 389 * // Starting the scheduler will start the timers running as they have already
fep 0:62cd296ba2a7 390 * // been set into the active state.
fep 0:62cd296ba2a7 391 * vTaskStartScheduler();
fep 0:62cd296ba2a7 392 *
fep 0:62cd296ba2a7 393 * // Should not reach here.
fep 0:62cd296ba2a7 394 * for( ;; );
fep 0:62cd296ba2a7 395 * }
fep 0:62cd296ba2a7 396 * @endverbatim
fep 0:62cd296ba2a7 397 */
fep 0:62cd296ba2a7 398 #if( configSUPPORT_STATIC_ALLOCATION == 1 )
fep 0:62cd296ba2a7 399 TimerHandle_t xTimerCreateStatic( const char * const pcTimerName,
fep 0:62cd296ba2a7 400 const TickType_t xTimerPeriodInTicks,
fep 0:62cd296ba2a7 401 const UBaseType_t uxAutoReload,
fep 0:62cd296ba2a7 402 void * const pvTimerID,
fep 0:62cd296ba2a7 403 TimerCallbackFunction_t pxCallbackFunction,
fep 0:62cd296ba2a7 404 StaticTimer_t *pxTimerBuffer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
fep 0:62cd296ba2a7 405 #endif /* configSUPPORT_STATIC_ALLOCATION */
fep 0:62cd296ba2a7 406
fep 0:62cd296ba2a7 407 /**
fep 0:62cd296ba2a7 408 * void *pvTimerGetTimerID( TimerHandle_t xTimer );
fep 0:62cd296ba2a7 409 *
fep 0:62cd296ba2a7 410 * Returns the ID assigned to the timer.
fep 0:62cd296ba2a7 411 *
fep 0:62cd296ba2a7 412 * IDs are assigned to timers using the pvTimerID parameter of the call to
fep 0:62cd296ba2a7 413 * xTimerCreated() that was used to create the timer, and by calling the
fep 0:62cd296ba2a7 414 * vTimerSetTimerID() API function.
fep 0:62cd296ba2a7 415 *
fep 0:62cd296ba2a7 416 * If the same callback function is assigned to multiple timers then the timer
fep 0:62cd296ba2a7 417 * ID can be used as time specific (timer local) storage.
fep 0:62cd296ba2a7 418 *
fep 0:62cd296ba2a7 419 * @param xTimer The timer being queried.
fep 0:62cd296ba2a7 420 *
fep 0:62cd296ba2a7 421 * @return The ID assigned to the timer being queried.
fep 0:62cd296ba2a7 422 *
fep 0:62cd296ba2a7 423 * Example usage:
fep 0:62cd296ba2a7 424 *
fep 0:62cd296ba2a7 425 * See the xTimerCreate() API function example usage scenario.
fep 0:62cd296ba2a7 426 */
fep 0:62cd296ba2a7 427 void *pvTimerGetTimerID( const TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 428
fep 0:62cd296ba2a7 429 /**
fep 0:62cd296ba2a7 430 * void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID );
fep 0:62cd296ba2a7 431 *
fep 0:62cd296ba2a7 432 * Sets the ID assigned to the timer.
fep 0:62cd296ba2a7 433 *
fep 0:62cd296ba2a7 434 * IDs are assigned to timers using the pvTimerID parameter of the call to
fep 0:62cd296ba2a7 435 * xTimerCreated() that was used to create the timer.
fep 0:62cd296ba2a7 436 *
fep 0:62cd296ba2a7 437 * If the same callback function is assigned to multiple timers then the timer
fep 0:62cd296ba2a7 438 * ID can be used as time specific (timer local) storage.
fep 0:62cd296ba2a7 439 *
fep 0:62cd296ba2a7 440 * @param xTimer The timer being updated.
fep 0:62cd296ba2a7 441 *
fep 0:62cd296ba2a7 442 * @param pvNewID The ID to assign to the timer.
fep 0:62cd296ba2a7 443 *
fep 0:62cd296ba2a7 444 * Example usage:
fep 0:62cd296ba2a7 445 *
fep 0:62cd296ba2a7 446 * See the xTimerCreate() API function example usage scenario.
fep 0:62cd296ba2a7 447 */
fep 0:62cd296ba2a7 448 void vTimerSetTimerID( TimerHandle_t xTimer, void *pvNewID ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 449
fep 0:62cd296ba2a7 450 /**
fep 0:62cd296ba2a7 451 * BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer );
fep 0:62cd296ba2a7 452 *
fep 0:62cd296ba2a7 453 * Queries a timer to see if it is active or dormant.
fep 0:62cd296ba2a7 454 *
fep 0:62cd296ba2a7 455 * A timer will be dormant if:
fep 0:62cd296ba2a7 456 * 1) It has been created but not started, or
fep 0:62cd296ba2a7 457 * 2) It is an expired one-shot timer that has not been restarted.
fep 0:62cd296ba2a7 458 *
fep 0:62cd296ba2a7 459 * Timers are created in the dormant state. The xTimerStart(), xTimerReset(),
fep 0:62cd296ba2a7 460 * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and
fep 0:62cd296ba2a7 461 * xTimerChangePeriodFromISR() API functions can all be used to transition a timer into the
fep 0:62cd296ba2a7 462 * active state.
fep 0:62cd296ba2a7 463 *
fep 0:62cd296ba2a7 464 * @param xTimer The timer being queried.
fep 0:62cd296ba2a7 465 *
fep 0:62cd296ba2a7 466 * @return pdFALSE will be returned if the timer is dormant. A value other than
fep 0:62cd296ba2a7 467 * pdFALSE will be returned if the timer is active.
fep 0:62cd296ba2a7 468 *
fep 0:62cd296ba2a7 469 * Example usage:
fep 0:62cd296ba2a7 470 * @verbatim
fep 0:62cd296ba2a7 471 * // This function assumes xTimer has already been created.
fep 0:62cd296ba2a7 472 * void vAFunction( TimerHandle_t xTimer )
fep 0:62cd296ba2a7 473 * {
fep 0:62cd296ba2a7 474 * if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and equivalently "if( xTimerIsTimerActive( xTimer ) )"
fep 0:62cd296ba2a7 475 * {
fep 0:62cd296ba2a7 476 * // xTimer is active, do something.
fep 0:62cd296ba2a7 477 * }
fep 0:62cd296ba2a7 478 * else
fep 0:62cd296ba2a7 479 * {
fep 0:62cd296ba2a7 480 * // xTimer is not active, do something else.
fep 0:62cd296ba2a7 481 * }
fep 0:62cd296ba2a7 482 * }
fep 0:62cd296ba2a7 483 * @endverbatim
fep 0:62cd296ba2a7 484 */
fep 0:62cd296ba2a7 485 BaseType_t xTimerIsTimerActive( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 486
fep 0:62cd296ba2a7 487 /**
fep 0:62cd296ba2a7 488 * TaskHandle_t xTimerGetTimerDaemonTaskHandle( void );
fep 0:62cd296ba2a7 489 *
fep 0:62cd296ba2a7 490 * Simply returns the handle of the timer service/daemon task. It it not valid
fep 0:62cd296ba2a7 491 * to call xTimerGetTimerDaemonTaskHandle() before the scheduler has been started.
fep 0:62cd296ba2a7 492 */
fep 0:62cd296ba2a7 493 TaskHandle_t xTimerGetTimerDaemonTaskHandle( void ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 494
fep 0:62cd296ba2a7 495 /**
fep 0:62cd296ba2a7 496 * BaseType_t xTimerStart( TimerHandle_t xTimer, TickType_t xTicksToWait );
fep 0:62cd296ba2a7 497 *
fep 0:62cd296ba2a7 498 * Timer functionality is provided by a timer service/daemon task. Many of the
fep 0:62cd296ba2a7 499 * public FreeRTOS timer API functions send commands to the timer service task
fep 0:62cd296ba2a7 500 * through a queue called the timer command queue. The timer command queue is
fep 0:62cd296ba2a7 501 * private to the kernel itself and is not directly accessible to application
fep 0:62cd296ba2a7 502 * code. The length of the timer command queue is set by the
fep 0:62cd296ba2a7 503 * configTIMER_QUEUE_LENGTH configuration constant.
fep 0:62cd296ba2a7 504 *
fep 0:62cd296ba2a7 505 * xTimerStart() starts a timer that was previously created using the
fep 0:62cd296ba2a7 506 * xTimerCreate() API function. If the timer had already been started and was
fep 0:62cd296ba2a7 507 * already in the active state, then xTimerStart() has equivalent functionality
fep 0:62cd296ba2a7 508 * to the xTimerReset() API function.
fep 0:62cd296ba2a7 509 *
fep 0:62cd296ba2a7 510 * Starting a timer ensures the timer is in the active state. If the timer
fep 0:62cd296ba2a7 511 * is not stopped, deleted, or reset in the mean time, the callback function
fep 0:62cd296ba2a7 512 * associated with the timer will get called 'n' ticks after xTimerStart() was
fep 0:62cd296ba2a7 513 * called, where 'n' is the timers defined period.
fep 0:62cd296ba2a7 514 *
fep 0:62cd296ba2a7 515 * It is valid to call xTimerStart() before the scheduler has been started, but
fep 0:62cd296ba2a7 516 * when this is done the timer will not actually start until the scheduler is
fep 0:62cd296ba2a7 517 * started, and the timers expiry time will be relative to when the scheduler is
fep 0:62cd296ba2a7 518 * started, not relative to when xTimerStart() was called.
fep 0:62cd296ba2a7 519 *
fep 0:62cd296ba2a7 520 * The configUSE_TIMERS configuration constant must be set to 1 for xTimerStart()
fep 0:62cd296ba2a7 521 * to be available.
fep 0:62cd296ba2a7 522 *
fep 0:62cd296ba2a7 523 * @param xTimer The handle of the timer being started/restarted.
fep 0:62cd296ba2a7 524 *
fep 0:62cd296ba2a7 525 * @param xTicksToWait Specifies the time, in ticks, that the calling task should
fep 0:62cd296ba2a7 526 * be held in the Blocked state to wait for the start command to be successfully
fep 0:62cd296ba2a7 527 * sent to the timer command queue, should the queue already be full when
fep 0:62cd296ba2a7 528 * xTimerStart() was called. xTicksToWait is ignored if xTimerStart() is called
fep 0:62cd296ba2a7 529 * before the scheduler is started.
fep 0:62cd296ba2a7 530 *
fep 0:62cd296ba2a7 531 * @return pdFAIL will be returned if the start command could not be sent to
fep 0:62cd296ba2a7 532 * the timer command queue even after xTicksToWait ticks had passed. pdPASS will
fep 0:62cd296ba2a7 533 * be returned if the command was successfully sent to the timer command queue.
fep 0:62cd296ba2a7 534 * When the command is actually processed will depend on the priority of the
fep 0:62cd296ba2a7 535 * timer service/daemon task relative to other tasks in the system, although the
fep 0:62cd296ba2a7 536 * timers expiry time is relative to when xTimerStart() is actually called. The
fep 0:62cd296ba2a7 537 * timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY
fep 0:62cd296ba2a7 538 * configuration constant.
fep 0:62cd296ba2a7 539 *
fep 0:62cd296ba2a7 540 * Example usage:
fep 0:62cd296ba2a7 541 *
fep 0:62cd296ba2a7 542 * See the xTimerCreate() API function example usage scenario.
fep 0:62cd296ba2a7 543 *
fep 0:62cd296ba2a7 544 */
fep 0:62cd296ba2a7 545 #define xTimerStart( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START, ( xTaskGetTickCount() ), NULL, ( xTicksToWait ) )
fep 0:62cd296ba2a7 546
fep 0:62cd296ba2a7 547 /**
fep 0:62cd296ba2a7 548 * BaseType_t xTimerStop( TimerHandle_t xTimer, TickType_t xTicksToWait );
fep 0:62cd296ba2a7 549 *
fep 0:62cd296ba2a7 550 * Timer functionality is provided by a timer service/daemon task. Many of the
fep 0:62cd296ba2a7 551 * public FreeRTOS timer API functions send commands to the timer service task
fep 0:62cd296ba2a7 552 * through a queue called the timer command queue. The timer command queue is
fep 0:62cd296ba2a7 553 * private to the kernel itself and is not directly accessible to application
fep 0:62cd296ba2a7 554 * code. The length of the timer command queue is set by the
fep 0:62cd296ba2a7 555 * configTIMER_QUEUE_LENGTH configuration constant.
fep 0:62cd296ba2a7 556 *
fep 0:62cd296ba2a7 557 * xTimerStop() stops a timer that was previously started using either of the
fep 0:62cd296ba2a7 558 * The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimerResetFromISR(),
fep 0:62cd296ba2a7 559 * xTimerChangePeriod() or xTimerChangePeriodFromISR() API functions.
fep 0:62cd296ba2a7 560 *
fep 0:62cd296ba2a7 561 * Stopping a timer ensures the timer is not in the active state.
fep 0:62cd296ba2a7 562 *
fep 0:62cd296ba2a7 563 * The configUSE_TIMERS configuration constant must be set to 1 for xTimerStop()
fep 0:62cd296ba2a7 564 * to be available.
fep 0:62cd296ba2a7 565 *
fep 0:62cd296ba2a7 566 * @param xTimer The handle of the timer being stopped.
fep 0:62cd296ba2a7 567 *
fep 0:62cd296ba2a7 568 * @param xTicksToWait Specifies the time, in ticks, that the calling task should
fep 0:62cd296ba2a7 569 * be held in the Blocked state to wait for the stop command to be successfully
fep 0:62cd296ba2a7 570 * sent to the timer command queue, should the queue already be full when
fep 0:62cd296ba2a7 571 * xTimerStop() was called. xTicksToWait is ignored if xTimerStop() is called
fep 0:62cd296ba2a7 572 * before the scheduler is started.
fep 0:62cd296ba2a7 573 *
fep 0:62cd296ba2a7 574 * @return pdFAIL will be returned if the stop command could not be sent to
fep 0:62cd296ba2a7 575 * the timer command queue even after xTicksToWait ticks had passed. pdPASS will
fep 0:62cd296ba2a7 576 * be returned if the command was successfully sent to the timer command queue.
fep 0:62cd296ba2a7 577 * When the command is actually processed will depend on the priority of the
fep 0:62cd296ba2a7 578 * timer service/daemon task relative to other tasks in the system. The timer
fep 0:62cd296ba2a7 579 * service/daemon task priority is set by the configTIMER_TASK_PRIORITY
fep 0:62cd296ba2a7 580 * configuration constant.
fep 0:62cd296ba2a7 581 *
fep 0:62cd296ba2a7 582 * Example usage:
fep 0:62cd296ba2a7 583 *
fep 0:62cd296ba2a7 584 * See the xTimerCreate() API function example usage scenario.
fep 0:62cd296ba2a7 585 *
fep 0:62cd296ba2a7 586 */
fep 0:62cd296ba2a7 587 #define xTimerStop( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP, 0U, NULL, ( xTicksToWait ) )
fep 0:62cd296ba2a7 588
fep 0:62cd296ba2a7 589 /**
fep 0:62cd296ba2a7 590 * BaseType_t xTimerChangePeriod( TimerHandle_t xTimer,
fep 0:62cd296ba2a7 591 * TickType_t xNewPeriod,
fep 0:62cd296ba2a7 592 * TickType_t xTicksToWait );
fep 0:62cd296ba2a7 593 *
fep 0:62cd296ba2a7 594 * Timer functionality is provided by a timer service/daemon task. Many of the
fep 0:62cd296ba2a7 595 * public FreeRTOS timer API functions send commands to the timer service task
fep 0:62cd296ba2a7 596 * through a queue called the timer command queue. The timer command queue is
fep 0:62cd296ba2a7 597 * private to the kernel itself and is not directly accessible to application
fep 0:62cd296ba2a7 598 * code. The length of the timer command queue is set by the
fep 0:62cd296ba2a7 599 * configTIMER_QUEUE_LENGTH configuration constant.
fep 0:62cd296ba2a7 600 *
fep 0:62cd296ba2a7 601 * xTimerChangePeriod() changes the period of a timer that was previously
fep 0:62cd296ba2a7 602 * created using the xTimerCreate() API function.
fep 0:62cd296ba2a7 603 *
fep 0:62cd296ba2a7 604 * xTimerChangePeriod() can be called to change the period of an active or
fep 0:62cd296ba2a7 605 * dormant state timer.
fep 0:62cd296ba2a7 606 *
fep 0:62cd296ba2a7 607 * The configUSE_TIMERS configuration constant must be set to 1 for
fep 0:62cd296ba2a7 608 * xTimerChangePeriod() to be available.
fep 0:62cd296ba2a7 609 *
fep 0:62cd296ba2a7 610 * @param xTimer The handle of the timer that is having its period changed.
fep 0:62cd296ba2a7 611 *
fep 0:62cd296ba2a7 612 * @param xNewPeriod The new period for xTimer. Timer periods are specified in
fep 0:62cd296ba2a7 613 * tick periods, so the constant portTICK_PERIOD_MS can be used to convert a time
fep 0:62cd296ba2a7 614 * that has been specified in milliseconds. For example, if the timer must
fep 0:62cd296ba2a7 615 * expire after 100 ticks, then xNewPeriod should be set to 100. Alternatively,
fep 0:62cd296ba2a7 616 * if the timer must expire after 500ms, then xNewPeriod can be set to
fep 0:62cd296ba2a7 617 * ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than
fep 0:62cd296ba2a7 618 * or equal to 1000.
fep 0:62cd296ba2a7 619 *
fep 0:62cd296ba2a7 620 * @param xTicksToWait Specifies the time, in ticks, that the calling task should
fep 0:62cd296ba2a7 621 * be held in the Blocked state to wait for the change period command to be
fep 0:62cd296ba2a7 622 * successfully sent to the timer command queue, should the queue already be
fep 0:62cd296ba2a7 623 * full when xTimerChangePeriod() was called. xTicksToWait is ignored if
fep 0:62cd296ba2a7 624 * xTimerChangePeriod() is called before the scheduler is started.
fep 0:62cd296ba2a7 625 *
fep 0:62cd296ba2a7 626 * @return pdFAIL will be returned if the change period command could not be
fep 0:62cd296ba2a7 627 * sent to the timer command queue even after xTicksToWait ticks had passed.
fep 0:62cd296ba2a7 628 * pdPASS will be returned if the command was successfully sent to the timer
fep 0:62cd296ba2a7 629 * command queue. When the command is actually processed will depend on the
fep 0:62cd296ba2a7 630 * priority of the timer service/daemon task relative to other tasks in the
fep 0:62cd296ba2a7 631 * system. The timer service/daemon task priority is set by the
fep 0:62cd296ba2a7 632 * configTIMER_TASK_PRIORITY configuration constant.
fep 0:62cd296ba2a7 633 *
fep 0:62cd296ba2a7 634 * Example usage:
fep 0:62cd296ba2a7 635 * @verbatim
fep 0:62cd296ba2a7 636 * // This function assumes xTimer has already been created. If the timer
fep 0:62cd296ba2a7 637 * // referenced by xTimer is already active when it is called, then the timer
fep 0:62cd296ba2a7 638 * // is deleted. If the timer referenced by xTimer is not active when it is
fep 0:62cd296ba2a7 639 * // called, then the period of the timer is set to 500ms and the timer is
fep 0:62cd296ba2a7 640 * // started.
fep 0:62cd296ba2a7 641 * void vAFunction( TimerHandle_t xTimer )
fep 0:62cd296ba2a7 642 * {
fep 0:62cd296ba2a7 643 * if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and equivalently "if( xTimerIsTimerActive( xTimer ) )"
fep 0:62cd296ba2a7 644 * {
fep 0:62cd296ba2a7 645 * // xTimer is already active - delete it.
fep 0:62cd296ba2a7 646 * xTimerDelete( xTimer );
fep 0:62cd296ba2a7 647 * }
fep 0:62cd296ba2a7 648 * else
fep 0:62cd296ba2a7 649 * {
fep 0:62cd296ba2a7 650 * // xTimer is not active, change its period to 500ms. This will also
fep 0:62cd296ba2a7 651 * // cause the timer to start. Block for a maximum of 100 ticks if the
fep 0:62cd296ba2a7 652 * // change period command cannot immediately be sent to the timer
fep 0:62cd296ba2a7 653 * // command queue.
fep 0:62cd296ba2a7 654 * if( xTimerChangePeriod( xTimer, 500 / portTICK_PERIOD_MS, 100 ) == pdPASS )
fep 0:62cd296ba2a7 655 * {
fep 0:62cd296ba2a7 656 * // The command was successfully sent.
fep 0:62cd296ba2a7 657 * }
fep 0:62cd296ba2a7 658 * else
fep 0:62cd296ba2a7 659 * {
fep 0:62cd296ba2a7 660 * // The command could not be sent, even after waiting for 100 ticks
fep 0:62cd296ba2a7 661 * // to pass. Take appropriate action here.
fep 0:62cd296ba2a7 662 * }
fep 0:62cd296ba2a7 663 * }
fep 0:62cd296ba2a7 664 * }
fep 0:62cd296ba2a7 665 * @endverbatim
fep 0:62cd296ba2a7 666 */
fep 0:62cd296ba2a7 667 #define xTimerChangePeriod( xTimer, xNewPeriod, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD, ( xNewPeriod ), NULL, ( xTicksToWait ) )
fep 0:62cd296ba2a7 668
fep 0:62cd296ba2a7 669 /**
fep 0:62cd296ba2a7 670 * BaseType_t xTimerDelete( TimerHandle_t xTimer, TickType_t xTicksToWait );
fep 0:62cd296ba2a7 671 *
fep 0:62cd296ba2a7 672 * Timer functionality is provided by a timer service/daemon task. Many of the
fep 0:62cd296ba2a7 673 * public FreeRTOS timer API functions send commands to the timer service task
fep 0:62cd296ba2a7 674 * through a queue called the timer command queue. The timer command queue is
fep 0:62cd296ba2a7 675 * private to the kernel itself and is not directly accessible to application
fep 0:62cd296ba2a7 676 * code. The length of the timer command queue is set by the
fep 0:62cd296ba2a7 677 * configTIMER_QUEUE_LENGTH configuration constant.
fep 0:62cd296ba2a7 678 *
fep 0:62cd296ba2a7 679 * xTimerDelete() deletes a timer that was previously created using the
fep 0:62cd296ba2a7 680 * xTimerCreate() API function.
fep 0:62cd296ba2a7 681 *
fep 0:62cd296ba2a7 682 * The configUSE_TIMERS configuration constant must be set to 1 for
fep 0:62cd296ba2a7 683 * xTimerDelete() to be available.
fep 0:62cd296ba2a7 684 *
fep 0:62cd296ba2a7 685 * @param xTimer The handle of the timer being deleted.
fep 0:62cd296ba2a7 686 *
fep 0:62cd296ba2a7 687 * @param xTicksToWait Specifies the time, in ticks, that the calling task should
fep 0:62cd296ba2a7 688 * be held in the Blocked state to wait for the delete command to be
fep 0:62cd296ba2a7 689 * successfully sent to the timer command queue, should the queue already be
fep 0:62cd296ba2a7 690 * full when xTimerDelete() was called. xTicksToWait is ignored if xTimerDelete()
fep 0:62cd296ba2a7 691 * is called before the scheduler is started.
fep 0:62cd296ba2a7 692 *
fep 0:62cd296ba2a7 693 * @return pdFAIL will be returned if the delete command could not be sent to
fep 0:62cd296ba2a7 694 * the timer command queue even after xTicksToWait ticks had passed. pdPASS will
fep 0:62cd296ba2a7 695 * be returned if the command was successfully sent to the timer command queue.
fep 0:62cd296ba2a7 696 * When the command is actually processed will depend on the priority of the
fep 0:62cd296ba2a7 697 * timer service/daemon task relative to other tasks in the system. The timer
fep 0:62cd296ba2a7 698 * service/daemon task priority is set by the configTIMER_TASK_PRIORITY
fep 0:62cd296ba2a7 699 * configuration constant.
fep 0:62cd296ba2a7 700 *
fep 0:62cd296ba2a7 701 * Example usage:
fep 0:62cd296ba2a7 702 *
fep 0:62cd296ba2a7 703 * See the xTimerChangePeriod() API function example usage scenario.
fep 0:62cd296ba2a7 704 */
fep 0:62cd296ba2a7 705 #define xTimerDelete( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_DELETE, 0U, NULL, ( xTicksToWait ) )
fep 0:62cd296ba2a7 706
fep 0:62cd296ba2a7 707 /**
fep 0:62cd296ba2a7 708 * BaseType_t xTimerReset( TimerHandle_t xTimer, TickType_t xTicksToWait );
fep 0:62cd296ba2a7 709 *
fep 0:62cd296ba2a7 710 * Timer functionality is provided by a timer service/daemon task. Many of the
fep 0:62cd296ba2a7 711 * public FreeRTOS timer API functions send commands to the timer service task
fep 0:62cd296ba2a7 712 * through a queue called the timer command queue. The timer command queue is
fep 0:62cd296ba2a7 713 * private to the kernel itself and is not directly accessible to application
fep 0:62cd296ba2a7 714 * code. The length of the timer command queue is set by the
fep 0:62cd296ba2a7 715 * configTIMER_QUEUE_LENGTH configuration constant.
fep 0:62cd296ba2a7 716 *
fep 0:62cd296ba2a7 717 * xTimerReset() re-starts a timer that was previously created using the
fep 0:62cd296ba2a7 718 * xTimerCreate() API function. If the timer had already been started and was
fep 0:62cd296ba2a7 719 * already in the active state, then xTimerReset() will cause the timer to
fep 0:62cd296ba2a7 720 * re-evaluate its expiry time so that it is relative to when xTimerReset() was
fep 0:62cd296ba2a7 721 * called. If the timer was in the dormant state then xTimerReset() has
fep 0:62cd296ba2a7 722 * equivalent functionality to the xTimerStart() API function.
fep 0:62cd296ba2a7 723 *
fep 0:62cd296ba2a7 724 * Resetting a timer ensures the timer is in the active state. If the timer
fep 0:62cd296ba2a7 725 * is not stopped, deleted, or reset in the mean time, the callback function
fep 0:62cd296ba2a7 726 * associated with the timer will get called 'n' ticks after xTimerReset() was
fep 0:62cd296ba2a7 727 * called, where 'n' is the timers defined period.
fep 0:62cd296ba2a7 728 *
fep 0:62cd296ba2a7 729 * It is valid to call xTimerReset() before the scheduler has been started, but
fep 0:62cd296ba2a7 730 * when this is done the timer will not actually start until the scheduler is
fep 0:62cd296ba2a7 731 * started, and the timers expiry time will be relative to when the scheduler is
fep 0:62cd296ba2a7 732 * started, not relative to when xTimerReset() was called.
fep 0:62cd296ba2a7 733 *
fep 0:62cd296ba2a7 734 * The configUSE_TIMERS configuration constant must be set to 1 for xTimerReset()
fep 0:62cd296ba2a7 735 * to be available.
fep 0:62cd296ba2a7 736 *
fep 0:62cd296ba2a7 737 * @param xTimer The handle of the timer being reset/started/restarted.
fep 0:62cd296ba2a7 738 *
fep 0:62cd296ba2a7 739 * @param xTicksToWait Specifies the time, in ticks, that the calling task should
fep 0:62cd296ba2a7 740 * be held in the Blocked state to wait for the reset command to be successfully
fep 0:62cd296ba2a7 741 * sent to the timer command queue, should the queue already be full when
fep 0:62cd296ba2a7 742 * xTimerReset() was called. xTicksToWait is ignored if xTimerReset() is called
fep 0:62cd296ba2a7 743 * before the scheduler is started.
fep 0:62cd296ba2a7 744 *
fep 0:62cd296ba2a7 745 * @return pdFAIL will be returned if the reset command could not be sent to
fep 0:62cd296ba2a7 746 * the timer command queue even after xTicksToWait ticks had passed. pdPASS will
fep 0:62cd296ba2a7 747 * be returned if the command was successfully sent to the timer command queue.
fep 0:62cd296ba2a7 748 * When the command is actually processed will depend on the priority of the
fep 0:62cd296ba2a7 749 * timer service/daemon task relative to other tasks in the system, although the
fep 0:62cd296ba2a7 750 * timers expiry time is relative to when xTimerStart() is actually called. The
fep 0:62cd296ba2a7 751 * timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY
fep 0:62cd296ba2a7 752 * configuration constant.
fep 0:62cd296ba2a7 753 *
fep 0:62cd296ba2a7 754 * Example usage:
fep 0:62cd296ba2a7 755 * @verbatim
fep 0:62cd296ba2a7 756 * // When a key is pressed, an LCD back-light is switched on. If 5 seconds pass
fep 0:62cd296ba2a7 757 * // without a key being pressed, then the LCD back-light is switched off. In
fep 0:62cd296ba2a7 758 * // this case, the timer is a one-shot timer.
fep 0:62cd296ba2a7 759 *
fep 0:62cd296ba2a7 760 * TimerHandle_t xBacklightTimer = NULL;
fep 0:62cd296ba2a7 761 *
fep 0:62cd296ba2a7 762 * // The callback function assigned to the one-shot timer. In this case the
fep 0:62cd296ba2a7 763 * // parameter is not used.
fep 0:62cd296ba2a7 764 * void vBacklightTimerCallback( TimerHandle_t pxTimer )
fep 0:62cd296ba2a7 765 * {
fep 0:62cd296ba2a7 766 * // The timer expired, therefore 5 seconds must have passed since a key
fep 0:62cd296ba2a7 767 * // was pressed. Switch off the LCD back-light.
fep 0:62cd296ba2a7 768 * vSetBacklightState( BACKLIGHT_OFF );
fep 0:62cd296ba2a7 769 * }
fep 0:62cd296ba2a7 770 *
fep 0:62cd296ba2a7 771 * // The key press event handler.
fep 0:62cd296ba2a7 772 * void vKeyPressEventHandler( char cKey )
fep 0:62cd296ba2a7 773 * {
fep 0:62cd296ba2a7 774 * // Ensure the LCD back-light is on, then reset the timer that is
fep 0:62cd296ba2a7 775 * // responsible for turning the back-light off after 5 seconds of
fep 0:62cd296ba2a7 776 * // key inactivity. Wait 10 ticks for the command to be successfully sent
fep 0:62cd296ba2a7 777 * // if it cannot be sent immediately.
fep 0:62cd296ba2a7 778 * vSetBacklightState( BACKLIGHT_ON );
fep 0:62cd296ba2a7 779 * if( xTimerReset( xBacklightTimer, 100 ) != pdPASS )
fep 0:62cd296ba2a7 780 * {
fep 0:62cd296ba2a7 781 * // The reset command was not executed successfully. Take appropriate
fep 0:62cd296ba2a7 782 * // action here.
fep 0:62cd296ba2a7 783 * }
fep 0:62cd296ba2a7 784 *
fep 0:62cd296ba2a7 785 * // Perform the rest of the key processing here.
fep 0:62cd296ba2a7 786 * }
fep 0:62cd296ba2a7 787 *
fep 0:62cd296ba2a7 788 * void main( void )
fep 0:62cd296ba2a7 789 * {
fep 0:62cd296ba2a7 790 * int32_t x;
fep 0:62cd296ba2a7 791 *
fep 0:62cd296ba2a7 792 * // Create then start the one-shot timer that is responsible for turning
fep 0:62cd296ba2a7 793 * // the back-light off if no keys are pressed within a 5 second period.
fep 0:62cd296ba2a7 794 * xBacklightTimer = xTimerCreate( "BacklightTimer", // Just a text name, not used by the kernel.
fep 0:62cd296ba2a7 795 * ( 5000 / portTICK_PERIOD_MS), // The timer period in ticks.
fep 0:62cd296ba2a7 796 * pdFALSE, // The timer is a one-shot timer.
fep 0:62cd296ba2a7 797 * 0, // The id is not used by the callback so can take any value.
fep 0:62cd296ba2a7 798 * vBacklightTimerCallback // The callback function that switches the LCD back-light off.
fep 0:62cd296ba2a7 799 * );
fep 0:62cd296ba2a7 800 *
fep 0:62cd296ba2a7 801 * if( xBacklightTimer == NULL )
fep 0:62cd296ba2a7 802 * {
fep 0:62cd296ba2a7 803 * // The timer was not created.
fep 0:62cd296ba2a7 804 * }
fep 0:62cd296ba2a7 805 * else
fep 0:62cd296ba2a7 806 * {
fep 0:62cd296ba2a7 807 * // Start the timer. No block time is specified, and even if one was
fep 0:62cd296ba2a7 808 * // it would be ignored because the scheduler has not yet been
fep 0:62cd296ba2a7 809 * // started.
fep 0:62cd296ba2a7 810 * if( xTimerStart( xBacklightTimer, 0 ) != pdPASS )
fep 0:62cd296ba2a7 811 * {
fep 0:62cd296ba2a7 812 * // The timer could not be set into the Active state.
fep 0:62cd296ba2a7 813 * }
fep 0:62cd296ba2a7 814 * }
fep 0:62cd296ba2a7 815 *
fep 0:62cd296ba2a7 816 * // ...
fep 0:62cd296ba2a7 817 * // Create tasks here.
fep 0:62cd296ba2a7 818 * // ...
fep 0:62cd296ba2a7 819 *
fep 0:62cd296ba2a7 820 * // Starting the scheduler will start the timer running as it has already
fep 0:62cd296ba2a7 821 * // been set into the active state.
fep 0:62cd296ba2a7 822 * vTaskStartScheduler();
fep 0:62cd296ba2a7 823 *
fep 0:62cd296ba2a7 824 * // Should not reach here.
fep 0:62cd296ba2a7 825 * for( ;; );
fep 0:62cd296ba2a7 826 * }
fep 0:62cd296ba2a7 827 * @endverbatim
fep 0:62cd296ba2a7 828 */
fep 0:62cd296ba2a7 829 #define xTimerReset( xTimer, xTicksToWait ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_RESET, ( xTaskGetTickCount() ), NULL, ( xTicksToWait ) )
fep 0:62cd296ba2a7 830
fep 0:62cd296ba2a7 831 /**
fep 0:62cd296ba2a7 832 * BaseType_t xTimerStartFromISR( TimerHandle_t xTimer,
fep 0:62cd296ba2a7 833 * BaseType_t *pxHigherPriorityTaskWoken );
fep 0:62cd296ba2a7 834 *
fep 0:62cd296ba2a7 835 * A version of xTimerStart() that can be called from an interrupt service
fep 0:62cd296ba2a7 836 * routine.
fep 0:62cd296ba2a7 837 *
fep 0:62cd296ba2a7 838 * @param xTimer The handle of the timer being started/restarted.
fep 0:62cd296ba2a7 839 *
fep 0:62cd296ba2a7 840 * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most
fep 0:62cd296ba2a7 841 * of its time in the Blocked state, waiting for messages to arrive on the timer
fep 0:62cd296ba2a7 842 * command queue. Calling xTimerStartFromISR() writes a message to the timer
fep 0:62cd296ba2a7 843 * command queue, so has the potential to transition the timer service/daemon
fep 0:62cd296ba2a7 844 * task out of the Blocked state. If calling xTimerStartFromISR() causes the
fep 0:62cd296ba2a7 845 * timer service/daemon task to leave the Blocked state, and the timer service/
fep 0:62cd296ba2a7 846 * daemon task has a priority equal to or greater than the currently executing
fep 0:62cd296ba2a7 847 * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will
fep 0:62cd296ba2a7 848 * get set to pdTRUE internally within the xTimerStartFromISR() function. If
fep 0:62cd296ba2a7 849 * xTimerStartFromISR() sets this value to pdTRUE then a context switch should
fep 0:62cd296ba2a7 850 * be performed before the interrupt exits.
fep 0:62cd296ba2a7 851 *
fep 0:62cd296ba2a7 852 * @return pdFAIL will be returned if the start command could not be sent to
fep 0:62cd296ba2a7 853 * the timer command queue. pdPASS will be returned if the command was
fep 0:62cd296ba2a7 854 * successfully sent to the timer command queue. When the command is actually
fep 0:62cd296ba2a7 855 * processed will depend on the priority of the timer service/daemon task
fep 0:62cd296ba2a7 856 * relative to other tasks in the system, although the timers expiry time is
fep 0:62cd296ba2a7 857 * relative to when xTimerStartFromISR() is actually called. The timer
fep 0:62cd296ba2a7 858 * service/daemon task priority is set by the configTIMER_TASK_PRIORITY
fep 0:62cd296ba2a7 859 * configuration constant.
fep 0:62cd296ba2a7 860 *
fep 0:62cd296ba2a7 861 * Example usage:
fep 0:62cd296ba2a7 862 * @verbatim
fep 0:62cd296ba2a7 863 * // This scenario assumes xBacklightTimer has already been created. When a
fep 0:62cd296ba2a7 864 * // key is pressed, an LCD back-light is switched on. If 5 seconds pass
fep 0:62cd296ba2a7 865 * // without a key being pressed, then the LCD back-light is switched off. In
fep 0:62cd296ba2a7 866 * // this case, the timer is a one-shot timer, and unlike the example given for
fep 0:62cd296ba2a7 867 * // the xTimerReset() function, the key press event handler is an interrupt
fep 0:62cd296ba2a7 868 * // service routine.
fep 0:62cd296ba2a7 869 *
fep 0:62cd296ba2a7 870 * // The callback function assigned to the one-shot timer. In this case the
fep 0:62cd296ba2a7 871 * // parameter is not used.
fep 0:62cd296ba2a7 872 * void vBacklightTimerCallback( TimerHandle_t pxTimer )
fep 0:62cd296ba2a7 873 * {
fep 0:62cd296ba2a7 874 * // The timer expired, therefore 5 seconds must have passed since a key
fep 0:62cd296ba2a7 875 * // was pressed. Switch off the LCD back-light.
fep 0:62cd296ba2a7 876 * vSetBacklightState( BACKLIGHT_OFF );
fep 0:62cd296ba2a7 877 * }
fep 0:62cd296ba2a7 878 *
fep 0:62cd296ba2a7 879 * // The key press interrupt service routine.
fep 0:62cd296ba2a7 880 * void vKeyPressEventInterruptHandler( void )
fep 0:62cd296ba2a7 881 * {
fep 0:62cd296ba2a7 882 * BaseType_t xHigherPriorityTaskWoken = pdFALSE;
fep 0:62cd296ba2a7 883 *
fep 0:62cd296ba2a7 884 * // Ensure the LCD back-light is on, then restart the timer that is
fep 0:62cd296ba2a7 885 * // responsible for turning the back-light off after 5 seconds of
fep 0:62cd296ba2a7 886 * // key inactivity. This is an interrupt service routine so can only
fep 0:62cd296ba2a7 887 * // call FreeRTOS API functions that end in "FromISR".
fep 0:62cd296ba2a7 888 * vSetBacklightState( BACKLIGHT_ON );
fep 0:62cd296ba2a7 889 *
fep 0:62cd296ba2a7 890 * // xTimerStartFromISR() or xTimerResetFromISR() could be called here
fep 0:62cd296ba2a7 891 * // as both cause the timer to re-calculate its expiry time.
fep 0:62cd296ba2a7 892 * // xHigherPriorityTaskWoken was initialised to pdFALSE when it was
fep 0:62cd296ba2a7 893 * // declared (in this function).
fep 0:62cd296ba2a7 894 * if( xTimerStartFromISR( xBacklightTimer, &xHigherPriorityTaskWoken ) != pdPASS )
fep 0:62cd296ba2a7 895 * {
fep 0:62cd296ba2a7 896 * // The start command was not executed successfully. Take appropriate
fep 0:62cd296ba2a7 897 * // action here.
fep 0:62cd296ba2a7 898 * }
fep 0:62cd296ba2a7 899 *
fep 0:62cd296ba2a7 900 * // Perform the rest of the key processing here.
fep 0:62cd296ba2a7 901 *
fep 0:62cd296ba2a7 902 * // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch
fep 0:62cd296ba2a7 903 * // should be performed. The syntax required to perform a context switch
fep 0:62cd296ba2a7 904 * // from inside an ISR varies from port to port, and from compiler to
fep 0:62cd296ba2a7 905 * // compiler. Inspect the demos for the port you are using to find the
fep 0:62cd296ba2a7 906 * // actual syntax required.
fep 0:62cd296ba2a7 907 * if( xHigherPriorityTaskWoken != pdFALSE )
fep 0:62cd296ba2a7 908 * {
fep 0:62cd296ba2a7 909 * // Call the interrupt safe yield function here (actual function
fep 0:62cd296ba2a7 910 * // depends on the FreeRTOS port being used).
fep 0:62cd296ba2a7 911 * }
fep 0:62cd296ba2a7 912 * }
fep 0:62cd296ba2a7 913 * @endverbatim
fep 0:62cd296ba2a7 914 */
fep 0:62cd296ba2a7 915 #define xTimerStartFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START_FROM_ISR, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U )
fep 0:62cd296ba2a7 916
fep 0:62cd296ba2a7 917 /**
fep 0:62cd296ba2a7 918 * BaseType_t xTimerStopFromISR( TimerHandle_t xTimer,
fep 0:62cd296ba2a7 919 * BaseType_t *pxHigherPriorityTaskWoken );
fep 0:62cd296ba2a7 920 *
fep 0:62cd296ba2a7 921 * A version of xTimerStop() that can be called from an interrupt service
fep 0:62cd296ba2a7 922 * routine.
fep 0:62cd296ba2a7 923 *
fep 0:62cd296ba2a7 924 * @param xTimer The handle of the timer being stopped.
fep 0:62cd296ba2a7 925 *
fep 0:62cd296ba2a7 926 * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most
fep 0:62cd296ba2a7 927 * of its time in the Blocked state, waiting for messages to arrive on the timer
fep 0:62cd296ba2a7 928 * command queue. Calling xTimerStopFromISR() writes a message to the timer
fep 0:62cd296ba2a7 929 * command queue, so has the potential to transition the timer service/daemon
fep 0:62cd296ba2a7 930 * task out of the Blocked state. If calling xTimerStopFromISR() causes the
fep 0:62cd296ba2a7 931 * timer service/daemon task to leave the Blocked state, and the timer service/
fep 0:62cd296ba2a7 932 * daemon task has a priority equal to or greater than the currently executing
fep 0:62cd296ba2a7 933 * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will
fep 0:62cd296ba2a7 934 * get set to pdTRUE internally within the xTimerStopFromISR() function. If
fep 0:62cd296ba2a7 935 * xTimerStopFromISR() sets this value to pdTRUE then a context switch should
fep 0:62cd296ba2a7 936 * be performed before the interrupt exits.
fep 0:62cd296ba2a7 937 *
fep 0:62cd296ba2a7 938 * @return pdFAIL will be returned if the stop command could not be sent to
fep 0:62cd296ba2a7 939 * the timer command queue. pdPASS will be returned if the command was
fep 0:62cd296ba2a7 940 * successfully sent to the timer command queue. When the command is actually
fep 0:62cd296ba2a7 941 * processed will depend on the priority of the timer service/daemon task
fep 0:62cd296ba2a7 942 * relative to other tasks in the system. The timer service/daemon task
fep 0:62cd296ba2a7 943 * priority is set by the configTIMER_TASK_PRIORITY configuration constant.
fep 0:62cd296ba2a7 944 *
fep 0:62cd296ba2a7 945 * Example usage:
fep 0:62cd296ba2a7 946 * @verbatim
fep 0:62cd296ba2a7 947 * // This scenario assumes xTimer has already been created and started. When
fep 0:62cd296ba2a7 948 * // an interrupt occurs, the timer should be simply stopped.
fep 0:62cd296ba2a7 949 *
fep 0:62cd296ba2a7 950 * // The interrupt service routine that stops the timer.
fep 0:62cd296ba2a7 951 * void vAnExampleInterruptServiceRoutine( void )
fep 0:62cd296ba2a7 952 * {
fep 0:62cd296ba2a7 953 * BaseType_t xHigherPriorityTaskWoken = pdFALSE;
fep 0:62cd296ba2a7 954 *
fep 0:62cd296ba2a7 955 * // The interrupt has occurred - simply stop the timer.
fep 0:62cd296ba2a7 956 * // xHigherPriorityTaskWoken was set to pdFALSE where it was defined
fep 0:62cd296ba2a7 957 * // (within this function). As this is an interrupt service routine, only
fep 0:62cd296ba2a7 958 * // FreeRTOS API functions that end in "FromISR" can be used.
fep 0:62cd296ba2a7 959 * if( xTimerStopFromISR( xTimer, &xHigherPriorityTaskWoken ) != pdPASS )
fep 0:62cd296ba2a7 960 * {
fep 0:62cd296ba2a7 961 * // The stop command was not executed successfully. Take appropriate
fep 0:62cd296ba2a7 962 * // action here.
fep 0:62cd296ba2a7 963 * }
fep 0:62cd296ba2a7 964 *
fep 0:62cd296ba2a7 965 * // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch
fep 0:62cd296ba2a7 966 * // should be performed. The syntax required to perform a context switch
fep 0:62cd296ba2a7 967 * // from inside an ISR varies from port to port, and from compiler to
fep 0:62cd296ba2a7 968 * // compiler. Inspect the demos for the port you are using to find the
fep 0:62cd296ba2a7 969 * // actual syntax required.
fep 0:62cd296ba2a7 970 * if( xHigherPriorityTaskWoken != pdFALSE )
fep 0:62cd296ba2a7 971 * {
fep 0:62cd296ba2a7 972 * // Call the interrupt safe yield function here (actual function
fep 0:62cd296ba2a7 973 * // depends on the FreeRTOS port being used).
fep 0:62cd296ba2a7 974 * }
fep 0:62cd296ba2a7 975 * }
fep 0:62cd296ba2a7 976 * @endverbatim
fep 0:62cd296ba2a7 977 */
fep 0:62cd296ba2a7 978 #define xTimerStopFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP_FROM_ISR, 0, ( pxHigherPriorityTaskWoken ), 0U )
fep 0:62cd296ba2a7 979
fep 0:62cd296ba2a7 980 /**
fep 0:62cd296ba2a7 981 * BaseType_t xTimerChangePeriodFromISR( TimerHandle_t xTimer,
fep 0:62cd296ba2a7 982 * TickType_t xNewPeriod,
fep 0:62cd296ba2a7 983 * BaseType_t *pxHigherPriorityTaskWoken );
fep 0:62cd296ba2a7 984 *
fep 0:62cd296ba2a7 985 * A version of xTimerChangePeriod() that can be called from an interrupt
fep 0:62cd296ba2a7 986 * service routine.
fep 0:62cd296ba2a7 987 *
fep 0:62cd296ba2a7 988 * @param xTimer The handle of the timer that is having its period changed.
fep 0:62cd296ba2a7 989 *
fep 0:62cd296ba2a7 990 * @param xNewPeriod The new period for xTimer. Timer periods are specified in
fep 0:62cd296ba2a7 991 * tick periods, so the constant portTICK_PERIOD_MS can be used to convert a time
fep 0:62cd296ba2a7 992 * that has been specified in milliseconds. For example, if the timer must
fep 0:62cd296ba2a7 993 * expire after 100 ticks, then xNewPeriod should be set to 100. Alternatively,
fep 0:62cd296ba2a7 994 * if the timer must expire after 500ms, then xNewPeriod can be set to
fep 0:62cd296ba2a7 995 * ( 500 / portTICK_PERIOD_MS ) provided configTICK_RATE_HZ is less than
fep 0:62cd296ba2a7 996 * or equal to 1000.
fep 0:62cd296ba2a7 997 *
fep 0:62cd296ba2a7 998 * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most
fep 0:62cd296ba2a7 999 * of its time in the Blocked state, waiting for messages to arrive on the timer
fep 0:62cd296ba2a7 1000 * command queue. Calling xTimerChangePeriodFromISR() writes a message to the
fep 0:62cd296ba2a7 1001 * timer command queue, so has the potential to transition the timer service/
fep 0:62cd296ba2a7 1002 * daemon task out of the Blocked state. If calling xTimerChangePeriodFromISR()
fep 0:62cd296ba2a7 1003 * causes the timer service/daemon task to leave the Blocked state, and the
fep 0:62cd296ba2a7 1004 * timer service/daemon task has a priority equal to or greater than the
fep 0:62cd296ba2a7 1005 * currently executing task (the task that was interrupted), then
fep 0:62cd296ba2a7 1006 * *pxHigherPriorityTaskWoken will get set to pdTRUE internally within the
fep 0:62cd296ba2a7 1007 * xTimerChangePeriodFromISR() function. If xTimerChangePeriodFromISR() sets
fep 0:62cd296ba2a7 1008 * this value to pdTRUE then a context switch should be performed before the
fep 0:62cd296ba2a7 1009 * interrupt exits.
fep 0:62cd296ba2a7 1010 *
fep 0:62cd296ba2a7 1011 * @return pdFAIL will be returned if the command to change the timers period
fep 0:62cd296ba2a7 1012 * could not be sent to the timer command queue. pdPASS will be returned if the
fep 0:62cd296ba2a7 1013 * command was successfully sent to the timer command queue. When the command
fep 0:62cd296ba2a7 1014 * is actually processed will depend on the priority of the timer service/daemon
fep 0:62cd296ba2a7 1015 * task relative to other tasks in the system. The timer service/daemon task
fep 0:62cd296ba2a7 1016 * priority is set by the configTIMER_TASK_PRIORITY configuration constant.
fep 0:62cd296ba2a7 1017 *
fep 0:62cd296ba2a7 1018 * Example usage:
fep 0:62cd296ba2a7 1019 * @verbatim
fep 0:62cd296ba2a7 1020 * // This scenario assumes xTimer has already been created and started. When
fep 0:62cd296ba2a7 1021 * // an interrupt occurs, the period of xTimer should be changed to 500ms.
fep 0:62cd296ba2a7 1022 *
fep 0:62cd296ba2a7 1023 * // The interrupt service routine that changes the period of xTimer.
fep 0:62cd296ba2a7 1024 * void vAnExampleInterruptServiceRoutine( void )
fep 0:62cd296ba2a7 1025 * {
fep 0:62cd296ba2a7 1026 * BaseType_t xHigherPriorityTaskWoken = pdFALSE;
fep 0:62cd296ba2a7 1027 *
fep 0:62cd296ba2a7 1028 * // The interrupt has occurred - change the period of xTimer to 500ms.
fep 0:62cd296ba2a7 1029 * // xHigherPriorityTaskWoken was set to pdFALSE where it was defined
fep 0:62cd296ba2a7 1030 * // (within this function). As this is an interrupt service routine, only
fep 0:62cd296ba2a7 1031 * // FreeRTOS API functions that end in "FromISR" can be used.
fep 0:62cd296ba2a7 1032 * if( xTimerChangePeriodFromISR( xTimer, &xHigherPriorityTaskWoken ) != pdPASS )
fep 0:62cd296ba2a7 1033 * {
fep 0:62cd296ba2a7 1034 * // The command to change the timers period was not executed
fep 0:62cd296ba2a7 1035 * // successfully. Take appropriate action here.
fep 0:62cd296ba2a7 1036 * }
fep 0:62cd296ba2a7 1037 *
fep 0:62cd296ba2a7 1038 * // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch
fep 0:62cd296ba2a7 1039 * // should be performed. The syntax required to perform a context switch
fep 0:62cd296ba2a7 1040 * // from inside an ISR varies from port to port, and from compiler to
fep 0:62cd296ba2a7 1041 * // compiler. Inspect the demos for the port you are using to find the
fep 0:62cd296ba2a7 1042 * // actual syntax required.
fep 0:62cd296ba2a7 1043 * if( xHigherPriorityTaskWoken != pdFALSE )
fep 0:62cd296ba2a7 1044 * {
fep 0:62cd296ba2a7 1045 * // Call the interrupt safe yield function here (actual function
fep 0:62cd296ba2a7 1046 * // depends on the FreeRTOS port being used).
fep 0:62cd296ba2a7 1047 * }
fep 0:62cd296ba2a7 1048 * }
fep 0:62cd296ba2a7 1049 * @endverbatim
fep 0:62cd296ba2a7 1050 */
fep 0:62cd296ba2a7 1051 #define xTimerChangePeriodFromISR( xTimer, xNewPeriod, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD_FROM_ISR, ( xNewPeriod ), ( pxHigherPriorityTaskWoken ), 0U )
fep 0:62cd296ba2a7 1052
fep 0:62cd296ba2a7 1053 /**
fep 0:62cd296ba2a7 1054 * BaseType_t xTimerResetFromISR( TimerHandle_t xTimer,
fep 0:62cd296ba2a7 1055 * BaseType_t *pxHigherPriorityTaskWoken );
fep 0:62cd296ba2a7 1056 *
fep 0:62cd296ba2a7 1057 * A version of xTimerReset() that can be called from an interrupt service
fep 0:62cd296ba2a7 1058 * routine.
fep 0:62cd296ba2a7 1059 *
fep 0:62cd296ba2a7 1060 * @param xTimer The handle of the timer that is to be started, reset, or
fep 0:62cd296ba2a7 1061 * restarted.
fep 0:62cd296ba2a7 1062 *
fep 0:62cd296ba2a7 1063 * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most
fep 0:62cd296ba2a7 1064 * of its time in the Blocked state, waiting for messages to arrive on the timer
fep 0:62cd296ba2a7 1065 * command queue. Calling xTimerResetFromISR() writes a message to the timer
fep 0:62cd296ba2a7 1066 * command queue, so has the potential to transition the timer service/daemon
fep 0:62cd296ba2a7 1067 * task out of the Blocked state. If calling xTimerResetFromISR() causes the
fep 0:62cd296ba2a7 1068 * timer service/daemon task to leave the Blocked state, and the timer service/
fep 0:62cd296ba2a7 1069 * daemon task has a priority equal to or greater than the currently executing
fep 0:62cd296ba2a7 1070 * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will
fep 0:62cd296ba2a7 1071 * get set to pdTRUE internally within the xTimerResetFromISR() function. If
fep 0:62cd296ba2a7 1072 * xTimerResetFromISR() sets this value to pdTRUE then a context switch should
fep 0:62cd296ba2a7 1073 * be performed before the interrupt exits.
fep 0:62cd296ba2a7 1074 *
fep 0:62cd296ba2a7 1075 * @return pdFAIL will be returned if the reset command could not be sent to
fep 0:62cd296ba2a7 1076 * the timer command queue. pdPASS will be returned if the command was
fep 0:62cd296ba2a7 1077 * successfully sent to the timer command queue. When the command is actually
fep 0:62cd296ba2a7 1078 * processed will depend on the priority of the timer service/daemon task
fep 0:62cd296ba2a7 1079 * relative to other tasks in the system, although the timers expiry time is
fep 0:62cd296ba2a7 1080 * relative to when xTimerResetFromISR() is actually called. The timer service/daemon
fep 0:62cd296ba2a7 1081 * task priority is set by the configTIMER_TASK_PRIORITY configuration constant.
fep 0:62cd296ba2a7 1082 *
fep 0:62cd296ba2a7 1083 * Example usage:
fep 0:62cd296ba2a7 1084 * @verbatim
fep 0:62cd296ba2a7 1085 * // This scenario assumes xBacklightTimer has already been created. When a
fep 0:62cd296ba2a7 1086 * // key is pressed, an LCD back-light is switched on. If 5 seconds pass
fep 0:62cd296ba2a7 1087 * // without a key being pressed, then the LCD back-light is switched off. In
fep 0:62cd296ba2a7 1088 * // this case, the timer is a one-shot timer, and unlike the example given for
fep 0:62cd296ba2a7 1089 * // the xTimerReset() function, the key press event handler is an interrupt
fep 0:62cd296ba2a7 1090 * // service routine.
fep 0:62cd296ba2a7 1091 *
fep 0:62cd296ba2a7 1092 * // The callback function assigned to the one-shot timer. In this case the
fep 0:62cd296ba2a7 1093 * // parameter is not used.
fep 0:62cd296ba2a7 1094 * void vBacklightTimerCallback( TimerHandle_t pxTimer )
fep 0:62cd296ba2a7 1095 * {
fep 0:62cd296ba2a7 1096 * // The timer expired, therefore 5 seconds must have passed since a key
fep 0:62cd296ba2a7 1097 * // was pressed. Switch off the LCD back-light.
fep 0:62cd296ba2a7 1098 * vSetBacklightState( BACKLIGHT_OFF );
fep 0:62cd296ba2a7 1099 * }
fep 0:62cd296ba2a7 1100 *
fep 0:62cd296ba2a7 1101 * // The key press interrupt service routine.
fep 0:62cd296ba2a7 1102 * void vKeyPressEventInterruptHandler( void )
fep 0:62cd296ba2a7 1103 * {
fep 0:62cd296ba2a7 1104 * BaseType_t xHigherPriorityTaskWoken = pdFALSE;
fep 0:62cd296ba2a7 1105 *
fep 0:62cd296ba2a7 1106 * // Ensure the LCD back-light is on, then reset the timer that is
fep 0:62cd296ba2a7 1107 * // responsible for turning the back-light off after 5 seconds of
fep 0:62cd296ba2a7 1108 * // key inactivity. This is an interrupt service routine so can only
fep 0:62cd296ba2a7 1109 * // call FreeRTOS API functions that end in "FromISR".
fep 0:62cd296ba2a7 1110 * vSetBacklightState( BACKLIGHT_ON );
fep 0:62cd296ba2a7 1111 *
fep 0:62cd296ba2a7 1112 * // xTimerStartFromISR() or xTimerResetFromISR() could be called here
fep 0:62cd296ba2a7 1113 * // as both cause the timer to re-calculate its expiry time.
fep 0:62cd296ba2a7 1114 * // xHigherPriorityTaskWoken was initialised to pdFALSE when it was
fep 0:62cd296ba2a7 1115 * // declared (in this function).
fep 0:62cd296ba2a7 1116 * if( xTimerResetFromISR( xBacklightTimer, &xHigherPriorityTaskWoken ) != pdPASS )
fep 0:62cd296ba2a7 1117 * {
fep 0:62cd296ba2a7 1118 * // The reset command was not executed successfully. Take appropriate
fep 0:62cd296ba2a7 1119 * // action here.
fep 0:62cd296ba2a7 1120 * }
fep 0:62cd296ba2a7 1121 *
fep 0:62cd296ba2a7 1122 * // Perform the rest of the key processing here.
fep 0:62cd296ba2a7 1123 *
fep 0:62cd296ba2a7 1124 * // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch
fep 0:62cd296ba2a7 1125 * // should be performed. The syntax required to perform a context switch
fep 0:62cd296ba2a7 1126 * // from inside an ISR varies from port to port, and from compiler to
fep 0:62cd296ba2a7 1127 * // compiler. Inspect the demos for the port you are using to find the
fep 0:62cd296ba2a7 1128 * // actual syntax required.
fep 0:62cd296ba2a7 1129 * if( xHigherPriorityTaskWoken != pdFALSE )
fep 0:62cd296ba2a7 1130 * {
fep 0:62cd296ba2a7 1131 * // Call the interrupt safe yield function here (actual function
fep 0:62cd296ba2a7 1132 * // depends on the FreeRTOS port being used).
fep 0:62cd296ba2a7 1133 * }
fep 0:62cd296ba2a7 1134 * }
fep 0:62cd296ba2a7 1135 * @endverbatim
fep 0:62cd296ba2a7 1136 */
fep 0:62cd296ba2a7 1137 #define xTimerResetFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_RESET_FROM_ISR, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U )
fep 0:62cd296ba2a7 1138
fep 0:62cd296ba2a7 1139
fep 0:62cd296ba2a7 1140 /**
fep 0:62cd296ba2a7 1141 * BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend,
fep 0:62cd296ba2a7 1142 * void *pvParameter1,
fep 0:62cd296ba2a7 1143 * uint32_t ulParameter2,
fep 0:62cd296ba2a7 1144 * BaseType_t *pxHigherPriorityTaskWoken );
fep 0:62cd296ba2a7 1145 *
fep 0:62cd296ba2a7 1146 *
fep 0:62cd296ba2a7 1147 * Used from application interrupt service routines to defer the execution of a
fep 0:62cd296ba2a7 1148 * function to the RTOS daemon task (the timer service task, hence this function
fep 0:62cd296ba2a7 1149 * is implemented in timers.c and is prefixed with 'Timer').
fep 0:62cd296ba2a7 1150 *
fep 0:62cd296ba2a7 1151 * Ideally an interrupt service routine (ISR) is kept as short as possible, but
fep 0:62cd296ba2a7 1152 * sometimes an ISR either has a lot of processing to do, or needs to perform
fep 0:62cd296ba2a7 1153 * processing that is not deterministic. In these cases
fep 0:62cd296ba2a7 1154 * xTimerPendFunctionCallFromISR() can be used to defer processing of a function
fep 0:62cd296ba2a7 1155 * to the RTOS daemon task.
fep 0:62cd296ba2a7 1156 *
fep 0:62cd296ba2a7 1157 * A mechanism is provided that allows the interrupt to return directly to the
fep 0:62cd296ba2a7 1158 * task that will subsequently execute the pended callback function. This
fep 0:62cd296ba2a7 1159 * allows the callback function to execute contiguously in time with the
fep 0:62cd296ba2a7 1160 * interrupt - just as if the callback had executed in the interrupt itself.
fep 0:62cd296ba2a7 1161 *
fep 0:62cd296ba2a7 1162 * @param xFunctionToPend The function to execute from the timer service/
fep 0:62cd296ba2a7 1163 * daemon task. The function must conform to the PendedFunction_t
fep 0:62cd296ba2a7 1164 * prototype.
fep 0:62cd296ba2a7 1165 *
fep 0:62cd296ba2a7 1166 * @param pvParameter1 The value of the callback function's first parameter.
fep 0:62cd296ba2a7 1167 * The parameter has a void * type to allow it to be used to pass any type.
fep 0:62cd296ba2a7 1168 * For example, unsigned longs can be cast to a void *, or the void * can be
fep 0:62cd296ba2a7 1169 * used to point to a structure.
fep 0:62cd296ba2a7 1170 *
fep 0:62cd296ba2a7 1171 * @param ulParameter2 The value of the callback function's second parameter.
fep 0:62cd296ba2a7 1172 *
fep 0:62cd296ba2a7 1173 * @param pxHigherPriorityTaskWoken As mentioned above, calling this function
fep 0:62cd296ba2a7 1174 * will result in a message being sent to the timer daemon task. If the
fep 0:62cd296ba2a7 1175 * priority of the timer daemon task (which is set using
fep 0:62cd296ba2a7 1176 * configTIMER_TASK_PRIORITY in FreeRTOSConfig.h) is higher than the priority of
fep 0:62cd296ba2a7 1177 * the currently running task (the task the interrupt interrupted) then
fep 0:62cd296ba2a7 1178 * *pxHigherPriorityTaskWoken will be set to pdTRUE within
fep 0:62cd296ba2a7 1179 * xTimerPendFunctionCallFromISR(), indicating that a context switch should be
fep 0:62cd296ba2a7 1180 * requested before the interrupt exits. For that reason
fep 0:62cd296ba2a7 1181 * *pxHigherPriorityTaskWoken must be initialised to pdFALSE. See the
fep 0:62cd296ba2a7 1182 * example code below.
fep 0:62cd296ba2a7 1183 *
fep 0:62cd296ba2a7 1184 * @return pdPASS is returned if the message was successfully sent to the
fep 0:62cd296ba2a7 1185 * timer daemon task, otherwise pdFALSE is returned.
fep 0:62cd296ba2a7 1186 *
fep 0:62cd296ba2a7 1187 * Example usage:
fep 0:62cd296ba2a7 1188 * @verbatim
fep 0:62cd296ba2a7 1189 *
fep 0:62cd296ba2a7 1190 * // The callback function that will execute in the context of the daemon task.
fep 0:62cd296ba2a7 1191 * // Note callback functions must all use this same prototype.
fep 0:62cd296ba2a7 1192 * void vProcessInterface( void *pvParameter1, uint32_t ulParameter2 )
fep 0:62cd296ba2a7 1193 * {
fep 0:62cd296ba2a7 1194 * BaseType_t xInterfaceToService;
fep 0:62cd296ba2a7 1195 *
fep 0:62cd296ba2a7 1196 * // The interface that requires servicing is passed in the second
fep 0:62cd296ba2a7 1197 * // parameter. The first parameter is not used in this case.
fep 0:62cd296ba2a7 1198 * xInterfaceToService = ( BaseType_t ) ulParameter2;
fep 0:62cd296ba2a7 1199 *
fep 0:62cd296ba2a7 1200 * // ...Perform the processing here...
fep 0:62cd296ba2a7 1201 * }
fep 0:62cd296ba2a7 1202 *
fep 0:62cd296ba2a7 1203 * // An ISR that receives data packets from multiple interfaces
fep 0:62cd296ba2a7 1204 * void vAnISR( void )
fep 0:62cd296ba2a7 1205 * {
fep 0:62cd296ba2a7 1206 * BaseType_t xInterfaceToService, xHigherPriorityTaskWoken;
fep 0:62cd296ba2a7 1207 *
fep 0:62cd296ba2a7 1208 * // Query the hardware to determine which interface needs processing.
fep 0:62cd296ba2a7 1209 * xInterfaceToService = prvCheckInterfaces();
fep 0:62cd296ba2a7 1210 *
fep 0:62cd296ba2a7 1211 * // The actual processing is to be deferred to a task. Request the
fep 0:62cd296ba2a7 1212 * // vProcessInterface() callback function is executed, passing in the
fep 0:62cd296ba2a7 1213 * // number of the interface that needs processing. The interface to
fep 0:62cd296ba2a7 1214 * // service is passed in the second parameter. The first parameter is
fep 0:62cd296ba2a7 1215 * // not used in this case.
fep 0:62cd296ba2a7 1216 * xHigherPriorityTaskWoken = pdFALSE;
fep 0:62cd296ba2a7 1217 * xTimerPendFunctionCallFromISR( vProcessInterface, NULL, ( uint32_t ) xInterfaceToService, &xHigherPriorityTaskWoken );
fep 0:62cd296ba2a7 1218 *
fep 0:62cd296ba2a7 1219 * // If xHigherPriorityTaskWoken is now set to pdTRUE then a context
fep 0:62cd296ba2a7 1220 * // switch should be requested. The macro used is port specific and will
fep 0:62cd296ba2a7 1221 * // be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() - refer to
fep 0:62cd296ba2a7 1222 * // the documentation page for the port being used.
fep 0:62cd296ba2a7 1223 * portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
fep 0:62cd296ba2a7 1224 *
fep 0:62cd296ba2a7 1225 * }
fep 0:62cd296ba2a7 1226 * @endverbatim
fep 0:62cd296ba2a7 1227 */
fep 0:62cd296ba2a7 1228 BaseType_t xTimerPendFunctionCallFromISR( PendedFunction_t xFunctionToPend, void *pvParameter1, uint32_t ulParameter2, BaseType_t *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 1229
fep 0:62cd296ba2a7 1230 /**
fep 0:62cd296ba2a7 1231 * BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend,
fep 0:62cd296ba2a7 1232 * void *pvParameter1,
fep 0:62cd296ba2a7 1233 * uint32_t ulParameter2,
fep 0:62cd296ba2a7 1234 * TickType_t xTicksToWait );
fep 0:62cd296ba2a7 1235 *
fep 0:62cd296ba2a7 1236 *
fep 0:62cd296ba2a7 1237 * Used to defer the execution of a function to the RTOS daemon task (the timer
fep 0:62cd296ba2a7 1238 * service task, hence this function is implemented in timers.c and is prefixed
fep 0:62cd296ba2a7 1239 * with 'Timer').
fep 0:62cd296ba2a7 1240 *
fep 0:62cd296ba2a7 1241 * @param xFunctionToPend The function to execute from the timer service/
fep 0:62cd296ba2a7 1242 * daemon task. The function must conform to the PendedFunction_t
fep 0:62cd296ba2a7 1243 * prototype.
fep 0:62cd296ba2a7 1244 *
fep 0:62cd296ba2a7 1245 * @param pvParameter1 The value of the callback function's first parameter.
fep 0:62cd296ba2a7 1246 * The parameter has a void * type to allow it to be used to pass any type.
fep 0:62cd296ba2a7 1247 * For example, unsigned longs can be cast to a void *, or the void * can be
fep 0:62cd296ba2a7 1248 * used to point to a structure.
fep 0:62cd296ba2a7 1249 *
fep 0:62cd296ba2a7 1250 * @param ulParameter2 The value of the callback function's second parameter.
fep 0:62cd296ba2a7 1251 *
fep 0:62cd296ba2a7 1252 * @param xTicksToWait Calling this function will result in a message being
fep 0:62cd296ba2a7 1253 * sent to the timer daemon task on a queue. xTicksToWait is the amount of
fep 0:62cd296ba2a7 1254 * time the calling task should remain in the Blocked state (so not using any
fep 0:62cd296ba2a7 1255 * processing time) for space to become available on the timer queue if the
fep 0:62cd296ba2a7 1256 * queue is found to be full.
fep 0:62cd296ba2a7 1257 *
fep 0:62cd296ba2a7 1258 * @return pdPASS is returned if the message was successfully sent to the
fep 0:62cd296ba2a7 1259 * timer daemon task, otherwise pdFALSE is returned.
fep 0:62cd296ba2a7 1260 *
fep 0:62cd296ba2a7 1261 */
fep 0:62cd296ba2a7 1262 BaseType_t xTimerPendFunctionCall( PendedFunction_t xFunctionToPend, void *pvParameter1, uint32_t ulParameter2, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 1263
fep 0:62cd296ba2a7 1264 /**
fep 0:62cd296ba2a7 1265 * const char * const pcTimerGetName( TimerHandle_t xTimer );
fep 0:62cd296ba2a7 1266 *
fep 0:62cd296ba2a7 1267 * Returns the name that was assigned to a timer when the timer was created.
fep 0:62cd296ba2a7 1268 *
fep 0:62cd296ba2a7 1269 * @param xTimer The handle of the timer being queried.
fep 0:62cd296ba2a7 1270 *
fep 0:62cd296ba2a7 1271 * @return The name assigned to the timer specified by the xTimer parameter.
fep 0:62cd296ba2a7 1272 */
fep 0:62cd296ba2a7 1273 const char * pcTimerGetName( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
fep 0:62cd296ba2a7 1274
fep 0:62cd296ba2a7 1275 /**
fep 0:62cd296ba2a7 1276 * TickType_t xTimerGetPeriod( TimerHandle_t xTimer );
fep 0:62cd296ba2a7 1277 *
fep 0:62cd296ba2a7 1278 * Returns the period of a timer.
fep 0:62cd296ba2a7 1279 *
fep 0:62cd296ba2a7 1280 * @param xTimer The handle of the timer being queried.
fep 0:62cd296ba2a7 1281 *
fep 0:62cd296ba2a7 1282 * @return The period of the timer in ticks.
fep 0:62cd296ba2a7 1283 */
fep 0:62cd296ba2a7 1284 TickType_t xTimerGetPeriod( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 1285
fep 0:62cd296ba2a7 1286 /**
fep 0:62cd296ba2a7 1287 * TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer );
fep 0:62cd296ba2a7 1288 *
fep 0:62cd296ba2a7 1289 * Returns the time in ticks at which the timer will expire. If this is less
fep 0:62cd296ba2a7 1290 * than the current tick count then the expiry time has overflowed from the
fep 0:62cd296ba2a7 1291 * current time.
fep 0:62cd296ba2a7 1292 *
fep 0:62cd296ba2a7 1293 * @param xTimer The handle of the timer being queried.
fep 0:62cd296ba2a7 1294 *
fep 0:62cd296ba2a7 1295 * @return If the timer is running then the time in ticks at which the timer
fep 0:62cd296ba2a7 1296 * will next expire is returned. If the timer is not running then the return
fep 0:62cd296ba2a7 1297 * value is undefined.
fep 0:62cd296ba2a7 1298 */
fep 0:62cd296ba2a7 1299 TickType_t xTimerGetExpiryTime( TimerHandle_t xTimer ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 1300
fep 0:62cd296ba2a7 1301 /*
fep 0:62cd296ba2a7 1302 * Functions beyond this part are not part of the public API and are intended
fep 0:62cd296ba2a7 1303 * for use by the kernel only.
fep 0:62cd296ba2a7 1304 */
fep 0:62cd296ba2a7 1305 BaseType_t xTimerCreateTimerTask( void ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 1306 BaseType_t xTimerGenericCommand( TimerHandle_t xTimer, const BaseType_t xCommandID, const TickType_t xOptionalValue, BaseType_t * const pxHigherPriorityTaskWoken, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
fep 0:62cd296ba2a7 1307
fep 0:62cd296ba2a7 1308 #ifdef __cplusplus
fep 0:62cd296ba2a7 1309 }
fep 0:62cd296ba2a7 1310 #endif
fep 0:62cd296ba2a7 1311 #endif /* TIMERS_H */
fep 0:62cd296ba2a7 1312
fep 0:62cd296ba2a7 1313
fep 0:62cd296ba2a7 1314
fep 0:62cd296ba2a7 1315