Rohit Grover
www.freertos.org
Dependents: Nucleo freertos_test FreeRTOS_test freertos_bluetooth ... more
Embed:
(wiki syntax)
Show/hide line numbers
timers.h
00001 /* 00002 FreeRTOS V7.6.0 - Copyright (C) 2013 Real Time Engineers Ltd. 00003 All rights reserved 00004 00005 VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION. 00006 00007 *************************************************************************** 00008 * * 00009 * FreeRTOS provides completely free yet professionally developed, * 00010 * robust, strictly quality controlled, supported, and cross * 00011 * platform software that has become a de facto standard. * 00012 * * 00013 * Help yourself get started quickly and support the FreeRTOS * 00014 * project by purchasing a FreeRTOS tutorial book, reference * 00015 * manual, or both from: http://www.FreeRTOS.org/Documentation * 00016 * * 00017 * Thank you! * 00018 * * 00019 *************************************************************************** 00020 00021 This file is part of the FreeRTOS distribution. 00022 00023 FreeRTOS is free software; you can redistribute it and/or modify it under 00024 the terms of the GNU General Public License (version 2) as published by the 00025 Free Software Foundation >>!AND MODIFIED BY!<< the FreeRTOS exception. 00026 00027 >>! NOTE: The modification to the GPL is included to allow you to distribute 00028 >>! a combined work that includes FreeRTOS without being obliged to provide 00029 >>! the source code for proprietary components outside of the FreeRTOS 00030 >>! kernel. 00031 00032 FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY 00033 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00034 FOR A PARTICULAR PURPOSE. Full license text is available from the following 00035 link: http://www.freertos.org/a00114.html 00036 00037 1 tab == 4 spaces! 00038 00039 *************************************************************************** 00040 * * 00041 * Having a problem? Start by reading the FAQ "My application does * 00042 * not run, what could be wrong?" * 00043 * * 00044 * http://www.FreeRTOS.org/FAQHelp.html * 00045 * * 00046 *************************************************************************** 00047 00048 http://www.FreeRTOS.org - Documentation, books, training, latest versions, 00049 license and Real Time Engineers Ltd. contact details. 00050 00051 http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products, 00052 including FreeRTOS+Trace - an indispensable productivity tool, a DOS 00053 compatible FAT file system, and our tiny thread aware UDP/IP stack. 00054 00055 http://www.OpenRTOS.com - Real Time Engineers ltd license FreeRTOS to High 00056 Integrity Systems to sell under the OpenRTOS brand. Low cost OpenRTOS 00057 licenses offer ticketed support, indemnification and middleware. 00058 00059 http://www.SafeRTOS.com - High Integrity Systems also provide a safety 00060 engineered and independently SIL3 certified version for use in safety and 00061 mission critical applications that require provable dependability. 00062 00063 1 tab == 4 spaces! 00064 */ 00065 00066 00067 #ifndef TIMERS_H 00068 #define TIMERS_H 00069 00070 #ifndef INC_FREERTOS_H 00071 #error "include FreeRTOS.h must appear in source files before include timers.h" 00072 #endif 00073 00074 /*lint -e537 This headers are only multiply included if the application code 00075 happens to also be including task.h. */ 00076 #include "task.h" 00077 /*lint +e956 */ 00078 00079 #ifdef __cplusplus 00080 extern "C" { 00081 #endif 00082 00083 /* IDs for commands that can be sent/received on the timer queue. These are to 00084 be used solely through the macros that make up the public software timer API, 00085 as defined below. */ 00086 #define tmrCOMMAND_START ( ( portBASE_TYPE ) 0 ) 00087 #define tmrCOMMAND_STOP ( ( portBASE_TYPE ) 1 ) 00088 #define tmrCOMMAND_CHANGE_PERIOD ( ( portBASE_TYPE ) 2 ) 00089 #define tmrCOMMAND_DELETE ( ( portBASE_TYPE ) 3 ) 00090 00091 /*----------------------------------------------------------- 00092 * MACROS AND DEFINITIONS 00093 *----------------------------------------------------------*/ 00094 00095 /** 00096 * Type by which software timers are referenced. For example, a call to 00097 * xTimerCreate() returns an xTimerHandle variable that can then be used to 00098 * reference the subject timer in calls to other software timer API functions 00099 * (for example, xTimerStart(), xTimerReset(), etc.). 00100 */ 00101 typedef void * xTimerHandle; 00102 00103 /* Define the prototype to which timer callback functions must conform. */ 00104 typedef void (*tmrTIMER_CALLBACK)( xTimerHandle xTimer ); 00105 00106 /** 00107 * xTimerHandle xTimerCreate( const signed char *pcTimerName, 00108 * portTickType xTimerPeriodInTicks, 00109 * unsigned portBASE_TYPE uxAutoReload, 00110 * void * pvTimerID, 00111 * tmrTIMER_CALLBACK pxCallbackFunction ); 00112 * 00113 * Creates a new software timer instance. This allocates the storage required 00114 * by the new timer, initialises the new timers internal state, and returns a 00115 * handle by which the new timer can be referenced. 00116 * 00117 * Timers are created in the dormant state. The xTimerStart(), xTimerReset(), 00118 * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and 00119 * xTimerChangePeriodFromISR() API functions can all be used to transition a timer into the 00120 * active state. 00121 * 00122 * @param pcTimerName A text name that is assigned to the timer. This is done 00123 * purely to assist debugging. The kernel itself only ever references a timer by 00124 * its handle, and never by its name. 00125 * 00126 * @param xTimerPeriodInTicks The timer period. The time is defined in tick periods so 00127 * the constant portTICK_RATE_MS can be used to convert a time that has been 00128 * specified in milliseconds. For example, if the timer must expire after 100 00129 * ticks, then xTimerPeriodInTicks should be set to 100. Alternatively, if the timer 00130 * must expire after 500ms, then xPeriod can be set to ( 500 / portTICK_RATE_MS ) 00131 * provided configTICK_RATE_HZ is less than or equal to 1000. 00132 * 00133 * @param uxAutoReload If uxAutoReload is set to pdTRUE then the timer will 00134 * expire repeatedly with a frequency set by the xTimerPeriodInTicks parameter. If 00135 * uxAutoReload is set to pdFALSE then the timer will be a one-shot timer and 00136 * enter the dormant state after it expires. 00137 * 00138 * @param pvTimerID An identifier that is assigned to the timer being created. 00139 * Typically this would be used in the timer callback function to identify which 00140 * timer expired when the same callback function is assigned to more than one 00141 * timer. 00142 * 00143 * @param pxCallbackFunction The function to call when the timer expires. 00144 * Callback functions must have the prototype defined by tmrTIMER_CALLBACK, 00145 * which is "void vCallbackFunction( xTimerHandle xTimer );". 00146 * 00147 * @return If the timer is successfully create then a handle to the newly 00148 * created timer is returned. If the timer cannot be created (because either 00149 * there is insufficient FreeRTOS heap remaining to allocate the timer 00150 * structures, or the timer period was set to 0) then 0 is returned. 00151 * 00152 * Example usage: 00153 * @verbatim 00154 * #define NUM_TIMERS 5 00155 * 00156 * // An array to hold handles to the created timers. 00157 * xTimerHandle xTimers[ NUM_TIMERS ]; 00158 * 00159 * // An array to hold a count of the number of times each timer expires. 00160 * long lExpireCounters[ NUM_TIMERS ] = { 0 }; 00161 * 00162 * // Define a callback function that will be used by multiple timer instances. 00163 * // The callback function does nothing but count the number of times the 00164 * // associated timer expires, and stop the timer once the timer has expired 00165 * // 10 times. 00166 * void vTimerCallback( xTimerHandle pxTimer ) 00167 * { 00168 * long lArrayIndex; 00169 * const long xMaxExpiryCountBeforeStopping = 10; 00170 * 00171 * // Optionally do something if the pxTimer parameter is NULL. 00172 * configASSERT( pxTimer ); 00173 * 00174 * // Which timer expired? 00175 * lArrayIndex = ( long ) pvTimerGetTimerID( pxTimer ); 00176 * 00177 * // Increment the number of times that pxTimer has expired. 00178 * lExpireCounters[ lArrayIndex ] += 1; 00179 * 00180 * // If the timer has expired 10 times then stop it from running. 00181 * if( lExpireCounters[ lArrayIndex ] == xMaxExpiryCountBeforeStopping ) 00182 * { 00183 * // Do not use a block time if calling a timer API function from a 00184 * // timer callback function, as doing so could cause a deadlock! 00185 * xTimerStop( pxTimer, 0 ); 00186 * } 00187 * } 00188 * 00189 * void main( void ) 00190 * { 00191 * long x; 00192 * 00193 * // Create then start some timers. Starting the timers before the scheduler 00194 * // has been started means the timers will start running immediately that 00195 * // the scheduler starts. 00196 * for( x = 0; x < NUM_TIMERS; x++ ) 00197 * { 00198 * xTimers[ x ] = xTimerCreate( "Timer", // Just a text name, not used by the kernel. 00199 * ( 100 * x ), // The timer period in ticks. 00200 * pdTRUE, // The timers will auto-reload themselves when they expire. 00201 * ( void * ) x, // Assign each timer a unique id equal to its array index. 00202 * vTimerCallback // Each timer calls the same callback when it expires. 00203 * ); 00204 * 00205 * if( xTimers[ x ] == NULL ) 00206 * { 00207 * // The timer was not created. 00208 * } 00209 * else 00210 * { 00211 * // Start the timer. No block time is specified, and even if one was 00212 * // it would be ignored because the scheduler has not yet been 00213 * // started. 00214 * if( xTimerStart( xTimers[ x ], 0 ) != pdPASS ) 00215 * { 00216 * // The timer could not be set into the Active state. 00217 * } 00218 * } 00219 * } 00220 * 00221 * // ... 00222 * // Create tasks here. 00223 * // ... 00224 * 00225 * // Starting the scheduler will start the timers running as they have already 00226 * // been set into the active state. 00227 * xTaskStartScheduler(); 00228 * 00229 * // Should not reach here. 00230 * for( ;; ); 00231 * } 00232 * @endverbatim 00233 */ 00234 xTimerHandle xTimerCreate( const signed char * const pcTimerName, portTickType xTimerPeriodInTicks, unsigned portBASE_TYPE uxAutoReload, void * pvTimerID, tmrTIMER_CALLBACK pxCallbackFunction ) PRIVILEGED_FUNCTION; 00235 00236 /** 00237 * void *pvTimerGetTimerID( xTimerHandle xTimer ); 00238 * 00239 * Returns the ID assigned to the timer. 00240 * 00241 * IDs are assigned to timers using the pvTimerID parameter of the call to 00242 * xTimerCreated() that was used to create the timer. 00243 * 00244 * If the same callback function is assigned to multiple timers then the timer 00245 * ID can be used within the callback function to identify which timer actually 00246 * expired. 00247 * 00248 * @param xTimer The timer being queried. 00249 * 00250 * @return The ID assigned to the timer being queried. 00251 * 00252 * Example usage: 00253 * 00254 * See the xTimerCreate() API function example usage scenario. 00255 */ 00256 void *pvTimerGetTimerID( xTimerHandle xTimer ) PRIVILEGED_FUNCTION; 00257 00258 /** 00259 * portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ); 00260 * 00261 * Queries a timer to see if it is active or dormant. 00262 * 00263 * A timer will be dormant if: 00264 * 1) It has been created but not started, or 00265 * 2) It is an expired on-shot timer that has not been restarted. 00266 * 00267 * Timers are created in the dormant state. The xTimerStart(), xTimerReset(), 00268 * xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and 00269 * xTimerChangePeriodFromISR() API functions can all be used to transition a timer into the 00270 * active state. 00271 * 00272 * @param xTimer The timer being queried. 00273 * 00274 * @return pdFALSE will be returned if the timer is dormant. A value other than 00275 * pdFALSE will be returned if the timer is active. 00276 * 00277 * Example usage: 00278 * @verbatim 00279 * // This function assumes xTimer has already been created. 00280 * void vAFunction( xTimerHandle xTimer ) 00281 * { 00282 * if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and equivalently "if( xTimerIsTimerActive( xTimer ) )" 00283 * { 00284 * // xTimer is active, do something. 00285 * } 00286 * else 00287 * { 00288 * // xTimer is not active, do something else. 00289 * } 00290 * } 00291 * @endverbatim 00292 */ 00293 portBASE_TYPE xTimerIsTimerActive( xTimerHandle xTimer ) PRIVILEGED_FUNCTION; 00294 00295 /** 00296 * xTimerGetTimerDaemonTaskHandle() is only available if 00297 * INCLUDE_xTimerGetTimerDaemonTaskHandle is set to 1 in FreeRTOSConfig.h. 00298 * 00299 * Simply returns the handle of the timer service/daemon task. It it not valid 00300 * to call xTimerGetTimerDaemonTaskHandle() before the scheduler has been started. 00301 */ 00302 xTaskHandle xTimerGetTimerDaemonTaskHandle( void ); 00303 00304 /** 00305 * portBASE_TYPE xTimerStart( xTimerHandle xTimer, portTickType xBlockTime ); 00306 * 00307 * Timer functionality is provided by a timer service/daemon task. Many of the 00308 * public FreeRTOS timer API functions send commands to the timer service task 00309 * though a queue called the timer command queue. The timer command queue is 00310 * private to the kernel itself and is not directly accessible to application 00311 * code. The length of the timer command queue is set by the 00312 * configTIMER_QUEUE_LENGTH configuration constant. 00313 * 00314 * xTimerStart() starts a timer that was previously created using the 00315 * xTimerCreate() API function. If the timer had already been started and was 00316 * already in the active state, then xTimerStart() has equivalent functionality 00317 * to the xTimerReset() API function. 00318 * 00319 * Starting a timer ensures the timer is in the active state. If the timer 00320 * is not stopped, deleted, or reset in the mean time, the callback function 00321 * associated with the timer will get called 'n' ticks after xTimerStart() was 00322 * called, where 'n' is the timers defined period. 00323 * 00324 * It is valid to call xTimerStart() before the scheduler has been started, but 00325 * when this is done the timer will not actually start until the scheduler is 00326 * started, and the timers expiry time will be relative to when the scheduler is 00327 * started, not relative to when xTimerStart() was called. 00328 * 00329 * The configUSE_TIMERS configuration constant must be set to 1 for xTimerStart() 00330 * to be available. 00331 * 00332 * @param xTimer The handle of the timer being started/restarted. 00333 * 00334 * @param xBlockTime Specifies the time, in ticks, that the calling task should 00335 * be held in the Blocked state to wait for the start command to be successfully 00336 * sent to the timer command queue, should the queue already be full when 00337 * xTimerStart() was called. xBlockTime is ignored if xTimerStart() is called 00338 * before the scheduler is started. 00339 * 00340 * @return pdFAIL will be returned if the start command could not be sent to 00341 * the timer command queue even after xBlockTime ticks had passed. pdPASS will 00342 * be returned if the command was successfully sent to the timer command queue. 00343 * When the command is actually processed will depend on the priority of the 00344 * timer service/daemon task relative to other tasks in the system, although the 00345 * timers expiry time is relative to when xTimerStart() is actually called. The 00346 * timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY 00347 * configuration constant. 00348 * 00349 * Example usage: 00350 * 00351 * See the xTimerCreate() API function example usage scenario. 00352 * 00353 */ 00354 #define xTimerStart( xTimer, xBlockTime ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START, ( xTaskGetTickCount() ), NULL, ( xBlockTime ) ) 00355 00356 /** 00357 * portBASE_TYPE xTimerStop( xTimerHandle xTimer, portTickType xBlockTime ); 00358 * 00359 * Timer functionality is provided by a timer service/daemon task. Many of the 00360 * public FreeRTOS timer API functions send commands to the timer service task 00361 * though a queue called the timer command queue. The timer command queue is 00362 * private to the kernel itself and is not directly accessible to application 00363 * code. The length of the timer command queue is set by the 00364 * configTIMER_QUEUE_LENGTH configuration constant. 00365 * 00366 * xTimerStop() stops a timer that was previously started using either of the 00367 * The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimerResetFromISR(), 00368 * xTimerChangePeriod() or xTimerChangePeriodFromISR() API functions. 00369 * 00370 * Stopping a timer ensures the timer is not in the active state. 00371 * 00372 * The configUSE_TIMERS configuration constant must be set to 1 for xTimerStop() 00373 * to be available. 00374 * 00375 * @param xTimer The handle of the timer being stopped. 00376 * 00377 * @param xBlockTime Specifies the time, in ticks, that the calling task should 00378 * be held in the Blocked state to wait for the stop command to be successfully 00379 * sent to the timer command queue, should the queue already be full when 00380 * xTimerStop() was called. xBlockTime is ignored if xTimerStop() is called 00381 * before the scheduler is started. 00382 * 00383 * @return pdFAIL will be returned if the stop command could not be sent to 00384 * the timer command queue even after xBlockTime ticks had passed. pdPASS will 00385 * be returned if the command was successfully sent to the timer command queue. 00386 * When the command is actually processed will depend on the priority of the 00387 * timer service/daemon task relative to other tasks in the system. The timer 00388 * service/daemon task priority is set by the configTIMER_TASK_PRIORITY 00389 * configuration constant. 00390 * 00391 * Example usage: 00392 * 00393 * See the xTimerCreate() API function example usage scenario. 00394 * 00395 */ 00396 #define xTimerStop( xTimer, xBlockTime ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP, 0U, NULL, ( xBlockTime ) ) 00397 00398 /** 00399 * portBASE_TYPE xTimerChangePeriod( xTimerHandle xTimer, 00400 * portTickType xNewPeriod, 00401 * portTickType xBlockTime ); 00402 * 00403 * Timer functionality is provided by a timer service/daemon task. Many of the 00404 * public FreeRTOS timer API functions send commands to the timer service task 00405 * though a queue called the timer command queue. The timer command queue is 00406 * private to the kernel itself and is not directly accessible to application 00407 * code. The length of the timer command queue is set by the 00408 * configTIMER_QUEUE_LENGTH configuration constant. 00409 * 00410 * xTimerChangePeriod() changes the period of a timer that was previously 00411 * created using the xTimerCreate() API function. 00412 * 00413 * xTimerChangePeriod() can be called to change the period of an active or 00414 * dormant state timer. 00415 * 00416 * The configUSE_TIMERS configuration constant must be set to 1 for 00417 * xTimerChangePeriod() to be available. 00418 * 00419 * @param xTimer The handle of the timer that is having its period changed. 00420 * 00421 * @param xNewPeriod The new period for xTimer. Timer periods are specified in 00422 * tick periods, so the constant portTICK_RATE_MS can be used to convert a time 00423 * that has been specified in milliseconds. For example, if the timer must 00424 * expire after 100 ticks, then xNewPeriod should be set to 100. Alternatively, 00425 * if the timer must expire after 500ms, then xNewPeriod can be set to 00426 * ( 500 / portTICK_RATE_MS ) provided configTICK_RATE_HZ is less than 00427 * or equal to 1000. 00428 * 00429 * @param xBlockTime Specifies the time, in ticks, that the calling task should 00430 * be held in the Blocked state to wait for the change period command to be 00431 * successfully sent to the timer command queue, should the queue already be 00432 * full when xTimerChangePeriod() was called. xBlockTime is ignored if 00433 * xTimerChangePeriod() is called before the scheduler is started. 00434 * 00435 * @return pdFAIL will be returned if the change period command could not be 00436 * sent to the timer command queue even after xBlockTime ticks had passed. 00437 * pdPASS will be returned if the command was successfully sent to the timer 00438 * command queue. When the command is actually processed will depend on the 00439 * priority of the timer service/daemon task relative to other tasks in the 00440 * system. The timer service/daemon task priority is set by the 00441 * configTIMER_TASK_PRIORITY configuration constant. 00442 * 00443 * Example usage: 00444 * @verbatim 00445 * // This function assumes xTimer has already been created. If the timer 00446 * // referenced by xTimer is already active when it is called, then the timer 00447 * // is deleted. If the timer referenced by xTimer is not active when it is 00448 * // called, then the period of the timer is set to 500ms and the timer is 00449 * // started. 00450 * void vAFunction( xTimerHandle xTimer ) 00451 * { 00452 * if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and equivalently "if( xTimerIsTimerActive( xTimer ) )" 00453 * { 00454 * // xTimer is already active - delete it. 00455 * xTimerDelete( xTimer ); 00456 * } 00457 * else 00458 * { 00459 * // xTimer is not active, change its period to 500ms. This will also 00460 * // cause the timer to start. Block for a maximum of 100 ticks if the 00461 * // change period command cannot immediately be sent to the timer 00462 * // command queue. 00463 * if( xTimerChangePeriod( xTimer, 500 / portTICK_RATE_MS, 100 ) == pdPASS ) 00464 * { 00465 * // The command was successfully sent. 00466 * } 00467 * else 00468 * { 00469 * // The command could not be sent, even after waiting for 100 ticks 00470 * // to pass. Take appropriate action here. 00471 * } 00472 * } 00473 * } 00474 * @endverbatim 00475 */ 00476 #define xTimerChangePeriod( xTimer, xNewPeriod, xBlockTime ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD, ( xNewPeriod ), NULL, ( xBlockTime ) ) 00477 00478 /** 00479 * portBASE_TYPE xTimerDelete( xTimerHandle xTimer, portTickType xBlockTime ); 00480 * 00481 * Timer functionality is provided by a timer service/daemon task. Many of the 00482 * public FreeRTOS timer API functions send commands to the timer service task 00483 * though a queue called the timer command queue. The timer command queue is 00484 * private to the kernel itself and is not directly accessible to application 00485 * code. The length of the timer command queue is set by the 00486 * configTIMER_QUEUE_LENGTH configuration constant. 00487 * 00488 * xTimerDelete() deletes a timer that was previously created using the 00489 * xTimerCreate() API function. 00490 * 00491 * The configUSE_TIMERS configuration constant must be set to 1 for 00492 * xTimerDelete() to be available. 00493 * 00494 * @param xTimer The handle of the timer being deleted. 00495 * 00496 * @param xBlockTime Specifies the time, in ticks, that the calling task should 00497 * be held in the Blocked state to wait for the delete command to be 00498 * successfully sent to the timer command queue, should the queue already be 00499 * full when xTimerDelete() was called. xBlockTime is ignored if xTimerDelete() 00500 * is called before the scheduler is started. 00501 * 00502 * @return pdFAIL will be returned if the delete command could not be sent to 00503 * the timer command queue even after xBlockTime ticks had passed. pdPASS will 00504 * be returned if the command was successfully sent to the timer command queue. 00505 * When the command is actually processed will depend on the priority of the 00506 * timer service/daemon task relative to other tasks in the system. The timer 00507 * service/daemon task priority is set by the configTIMER_TASK_PRIORITY 00508 * configuration constant. 00509 * 00510 * Example usage: 00511 * 00512 * See the xTimerChangePeriod() API function example usage scenario. 00513 */ 00514 #define xTimerDelete( xTimer, xBlockTime ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_DELETE, 0U, NULL, ( xBlockTime ) ) 00515 00516 /** 00517 * portBASE_TYPE xTimerReset( xTimerHandle xTimer, portTickType xBlockTime ); 00518 * 00519 * Timer functionality is provided by a timer service/daemon task. Many of the 00520 * public FreeRTOS timer API functions send commands to the timer service task 00521 * though a queue called the timer command queue. The timer command queue is 00522 * private to the kernel itself and is not directly accessible to application 00523 * code. The length of the timer command queue is set by the 00524 * configTIMER_QUEUE_LENGTH configuration constant. 00525 * 00526 * xTimerReset() re-starts a timer that was previously created using the 00527 * xTimerCreate() API function. If the timer had already been started and was 00528 * already in the active state, then xTimerReset() will cause the timer to 00529 * re-evaluate its expiry time so that it is relative to when xTimerReset() was 00530 * called. If the timer was in the dormant state then xTimerReset() has 00531 * equivalent functionality to the xTimerStart() API function. 00532 * 00533 * Resetting a timer ensures the timer is in the active state. If the timer 00534 * is not stopped, deleted, or reset in the mean time, the callback function 00535 * associated with the timer will get called 'n' ticks after xTimerReset() was 00536 * called, where 'n' is the timers defined period. 00537 * 00538 * It is valid to call xTimerReset() before the scheduler has been started, but 00539 * when this is done the timer will not actually start until the scheduler is 00540 * started, and the timers expiry time will be relative to when the scheduler is 00541 * started, not relative to when xTimerReset() was called. 00542 * 00543 * The configUSE_TIMERS configuration constant must be set to 1 for xTimerReset() 00544 * to be available. 00545 * 00546 * @param xTimer The handle of the timer being reset/started/restarted. 00547 * 00548 * @param xBlockTime Specifies the time, in ticks, that the calling task should 00549 * be held in the Blocked state to wait for the reset command to be successfully 00550 * sent to the timer command queue, should the queue already be full when 00551 * xTimerReset() was called. xBlockTime is ignored if xTimerReset() is called 00552 * before the scheduler is started. 00553 * 00554 * @return pdFAIL will be returned if the reset command could not be sent to 00555 * the timer command queue even after xBlockTime ticks had passed. pdPASS will 00556 * be returned if the command was successfully sent to the timer command queue. 00557 * When the command is actually processed will depend on the priority of the 00558 * timer service/daemon task relative to other tasks in the system, although the 00559 * timers expiry time is relative to when xTimerStart() is actually called. The 00560 * timer service/daemon task priority is set by the configTIMER_TASK_PRIORITY 00561 * configuration constant. 00562 * 00563 * Example usage: 00564 * @verbatim 00565 * // When a key is pressed, an LCD back-light is switched on. If 5 seconds pass 00566 * // without a key being pressed, then the LCD back-light is switched off. In 00567 * // this case, the timer is a one-shot timer. 00568 * 00569 * xTimerHandle xBacklightTimer = NULL; 00570 * 00571 * // The callback function assigned to the one-shot timer. In this case the 00572 * // parameter is not used. 00573 * void vBacklightTimerCallback( xTimerHandle pxTimer ) 00574 * { 00575 * // The timer expired, therefore 5 seconds must have passed since a key 00576 * // was pressed. Switch off the LCD back-light. 00577 * vSetBacklightState( BACKLIGHT_OFF ); 00578 * } 00579 * 00580 * // The key press event handler. 00581 * void vKeyPressEventHandler( char cKey ) 00582 * { 00583 * // Ensure the LCD back-light is on, then reset the timer that is 00584 * // responsible for turning the back-light off after 5 seconds of 00585 * // key inactivity. Wait 10 ticks for the command to be successfully sent 00586 * // if it cannot be sent immediately. 00587 * vSetBacklightState( BACKLIGHT_ON ); 00588 * if( xTimerReset( xBacklightTimer, 100 ) != pdPASS ) 00589 * { 00590 * // The reset command was not executed successfully. Take appropriate 00591 * // action here. 00592 * } 00593 * 00594 * // Perform the rest of the key processing here. 00595 * } 00596 * 00597 * void main( void ) 00598 * { 00599 * long x; 00600 * 00601 * // Create then start the one-shot timer that is responsible for turning 00602 * // the back-light off if no keys are pressed within a 5 second period. 00603 * xBacklightTimer = xTimerCreate( "BacklightTimer", // Just a text name, not used by the kernel. 00604 * ( 5000 / portTICK_RATE_MS), // The timer period in ticks. 00605 * pdFALSE, // The timer is a one-shot timer. 00606 * 0, // The id is not used by the callback so can take any value. 00607 * vBacklightTimerCallback // The callback function that switches the LCD back-light off. 00608 * ); 00609 * 00610 * if( xBacklightTimer == NULL ) 00611 * { 00612 * // The timer was not created. 00613 * } 00614 * else 00615 * { 00616 * // Start the timer. No block time is specified, and even if one was 00617 * // it would be ignored because the scheduler has not yet been 00618 * // started. 00619 * if( xTimerStart( xBacklightTimer, 0 ) != pdPASS ) 00620 * { 00621 * // The timer could not be set into the Active state. 00622 * } 00623 * } 00624 * 00625 * // ... 00626 * // Create tasks here. 00627 * // ... 00628 * 00629 * // Starting the scheduler will start the timer running as it has already 00630 * // been set into the active state. 00631 * xTaskStartScheduler(); 00632 * 00633 * // Should not reach here. 00634 * for( ;; ); 00635 * } 00636 * @endverbatim 00637 */ 00638 #define xTimerReset( xTimer, xBlockTime ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START, ( xTaskGetTickCount() ), NULL, ( xBlockTime ) ) 00639 00640 /** 00641 * portBASE_TYPE xTimerStartFromISR( xTimerHandle xTimer, 00642 * portBASE_TYPE *pxHigherPriorityTaskWoken ); 00643 * 00644 * A version of xTimerStart() that can be called from an interrupt service 00645 * routine. 00646 * 00647 * @param xTimer The handle of the timer being started/restarted. 00648 * 00649 * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most 00650 * of its time in the Blocked state, waiting for messages to arrive on the timer 00651 * command queue. Calling xTimerStartFromISR() writes a message to the timer 00652 * command queue, so has the potential to transition the timer service/daemon 00653 * task out of the Blocked state. If calling xTimerStartFromISR() causes the 00654 * timer service/daemon task to leave the Blocked state, and the timer service/ 00655 * daemon task has a priority equal to or greater than the currently executing 00656 * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will 00657 * get set to pdTRUE internally within the xTimerStartFromISR() function. If 00658 * xTimerStartFromISR() sets this value to pdTRUE then a context switch should 00659 * be performed before the interrupt exits. 00660 * 00661 * @return pdFAIL will be returned if the start command could not be sent to 00662 * the timer command queue. pdPASS will be returned if the command was 00663 * successfully sent to the timer command queue. When the command is actually 00664 * processed will depend on the priority of the timer service/daemon task 00665 * relative to other tasks in the system, although the timers expiry time is 00666 * relative to when xTimerStartFromISR() is actually called. The timer service/daemon 00667 * task priority is set by the configTIMER_TASK_PRIORITY configuration constant. 00668 * 00669 * Example usage: 00670 * @verbatim 00671 * // This scenario assumes xBacklightTimer has already been created. When a 00672 * // key is pressed, an LCD back-light is switched on. If 5 seconds pass 00673 * // without a key being pressed, then the LCD back-light is switched off. In 00674 * // this case, the timer is a one-shot timer, and unlike the example given for 00675 * // the xTimerReset() function, the key press event handler is an interrupt 00676 * // service routine. 00677 * 00678 * // The callback function assigned to the one-shot timer. In this case the 00679 * // parameter is not used. 00680 * void vBacklightTimerCallback( xTimerHandle pxTimer ) 00681 * { 00682 * // The timer expired, therefore 5 seconds must have passed since a key 00683 * // was pressed. Switch off the LCD back-light. 00684 * vSetBacklightState( BACKLIGHT_OFF ); 00685 * } 00686 * 00687 * // The key press interrupt service routine. 00688 * void vKeyPressEventInterruptHandler( void ) 00689 * { 00690 * portBASE_TYPE xHigherPriorityTaskWoken = pdFALSE; 00691 * 00692 * // Ensure the LCD back-light is on, then restart the timer that is 00693 * // responsible for turning the back-light off after 5 seconds of 00694 * // key inactivity. This is an interrupt service routine so can only 00695 * // call FreeRTOS API functions that end in "FromISR". 00696 * vSetBacklightState( BACKLIGHT_ON ); 00697 * 00698 * // xTimerStartFromISR() or xTimerResetFromISR() could be called here 00699 * // as both cause the timer to re-calculate its expiry time. 00700 * // xHigherPriorityTaskWoken was initialised to pdFALSE when it was 00701 * // declared (in this function). 00702 * if( xTimerStartFromISR( xBacklightTimer, &xHigherPriorityTaskWoken ) != pdPASS ) 00703 * { 00704 * // The start command was not executed successfully. Take appropriate 00705 * // action here. 00706 * } 00707 * 00708 * // Perform the rest of the key processing here. 00709 * 00710 * // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch 00711 * // should be performed. The syntax required to perform a context switch 00712 * // from inside an ISR varies from port to port, and from compiler to 00713 * // compiler. Inspect the demos for the port you are using to find the 00714 * // actual syntax required. 00715 * if( xHigherPriorityTaskWoken != pdFALSE ) 00716 * { 00717 * // Call the interrupt safe yield function here (actual function 00718 * // depends on the FreeRTOS port being used. 00719 * } 00720 * } 00721 * @endverbatim 00722 */ 00723 #define xTimerStartFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U ) 00724 00725 /** 00726 * portBASE_TYPE xTimerStopFromISR( xTimerHandle xTimer, 00727 * portBASE_TYPE *pxHigherPriorityTaskWoken ); 00728 * 00729 * A version of xTimerStop() that can be called from an interrupt service 00730 * routine. 00731 * 00732 * @param xTimer The handle of the timer being stopped. 00733 * 00734 * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most 00735 * of its time in the Blocked state, waiting for messages to arrive on the timer 00736 * command queue. Calling xTimerStopFromISR() writes a message to the timer 00737 * command queue, so has the potential to transition the timer service/daemon 00738 * task out of the Blocked state. If calling xTimerStopFromISR() causes the 00739 * timer service/daemon task to leave the Blocked state, and the timer service/ 00740 * daemon task has a priority equal to or greater than the currently executing 00741 * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will 00742 * get set to pdTRUE internally within the xTimerStopFromISR() function. If 00743 * xTimerStopFromISR() sets this value to pdTRUE then a context switch should 00744 * be performed before the interrupt exits. 00745 * 00746 * @return pdFAIL will be returned if the stop command could not be sent to 00747 * the timer command queue. pdPASS will be returned if the command was 00748 * successfully sent to the timer command queue. When the command is actually 00749 * processed will depend on the priority of the timer service/daemon task 00750 * relative to other tasks in the system. The timer service/daemon task 00751 * priority is set by the configTIMER_TASK_PRIORITY configuration constant. 00752 * 00753 * Example usage: 00754 * @verbatim 00755 * // This scenario assumes xTimer has already been created and started. When 00756 * // an interrupt occurs, the timer should be simply stopped. 00757 * 00758 * // The interrupt service routine that stops the timer. 00759 * void vAnExampleInterruptServiceRoutine( void ) 00760 * { 00761 * portBASE_TYPE xHigherPriorityTaskWoken = pdFALSE; 00762 * 00763 * // The interrupt has occurred - simply stop the timer. 00764 * // xHigherPriorityTaskWoken was set to pdFALSE where it was defined 00765 * // (within this function). As this is an interrupt service routine, only 00766 * // FreeRTOS API functions that end in "FromISR" can be used. 00767 * if( xTimerStopFromISR( xTimer, &xHigherPriorityTaskWoken ) != pdPASS ) 00768 * { 00769 * // The stop command was not executed successfully. Take appropriate 00770 * // action here. 00771 * } 00772 * 00773 * // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch 00774 * // should be performed. The syntax required to perform a context switch 00775 * // from inside an ISR varies from port to port, and from compiler to 00776 * // compiler. Inspect the demos for the port you are using to find the 00777 * // actual syntax required. 00778 * if( xHigherPriorityTaskWoken != pdFALSE ) 00779 * { 00780 * // Call the interrupt safe yield function here (actual function 00781 * // depends on the FreeRTOS port being used. 00782 * } 00783 * } 00784 * @endverbatim 00785 */ 00786 #define xTimerStopFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_STOP, 0, ( pxHigherPriorityTaskWoken ), 0U ) 00787 00788 /** 00789 * portBASE_TYPE xTimerChangePeriodFromISR( xTimerHandle xTimer, 00790 * portTickType xNewPeriod, 00791 * portBASE_TYPE *pxHigherPriorityTaskWoken ); 00792 * 00793 * A version of xTimerChangePeriod() that can be called from an interrupt 00794 * service routine. 00795 * 00796 * @param xTimer The handle of the timer that is having its period changed. 00797 * 00798 * @param xNewPeriod The new period for xTimer. Timer periods are specified in 00799 * tick periods, so the constant portTICK_RATE_MS can be used to convert a time 00800 * that has been specified in milliseconds. For example, if the timer must 00801 * expire after 100 ticks, then xNewPeriod should be set to 100. Alternatively, 00802 * if the timer must expire after 500ms, then xNewPeriod can be set to 00803 * ( 500 / portTICK_RATE_MS ) provided configTICK_RATE_HZ is less than 00804 * or equal to 1000. 00805 * 00806 * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most 00807 * of its time in the Blocked state, waiting for messages to arrive on the timer 00808 * command queue. Calling xTimerChangePeriodFromISR() writes a message to the 00809 * timer command queue, so has the potential to transition the timer service/ 00810 * daemon task out of the Blocked state. If calling xTimerChangePeriodFromISR() 00811 * causes the timer service/daemon task to leave the Blocked state, and the 00812 * timer service/daemon task has a priority equal to or greater than the 00813 * currently executing task (the task that was interrupted), then 00814 * *pxHigherPriorityTaskWoken will get set to pdTRUE internally within the 00815 * xTimerChangePeriodFromISR() function. If xTimerChangePeriodFromISR() sets 00816 * this value to pdTRUE then a context switch should be performed before the 00817 * interrupt exits. 00818 * 00819 * @return pdFAIL will be returned if the command to change the timers period 00820 * could not be sent to the timer command queue. pdPASS will be returned if the 00821 * command was successfully sent to the timer command queue. When the command 00822 * is actually processed will depend on the priority of the timer service/daemon 00823 * task relative to other tasks in the system. The timer service/daemon task 00824 * priority is set by the configTIMER_TASK_PRIORITY configuration constant. 00825 * 00826 * Example usage: 00827 * @verbatim 00828 * // This scenario assumes xTimer has already been created and started. When 00829 * // an interrupt occurs, the period of xTimer should be changed to 500ms. 00830 * 00831 * // The interrupt service routine that changes the period of xTimer. 00832 * void vAnExampleInterruptServiceRoutine( void ) 00833 * { 00834 * portBASE_TYPE xHigherPriorityTaskWoken = pdFALSE; 00835 * 00836 * // The interrupt has occurred - change the period of xTimer to 500ms. 00837 * // xHigherPriorityTaskWoken was set to pdFALSE where it was defined 00838 * // (within this function). As this is an interrupt service routine, only 00839 * // FreeRTOS API functions that end in "FromISR" can be used. 00840 * if( xTimerChangePeriodFromISR( xTimer, &xHigherPriorityTaskWoken ) != pdPASS ) 00841 * { 00842 * // The command to change the timers period was not executed 00843 * // successfully. Take appropriate action here. 00844 * } 00845 * 00846 * // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch 00847 * // should be performed. The syntax required to perform a context switch 00848 * // from inside an ISR varies from port to port, and from compiler to 00849 * // compiler. Inspect the demos for the port you are using to find the 00850 * // actual syntax required. 00851 * if( xHigherPriorityTaskWoken != pdFALSE ) 00852 * { 00853 * // Call the interrupt safe yield function here (actual function 00854 * // depends on the FreeRTOS port being used. 00855 * } 00856 * } 00857 * @endverbatim 00858 */ 00859 #define xTimerChangePeriodFromISR( xTimer, xNewPeriod, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_CHANGE_PERIOD, ( xNewPeriod ), ( pxHigherPriorityTaskWoken ), 0U ) 00860 00861 /** 00862 * portBASE_TYPE xTimerResetFromISR( xTimerHandle xTimer, 00863 * portBASE_TYPE *pxHigherPriorityTaskWoken ); 00864 * 00865 * A version of xTimerReset() that can be called from an interrupt service 00866 * routine. 00867 * 00868 * @param xTimer The handle of the timer that is to be started, reset, or 00869 * restarted. 00870 * 00871 * @param pxHigherPriorityTaskWoken The timer service/daemon task spends most 00872 * of its time in the Blocked state, waiting for messages to arrive on the timer 00873 * command queue. Calling xTimerResetFromISR() writes a message to the timer 00874 * command queue, so has the potential to transition the timer service/daemon 00875 * task out of the Blocked state. If calling xTimerResetFromISR() causes the 00876 * timer service/daemon task to leave the Blocked state, and the timer service/ 00877 * daemon task has a priority equal to or greater than the currently executing 00878 * task (the task that was interrupted), then *pxHigherPriorityTaskWoken will 00879 * get set to pdTRUE internally within the xTimerResetFromISR() function. If 00880 * xTimerResetFromISR() sets this value to pdTRUE then a context switch should 00881 * be performed before the interrupt exits. 00882 * 00883 * @return pdFAIL will be returned if the reset command could not be sent to 00884 * the timer command queue. pdPASS will be returned if the command was 00885 * successfully sent to the timer command queue. When the command is actually 00886 * processed will depend on the priority of the timer service/daemon task 00887 * relative to other tasks in the system, although the timers expiry time is 00888 * relative to when xTimerResetFromISR() is actually called. The timer service/daemon 00889 * task priority is set by the configTIMER_TASK_PRIORITY configuration constant. 00890 * 00891 * Example usage: 00892 * @verbatim 00893 * // This scenario assumes xBacklightTimer has already been created. When a 00894 * // key is pressed, an LCD back-light is switched on. If 5 seconds pass 00895 * // without a key being pressed, then the LCD back-light is switched off. In 00896 * // this case, the timer is a one-shot timer, and unlike the example given for 00897 * // the xTimerReset() function, the key press event handler is an interrupt 00898 * // service routine. 00899 * 00900 * // The callback function assigned to the one-shot timer. In this case the 00901 * // parameter is not used. 00902 * void vBacklightTimerCallback( xTimerHandle pxTimer ) 00903 * { 00904 * // The timer expired, therefore 5 seconds must have passed since a key 00905 * // was pressed. Switch off the LCD back-light. 00906 * vSetBacklightState( BACKLIGHT_OFF ); 00907 * } 00908 * 00909 * // The key press interrupt service routine. 00910 * void vKeyPressEventInterruptHandler( void ) 00911 * { 00912 * portBASE_TYPE xHigherPriorityTaskWoken = pdFALSE; 00913 * 00914 * // Ensure the LCD back-light is on, then reset the timer that is 00915 * // responsible for turning the back-light off after 5 seconds of 00916 * // key inactivity. This is an interrupt service routine so can only 00917 * // call FreeRTOS API functions that end in "FromISR". 00918 * vSetBacklightState( BACKLIGHT_ON ); 00919 * 00920 * // xTimerStartFromISR() or xTimerResetFromISR() could be called here 00921 * // as both cause the timer to re-calculate its expiry time. 00922 * // xHigherPriorityTaskWoken was initialised to pdFALSE when it was 00923 * // declared (in this function). 00924 * if( xTimerResetFromISR( xBacklightTimer, &xHigherPriorityTaskWoken ) != pdPASS ) 00925 * { 00926 * // The reset command was not executed successfully. Take appropriate 00927 * // action here. 00928 * } 00929 * 00930 * // Perform the rest of the key processing here. 00931 * 00932 * // If xHigherPriorityTaskWoken equals pdTRUE, then a context switch 00933 * // should be performed. The syntax required to perform a context switch 00934 * // from inside an ISR varies from port to port, and from compiler to 00935 * // compiler. Inspect the demos for the port you are using to find the 00936 * // actual syntax required. 00937 * if( xHigherPriorityTaskWoken != pdFALSE ) 00938 * { 00939 * // Call the interrupt safe yield function here (actual function 00940 * // depends on the FreeRTOS port being used. 00941 * } 00942 * } 00943 * @endverbatim 00944 */ 00945 #define xTimerResetFromISR( xTimer, pxHigherPriorityTaskWoken ) xTimerGenericCommand( ( xTimer ), tmrCOMMAND_START, ( xTaskGetTickCountFromISR() ), ( pxHigherPriorityTaskWoken ), 0U ) 00946 00947 /* 00948 * Functions beyond this part are not part of the public API and are intended 00949 * for use by the kernel only. 00950 */ 00951 portBASE_TYPE xTimerCreateTimerTask( void ) PRIVILEGED_FUNCTION; 00952 portBASE_TYPE xTimerGenericCommand( xTimerHandle xTimer, portBASE_TYPE xCommandID, portTickType xOptionalValue, signed portBASE_TYPE *pxHigherPriorityTaskWoken, portTickType xBlockTime ) PRIVILEGED_FUNCTION; 00953 00954 #ifdef __cplusplus 00955 } 00956 #endif 00957 #endif /* TIMERS_H */ 00958 00959 00960
Generated on Tue Jul 12 2022 11:36:40 by
1.7.2