Rohit Grover
www.freertos.org
Dependents: Nucleo freertos_test FreeRTOS_test freertos_bluetooth ... more
Embed:
(wiki syntax)
Show/hide line numbers
croutine.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 #ifndef CO_ROUTINE_H 00067 #define CO_ROUTINE_H 00068 00069 #ifndef INC_FREERTOS_H 00070 #error "include FreeRTOS.h must appear in source files before include croutine.h" 00071 #endif 00072 00073 #include "list.h" 00074 00075 #ifdef __cplusplus 00076 extern "C" { 00077 #endif 00078 00079 /* Used to hide the implementation of the co-routine control block. The 00080 control block structure however has to be included in the header due to 00081 the macro implementation of the co-routine functionality. */ 00082 typedef void * xCoRoutineHandle; 00083 00084 /* Defines the prototype to which co-routine functions must conform. */ 00085 typedef void (*crCOROUTINE_CODE)( xCoRoutineHandle, unsigned portBASE_TYPE ); 00086 00087 typedef struct corCoRoutineControlBlock 00088 { 00089 crCOROUTINE_CODE pxCoRoutineFunction; 00090 xListItem xGenericListItem; /*< List item used to place the CRCB in ready and blocked queues. */ 00091 xListItem xEventListItem; /*< List item used to place the CRCB in event lists. */ 00092 unsigned portBASE_TYPE uxPriority; /*< The priority of the co-routine in relation to other co-routines. */ 00093 unsigned portBASE_TYPE uxIndex; /*< Used to distinguish between co-routines when multiple co-routines use the same co-routine function. */ 00094 unsigned short uxState; /*< Used internally by the co-routine implementation. */ 00095 } corCRCB; /* Co-routine control block. Note must be identical in size down to uxPriority with tskTCB. */ 00096 00097 /** 00098 * croutine. h 00099 *<pre> 00100 portBASE_TYPE xCoRoutineCreate( 00101 crCOROUTINE_CODE pxCoRoutineCode, 00102 unsigned portBASE_TYPE uxPriority, 00103 unsigned portBASE_TYPE uxIndex 00104 );</pre> 00105 * 00106 * Create a new co-routine and add it to the list of co-routines that are 00107 * ready to run. 00108 * 00109 * @param pxCoRoutineCode Pointer to the co-routine function. Co-routine 00110 * functions require special syntax - see the co-routine section of the WEB 00111 * documentation for more information. 00112 * 00113 * @param uxPriority The priority with respect to other co-routines at which 00114 * the co-routine will run. 00115 * 00116 * @param uxIndex Used to distinguish between different co-routines that 00117 * execute the same function. See the example below and the co-routine section 00118 * of the WEB documentation for further information. 00119 * 00120 * @return pdPASS if the co-routine was successfully created and added to a ready 00121 * list, otherwise an error code defined with ProjDefs.h. 00122 * 00123 * Example usage: 00124 <pre> 00125 // Co-routine to be created. 00126 void vFlashCoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex ) 00127 { 00128 // Variables in co-routines must be declared static if they must maintain value across a blocking call. 00129 // This may not be necessary for const variables. 00130 static const char cLedToFlash[ 2 ] = { 5, 6 }; 00131 static const portTickType uxFlashRates[ 2 ] = { 200, 400 }; 00132 00133 // Must start every co-routine with a call to crSTART(); 00134 crSTART( xHandle ); 00135 00136 for( ;; ) 00137 { 00138 // This co-routine just delays for a fixed period, then toggles 00139 // an LED. Two co-routines are created using this function, so 00140 // the uxIndex parameter is used to tell the co-routine which 00141 // LED to flash and how long to delay. This assumes xQueue has 00142 // already been created. 00143 vParTestToggleLED( cLedToFlash[ uxIndex ] ); 00144 crDELAY( xHandle, uxFlashRates[ uxIndex ] ); 00145 } 00146 00147 // Must end every co-routine with a call to crEND(); 00148 crEND(); 00149 } 00150 00151 // Function that creates two co-routines. 00152 void vOtherFunction( void ) 00153 { 00154 unsigned char ucParameterToPass; 00155 xTaskHandle xHandle; 00156 00157 // Create two co-routines at priority 0. The first is given index 0 00158 // so (from the code above) toggles LED 5 every 200 ticks. The second 00159 // is given index 1 so toggles LED 6 every 400 ticks. 00160 for( uxIndex = 0; uxIndex < 2; uxIndex++ ) 00161 { 00162 xCoRoutineCreate( vFlashCoRoutine, 0, uxIndex ); 00163 } 00164 } 00165 </pre> 00166 * \defgroup xCoRoutineCreate xCoRoutineCreate 00167 * \ingroup Tasks 00168 */ 00169 signed portBASE_TYPE xCoRoutineCreate( crCOROUTINE_CODE pxCoRoutineCode, unsigned portBASE_TYPE uxPriority, unsigned portBASE_TYPE uxIndex ); 00170 00171 00172 /** 00173 * croutine. h 00174 *<pre> 00175 void vCoRoutineSchedule( void );</pre> 00176 * 00177 * Run a co-routine. 00178 * 00179 * vCoRoutineSchedule() executes the highest priority co-routine that is able 00180 * to run. The co-routine will execute until it either blocks, yields or is 00181 * preempted by a task. Co-routines execute cooperatively so one 00182 * co-routine cannot be preempted by another, but can be preempted by a task. 00183 * 00184 * If an application comprises of both tasks and co-routines then 00185 * vCoRoutineSchedule should be called from the idle task (in an idle task 00186 * hook). 00187 * 00188 * Example usage: 00189 <pre> 00190 // This idle task hook will schedule a co-routine each time it is called. 00191 // The rest of the idle task will execute between co-routine calls. 00192 void vApplicationIdleHook( void ) 00193 { 00194 vCoRoutineSchedule(); 00195 } 00196 00197 // Alternatively, if you do not require any other part of the idle task to 00198 // execute, the idle task hook can call vCoRoutineScheduler() within an 00199 // infinite loop. 00200 void vApplicationIdleHook( void ) 00201 { 00202 for( ;; ) 00203 { 00204 vCoRoutineSchedule(); 00205 } 00206 } 00207 </pre> 00208 * \defgroup vCoRoutineSchedule vCoRoutineSchedule 00209 * \ingroup Tasks 00210 */ 00211 void vCoRoutineSchedule( void ); 00212 00213 /** 00214 * croutine. h 00215 * <pre> 00216 crSTART( xCoRoutineHandle xHandle );</pre> 00217 * 00218 * This macro MUST always be called at the start of a co-routine function. 00219 * 00220 * Example usage: 00221 <pre> 00222 // Co-routine to be created. 00223 void vACoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex ) 00224 { 00225 // Variables in co-routines must be declared static if they must maintain value across a blocking call. 00226 static long ulAVariable; 00227 00228 // Must start every co-routine with a call to crSTART(); 00229 crSTART( xHandle ); 00230 00231 for( ;; ) 00232 { 00233 // Co-routine functionality goes here. 00234 } 00235 00236 // Must end every co-routine with a call to crEND(); 00237 crEND(); 00238 }</pre> 00239 * \defgroup crSTART crSTART 00240 * \ingroup Tasks 00241 */ 00242 #define crSTART( pxCRCB ) switch( ( ( corCRCB * )( pxCRCB ) )->uxState ) { case 0: 00243 00244 /** 00245 * croutine. h 00246 * <pre> 00247 crEND();</pre> 00248 * 00249 * This macro MUST always be called at the end of a co-routine function. 00250 * 00251 * Example usage: 00252 <pre> 00253 // Co-routine to be created. 00254 void vACoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex ) 00255 { 00256 // Variables in co-routines must be declared static if they must maintain value across a blocking call. 00257 static long ulAVariable; 00258 00259 // Must start every co-routine with a call to crSTART(); 00260 crSTART( xHandle ); 00261 00262 for( ;; ) 00263 { 00264 // Co-routine functionality goes here. 00265 } 00266 00267 // Must end every co-routine with a call to crEND(); 00268 crEND(); 00269 }</pre> 00270 * \defgroup crSTART crSTART 00271 * \ingroup Tasks 00272 */ 00273 #define crEND() } 00274 00275 /* 00276 * These macros are intended for internal use by the co-routine implementation 00277 * only. The macros should not be used directly by application writers. 00278 */ 00279 #define crSET_STATE0( xHandle ) ( ( corCRCB * )( xHandle ) )->uxState = (__LINE__ * 2); return; case (__LINE__ * 2): 00280 #define crSET_STATE1( xHandle ) ( ( corCRCB * )( xHandle ) )->uxState = ((__LINE__ * 2)+1); return; case ((__LINE__ * 2)+1): 00281 00282 /** 00283 * croutine. h 00284 *<pre> 00285 crDELAY( xCoRoutineHandle xHandle, portTickType xTicksToDelay );</pre> 00286 * 00287 * Delay a co-routine for a fixed period of time. 00288 * 00289 * crDELAY can only be called from the co-routine function itself - not 00290 * from within a function called by the co-routine function. This is because 00291 * co-routines do not maintain their own stack. 00292 * 00293 * @param xHandle The handle of the co-routine to delay. This is the xHandle 00294 * parameter of the co-routine function. 00295 * 00296 * @param xTickToDelay The number of ticks that the co-routine should delay 00297 * for. The actual amount of time this equates to is defined by 00298 * configTICK_RATE_HZ (set in FreeRTOSConfig.h). The constant portTICK_RATE_MS 00299 * can be used to convert ticks to milliseconds. 00300 * 00301 * Example usage: 00302 <pre> 00303 // Co-routine to be created. 00304 void vACoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex ) 00305 { 00306 // Variables in co-routines must be declared static if they must maintain value across a blocking call. 00307 // This may not be necessary for const variables. 00308 // We are to delay for 200ms. 00309 static const xTickType xDelayTime = 200 / portTICK_RATE_MS; 00310 00311 // Must start every co-routine with a call to crSTART(); 00312 crSTART( xHandle ); 00313 00314 for( ;; ) 00315 { 00316 // Delay for 200ms. 00317 crDELAY( xHandle, xDelayTime ); 00318 00319 // Do something here. 00320 } 00321 00322 // Must end every co-routine with a call to crEND(); 00323 crEND(); 00324 }</pre> 00325 * \defgroup crDELAY crDELAY 00326 * \ingroup Tasks 00327 */ 00328 #define crDELAY( xHandle, xTicksToDelay ) \ 00329 if( ( xTicksToDelay ) > 0 ) \ 00330 { \ 00331 vCoRoutineAddToDelayedList( ( xTicksToDelay ), NULL ); \ 00332 } \ 00333 crSET_STATE0( ( xHandle ) ); 00334 00335 /** 00336 * <pre> 00337 crQUEUE_SEND( 00338 xCoRoutineHandle xHandle, 00339 xQueueHandle pxQueue, 00340 void *pvItemToQueue, 00341 portTickType xTicksToWait, 00342 portBASE_TYPE *pxResult 00343 )</pre> 00344 * 00345 * The macro's crQUEUE_SEND() and crQUEUE_RECEIVE() are the co-routine 00346 * equivalent to the xQueueSend() and xQueueReceive() functions used by tasks. 00347 * 00348 * crQUEUE_SEND and crQUEUE_RECEIVE can only be used from a co-routine whereas 00349 * xQueueSend() and xQueueReceive() can only be used from tasks. 00350 * 00351 * crQUEUE_SEND can only be called from the co-routine function itself - not 00352 * from within a function called by the co-routine function. This is because 00353 * co-routines do not maintain their own stack. 00354 * 00355 * See the co-routine section of the WEB documentation for information on 00356 * passing data between tasks and co-routines and between ISR's and 00357 * co-routines. 00358 * 00359 * @param xHandle The handle of the calling co-routine. This is the xHandle 00360 * parameter of the co-routine function. 00361 * 00362 * @param pxQueue The handle of the queue on which the data will be posted. 00363 * The handle is obtained as the return value when the queue is created using 00364 * the xQueueCreate() API function. 00365 * 00366 * @param pvItemToQueue A pointer to the data being posted onto the queue. 00367 * The number of bytes of each queued item is specified when the queue is 00368 * created. This number of bytes is copied from pvItemToQueue into the queue 00369 * itself. 00370 * 00371 * @param xTickToDelay The number of ticks that the co-routine should block 00372 * to wait for space to become available on the queue, should space not be 00373 * available immediately. The actual amount of time this equates to is defined 00374 * by configTICK_RATE_HZ (set in FreeRTOSConfig.h). The constant 00375 * portTICK_RATE_MS can be used to convert ticks to milliseconds (see example 00376 * below). 00377 * 00378 * @param pxResult The variable pointed to by pxResult will be set to pdPASS if 00379 * data was successfully posted onto the queue, otherwise it will be set to an 00380 * error defined within ProjDefs.h. 00381 * 00382 * Example usage: 00383 <pre> 00384 // Co-routine function that blocks for a fixed period then posts a number onto 00385 // a queue. 00386 static void prvCoRoutineFlashTask( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex ) 00387 { 00388 // Variables in co-routines must be declared static if they must maintain value across a blocking call. 00389 static portBASE_TYPE xNumberToPost = 0; 00390 static portBASE_TYPE xResult; 00391 00392 // Co-routines must begin with a call to crSTART(). 00393 crSTART( xHandle ); 00394 00395 for( ;; ) 00396 { 00397 // This assumes the queue has already been created. 00398 crQUEUE_SEND( xHandle, xCoRoutineQueue, &xNumberToPost, NO_DELAY, &xResult ); 00399 00400 if( xResult != pdPASS ) 00401 { 00402 // The message was not posted! 00403 } 00404 00405 // Increment the number to be posted onto the queue. 00406 xNumberToPost++; 00407 00408 // Delay for 100 ticks. 00409 crDELAY( xHandle, 100 ); 00410 } 00411 00412 // Co-routines must end with a call to crEND(). 00413 crEND(); 00414 }</pre> 00415 * \defgroup crQUEUE_SEND crQUEUE_SEND 00416 * \ingroup Tasks 00417 */ 00418 #define crQUEUE_SEND( xHandle, pxQueue, pvItemToQueue, xTicksToWait, pxResult ) \ 00419 { \ 00420 *( pxResult ) = xQueueCRSend( ( pxQueue) , ( pvItemToQueue) , ( xTicksToWait ) ); \ 00421 if( *( pxResult ) == errQUEUE_BLOCKED ) \ 00422 { \ 00423 crSET_STATE0( ( xHandle ) ); \ 00424 *pxResult = xQueueCRSend( ( pxQueue ), ( pvItemToQueue ), 0 ); \ 00425 } \ 00426 if( *pxResult == errQUEUE_YIELD ) \ 00427 { \ 00428 crSET_STATE1( ( xHandle ) ); \ 00429 *pxResult = pdPASS; \ 00430 } \ 00431 } 00432 00433 /** 00434 * croutine. h 00435 * <pre> 00436 crQUEUE_RECEIVE( 00437 xCoRoutineHandle xHandle, 00438 xQueueHandle pxQueue, 00439 void *pvBuffer, 00440 portTickType xTicksToWait, 00441 portBASE_TYPE *pxResult 00442 )</pre> 00443 * 00444 * The macro's crQUEUE_SEND() and crQUEUE_RECEIVE() are the co-routine 00445 * equivalent to the xQueueSend() and xQueueReceive() functions used by tasks. 00446 * 00447 * crQUEUE_SEND and crQUEUE_RECEIVE can only be used from a co-routine whereas 00448 * xQueueSend() and xQueueReceive() can only be used from tasks. 00449 * 00450 * crQUEUE_RECEIVE can only be called from the co-routine function itself - not 00451 * from within a function called by the co-routine function. This is because 00452 * co-routines do not maintain their own stack. 00453 * 00454 * See the co-routine section of the WEB documentation for information on 00455 * passing data between tasks and co-routines and between ISR's and 00456 * co-routines. 00457 * 00458 * @param xHandle The handle of the calling co-routine. This is the xHandle 00459 * parameter of the co-routine function. 00460 * 00461 * @param pxQueue The handle of the queue from which the data will be received. 00462 * The handle is obtained as the return value when the queue is created using 00463 * the xQueueCreate() API function. 00464 * 00465 * @param pvBuffer The buffer into which the received item is to be copied. 00466 * The number of bytes of each queued item is specified when the queue is 00467 * created. This number of bytes is copied into pvBuffer. 00468 * 00469 * @param xTickToDelay The number of ticks that the co-routine should block 00470 * to wait for data to become available from the queue, should data not be 00471 * available immediately. The actual amount of time this equates to is defined 00472 * by configTICK_RATE_HZ (set in FreeRTOSConfig.h). The constant 00473 * portTICK_RATE_MS can be used to convert ticks to milliseconds (see the 00474 * crQUEUE_SEND example). 00475 * 00476 * @param pxResult The variable pointed to by pxResult will be set to pdPASS if 00477 * data was successfully retrieved from the queue, otherwise it will be set to 00478 * an error code as defined within ProjDefs.h. 00479 * 00480 * Example usage: 00481 <pre> 00482 // A co-routine receives the number of an LED to flash from a queue. It 00483 // blocks on the queue until the number is received. 00484 static void prvCoRoutineFlashWorkTask( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex ) 00485 { 00486 // Variables in co-routines must be declared static if they must maintain value across a blocking call. 00487 static portBASE_TYPE xResult; 00488 static unsigned portBASE_TYPE uxLEDToFlash; 00489 00490 // All co-routines must start with a call to crSTART(). 00491 crSTART( xHandle ); 00492 00493 for( ;; ) 00494 { 00495 // Wait for data to become available on the queue. 00496 crQUEUE_RECEIVE( xHandle, xCoRoutineQueue, &uxLEDToFlash, portMAX_DELAY, &xResult ); 00497 00498 if( xResult == pdPASS ) 00499 { 00500 // We received the LED to flash - flash it! 00501 vParTestToggleLED( uxLEDToFlash ); 00502 } 00503 } 00504 00505 crEND(); 00506 }</pre> 00507 * \defgroup crQUEUE_RECEIVE crQUEUE_RECEIVE 00508 * \ingroup Tasks 00509 */ 00510 #define crQUEUE_RECEIVE( xHandle, pxQueue, pvBuffer, xTicksToWait, pxResult ) \ 00511 { \ 00512 *( pxResult ) = xQueueCRReceive( ( pxQueue) , ( pvBuffer ), ( xTicksToWait ) ); \ 00513 if( *( pxResult ) == errQUEUE_BLOCKED ) \ 00514 { \ 00515 crSET_STATE0( ( xHandle ) ); \ 00516 *( pxResult ) = xQueueCRReceive( ( pxQueue) , ( pvBuffer ), 0 ); \ 00517 } \ 00518 if( *( pxResult ) == errQUEUE_YIELD ) \ 00519 { \ 00520 crSET_STATE1( ( xHandle ) ); \ 00521 *( pxResult ) = pdPASS; \ 00522 } \ 00523 } 00524 00525 /** 00526 * croutine. h 00527 * <pre> 00528 crQUEUE_SEND_FROM_ISR( 00529 xQueueHandle pxQueue, 00530 void *pvItemToQueue, 00531 portBASE_TYPE xCoRoutinePreviouslyWoken 00532 )</pre> 00533 * 00534 * The macro's crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() are the 00535 * co-routine equivalent to the xQueueSendFromISR() and xQueueReceiveFromISR() 00536 * functions used by tasks. 00537 * 00538 * crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() can only be used to 00539 * pass data between a co-routine and and ISR, whereas xQueueSendFromISR() and 00540 * xQueueReceiveFromISR() can only be used to pass data between a task and and 00541 * ISR. 00542 * 00543 * crQUEUE_SEND_FROM_ISR can only be called from an ISR to send data to a queue 00544 * that is being used from within a co-routine. 00545 * 00546 * See the co-routine section of the WEB documentation for information on 00547 * passing data between tasks and co-routines and between ISR's and 00548 * co-routines. 00549 * 00550 * @param xQueue The handle to the queue on which the item is to be posted. 00551 * 00552 * @param pvItemToQueue A pointer to the item that is to be placed on the 00553 * queue. The size of the items the queue will hold was defined when the 00554 * queue was created, so this many bytes will be copied from pvItemToQueue 00555 * into the queue storage area. 00556 * 00557 * @param xCoRoutinePreviouslyWoken This is included so an ISR can post onto 00558 * the same queue multiple times from a single interrupt. The first call 00559 * should always pass in pdFALSE. Subsequent calls should pass in 00560 * the value returned from the previous call. 00561 * 00562 * @return pdTRUE if a co-routine was woken by posting onto the queue. This is 00563 * used by the ISR to determine if a context switch may be required following 00564 * the ISR. 00565 * 00566 * Example usage: 00567 <pre> 00568 // A co-routine that blocks on a queue waiting for characters to be received. 00569 static void vReceivingCoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex ) 00570 { 00571 char cRxedChar; 00572 portBASE_TYPE xResult; 00573 00574 // All co-routines must start with a call to crSTART(). 00575 crSTART( xHandle ); 00576 00577 for( ;; ) 00578 { 00579 // Wait for data to become available on the queue. This assumes the 00580 // queue xCommsRxQueue has already been created! 00581 crQUEUE_RECEIVE( xHandle, xCommsRxQueue, &uxLEDToFlash, portMAX_DELAY, &xResult ); 00582 00583 // Was a character received? 00584 if( xResult == pdPASS ) 00585 { 00586 // Process the character here. 00587 } 00588 } 00589 00590 // All co-routines must end with a call to crEND(). 00591 crEND(); 00592 } 00593 00594 // An ISR that uses a queue to send characters received on a serial port to 00595 // a co-routine. 00596 void vUART_ISR( void ) 00597 { 00598 char cRxedChar; 00599 portBASE_TYPE xCRWokenByPost = pdFALSE; 00600 00601 // We loop around reading characters until there are none left in the UART. 00602 while( UART_RX_REG_NOT_EMPTY() ) 00603 { 00604 // Obtain the character from the UART. 00605 cRxedChar = UART_RX_REG; 00606 00607 // Post the character onto a queue. xCRWokenByPost will be pdFALSE 00608 // the first time around the loop. If the post causes a co-routine 00609 // to be woken (unblocked) then xCRWokenByPost will be set to pdTRUE. 00610 // In this manner we can ensure that if more than one co-routine is 00611 // blocked on the queue only one is woken by this ISR no matter how 00612 // many characters are posted to the queue. 00613 xCRWokenByPost = crQUEUE_SEND_FROM_ISR( xCommsRxQueue, &cRxedChar, xCRWokenByPost ); 00614 } 00615 }</pre> 00616 * \defgroup crQUEUE_SEND_FROM_ISR crQUEUE_SEND_FROM_ISR 00617 * \ingroup Tasks 00618 */ 00619 #define crQUEUE_SEND_FROM_ISR( pxQueue, pvItemToQueue, xCoRoutinePreviouslyWoken ) xQueueCRSendFromISR( ( pxQueue ), ( pvItemToQueue ), ( xCoRoutinePreviouslyWoken ) ) 00620 00621 00622 /** 00623 * croutine. h 00624 * <pre> 00625 crQUEUE_SEND_FROM_ISR( 00626 xQueueHandle pxQueue, 00627 void *pvBuffer, 00628 portBASE_TYPE * pxCoRoutineWoken 00629 )</pre> 00630 * 00631 * The macro's crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() are the 00632 * co-routine equivalent to the xQueueSendFromISR() and xQueueReceiveFromISR() 00633 * functions used by tasks. 00634 * 00635 * crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() can only be used to 00636 * pass data between a co-routine and and ISR, whereas xQueueSendFromISR() and 00637 * xQueueReceiveFromISR() can only be used to pass data between a task and and 00638 * ISR. 00639 * 00640 * crQUEUE_RECEIVE_FROM_ISR can only be called from an ISR to receive data 00641 * from a queue that is being used from within a co-routine (a co-routine 00642 * posted to the queue). 00643 * 00644 * See the co-routine section of the WEB documentation for information on 00645 * passing data between tasks and co-routines and between ISR's and 00646 * co-routines. 00647 * 00648 * @param xQueue The handle to the queue on which the item is to be posted. 00649 * 00650 * @param pvBuffer A pointer to a buffer into which the received item will be 00651 * placed. The size of the items the queue will hold was defined when the 00652 * queue was created, so this many bytes will be copied from the queue into 00653 * pvBuffer. 00654 * 00655 * @param pxCoRoutineWoken A co-routine may be blocked waiting for space to become 00656 * available on the queue. If crQUEUE_RECEIVE_FROM_ISR causes such a 00657 * co-routine to unblock *pxCoRoutineWoken will get set to pdTRUE, otherwise 00658 * *pxCoRoutineWoken will remain unchanged. 00659 * 00660 * @return pdTRUE an item was successfully received from the queue, otherwise 00661 * pdFALSE. 00662 * 00663 * Example usage: 00664 <pre> 00665 // A co-routine that posts a character to a queue then blocks for a fixed 00666 // period. The character is incremented each time. 00667 static void vSendingCoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex ) 00668 { 00669 // cChar holds its value while this co-routine is blocked and must therefore 00670 // be declared static. 00671 static char cCharToTx = 'a'; 00672 portBASE_TYPE xResult; 00673 00674 // All co-routines must start with a call to crSTART(). 00675 crSTART( xHandle ); 00676 00677 for( ;; ) 00678 { 00679 // Send the next character to the queue. 00680 crQUEUE_SEND( xHandle, xCoRoutineQueue, &cCharToTx, NO_DELAY, &xResult ); 00681 00682 if( xResult == pdPASS ) 00683 { 00684 // The character was successfully posted to the queue. 00685 } 00686 else 00687 { 00688 // Could not post the character to the queue. 00689 } 00690 00691 // Enable the UART Tx interrupt to cause an interrupt in this 00692 // hypothetical UART. The interrupt will obtain the character 00693 // from the queue and send it. 00694 ENABLE_RX_INTERRUPT(); 00695 00696 // Increment to the next character then block for a fixed period. 00697 // cCharToTx will maintain its value across the delay as it is 00698 // declared static. 00699 cCharToTx++; 00700 if( cCharToTx > 'x' ) 00701 { 00702 cCharToTx = 'a'; 00703 } 00704 crDELAY( 100 ); 00705 } 00706 00707 // All co-routines must end with a call to crEND(). 00708 crEND(); 00709 } 00710 00711 // An ISR that uses a queue to receive characters to send on a UART. 00712 void vUART_ISR( void ) 00713 { 00714 char cCharToTx; 00715 portBASE_TYPE xCRWokenByPost = pdFALSE; 00716 00717 while( UART_TX_REG_EMPTY() ) 00718 { 00719 // Are there any characters in the queue waiting to be sent? 00720 // xCRWokenByPost will automatically be set to pdTRUE if a co-routine 00721 // is woken by the post - ensuring that only a single co-routine is 00722 // woken no matter how many times we go around this loop. 00723 if( crQUEUE_RECEIVE_FROM_ISR( pxQueue, &cCharToTx, &xCRWokenByPost ) ) 00724 { 00725 SEND_CHARACTER( cCharToTx ); 00726 } 00727 } 00728 }</pre> 00729 * \defgroup crQUEUE_RECEIVE_FROM_ISR crQUEUE_RECEIVE_FROM_ISR 00730 * \ingroup Tasks 00731 */ 00732 #define crQUEUE_RECEIVE_FROM_ISR( pxQueue, pvBuffer, pxCoRoutineWoken ) xQueueCRReceiveFromISR( ( pxQueue ), ( pvBuffer ), ( pxCoRoutineWoken ) ) 00733 00734 /* 00735 * This function is intended for internal use by the co-routine macros only. 00736 * The macro nature of the co-routine implementation requires that the 00737 * prototype appears here. The function should not be used by application 00738 * writers. 00739 * 00740 * Removes the current co-routine from its ready list and places it in the 00741 * appropriate delayed list. 00742 */ 00743 void vCoRoutineAddToDelayedList( portTickType xTicksToDelay, xList *pxEventList ); 00744 00745 /* 00746 * This function is intended for internal use by the queue implementation only. 00747 * The function should not be used by application writers. 00748 * 00749 * Removes the highest priority co-routine from the event list and places it in 00750 * the pending ready list. 00751 */ 00752 signed portBASE_TYPE xCoRoutineRemoveFromEventList( const xList *pxEventList ); 00753 00754 #ifdef __cplusplus 00755 } 00756 #endif 00757 00758 #endif /* CO_ROUTINE_H */
Generated on Tue Jul 12 2022 11:36:40 by
1.7.2