| blob | ee7ae19b9a5ae195847a716f5ae90e360cc4ae7a |
1 /*
2 FreeRTOS V6.0.5 - Copyright (C) 2010 Real Time Engineers Ltd.
4 ***************************************************************************
5 * *
6 * If you are: *
7 * *
8 * + New to FreeRTOS, *
9 * + Wanting to learn FreeRTOS or multitasking in general quickly *
10 * + Looking for basic training, *
11 * + Wanting to improve your FreeRTOS skills and productivity *
12 * *
13 * then take a look at the FreeRTOS eBook *
14 * *
15 * "Using the FreeRTOS Real Time Kernel - a Practical Guide" *
16 * http://www.FreeRTOS.org/Documentation *
17 * *
18 * A pdf reference manual is also available. Both are usually delivered *
19 * to your inbox within 20 minutes to two hours when purchased between 8am *
20 * and 8pm GMT (although please allow up to 24 hours in case of *
21 * exceptional circumstances). Thank you for your support! *
22 * *
23 ***************************************************************************
25 This file is part of the FreeRTOS distribution.
27 FreeRTOS is free software; you can redistribute it and/or modify it under
28 the terms of the GNU General Public License (version 2) as published by the
29 Free Software Foundation AND MODIFIED BY the FreeRTOS exception.
30 ***NOTE*** The exception to the GPL is included to allow you to distribute
31 a combined work that includes FreeRTOS without being obliged to provide the
32 source code for proprietary components outside of the FreeRTOS kernel.
33 FreeRTOS is distributed in the hope that it will be useful, but WITHOUT
34 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
35 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
36 more details. You should have received a copy of the GNU General Public
37 License and the FreeRTOS license exception along with FreeRTOS; if not it
38 can be viewed here: http://www.freertos.org/a00114.html and also obtained
39 by writing to Richard Barry, contact details for whom are available on the
40 FreeRTOS WEB site.
42 1 tab == 4 spaces!
44 http://www.FreeRTOS.org - Documentation, latest information, license and
45 contact details.
47 http://www.SafeRTOS.com - A version that is certified for use in safety
48 critical systems.
50 http://www.OpenRTOS.com - Commercial support, development, porting,
51 licensing and training services.
52 */
54 #ifndef INC_FREERTOS_H
56 #endif
61 #ifndef CO_ROUTINE_H
62 #define CO_ROUTINE_H
66 #ifdef __cplusplus
68 #endif
70 /* Used to hide the implementation of the co-routine control block. The
71 control block structure however has to be included in the header due to
72 the macro implementation of the co-routine functionality. */
75 /* Defines the prototype to which co-routine functions must conform. */
79 {
80 crCOROUTINE_CODE pxCoRoutineFunction;
83 unsigned portBASE_TYPE uxPriority; /*< The priority of the co-routine in relation to other co-routines. */
84 unsigned portBASE_TYPE uxIndex; /*< Used to distinguish between co-routines when multiple co-routines use the same co-routine function. */
86 } corCRCB; /* Co-routine control block. Note must be identical in size down to uxPriority with tskTCB. */
88 /**
89 * croutine. h
90 *<pre>
91 portBASE_TYPE xCoRoutineCreate(
92 crCOROUTINE_CODE pxCoRoutineCode,
93 unsigned portBASE_TYPE uxPriority,
94 unsigned portBASE_TYPE uxIndex
95 );</pre>
96 *
97 * Create a new co-routine and add it to the list of co-routines that are
98 * ready to run.
99 *
100 * @param pxCoRoutineCode Pointer to the co-routine function. Co-routine
101 * functions require special syntax - see the co-routine section of the WEB
102 * documentation for more information.
103 *
104 * @param uxPriority The priority with respect to other co-routines at which
105 * the co-routine will run.
106 *
107 * @param uxIndex Used to distinguish between different co-routines that
108 * execute the same function. See the example below and the co-routine section
109 * of the WEB documentation for further information.
110 *
111 * @return pdPASS if the co-routine was successfully created and added to a ready
112 * list, otherwise an error code defined with ProjDefs.h.
113 *
114 * Example usage:
115 <pre>
116 // Co-routine to be created.
117 void vFlashCoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )
118 {
119 // Variables in co-routines must be declared static if they must maintain value across a blocking call.
120 // This may not be necessary for const variables.
121 static const char cLedToFlash[ 2 ] = { 5, 6 };
122 static const portTickType uxFlashRates[ 2 ] = { 200, 400 };
124 // Must start every co-routine with a call to crSTART();
125 crSTART( xHandle );
127 for( ;; )
128 {
129 // This co-routine just delays for a fixed period, then toggles
130 // an LED. Two co-routines are created using this function, so
131 // the uxIndex parameter is used to tell the co-routine which
132 // LED to flash and how long to delay. This assumes xQueue has
133 // already been created.
134 vParTestToggleLED( cLedToFlash[ uxIndex ] );
135 crDELAY( xHandle, uxFlashRates[ uxIndex ] );
136 }
138 // Must end every co-routine with a call to crEND();
139 crEND();
140 }
142 // Function that creates two co-routines.
143 void vOtherFunction( void )
144 {
145 unsigned char ucParameterToPass;
146 xTaskHandle xHandle;
148 // Create two co-routines at priority 0. The first is given index 0
149 // so (from the code above) toggles LED 5 every 200 ticks. The second
150 // is given index 1 so toggles LED 6 every 400 ticks.
151 for( uxIndex = 0; uxIndex < 2; uxIndex++ )
152 {
153 xCoRoutineCreate( vFlashCoRoutine, 0, uxIndex );
154 }
155 }
156 </pre>
157 * \defgroup xCoRoutineCreate xCoRoutineCreate
158 * \ingroup Tasks
159 */
160 signed portBASE_TYPE xCoRoutineCreate( crCOROUTINE_CODE pxCoRoutineCode, unsigned portBASE_TYPE uxPriority, unsigned portBASE_TYPE uxIndex );
163 /**
164 * croutine. h
165 *<pre>
166 void vCoRoutineSchedule( void );</pre>
167 *
168 * Run a co-routine.
169 *
170 * vCoRoutineSchedule() executes the highest priority co-routine that is able
171 * to run. The co-routine will execute until it either blocks, yields or is
172 * preempted by a task. Co-routines execute cooperatively so one
173 * co-routine cannot be preempted by another, but can be preempted by a task.
174 *
175 * If an application comprises of both tasks and co-routines then
176 * vCoRoutineSchedule should be called from the idle task (in an idle task
177 * hook).
178 *
179 * Example usage:
180 <pre>
181 // This idle task hook will schedule a co-routine each time it is called.
182 // The rest of the idle task will execute between co-routine calls.
183 void vApplicationIdleHook( void )
184 {
185 vCoRoutineSchedule();
186 }
188 // Alternatively, if you do not require any other part of the idle task to
189 // execute, the idle task hook can call vCoRoutineScheduler() within an
190 // infinite loop.
191 void vApplicationIdleHook( void )
192 {
193 for( ;; )
194 {
195 vCoRoutineSchedule();
196 }
197 }
198 </pre>
199 * \defgroup vCoRoutineSchedule vCoRoutineSchedule
200 * \ingroup Tasks
201 */
204 /**
205 * croutine. h
206 * <pre>
207 crSTART( xCoRoutineHandle xHandle );</pre>
208 *
209 * This macro MUST always be called at the start of a co-routine function.
210 *
211 * Example usage:
212 <pre>
213 // Co-routine to be created.
214 void vACoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )
215 {
216 // Variables in co-routines must be declared static if they must maintain value across a blocking call.
217 static long ulAVariable;
219 // Must start every co-routine with a call to crSTART();
220 crSTART( xHandle );
222 for( ;; )
223 {
224 // Co-routine functionality goes here.
225 }
227 // Must end every co-routine with a call to crEND();
228 crEND();
229 }</pre>
230 * \defgroup crSTART crSTART
231 * \ingroup Tasks
232 */
233 #define crSTART( pxCRCB ) switch( ( ( corCRCB * )pxCRCB )->uxState ) { case 0:
235 /**
236 * croutine. h
237 * <pre>
238 crEND();</pre>
239 *
240 * This macro MUST always be called at the end of a co-routine function.
241 *
242 * Example usage:
243 <pre>
244 // Co-routine to be created.
245 void vACoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )
246 {
247 // Variables in co-routines must be declared static if they must maintain value across a blocking call.
248 static long ulAVariable;
250 // Must start every co-routine with a call to crSTART();
251 crSTART( xHandle );
253 for( ;; )
254 {
255 // Co-routine functionality goes here.
256 }
258 // Must end every co-routine with a call to crEND();
259 crEND();
260 }</pre>
261 * \defgroup crSTART crSTART
262 * \ingroup Tasks
263 */
264 #define crEND() }
266 /*
267 * These macros are intended for internal use by the co-routine implementation
268 * only. The macros should not be used directly by application writers.
269 */
270 #define crSET_STATE0( xHandle ) ( ( corCRCB * )xHandle)->uxState = (__LINE__ * 2); return; case (__LINE__ * 2):
271 #define crSET_STATE1( xHandle ) ( ( corCRCB * )xHandle)->uxState = ((__LINE__ * 2)+1); return; case ((__LINE__ * 2)+1):
273 /**
274 * croutine. h
275 *<pre>
276 crDELAY( xCoRoutineHandle xHandle, portTickType xTicksToDelay );</pre>
277 *
278 * Delay a co-routine for a fixed period of time.
279 *
280 * crDELAY can only be called from the co-routine function itself - not
281 * from within a function called by the co-routine function. This is because
282 * co-routines do not maintain their own stack.
283 *
284 * @param xHandle The handle of the co-routine to delay. This is the xHandle
285 * parameter of the co-routine function.
286 *
287 * @param xTickToDelay The number of ticks that the co-routine should delay
288 * for. The actual amount of time this equates to is defined by
289 * configTICK_RATE_HZ (set in FreeRTOSConfig.h). The constant portTICK_RATE_MS
290 * can be used to convert ticks to milliseconds.
291 *
292 * Example usage:
293 <pre>
294 // Co-routine to be created.
295 void vACoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )
296 {
297 // Variables in co-routines must be declared static if they must maintain value across a blocking call.
298 // This may not be necessary for const variables.
299 // We are to delay for 200ms.
300 static const xTickType xDelayTime = 200 / portTICK_RATE_MS;
302 // Must start every co-routine with a call to crSTART();
303 crSTART( xHandle );
305 for( ;; )
306 {
307 // Delay for 200ms.
308 crDELAY( xHandle, xDelayTime );
310 // Do something here.
311 }
313 // Must end every co-routine with a call to crEND();
314 crEND();
315 }</pre>
316 * \defgroup crDELAY crDELAY
317 * \ingroup Tasks
318 */
319 #define crDELAY( xHandle, xTicksToDelay ) \
320 if( xTicksToDelay > 0 ) \
321 { \
322 vCoRoutineAddToDelayedList( xTicksToDelay, NULL ); \
323 } \
324 crSET_STATE0( xHandle );
326 /**
327 * <pre>
328 crQUEUE_SEND(
329 xCoRoutineHandle xHandle,
330 xQueueHandle pxQueue,
331 void *pvItemToQueue,
332 portTickType xTicksToWait,
333 portBASE_TYPE *pxResult
334 )</pre>
335 *
336 * The macro's crQUEUE_SEND() and crQUEUE_RECEIVE() are the co-routine
337 * equivalent to the xQueueSend() and xQueueReceive() functions used by tasks.
338 *
339 * crQUEUE_SEND and crQUEUE_RECEIVE can only be used from a co-routine whereas
340 * xQueueSend() and xQueueReceive() can only be used from tasks.
341 *
342 * crQUEUE_SEND can only be called from the co-routine function itself - not
343 * from within a function called by the co-routine function. This is because
344 * co-routines do not maintain their own stack.
345 *
346 * See the co-routine section of the WEB documentation for information on
347 * passing data between tasks and co-routines and between ISR's and
348 * co-routines.
349 *
350 * @param xHandle The handle of the calling co-routine. This is the xHandle
351 * parameter of the co-routine function.
352 *
353 * @param pxQueue The handle of the queue on which the data will be posted.
354 * The handle is obtained as the return value when the queue is created using
355 * the xQueueCreate() API function.
356 *
357 * @param pvItemToQueue A pointer to the data being posted onto the queue.
358 * The number of bytes of each queued item is specified when the queue is
359 * created. This number of bytes is copied from pvItemToQueue into the queue
360 * itself.
361 *
362 * @param xTickToDelay The number of ticks that the co-routine should block
363 * to wait for space to become available on the queue, should space not be
364 * available immediately. The actual amount of time this equates to is defined
365 * by configTICK_RATE_HZ (set in FreeRTOSConfig.h). The constant
366 * portTICK_RATE_MS can be used to convert ticks to milliseconds (see example
367 * below).
368 *
369 * @param pxResult The variable pointed to by pxResult will be set to pdPASS if
370 * data was successfully posted onto the queue, otherwise it will be set to an
371 * error defined within ProjDefs.h.
372 *
373 * Example usage:
374 <pre>
375 // Co-routine function that blocks for a fixed period then posts a number onto
376 // a queue.
377 static void prvCoRoutineFlashTask( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )
378 {
379 // Variables in co-routines must be declared static if they must maintain value across a blocking call.
380 static portBASE_TYPE xNumberToPost = 0;
381 static portBASE_TYPE xResult;
383 // Co-routines must begin with a call to crSTART().
384 crSTART( xHandle );
386 for( ;; )
387 {
388 // This assumes the queue has already been created.
389 crQUEUE_SEND( xHandle, xCoRoutineQueue, &xNumberToPost, NO_DELAY, &xResult );
391 if( xResult != pdPASS )
392 {
393 // The message was not posted!
394 }
396 // Increment the number to be posted onto the queue.
397 xNumberToPost++;
399 // Delay for 100 ticks.
400 crDELAY( xHandle, 100 );
401 }
403 // Co-routines must end with a call to crEND().
404 crEND();
405 }</pre>
406 * \defgroup crQUEUE_SEND crQUEUE_SEND
407 * \ingroup Tasks
408 */
409 #define crQUEUE_SEND( xHandle, pxQueue, pvItemToQueue, xTicksToWait, pxResult ) \
410 { \
411 *pxResult = xQueueCRSend( pxQueue, pvItemToQueue, xTicksToWait ); \
412 if( *pxResult == errQUEUE_BLOCKED ) \
413 { \
414 crSET_STATE0( xHandle ); \
415 *pxResult = xQueueCRSend( pxQueue, pvItemToQueue, 0 ); \
416 } \
417 if( *pxResult == errQUEUE_YIELD ) \
418 { \
419 crSET_STATE1( xHandle ); \
420 *pxResult = pdPASS; \
421 } \
422 }
424 /**
425 * croutine. h
426 * <pre>
427 crQUEUE_RECEIVE(
428 xCoRoutineHandle xHandle,
429 xQueueHandle pxQueue,
430 void *pvBuffer,
431 portTickType xTicksToWait,
432 portBASE_TYPE *pxResult
433 )</pre>
434 *
435 * The macro's crQUEUE_SEND() and crQUEUE_RECEIVE() are the co-routine
436 * equivalent to the xQueueSend() and xQueueReceive() functions used by tasks.
437 *
438 * crQUEUE_SEND and crQUEUE_RECEIVE can only be used from a co-routine whereas
439 * xQueueSend() and xQueueReceive() can only be used from tasks.
440 *
441 * crQUEUE_RECEIVE can only be called from the co-routine function itself - not
442 * from within a function called by the co-routine function. This is because
443 * co-routines do not maintain their own stack.
444 *
445 * See the co-routine section of the WEB documentation for information on
446 * passing data between tasks and co-routines and between ISR's and
447 * co-routines.
448 *
449 * @param xHandle The handle of the calling co-routine. This is the xHandle
450 * parameter of the co-routine function.
451 *
452 * @param pxQueue The handle of the queue from which the data will be received.
453 * The handle is obtained as the return value when the queue is created using
454 * the xQueueCreate() API function.
455 *
456 * @param pvBuffer The buffer into which the received item is to be copied.
457 * The number of bytes of each queued item is specified when the queue is
458 * created. This number of bytes is copied into pvBuffer.
459 *
460 * @param xTickToDelay The number of ticks that the co-routine should block
461 * to wait for data to become available from the queue, should data not be
462 * available immediately. The actual amount of time this equates to is defined
463 * by configTICK_RATE_HZ (set in FreeRTOSConfig.h). The constant
464 * portTICK_RATE_MS can be used to convert ticks to milliseconds (see the
465 * crQUEUE_SEND example).
466 *
467 * @param pxResult The variable pointed to by pxResult will be set to pdPASS if
468 * data was successfully retrieved from the queue, otherwise it will be set to
469 * an error code as defined within ProjDefs.h.
470 *
471 * Example usage:
472 <pre>
473 // A co-routine receives the number of an LED to flash from a queue. It
474 // blocks on the queue until the number is received.
475 static void prvCoRoutineFlashWorkTask( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )
476 {
477 // Variables in co-routines must be declared static if they must maintain value across a blocking call.
478 static portBASE_TYPE xResult;
479 static unsigned portBASE_TYPE uxLEDToFlash;
481 // All co-routines must start with a call to crSTART().
482 crSTART( xHandle );
484 for( ;; )
485 {
486 // Wait for data to become available on the queue.
487 crQUEUE_RECEIVE( xHandle, xCoRoutineQueue, &uxLEDToFlash, portMAX_DELAY, &xResult );
489 if( xResult == pdPASS )
490 {
491 // We received the LED to flash - flash it!
492 vParTestToggleLED( uxLEDToFlash );
493 }
494 }
496 crEND();
497 }</pre>
498 * \defgroup crQUEUE_RECEIVE crQUEUE_RECEIVE
499 * \ingroup Tasks
500 */
501 #define crQUEUE_RECEIVE( xHandle, pxQueue, pvBuffer, xTicksToWait, pxResult ) \
502 { \
503 *pxResult = xQueueCRReceive( pxQueue, pvBuffer, xTicksToWait ); \
504 if( *pxResult == errQUEUE_BLOCKED ) \
505 { \
506 crSET_STATE0( xHandle ); \
507 *pxResult = xQueueCRReceive( pxQueue, pvBuffer, 0 ); \
508 } \
509 if( *pxResult == errQUEUE_YIELD ) \
510 { \
511 crSET_STATE1( xHandle ); \
512 *pxResult = pdPASS; \
513 } \
514 }
516 /**
517 * croutine. h
518 * <pre>
519 crQUEUE_SEND_FROM_ISR(
520 xQueueHandle pxQueue,
521 void *pvItemToQueue,
522 portBASE_TYPE xCoRoutinePreviouslyWoken
523 )</pre>
524 *
525 * The macro's crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() are the
526 * co-routine equivalent to the xQueueSendFromISR() and xQueueReceiveFromISR()
527 * functions used by tasks.
528 *
529 * crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() can only be used to
530 * pass data between a co-routine and and ISR, whereas xQueueSendFromISR() and
531 * xQueueReceiveFromISR() can only be used to pass data between a task and and
532 * ISR.
533 *
534 * crQUEUE_SEND_FROM_ISR can only be called from an ISR to send data to a queue
535 * that is being used from within a co-routine.
536 *
537 * See the co-routine section of the WEB documentation for information on
538 * passing data between tasks and co-routines and between ISR's and
539 * co-routines.
540 *
541 * @param xQueue The handle to the queue on which the item is to be posted.
542 *
543 * @param pvItemToQueue A pointer to the item that is to be placed on the
544 * queue. The size of the items the queue will hold was defined when the
545 * queue was created, so this many bytes will be copied from pvItemToQueue
546 * into the queue storage area.
547 *
548 * @param xCoRoutinePreviouslyWoken This is included so an ISR can post onto
549 * the same queue multiple times from a single interrupt. The first call
550 * should always pass in pdFALSE. Subsequent calls should pass in
551 * the value returned from the previous call.
552 *
553 * @return pdTRUE if a co-routine was woken by posting onto the queue. This is
554 * used by the ISR to determine if a context switch may be required following
555 * the ISR.
556 *
557 * Example usage:
558 <pre>
559 // A co-routine that blocks on a queue waiting for characters to be received.
560 static void vReceivingCoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )
561 {
562 char cRxedChar;
563 portBASE_TYPE xResult;
565 // All co-routines must start with a call to crSTART().
566 crSTART( xHandle );
568 for( ;; )
569 {
570 // Wait for data to become available on the queue. This assumes the
571 // queue xCommsRxQueue has already been created!
572 crQUEUE_RECEIVE( xHandle, xCommsRxQueue, &uxLEDToFlash, portMAX_DELAY, &xResult );
574 // Was a character received?
575 if( xResult == pdPASS )
576 {
577 // Process the character here.
578 }
579 }
581 // All co-routines must end with a call to crEND().
582 crEND();
583 }
585 // An ISR that uses a queue to send characters received on a serial port to
586 // a co-routine.
587 void vUART_ISR( void )
588 {
589 char cRxedChar;
590 portBASE_TYPE xCRWokenByPost = pdFALSE;
592 // We loop around reading characters until there are none left in the UART.
593 while( UART_RX_REG_NOT_EMPTY() )
594 {
595 // Obtain the character from the UART.
596 cRxedChar = UART_RX_REG;
598 // Post the character onto a queue. xCRWokenByPost will be pdFALSE
599 // the first time around the loop. If the post causes a co-routine
600 // to be woken (unblocked) then xCRWokenByPost will be set to pdTRUE.
601 // In this manner we can ensure that if more than one co-routine is
602 // blocked on the queue only one is woken by this ISR no matter how
603 // many characters are posted to the queue.
604 xCRWokenByPost = crQUEUE_SEND_FROM_ISR( xCommsRxQueue, &cRxedChar, xCRWokenByPost );
605 }
606 }</pre>
607 * \defgroup crQUEUE_SEND_FROM_ISR crQUEUE_SEND_FROM_ISR
608 * \ingroup Tasks
609 */
610 #define crQUEUE_SEND_FROM_ISR( pxQueue, pvItemToQueue, xCoRoutinePreviouslyWoken ) xQueueCRSendFromISR( pxQueue, pvItemToQueue, xCoRoutinePreviouslyWoken )
613 /**
614 * croutine. h
615 * <pre>
616 crQUEUE_SEND_FROM_ISR(
617 xQueueHandle pxQueue,
618 void *pvBuffer,
619 portBASE_TYPE * pxCoRoutineWoken
620 )</pre>
621 *
622 * The macro's crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() are the
623 * co-routine equivalent to the xQueueSendFromISR() and xQueueReceiveFromISR()
624 * functions used by tasks.
625 *
626 * crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() can only be used to
627 * pass data between a co-routine and and ISR, whereas xQueueSendFromISR() and
628 * xQueueReceiveFromISR() can only be used to pass data between a task and and
629 * ISR.
630 *
631 * crQUEUE_RECEIVE_FROM_ISR can only be called from an ISR to receive data
632 * from a queue that is being used from within a co-routine (a co-routine
633 * posted to the queue).
634 *
635 * See the co-routine section of the WEB documentation for information on
636 * passing data between tasks and co-routines and between ISR's and
637 * co-routines.
638 *
639 * @param xQueue The handle to the queue on which the item is to be posted.
640 *
641 * @param pvBuffer A pointer to a buffer into which the received item will be
642 * placed. The size of the items the queue will hold was defined when the
643 * queue was created, so this many bytes will be copied from the queue into
644 * pvBuffer.
645 *
646 * @param pxCoRoutineWoken A co-routine may be blocked waiting for space to become
647 * available on the queue. If crQUEUE_RECEIVE_FROM_ISR causes such a
648 * co-routine to unblock *pxCoRoutineWoken will get set to pdTRUE, otherwise
649 * *pxCoRoutineWoken will remain unchanged.
650 *
651 * @return pdTRUE an item was successfully received from the queue, otherwise
652 * pdFALSE.
653 *
654 * Example usage:
655 <pre>
656 // A co-routine that posts a character to a queue then blocks for a fixed
657 // period. The character is incremented each time.
658 static void vSendingCoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )
659 {
660 // cChar holds its value while this co-routine is blocked and must therefore
661 // be declared static.
662 static char cCharToTx = 'a';
663 portBASE_TYPE xResult;
665 // All co-routines must start with a call to crSTART().
666 crSTART( xHandle );
668 for( ;; )
669 {
670 // Send the next character to the queue.
671 crQUEUE_SEND( xHandle, xCoRoutineQueue, &cCharToTx, NO_DELAY, &xResult );
673 if( xResult == pdPASS )
674 {
675 // The character was successfully posted to the queue.
676 }
677 else
678 {
679 // Could not post the character to the queue.
680 }
682 // Enable the UART Tx interrupt to cause an interrupt in this
683 // hypothetical UART. The interrupt will obtain the character
684 // from the queue and send it.
685 ENABLE_RX_INTERRUPT();
687 // Increment to the next character then block for a fixed period.
688 // cCharToTx will maintain its value across the delay as it is
689 // declared static.
690 cCharToTx++;
691 if( cCharToTx > 'x' )
692 {
693 cCharToTx = 'a';
694 }
695 crDELAY( 100 );
696 }
698 // All co-routines must end with a call to crEND().
699 crEND();
700 }
702 // An ISR that uses a queue to receive characters to send on a UART.
703 void vUART_ISR( void )
704 {
705 char cCharToTx;
706 portBASE_TYPE xCRWokenByPost = pdFALSE;
708 while( UART_TX_REG_EMPTY() )
709 {
710 // Are there any characters in the queue waiting to be sent?
711 // xCRWokenByPost will automatically be set to pdTRUE if a co-routine
712 // is woken by the post - ensuring that only a single co-routine is
713 // woken no matter how many times we go around this loop.
714 if( crQUEUE_RECEIVE_FROM_ISR( pxQueue, &cCharToTx, &xCRWokenByPost ) )
715 {
716 SEND_CHARACTER( cCharToTx );
717 }
718 }
719 }</pre>
720 * \defgroup crQUEUE_RECEIVE_FROM_ISR crQUEUE_RECEIVE_FROM_ISR
721 * \ingroup Tasks
722 */
723 #define crQUEUE_RECEIVE_FROM_ISR( pxQueue, pvBuffer, pxCoRoutineWoken ) xQueueCRReceiveFromISR( pxQueue, pvBuffer, pxCoRoutineWoken )
725 /*
726 * This function is intended for internal use by the co-routine macros only.
727 * The macro nature of the co-routine implementation requires that the
728 * prototype appears here. The function should not be used by application
729 * writers.
730 *
731 * Removes the current co-routine from its ready list and places it in the
732 * appropriate delayed list.
733 */
736 /*
737 * This function is intended for internal use by the queue implementation only.
738 * The function should not be used by application writers.
739 *
740 * Removes the highest priority co-routine from the event list and places it in
741 * the pending ready list.
742 */
745 #ifdef __cplusplus
746 }
747 #endif