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