Francisco Paez
/
freertos-cm3
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: mbed_lpc1768_freertos_lib
src/include/croutine.h@0:5ff20db10a96, 2017-05-31 (annotated)
- Committer:
- fep
- Date:
- Wed May 31 02:36:43 2017 +0000
- Revision:
- 0:5ff20db10a96
FreeRTOS v9.0.0 for ARM Cortex-M3 based boards.
Who changed what in which revision?
| User | Revision | Line number | New contents of line |
|---|---|---|---|
| fep | 0:5ff20db10a96 | 1 | /* |
| fep | 0:5ff20db10a96 | 2 | FreeRTOS V9.0.0 - Copyright (C) 2016 Real Time Engineers Ltd. |
| fep | 0:5ff20db10a96 | 3 | All rights reserved |
| fep | 0:5ff20db10a96 | 4 | |
| fep | 0:5ff20db10a96 | 5 | VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION. |
| fep | 0:5ff20db10a96 | 6 | |
| fep | 0:5ff20db10a96 | 7 | This file is part of the FreeRTOS distribution. |
| fep | 0:5ff20db10a96 | 8 | |
| fep | 0:5ff20db10a96 | 9 | FreeRTOS is free software; you can redistribute it and/or modify it under |
| fep | 0:5ff20db10a96 | 10 | the terms of the GNU General Public License (version 2) as published by the |
| fep | 0:5ff20db10a96 | 11 | Free Software Foundation >>>> AND MODIFIED BY <<<< the FreeRTOS exception. |
| fep | 0:5ff20db10a96 | 12 | |
| fep | 0:5ff20db10a96 | 13 | *************************************************************************** |
| fep | 0:5ff20db10a96 | 14 | >>! NOTE: The modification to the GPL is included to allow you to !<< |
| fep | 0:5ff20db10a96 | 15 | >>! distribute a combined work that includes FreeRTOS without being !<< |
| fep | 0:5ff20db10a96 | 16 | >>! obliged to provide the source code for proprietary components !<< |
| fep | 0:5ff20db10a96 | 17 | >>! outside of the FreeRTOS kernel. !<< |
| fep | 0:5ff20db10a96 | 18 | *************************************************************************** |
| fep | 0:5ff20db10a96 | 19 | |
| fep | 0:5ff20db10a96 | 20 | FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY |
| fep | 0:5ff20db10a96 | 21 | WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS |
| fep | 0:5ff20db10a96 | 22 | FOR A PARTICULAR PURPOSE. Full license text is available on the following |
| fep | 0:5ff20db10a96 | 23 | link: http://www.freertos.org/a00114.html |
| fep | 0:5ff20db10a96 | 24 | |
| fep | 0:5ff20db10a96 | 25 | *************************************************************************** |
| fep | 0:5ff20db10a96 | 26 | * * |
| fep | 0:5ff20db10a96 | 27 | * FreeRTOS provides completely free yet professionally developed, * |
| fep | 0:5ff20db10a96 | 28 | * robust, strictly quality controlled, supported, and cross * |
| fep | 0:5ff20db10a96 | 29 | * platform software that is more than just the market leader, it * |
| fep | 0:5ff20db10a96 | 30 | * is the industry's de facto standard. * |
| fep | 0:5ff20db10a96 | 31 | * * |
| fep | 0:5ff20db10a96 | 32 | * Help yourself get started quickly while simultaneously helping * |
| fep | 0:5ff20db10a96 | 33 | * to support the FreeRTOS project by purchasing a FreeRTOS * |
| fep | 0:5ff20db10a96 | 34 | * tutorial book, reference manual, or both: * |
| fep | 0:5ff20db10a96 | 35 | * http://www.FreeRTOS.org/Documentation * |
| fep | 0:5ff20db10a96 | 36 | * * |
| fep | 0:5ff20db10a96 | 37 | *************************************************************************** |
| fep | 0:5ff20db10a96 | 38 | |
| fep | 0:5ff20db10a96 | 39 | http://www.FreeRTOS.org/FAQHelp.html - Having a problem? Start by reading |
| fep | 0:5ff20db10a96 | 40 | the FAQ page "My application does not run, what could be wrong?". Have you |
| fep | 0:5ff20db10a96 | 41 | defined configASSERT()? |
| fep | 0:5ff20db10a96 | 42 | |
| fep | 0:5ff20db10a96 | 43 | http://www.FreeRTOS.org/support - In return for receiving this top quality |
| fep | 0:5ff20db10a96 | 44 | embedded software for free we request you assist our global community by |
| fep | 0:5ff20db10a96 | 45 | participating in the support forum. |
| fep | 0:5ff20db10a96 | 46 | |
| fep | 0:5ff20db10a96 | 47 | http://www.FreeRTOS.org/training - Investing in training allows your team to |
| fep | 0:5ff20db10a96 | 48 | be as productive as possible as early as possible. Now you can receive |
| fep | 0:5ff20db10a96 | 49 | FreeRTOS training directly from Richard Barry, CEO of Real Time Engineers |
| fep | 0:5ff20db10a96 | 50 | Ltd, and the world's leading authority on the world's leading RTOS. |
| fep | 0:5ff20db10a96 | 51 | |
| fep | 0:5ff20db10a96 | 52 | http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products, |
| fep | 0:5ff20db10a96 | 53 | including FreeRTOS+Trace - an indispensable productivity tool, a DOS |
| fep | 0:5ff20db10a96 | 54 | compatible FAT file system, and our tiny thread aware UDP/IP stack. |
| fep | 0:5ff20db10a96 | 55 | |
| fep | 0:5ff20db10a96 | 56 | http://www.FreeRTOS.org/labs - Where new FreeRTOS products go to incubate. |
| fep | 0:5ff20db10a96 | 57 | Come and try FreeRTOS+TCP, our new open source TCP/IP stack for FreeRTOS. |
| fep | 0:5ff20db10a96 | 58 | |
| fep | 0:5ff20db10a96 | 59 | http://www.OpenRTOS.com - Real Time Engineers ltd. license FreeRTOS to High |
| fep | 0:5ff20db10a96 | 60 | Integrity Systems ltd. to sell under the OpenRTOS brand. Low cost OpenRTOS |
| fep | 0:5ff20db10a96 | 61 | licenses offer ticketed support, indemnification and commercial middleware. |
| fep | 0:5ff20db10a96 | 62 | |
| fep | 0:5ff20db10a96 | 63 | http://www.SafeRTOS.com - High Integrity Systems also provide a safety |
| fep | 0:5ff20db10a96 | 64 | engineered and independently SIL3 certified version for use in safety and |
| fep | 0:5ff20db10a96 | 65 | mission critical applications that require provable dependability. |
| fep | 0:5ff20db10a96 | 66 | |
| fep | 0:5ff20db10a96 | 67 | 1 tab == 4 spaces! |
| fep | 0:5ff20db10a96 | 68 | */ |
| fep | 0:5ff20db10a96 | 69 | |
| fep | 0:5ff20db10a96 | 70 | #ifndef CO_ROUTINE_H |
| fep | 0:5ff20db10a96 | 71 | #define CO_ROUTINE_H |
| fep | 0:5ff20db10a96 | 72 | |
| fep | 0:5ff20db10a96 | 73 | #ifndef INC_FREERTOS_H |
| fep | 0:5ff20db10a96 | 74 | #error "include FreeRTOS.h must appear in source files before include croutine.h" |
| fep | 0:5ff20db10a96 | 75 | #endif |
| fep | 0:5ff20db10a96 | 76 | |
| fep | 0:5ff20db10a96 | 77 | #include "list.h" |
| fep | 0:5ff20db10a96 | 78 | |
| fep | 0:5ff20db10a96 | 79 | #ifdef __cplusplus |
| fep | 0:5ff20db10a96 | 80 | extern "C" { |
| fep | 0:5ff20db10a96 | 81 | #endif |
| fep | 0:5ff20db10a96 | 82 | |
| fep | 0:5ff20db10a96 | 83 | /* Used to hide the implementation of the co-routine control block. The |
| fep | 0:5ff20db10a96 | 84 | control block structure however has to be included in the header due to |
| fep | 0:5ff20db10a96 | 85 | the macro implementation of the co-routine functionality. */ |
| fep | 0:5ff20db10a96 | 86 | typedef void * CoRoutineHandle_t; |
| fep | 0:5ff20db10a96 | 87 | |
| fep | 0:5ff20db10a96 | 88 | /* Defines the prototype to which co-routine functions must conform. */ |
| fep | 0:5ff20db10a96 | 89 | typedef void (*crCOROUTINE_CODE)( CoRoutineHandle_t, UBaseType_t ); |
| fep | 0:5ff20db10a96 | 90 | |
| fep | 0:5ff20db10a96 | 91 | typedef struct corCoRoutineControlBlock |
| fep | 0:5ff20db10a96 | 92 | { |
| fep | 0:5ff20db10a96 | 93 | crCOROUTINE_CODE pxCoRoutineFunction; |
| fep | 0:5ff20db10a96 | 94 | ListItem_t xGenericListItem; /*< List item used to place the CRCB in ready and blocked queues. */ |
| fep | 0:5ff20db10a96 | 95 | ListItem_t xEventListItem; /*< List item used to place the CRCB in event lists. */ |
| fep | 0:5ff20db10a96 | 96 | UBaseType_t uxPriority; /*< The priority of the co-routine in relation to other co-routines. */ |
| fep | 0:5ff20db10a96 | 97 | UBaseType_t uxIndex; /*< Used to distinguish between co-routines when multiple co-routines use the same co-routine function. */ |
| fep | 0:5ff20db10a96 | 98 | uint16_t uxState; /*< Used internally by the co-routine implementation. */ |
| fep | 0:5ff20db10a96 | 99 | } CRCB_t; /* Co-routine control block. Note must be identical in size down to uxPriority with TCB_t. */ |
| fep | 0:5ff20db10a96 | 100 | |
| fep | 0:5ff20db10a96 | 101 | /** |
| fep | 0:5ff20db10a96 | 102 | * croutine. h |
| fep | 0:5ff20db10a96 | 103 | *<pre> |
| fep | 0:5ff20db10a96 | 104 | BaseType_t xCoRoutineCreate( |
| fep | 0:5ff20db10a96 | 105 | crCOROUTINE_CODE pxCoRoutineCode, |
| fep | 0:5ff20db10a96 | 106 | UBaseType_t uxPriority, |
| fep | 0:5ff20db10a96 | 107 | UBaseType_t uxIndex |
| fep | 0:5ff20db10a96 | 108 | );</pre> |
| fep | 0:5ff20db10a96 | 109 | * |
| fep | 0:5ff20db10a96 | 110 | * Create a new co-routine and add it to the list of co-routines that are |
| fep | 0:5ff20db10a96 | 111 | * ready to run. |
| fep | 0:5ff20db10a96 | 112 | * |
| fep | 0:5ff20db10a96 | 113 | * @param pxCoRoutineCode Pointer to the co-routine function. Co-routine |
| fep | 0:5ff20db10a96 | 114 | * functions require special syntax - see the co-routine section of the WEB |
| fep | 0:5ff20db10a96 | 115 | * documentation for more information. |
| fep | 0:5ff20db10a96 | 116 | * |
| fep | 0:5ff20db10a96 | 117 | * @param uxPriority The priority with respect to other co-routines at which |
| fep | 0:5ff20db10a96 | 118 | * the co-routine will run. |
| fep | 0:5ff20db10a96 | 119 | * |
| fep | 0:5ff20db10a96 | 120 | * @param uxIndex Used to distinguish between different co-routines that |
| fep | 0:5ff20db10a96 | 121 | * execute the same function. See the example below and the co-routine section |
| fep | 0:5ff20db10a96 | 122 | * of the WEB documentation for further information. |
| fep | 0:5ff20db10a96 | 123 | * |
| fep | 0:5ff20db10a96 | 124 | * @return pdPASS if the co-routine was successfully created and added to a ready |
| fep | 0:5ff20db10a96 | 125 | * list, otherwise an error code defined with ProjDefs.h. |
| fep | 0:5ff20db10a96 | 126 | * |
| fep | 0:5ff20db10a96 | 127 | * Example usage: |
| fep | 0:5ff20db10a96 | 128 | <pre> |
| fep | 0:5ff20db10a96 | 129 | // Co-routine to be created. |
| fep | 0:5ff20db10a96 | 130 | void vFlashCoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex ) |
| fep | 0:5ff20db10a96 | 131 | { |
| fep | 0:5ff20db10a96 | 132 | // Variables in co-routines must be declared static if they must maintain value across a blocking call. |
| fep | 0:5ff20db10a96 | 133 | // This may not be necessary for const variables. |
| fep | 0:5ff20db10a96 | 134 | static const char cLedToFlash[ 2 ] = { 5, 6 }; |
| fep | 0:5ff20db10a96 | 135 | static const TickType_t uxFlashRates[ 2 ] = { 200, 400 }; |
| fep | 0:5ff20db10a96 | 136 | |
| fep | 0:5ff20db10a96 | 137 | // Must start every co-routine with a call to crSTART(); |
| fep | 0:5ff20db10a96 | 138 | crSTART( xHandle ); |
| fep | 0:5ff20db10a96 | 139 | |
| fep | 0:5ff20db10a96 | 140 | for( ;; ) |
| fep | 0:5ff20db10a96 | 141 | { |
| fep | 0:5ff20db10a96 | 142 | // This co-routine just delays for a fixed period, then toggles |
| fep | 0:5ff20db10a96 | 143 | // an LED. Two co-routines are created using this function, so |
| fep | 0:5ff20db10a96 | 144 | // the uxIndex parameter is used to tell the co-routine which |
| fep | 0:5ff20db10a96 | 145 | // LED to flash and how int32_t to delay. This assumes xQueue has |
| fep | 0:5ff20db10a96 | 146 | // already been created. |
| fep | 0:5ff20db10a96 | 147 | vParTestToggleLED( cLedToFlash[ uxIndex ] ); |
| fep | 0:5ff20db10a96 | 148 | crDELAY( xHandle, uxFlashRates[ uxIndex ] ); |
| fep | 0:5ff20db10a96 | 149 | } |
| fep | 0:5ff20db10a96 | 150 | |
| fep | 0:5ff20db10a96 | 151 | // Must end every co-routine with a call to crEND(); |
| fep | 0:5ff20db10a96 | 152 | crEND(); |
| fep | 0:5ff20db10a96 | 153 | } |
| fep | 0:5ff20db10a96 | 154 | |
| fep | 0:5ff20db10a96 | 155 | // Function that creates two co-routines. |
| fep | 0:5ff20db10a96 | 156 | void vOtherFunction( void ) |
| fep | 0:5ff20db10a96 | 157 | { |
| fep | 0:5ff20db10a96 | 158 | uint8_t ucParameterToPass; |
| fep | 0:5ff20db10a96 | 159 | TaskHandle_t xHandle; |
| fep | 0:5ff20db10a96 | 160 | |
| fep | 0:5ff20db10a96 | 161 | // Create two co-routines at priority 0. The first is given index 0 |
| fep | 0:5ff20db10a96 | 162 | // so (from the code above) toggles LED 5 every 200 ticks. The second |
| fep | 0:5ff20db10a96 | 163 | // is given index 1 so toggles LED 6 every 400 ticks. |
| fep | 0:5ff20db10a96 | 164 | for( uxIndex = 0; uxIndex < 2; uxIndex++ ) |
| fep | 0:5ff20db10a96 | 165 | { |
| fep | 0:5ff20db10a96 | 166 | xCoRoutineCreate( vFlashCoRoutine, 0, uxIndex ); |
| fep | 0:5ff20db10a96 | 167 | } |
| fep | 0:5ff20db10a96 | 168 | } |
| fep | 0:5ff20db10a96 | 169 | </pre> |
| fep | 0:5ff20db10a96 | 170 | * \defgroup xCoRoutineCreate xCoRoutineCreate |
| fep | 0:5ff20db10a96 | 171 | * \ingroup Tasks |
| fep | 0:5ff20db10a96 | 172 | */ |
| fep | 0:5ff20db10a96 | 173 | BaseType_t xCoRoutineCreate( crCOROUTINE_CODE pxCoRoutineCode, UBaseType_t uxPriority, UBaseType_t uxIndex ); |
| fep | 0:5ff20db10a96 | 174 | |
| fep | 0:5ff20db10a96 | 175 | |
| fep | 0:5ff20db10a96 | 176 | /** |
| fep | 0:5ff20db10a96 | 177 | * croutine. h |
| fep | 0:5ff20db10a96 | 178 | *<pre> |
| fep | 0:5ff20db10a96 | 179 | void vCoRoutineSchedule( void );</pre> |
| fep | 0:5ff20db10a96 | 180 | * |
| fep | 0:5ff20db10a96 | 181 | * Run a co-routine. |
| fep | 0:5ff20db10a96 | 182 | * |
| fep | 0:5ff20db10a96 | 183 | * vCoRoutineSchedule() executes the highest priority co-routine that is able |
| fep | 0:5ff20db10a96 | 184 | * to run. The co-routine will execute until it either blocks, yields or is |
| fep | 0:5ff20db10a96 | 185 | * preempted by a task. Co-routines execute cooperatively so one |
| fep | 0:5ff20db10a96 | 186 | * co-routine cannot be preempted by another, but can be preempted by a task. |
| fep | 0:5ff20db10a96 | 187 | * |
| fep | 0:5ff20db10a96 | 188 | * If an application comprises of both tasks and co-routines then |
| fep | 0:5ff20db10a96 | 189 | * vCoRoutineSchedule should be called from the idle task (in an idle task |
| fep | 0:5ff20db10a96 | 190 | * hook). |
| fep | 0:5ff20db10a96 | 191 | * |
| fep | 0:5ff20db10a96 | 192 | * Example usage: |
| fep | 0:5ff20db10a96 | 193 | <pre> |
| fep | 0:5ff20db10a96 | 194 | // This idle task hook will schedule a co-routine each time it is called. |
| fep | 0:5ff20db10a96 | 195 | // The rest of the idle task will execute between co-routine calls. |
| fep | 0:5ff20db10a96 | 196 | void vApplicationIdleHook( void ) |
| fep | 0:5ff20db10a96 | 197 | { |
| fep | 0:5ff20db10a96 | 198 | vCoRoutineSchedule(); |
| fep | 0:5ff20db10a96 | 199 | } |
| fep | 0:5ff20db10a96 | 200 | |
| fep | 0:5ff20db10a96 | 201 | // Alternatively, if you do not require any other part of the idle task to |
| fep | 0:5ff20db10a96 | 202 | // execute, the idle task hook can call vCoRoutineScheduler() within an |
| fep | 0:5ff20db10a96 | 203 | // infinite loop. |
| fep | 0:5ff20db10a96 | 204 | void vApplicationIdleHook( void ) |
| fep | 0:5ff20db10a96 | 205 | { |
| fep | 0:5ff20db10a96 | 206 | for( ;; ) |
| fep | 0:5ff20db10a96 | 207 | { |
| fep | 0:5ff20db10a96 | 208 | vCoRoutineSchedule(); |
| fep | 0:5ff20db10a96 | 209 | } |
| fep | 0:5ff20db10a96 | 210 | } |
| fep | 0:5ff20db10a96 | 211 | </pre> |
| fep | 0:5ff20db10a96 | 212 | * \defgroup vCoRoutineSchedule vCoRoutineSchedule |
| fep | 0:5ff20db10a96 | 213 | * \ingroup Tasks |
| fep | 0:5ff20db10a96 | 214 | */ |
| fep | 0:5ff20db10a96 | 215 | void vCoRoutineSchedule( void ); |
| fep | 0:5ff20db10a96 | 216 | |
| fep | 0:5ff20db10a96 | 217 | /** |
| fep | 0:5ff20db10a96 | 218 | * croutine. h |
| fep | 0:5ff20db10a96 | 219 | * <pre> |
| fep | 0:5ff20db10a96 | 220 | crSTART( CoRoutineHandle_t xHandle );</pre> |
| fep | 0:5ff20db10a96 | 221 | * |
| fep | 0:5ff20db10a96 | 222 | * This macro MUST always be called at the start of a co-routine function. |
| fep | 0:5ff20db10a96 | 223 | * |
| fep | 0:5ff20db10a96 | 224 | * Example usage: |
| fep | 0:5ff20db10a96 | 225 | <pre> |
| fep | 0:5ff20db10a96 | 226 | // Co-routine to be created. |
| fep | 0:5ff20db10a96 | 227 | void vACoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex ) |
| fep | 0:5ff20db10a96 | 228 | { |
| fep | 0:5ff20db10a96 | 229 | // Variables in co-routines must be declared static if they must maintain value across a blocking call. |
| fep | 0:5ff20db10a96 | 230 | static int32_t ulAVariable; |
| fep | 0:5ff20db10a96 | 231 | |
| fep | 0:5ff20db10a96 | 232 | // Must start every co-routine with a call to crSTART(); |
| fep | 0:5ff20db10a96 | 233 | crSTART( xHandle ); |
| fep | 0:5ff20db10a96 | 234 | |
| fep | 0:5ff20db10a96 | 235 | for( ;; ) |
| fep | 0:5ff20db10a96 | 236 | { |
| fep | 0:5ff20db10a96 | 237 | // Co-routine functionality goes here. |
| fep | 0:5ff20db10a96 | 238 | } |
| fep | 0:5ff20db10a96 | 239 | |
| fep | 0:5ff20db10a96 | 240 | // Must end every co-routine with a call to crEND(); |
| fep | 0:5ff20db10a96 | 241 | crEND(); |
| fep | 0:5ff20db10a96 | 242 | }</pre> |
| fep | 0:5ff20db10a96 | 243 | * \defgroup crSTART crSTART |
| fep | 0:5ff20db10a96 | 244 | * \ingroup Tasks |
| fep | 0:5ff20db10a96 | 245 | */ |
| fep | 0:5ff20db10a96 | 246 | #define crSTART( pxCRCB ) switch( ( ( CRCB_t * )( pxCRCB ) )->uxState ) { case 0: |
| fep | 0:5ff20db10a96 | 247 | |
| fep | 0:5ff20db10a96 | 248 | /** |
| fep | 0:5ff20db10a96 | 249 | * croutine. h |
| fep | 0:5ff20db10a96 | 250 | * <pre> |
| fep | 0:5ff20db10a96 | 251 | crEND();</pre> |
| fep | 0:5ff20db10a96 | 252 | * |
| fep | 0:5ff20db10a96 | 253 | * This macro MUST always be called at the end of a co-routine function. |
| fep | 0:5ff20db10a96 | 254 | * |
| fep | 0:5ff20db10a96 | 255 | * Example usage: |
| fep | 0:5ff20db10a96 | 256 | <pre> |
| fep | 0:5ff20db10a96 | 257 | // Co-routine to be created. |
| fep | 0:5ff20db10a96 | 258 | void vACoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex ) |
| fep | 0:5ff20db10a96 | 259 | { |
| fep | 0:5ff20db10a96 | 260 | // Variables in co-routines must be declared static if they must maintain value across a blocking call. |
| fep | 0:5ff20db10a96 | 261 | static int32_t ulAVariable; |
| fep | 0:5ff20db10a96 | 262 | |
| fep | 0:5ff20db10a96 | 263 | // Must start every co-routine with a call to crSTART(); |
| fep | 0:5ff20db10a96 | 264 | crSTART( xHandle ); |
| fep | 0:5ff20db10a96 | 265 | |
| fep | 0:5ff20db10a96 | 266 | for( ;; ) |
| fep | 0:5ff20db10a96 | 267 | { |
| fep | 0:5ff20db10a96 | 268 | // Co-routine functionality goes here. |
| fep | 0:5ff20db10a96 | 269 | } |
| fep | 0:5ff20db10a96 | 270 | |
| fep | 0:5ff20db10a96 | 271 | // Must end every co-routine with a call to crEND(); |
| fep | 0:5ff20db10a96 | 272 | crEND(); |
| fep | 0:5ff20db10a96 | 273 | }</pre> |
| fep | 0:5ff20db10a96 | 274 | * \defgroup crSTART crSTART |
| fep | 0:5ff20db10a96 | 275 | * \ingroup Tasks |
| fep | 0:5ff20db10a96 | 276 | */ |
| fep | 0:5ff20db10a96 | 277 | #define crEND() } |
| fep | 0:5ff20db10a96 | 278 | |
| fep | 0:5ff20db10a96 | 279 | /* |
| fep | 0:5ff20db10a96 | 280 | * These macros are intended for internal use by the co-routine implementation |
| fep | 0:5ff20db10a96 | 281 | * only. The macros should not be used directly by application writers. |
| fep | 0:5ff20db10a96 | 282 | */ |
| fep | 0:5ff20db10a96 | 283 | #define crSET_STATE0( xHandle ) ( ( CRCB_t * )( xHandle ) )->uxState = (__LINE__ * 2); return; case (__LINE__ * 2): |
| fep | 0:5ff20db10a96 | 284 | #define crSET_STATE1( xHandle ) ( ( CRCB_t * )( xHandle ) )->uxState = ((__LINE__ * 2)+1); return; case ((__LINE__ * 2)+1): |
| fep | 0:5ff20db10a96 | 285 | |
| fep | 0:5ff20db10a96 | 286 | /** |
| fep | 0:5ff20db10a96 | 287 | * croutine. h |
| fep | 0:5ff20db10a96 | 288 | *<pre> |
| fep | 0:5ff20db10a96 | 289 | crDELAY( CoRoutineHandle_t xHandle, TickType_t xTicksToDelay );</pre> |
| fep | 0:5ff20db10a96 | 290 | * |
| fep | 0:5ff20db10a96 | 291 | * Delay a co-routine for a fixed period of time. |
| fep | 0:5ff20db10a96 | 292 | * |
| fep | 0:5ff20db10a96 | 293 | * crDELAY can only be called from the co-routine function itself - not |
| fep | 0:5ff20db10a96 | 294 | * from within a function called by the co-routine function. This is because |
| fep | 0:5ff20db10a96 | 295 | * co-routines do not maintain their own stack. |
| fep | 0:5ff20db10a96 | 296 | * |
| fep | 0:5ff20db10a96 | 297 | * @param xHandle The handle of the co-routine to delay. This is the xHandle |
| fep | 0:5ff20db10a96 | 298 | * parameter of the co-routine function. |
| fep | 0:5ff20db10a96 | 299 | * |
| fep | 0:5ff20db10a96 | 300 | * @param xTickToDelay The number of ticks that the co-routine should delay |
| fep | 0:5ff20db10a96 | 301 | * for. The actual amount of time this equates to is defined by |
| fep | 0:5ff20db10a96 | 302 | * configTICK_RATE_HZ (set in FreeRTOSConfig.h). The constant portTICK_PERIOD_MS |
| fep | 0:5ff20db10a96 | 303 | * can be used to convert ticks to milliseconds. |
| fep | 0:5ff20db10a96 | 304 | * |
| fep | 0:5ff20db10a96 | 305 | * Example usage: |
| fep | 0:5ff20db10a96 | 306 | <pre> |
| fep | 0:5ff20db10a96 | 307 | // Co-routine to be created. |
| fep | 0:5ff20db10a96 | 308 | void vACoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex ) |
| fep | 0:5ff20db10a96 | 309 | { |
| fep | 0:5ff20db10a96 | 310 | // Variables in co-routines must be declared static if they must maintain value across a blocking call. |
| fep | 0:5ff20db10a96 | 311 | // This may not be necessary for const variables. |
| fep | 0:5ff20db10a96 | 312 | // We are to delay for 200ms. |
| fep | 0:5ff20db10a96 | 313 | static const xTickType xDelayTime = 200 / portTICK_PERIOD_MS; |
| fep | 0:5ff20db10a96 | 314 | |
| fep | 0:5ff20db10a96 | 315 | // Must start every co-routine with a call to crSTART(); |
| fep | 0:5ff20db10a96 | 316 | crSTART( xHandle ); |
| fep | 0:5ff20db10a96 | 317 | |
| fep | 0:5ff20db10a96 | 318 | for( ;; ) |
| fep | 0:5ff20db10a96 | 319 | { |
| fep | 0:5ff20db10a96 | 320 | // Delay for 200ms. |
| fep | 0:5ff20db10a96 | 321 | crDELAY( xHandle, xDelayTime ); |
| fep | 0:5ff20db10a96 | 322 | |
| fep | 0:5ff20db10a96 | 323 | // Do something here. |
| fep | 0:5ff20db10a96 | 324 | } |
| fep | 0:5ff20db10a96 | 325 | |
| fep | 0:5ff20db10a96 | 326 | // Must end every co-routine with a call to crEND(); |
| fep | 0:5ff20db10a96 | 327 | crEND(); |
| fep | 0:5ff20db10a96 | 328 | }</pre> |
| fep | 0:5ff20db10a96 | 329 | * \defgroup crDELAY crDELAY |
| fep | 0:5ff20db10a96 | 330 | * \ingroup Tasks |
| fep | 0:5ff20db10a96 | 331 | */ |
| fep | 0:5ff20db10a96 | 332 | #define crDELAY( xHandle, xTicksToDelay ) \ |
| fep | 0:5ff20db10a96 | 333 | if( ( xTicksToDelay ) > 0 ) \ |
| fep | 0:5ff20db10a96 | 334 | { \ |
| fep | 0:5ff20db10a96 | 335 | vCoRoutineAddToDelayedList( ( xTicksToDelay ), NULL ); \ |
| fep | 0:5ff20db10a96 | 336 | } \ |
| fep | 0:5ff20db10a96 | 337 | crSET_STATE0( ( xHandle ) ); |
| fep | 0:5ff20db10a96 | 338 | |
| fep | 0:5ff20db10a96 | 339 | /** |
| fep | 0:5ff20db10a96 | 340 | * <pre> |
| fep | 0:5ff20db10a96 | 341 | crQUEUE_SEND( |
| fep | 0:5ff20db10a96 | 342 | CoRoutineHandle_t xHandle, |
| fep | 0:5ff20db10a96 | 343 | QueueHandle_t pxQueue, |
| fep | 0:5ff20db10a96 | 344 | void *pvItemToQueue, |
| fep | 0:5ff20db10a96 | 345 | TickType_t xTicksToWait, |
| fep | 0:5ff20db10a96 | 346 | BaseType_t *pxResult |
| fep | 0:5ff20db10a96 | 347 | )</pre> |
| fep | 0:5ff20db10a96 | 348 | * |
| fep | 0:5ff20db10a96 | 349 | * The macro's crQUEUE_SEND() and crQUEUE_RECEIVE() are the co-routine |
| fep | 0:5ff20db10a96 | 350 | * equivalent to the xQueueSend() and xQueueReceive() functions used by tasks. |
| fep | 0:5ff20db10a96 | 351 | * |
| fep | 0:5ff20db10a96 | 352 | * crQUEUE_SEND and crQUEUE_RECEIVE can only be used from a co-routine whereas |
| fep | 0:5ff20db10a96 | 353 | * xQueueSend() and xQueueReceive() can only be used from tasks. |
| fep | 0:5ff20db10a96 | 354 | * |
| fep | 0:5ff20db10a96 | 355 | * crQUEUE_SEND can only be called from the co-routine function itself - not |
| fep | 0:5ff20db10a96 | 356 | * from within a function called by the co-routine function. This is because |
| fep | 0:5ff20db10a96 | 357 | * co-routines do not maintain their own stack. |
| fep | 0:5ff20db10a96 | 358 | * |
| fep | 0:5ff20db10a96 | 359 | * See the co-routine section of the WEB documentation for information on |
| fep | 0:5ff20db10a96 | 360 | * passing data between tasks and co-routines and between ISR's and |
| fep | 0:5ff20db10a96 | 361 | * co-routines. |
| fep | 0:5ff20db10a96 | 362 | * |
| fep | 0:5ff20db10a96 | 363 | * @param xHandle The handle of the calling co-routine. This is the xHandle |
| fep | 0:5ff20db10a96 | 364 | * parameter of the co-routine function. |
| fep | 0:5ff20db10a96 | 365 | * |
| fep | 0:5ff20db10a96 | 366 | * @param pxQueue The handle of the queue on which the data will be posted. |
| fep | 0:5ff20db10a96 | 367 | * The handle is obtained as the return value when the queue is created using |
| fep | 0:5ff20db10a96 | 368 | * the xQueueCreate() API function. |
| fep | 0:5ff20db10a96 | 369 | * |
| fep | 0:5ff20db10a96 | 370 | * @param pvItemToQueue A pointer to the data being posted onto the queue. |
| fep | 0:5ff20db10a96 | 371 | * The number of bytes of each queued item is specified when the queue is |
| fep | 0:5ff20db10a96 | 372 | * created. This number of bytes is copied from pvItemToQueue into the queue |
| fep | 0:5ff20db10a96 | 373 | * itself. |
| fep | 0:5ff20db10a96 | 374 | * |
| fep | 0:5ff20db10a96 | 375 | * @param xTickToDelay The number of ticks that the co-routine should block |
| fep | 0:5ff20db10a96 | 376 | * to wait for space to become available on the queue, should space not be |
| fep | 0:5ff20db10a96 | 377 | * available immediately. The actual amount of time this equates to is defined |
| fep | 0:5ff20db10a96 | 378 | * by configTICK_RATE_HZ (set in FreeRTOSConfig.h). The constant |
| fep | 0:5ff20db10a96 | 379 | * portTICK_PERIOD_MS can be used to convert ticks to milliseconds (see example |
| fep | 0:5ff20db10a96 | 380 | * below). |
| fep | 0:5ff20db10a96 | 381 | * |
| fep | 0:5ff20db10a96 | 382 | * @param pxResult The variable pointed to by pxResult will be set to pdPASS if |
| fep | 0:5ff20db10a96 | 383 | * data was successfully posted onto the queue, otherwise it will be set to an |
| fep | 0:5ff20db10a96 | 384 | * error defined within ProjDefs.h. |
| fep | 0:5ff20db10a96 | 385 | * |
| fep | 0:5ff20db10a96 | 386 | * Example usage: |
| fep | 0:5ff20db10a96 | 387 | <pre> |
| fep | 0:5ff20db10a96 | 388 | // Co-routine function that blocks for a fixed period then posts a number onto |
| fep | 0:5ff20db10a96 | 389 | // a queue. |
| fep | 0:5ff20db10a96 | 390 | static void prvCoRoutineFlashTask( CoRoutineHandle_t xHandle, UBaseType_t uxIndex ) |
| fep | 0:5ff20db10a96 | 391 | { |
| fep | 0:5ff20db10a96 | 392 | // Variables in co-routines must be declared static if they must maintain value across a blocking call. |
| fep | 0:5ff20db10a96 | 393 | static BaseType_t xNumberToPost = 0; |
| fep | 0:5ff20db10a96 | 394 | static BaseType_t xResult; |
| fep | 0:5ff20db10a96 | 395 | |
| fep | 0:5ff20db10a96 | 396 | // Co-routines must begin with a call to crSTART(). |
| fep | 0:5ff20db10a96 | 397 | crSTART( xHandle ); |
| fep | 0:5ff20db10a96 | 398 | |
| fep | 0:5ff20db10a96 | 399 | for( ;; ) |
| fep | 0:5ff20db10a96 | 400 | { |
| fep | 0:5ff20db10a96 | 401 | // This assumes the queue has already been created. |
| fep | 0:5ff20db10a96 | 402 | crQUEUE_SEND( xHandle, xCoRoutineQueue, &xNumberToPost, NO_DELAY, &xResult ); |
| fep | 0:5ff20db10a96 | 403 | |
| fep | 0:5ff20db10a96 | 404 | if( xResult != pdPASS ) |
| fep | 0:5ff20db10a96 | 405 | { |
| fep | 0:5ff20db10a96 | 406 | // The message was not posted! |
| fep | 0:5ff20db10a96 | 407 | } |
| fep | 0:5ff20db10a96 | 408 | |
| fep | 0:5ff20db10a96 | 409 | // Increment the number to be posted onto the queue. |
| fep | 0:5ff20db10a96 | 410 | xNumberToPost++; |
| fep | 0:5ff20db10a96 | 411 | |
| fep | 0:5ff20db10a96 | 412 | // Delay for 100 ticks. |
| fep | 0:5ff20db10a96 | 413 | crDELAY( xHandle, 100 ); |
| fep | 0:5ff20db10a96 | 414 | } |
| fep | 0:5ff20db10a96 | 415 | |
| fep | 0:5ff20db10a96 | 416 | // Co-routines must end with a call to crEND(). |
| fep | 0:5ff20db10a96 | 417 | crEND(); |
| fep | 0:5ff20db10a96 | 418 | }</pre> |
| fep | 0:5ff20db10a96 | 419 | * \defgroup crQUEUE_SEND crQUEUE_SEND |
| fep | 0:5ff20db10a96 | 420 | * \ingroup Tasks |
| fep | 0:5ff20db10a96 | 421 | */ |
| fep | 0:5ff20db10a96 | 422 | #define crQUEUE_SEND( xHandle, pxQueue, pvItemToQueue, xTicksToWait, pxResult ) \ |
| fep | 0:5ff20db10a96 | 423 | { \ |
| fep | 0:5ff20db10a96 | 424 | *( pxResult ) = xQueueCRSend( ( pxQueue) , ( pvItemToQueue) , ( xTicksToWait ) ); \ |
| fep | 0:5ff20db10a96 | 425 | if( *( pxResult ) == errQUEUE_BLOCKED ) \ |
| fep | 0:5ff20db10a96 | 426 | { \ |
| fep | 0:5ff20db10a96 | 427 | crSET_STATE0( ( xHandle ) ); \ |
| fep | 0:5ff20db10a96 | 428 | *pxResult = xQueueCRSend( ( pxQueue ), ( pvItemToQueue ), 0 ); \ |
| fep | 0:5ff20db10a96 | 429 | } \ |
| fep | 0:5ff20db10a96 | 430 | if( *pxResult == errQUEUE_YIELD ) \ |
| fep | 0:5ff20db10a96 | 431 | { \ |
| fep | 0:5ff20db10a96 | 432 | crSET_STATE1( ( xHandle ) ); \ |
| fep | 0:5ff20db10a96 | 433 | *pxResult = pdPASS; \ |
| fep | 0:5ff20db10a96 | 434 | } \ |
| fep | 0:5ff20db10a96 | 435 | } |
| fep | 0:5ff20db10a96 | 436 | |
| fep | 0:5ff20db10a96 | 437 | /** |
| fep | 0:5ff20db10a96 | 438 | * croutine. h |
| fep | 0:5ff20db10a96 | 439 | * <pre> |
| fep | 0:5ff20db10a96 | 440 | crQUEUE_RECEIVE( |
| fep | 0:5ff20db10a96 | 441 | CoRoutineHandle_t xHandle, |
| fep | 0:5ff20db10a96 | 442 | QueueHandle_t pxQueue, |
| fep | 0:5ff20db10a96 | 443 | void *pvBuffer, |
| fep | 0:5ff20db10a96 | 444 | TickType_t xTicksToWait, |
| fep | 0:5ff20db10a96 | 445 | BaseType_t *pxResult |
| fep | 0:5ff20db10a96 | 446 | )</pre> |
| fep | 0:5ff20db10a96 | 447 | * |
| fep | 0:5ff20db10a96 | 448 | * The macro's crQUEUE_SEND() and crQUEUE_RECEIVE() are the co-routine |
| fep | 0:5ff20db10a96 | 449 | * equivalent to the xQueueSend() and xQueueReceive() functions used by tasks. |
| fep | 0:5ff20db10a96 | 450 | * |
| fep | 0:5ff20db10a96 | 451 | * crQUEUE_SEND and crQUEUE_RECEIVE can only be used from a co-routine whereas |
| fep | 0:5ff20db10a96 | 452 | * xQueueSend() and xQueueReceive() can only be used from tasks. |
| fep | 0:5ff20db10a96 | 453 | * |
| fep | 0:5ff20db10a96 | 454 | * crQUEUE_RECEIVE can only be called from the co-routine function itself - not |
| fep | 0:5ff20db10a96 | 455 | * from within a function called by the co-routine function. This is because |
| fep | 0:5ff20db10a96 | 456 | * co-routines do not maintain their own stack. |
| fep | 0:5ff20db10a96 | 457 | * |
| fep | 0:5ff20db10a96 | 458 | * See the co-routine section of the WEB documentation for information on |
| fep | 0:5ff20db10a96 | 459 | * passing data between tasks and co-routines and between ISR's and |
| fep | 0:5ff20db10a96 | 460 | * co-routines. |
| fep | 0:5ff20db10a96 | 461 | * |
| fep | 0:5ff20db10a96 | 462 | * @param xHandle The handle of the calling co-routine. This is the xHandle |
| fep | 0:5ff20db10a96 | 463 | * parameter of the co-routine function. |
| fep | 0:5ff20db10a96 | 464 | * |
| fep | 0:5ff20db10a96 | 465 | * @param pxQueue The handle of the queue from which the data will be received. |
| fep | 0:5ff20db10a96 | 466 | * The handle is obtained as the return value when the queue is created using |
| fep | 0:5ff20db10a96 | 467 | * the xQueueCreate() API function. |
| fep | 0:5ff20db10a96 | 468 | * |
| fep | 0:5ff20db10a96 | 469 | * @param pvBuffer The buffer into which the received item is to be copied. |
| fep | 0:5ff20db10a96 | 470 | * The number of bytes of each queued item is specified when the queue is |
| fep | 0:5ff20db10a96 | 471 | * created. This number of bytes is copied into pvBuffer. |
| fep | 0:5ff20db10a96 | 472 | * |
| fep | 0:5ff20db10a96 | 473 | * @param xTickToDelay The number of ticks that the co-routine should block |
| fep | 0:5ff20db10a96 | 474 | * to wait for data to become available from the queue, should data not be |
| fep | 0:5ff20db10a96 | 475 | * available immediately. The actual amount of time this equates to is defined |
| fep | 0:5ff20db10a96 | 476 | * by configTICK_RATE_HZ (set in FreeRTOSConfig.h). The constant |
| fep | 0:5ff20db10a96 | 477 | * portTICK_PERIOD_MS can be used to convert ticks to milliseconds (see the |
| fep | 0:5ff20db10a96 | 478 | * crQUEUE_SEND example). |
| fep | 0:5ff20db10a96 | 479 | * |
| fep | 0:5ff20db10a96 | 480 | * @param pxResult The variable pointed to by pxResult will be set to pdPASS if |
| fep | 0:5ff20db10a96 | 481 | * data was successfully retrieved from the queue, otherwise it will be set to |
| fep | 0:5ff20db10a96 | 482 | * an error code as defined within ProjDefs.h. |
| fep | 0:5ff20db10a96 | 483 | * |
| fep | 0:5ff20db10a96 | 484 | * Example usage: |
| fep | 0:5ff20db10a96 | 485 | <pre> |
| fep | 0:5ff20db10a96 | 486 | // A co-routine receives the number of an LED to flash from a queue. It |
| fep | 0:5ff20db10a96 | 487 | // blocks on the queue until the number is received. |
| fep | 0:5ff20db10a96 | 488 | static void prvCoRoutineFlashWorkTask( CoRoutineHandle_t xHandle, UBaseType_t uxIndex ) |
| fep | 0:5ff20db10a96 | 489 | { |
| fep | 0:5ff20db10a96 | 490 | // Variables in co-routines must be declared static if they must maintain value across a blocking call. |
| fep | 0:5ff20db10a96 | 491 | static BaseType_t xResult; |
| fep | 0:5ff20db10a96 | 492 | static UBaseType_t uxLEDToFlash; |
| fep | 0:5ff20db10a96 | 493 | |
| fep | 0:5ff20db10a96 | 494 | // All co-routines must start with a call to crSTART(). |
| fep | 0:5ff20db10a96 | 495 | crSTART( xHandle ); |
| fep | 0:5ff20db10a96 | 496 | |
| fep | 0:5ff20db10a96 | 497 | for( ;; ) |
| fep | 0:5ff20db10a96 | 498 | { |
| fep | 0:5ff20db10a96 | 499 | // Wait for data to become available on the queue. |
| fep | 0:5ff20db10a96 | 500 | crQUEUE_RECEIVE( xHandle, xCoRoutineQueue, &uxLEDToFlash, portMAX_DELAY, &xResult ); |
| fep | 0:5ff20db10a96 | 501 | |
| fep | 0:5ff20db10a96 | 502 | if( xResult == pdPASS ) |
| fep | 0:5ff20db10a96 | 503 | { |
| fep | 0:5ff20db10a96 | 504 | // We received the LED to flash - flash it! |
| fep | 0:5ff20db10a96 | 505 | vParTestToggleLED( uxLEDToFlash ); |
| fep | 0:5ff20db10a96 | 506 | } |
| fep | 0:5ff20db10a96 | 507 | } |
| fep | 0:5ff20db10a96 | 508 | |
| fep | 0:5ff20db10a96 | 509 | crEND(); |
| fep | 0:5ff20db10a96 | 510 | }</pre> |
| fep | 0:5ff20db10a96 | 511 | * \defgroup crQUEUE_RECEIVE crQUEUE_RECEIVE |
| fep | 0:5ff20db10a96 | 512 | * \ingroup Tasks |
| fep | 0:5ff20db10a96 | 513 | */ |
| fep | 0:5ff20db10a96 | 514 | #define crQUEUE_RECEIVE( xHandle, pxQueue, pvBuffer, xTicksToWait, pxResult ) \ |
| fep | 0:5ff20db10a96 | 515 | { \ |
| fep | 0:5ff20db10a96 | 516 | *( pxResult ) = xQueueCRReceive( ( pxQueue) , ( pvBuffer ), ( xTicksToWait ) ); \ |
| fep | 0:5ff20db10a96 | 517 | if( *( pxResult ) == errQUEUE_BLOCKED ) \ |
| fep | 0:5ff20db10a96 | 518 | { \ |
| fep | 0:5ff20db10a96 | 519 | crSET_STATE0( ( xHandle ) ); \ |
| fep | 0:5ff20db10a96 | 520 | *( pxResult ) = xQueueCRReceive( ( pxQueue) , ( pvBuffer ), 0 ); \ |
| fep | 0:5ff20db10a96 | 521 | } \ |
| fep | 0:5ff20db10a96 | 522 | if( *( pxResult ) == errQUEUE_YIELD ) \ |
| fep | 0:5ff20db10a96 | 523 | { \ |
| fep | 0:5ff20db10a96 | 524 | crSET_STATE1( ( xHandle ) ); \ |
| fep | 0:5ff20db10a96 | 525 | *( pxResult ) = pdPASS; \ |
| fep | 0:5ff20db10a96 | 526 | } \ |
| fep | 0:5ff20db10a96 | 527 | } |
| fep | 0:5ff20db10a96 | 528 | |
| fep | 0:5ff20db10a96 | 529 | /** |
| fep | 0:5ff20db10a96 | 530 | * croutine. h |
| fep | 0:5ff20db10a96 | 531 | * <pre> |
| fep | 0:5ff20db10a96 | 532 | crQUEUE_SEND_FROM_ISR( |
| fep | 0:5ff20db10a96 | 533 | QueueHandle_t pxQueue, |
| fep | 0:5ff20db10a96 | 534 | void *pvItemToQueue, |
| fep | 0:5ff20db10a96 | 535 | BaseType_t xCoRoutinePreviouslyWoken |
| fep | 0:5ff20db10a96 | 536 | )</pre> |
| fep | 0:5ff20db10a96 | 537 | * |
| fep | 0:5ff20db10a96 | 538 | * The macro's crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() are the |
| fep | 0:5ff20db10a96 | 539 | * co-routine equivalent to the xQueueSendFromISR() and xQueueReceiveFromISR() |
| fep | 0:5ff20db10a96 | 540 | * functions used by tasks. |
| fep | 0:5ff20db10a96 | 541 | * |
| fep | 0:5ff20db10a96 | 542 | * crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() can only be used to |
| fep | 0:5ff20db10a96 | 543 | * pass data between a co-routine and and ISR, whereas xQueueSendFromISR() and |
| fep | 0:5ff20db10a96 | 544 | * xQueueReceiveFromISR() can only be used to pass data between a task and and |
| fep | 0:5ff20db10a96 | 545 | * ISR. |
| fep | 0:5ff20db10a96 | 546 | * |
| fep | 0:5ff20db10a96 | 547 | * crQUEUE_SEND_FROM_ISR can only be called from an ISR to send data to a queue |
| fep | 0:5ff20db10a96 | 548 | * that is being used from within a co-routine. |
| fep | 0:5ff20db10a96 | 549 | * |
| fep | 0:5ff20db10a96 | 550 | * See the co-routine section of the WEB documentation for information on |
| fep | 0:5ff20db10a96 | 551 | * passing data between tasks and co-routines and between ISR's and |
| fep | 0:5ff20db10a96 | 552 | * co-routines. |
| fep | 0:5ff20db10a96 | 553 | * |
| fep | 0:5ff20db10a96 | 554 | * @param xQueue The handle to the queue on which the item is to be posted. |
| fep | 0:5ff20db10a96 | 555 | * |
| fep | 0:5ff20db10a96 | 556 | * @param pvItemToQueue A pointer to the item that is to be placed on the |
| fep | 0:5ff20db10a96 | 557 | * queue. The size of the items the queue will hold was defined when the |
| fep | 0:5ff20db10a96 | 558 | * queue was created, so this many bytes will be copied from pvItemToQueue |
| fep | 0:5ff20db10a96 | 559 | * into the queue storage area. |
| fep | 0:5ff20db10a96 | 560 | * |
| fep | 0:5ff20db10a96 | 561 | * @param xCoRoutinePreviouslyWoken This is included so an ISR can post onto |
| fep | 0:5ff20db10a96 | 562 | * the same queue multiple times from a single interrupt. The first call |
| fep | 0:5ff20db10a96 | 563 | * should always pass in pdFALSE. Subsequent calls should pass in |
| fep | 0:5ff20db10a96 | 564 | * the value returned from the previous call. |
| fep | 0:5ff20db10a96 | 565 | * |
| fep | 0:5ff20db10a96 | 566 | * @return pdTRUE if a co-routine was woken by posting onto the queue. This is |
| fep | 0:5ff20db10a96 | 567 | * used by the ISR to determine if a context switch may be required following |
| fep | 0:5ff20db10a96 | 568 | * the ISR. |
| fep | 0:5ff20db10a96 | 569 | * |
| fep | 0:5ff20db10a96 | 570 | * Example usage: |
| fep | 0:5ff20db10a96 | 571 | <pre> |
| fep | 0:5ff20db10a96 | 572 | // A co-routine that blocks on a queue waiting for characters to be received. |
| fep | 0:5ff20db10a96 | 573 | static void vReceivingCoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex ) |
| fep | 0:5ff20db10a96 | 574 | { |
| fep | 0:5ff20db10a96 | 575 | char cRxedChar; |
| fep | 0:5ff20db10a96 | 576 | BaseType_t xResult; |
| fep | 0:5ff20db10a96 | 577 | |
| fep | 0:5ff20db10a96 | 578 | // All co-routines must start with a call to crSTART(). |
| fep | 0:5ff20db10a96 | 579 | crSTART( xHandle ); |
| fep | 0:5ff20db10a96 | 580 | |
| fep | 0:5ff20db10a96 | 581 | for( ;; ) |
| fep | 0:5ff20db10a96 | 582 | { |
| fep | 0:5ff20db10a96 | 583 | // Wait for data to become available on the queue. This assumes the |
| fep | 0:5ff20db10a96 | 584 | // queue xCommsRxQueue has already been created! |
| fep | 0:5ff20db10a96 | 585 | crQUEUE_RECEIVE( xHandle, xCommsRxQueue, &uxLEDToFlash, portMAX_DELAY, &xResult ); |
| fep | 0:5ff20db10a96 | 586 | |
| fep | 0:5ff20db10a96 | 587 | // Was a character received? |
| fep | 0:5ff20db10a96 | 588 | if( xResult == pdPASS ) |
| fep | 0:5ff20db10a96 | 589 | { |
| fep | 0:5ff20db10a96 | 590 | // Process the character here. |
| fep | 0:5ff20db10a96 | 591 | } |
| fep | 0:5ff20db10a96 | 592 | } |
| fep | 0:5ff20db10a96 | 593 | |
| fep | 0:5ff20db10a96 | 594 | // All co-routines must end with a call to crEND(). |
| fep | 0:5ff20db10a96 | 595 | crEND(); |
| fep | 0:5ff20db10a96 | 596 | } |
| fep | 0:5ff20db10a96 | 597 | |
| fep | 0:5ff20db10a96 | 598 | // An ISR that uses a queue to send characters received on a serial port to |
| fep | 0:5ff20db10a96 | 599 | // a co-routine. |
| fep | 0:5ff20db10a96 | 600 | void vUART_ISR( void ) |
| fep | 0:5ff20db10a96 | 601 | { |
| fep | 0:5ff20db10a96 | 602 | char cRxedChar; |
| fep | 0:5ff20db10a96 | 603 | BaseType_t xCRWokenByPost = pdFALSE; |
| fep | 0:5ff20db10a96 | 604 | |
| fep | 0:5ff20db10a96 | 605 | // We loop around reading characters until there are none left in the UART. |
| fep | 0:5ff20db10a96 | 606 | while( UART_RX_REG_NOT_EMPTY() ) |
| fep | 0:5ff20db10a96 | 607 | { |
| fep | 0:5ff20db10a96 | 608 | // Obtain the character from the UART. |
| fep | 0:5ff20db10a96 | 609 | cRxedChar = UART_RX_REG; |
| fep | 0:5ff20db10a96 | 610 | |
| fep | 0:5ff20db10a96 | 611 | // Post the character onto a queue. xCRWokenByPost will be pdFALSE |
| fep | 0:5ff20db10a96 | 612 | // the first time around the loop. If the post causes a co-routine |
| fep | 0:5ff20db10a96 | 613 | // to be woken (unblocked) then xCRWokenByPost will be set to pdTRUE. |
| fep | 0:5ff20db10a96 | 614 | // In this manner we can ensure that if more than one co-routine is |
| fep | 0:5ff20db10a96 | 615 | // blocked on the queue only one is woken by this ISR no matter how |
| fep | 0:5ff20db10a96 | 616 | // many characters are posted to the queue. |
| fep | 0:5ff20db10a96 | 617 | xCRWokenByPost = crQUEUE_SEND_FROM_ISR( xCommsRxQueue, &cRxedChar, xCRWokenByPost ); |
| fep | 0:5ff20db10a96 | 618 | } |
| fep | 0:5ff20db10a96 | 619 | }</pre> |
| fep | 0:5ff20db10a96 | 620 | * \defgroup crQUEUE_SEND_FROM_ISR crQUEUE_SEND_FROM_ISR |
| fep | 0:5ff20db10a96 | 621 | * \ingroup Tasks |
| fep | 0:5ff20db10a96 | 622 | */ |
| fep | 0:5ff20db10a96 | 623 | #define crQUEUE_SEND_FROM_ISR( pxQueue, pvItemToQueue, xCoRoutinePreviouslyWoken ) xQueueCRSendFromISR( ( pxQueue ), ( pvItemToQueue ), ( xCoRoutinePreviouslyWoken ) ) |
| fep | 0:5ff20db10a96 | 624 | |
| fep | 0:5ff20db10a96 | 625 | |
| fep | 0:5ff20db10a96 | 626 | /** |
| fep | 0:5ff20db10a96 | 627 | * croutine. h |
| fep | 0:5ff20db10a96 | 628 | * <pre> |
| fep | 0:5ff20db10a96 | 629 | crQUEUE_SEND_FROM_ISR( |
| fep | 0:5ff20db10a96 | 630 | QueueHandle_t pxQueue, |
| fep | 0:5ff20db10a96 | 631 | void *pvBuffer, |
| fep | 0:5ff20db10a96 | 632 | BaseType_t * pxCoRoutineWoken |
| fep | 0:5ff20db10a96 | 633 | )</pre> |
| fep | 0:5ff20db10a96 | 634 | * |
| fep | 0:5ff20db10a96 | 635 | * The macro's crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() are the |
| fep | 0:5ff20db10a96 | 636 | * co-routine equivalent to the xQueueSendFromISR() and xQueueReceiveFromISR() |
| fep | 0:5ff20db10a96 | 637 | * functions used by tasks. |
| fep | 0:5ff20db10a96 | 638 | * |
| fep | 0:5ff20db10a96 | 639 | * crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() can only be used to |
| fep | 0:5ff20db10a96 | 640 | * pass data between a co-routine and and ISR, whereas xQueueSendFromISR() and |
| fep | 0:5ff20db10a96 | 641 | * xQueueReceiveFromISR() can only be used to pass data between a task and and |
| fep | 0:5ff20db10a96 | 642 | * ISR. |
| fep | 0:5ff20db10a96 | 643 | * |
| fep | 0:5ff20db10a96 | 644 | * crQUEUE_RECEIVE_FROM_ISR can only be called from an ISR to receive data |
| fep | 0:5ff20db10a96 | 645 | * from a queue that is being used from within a co-routine (a co-routine |
| fep | 0:5ff20db10a96 | 646 | * posted to the queue). |
| fep | 0:5ff20db10a96 | 647 | * |
| fep | 0:5ff20db10a96 | 648 | * See the co-routine section of the WEB documentation for information on |
| fep | 0:5ff20db10a96 | 649 | * passing data between tasks and co-routines and between ISR's and |
| fep | 0:5ff20db10a96 | 650 | * co-routines. |
| fep | 0:5ff20db10a96 | 651 | * |
| fep | 0:5ff20db10a96 | 652 | * @param xQueue The handle to the queue on which the item is to be posted. |
| fep | 0:5ff20db10a96 | 653 | * |
| fep | 0:5ff20db10a96 | 654 | * @param pvBuffer A pointer to a buffer into which the received item will be |
| fep | 0:5ff20db10a96 | 655 | * placed. The size of the items the queue will hold was defined when the |
| fep | 0:5ff20db10a96 | 656 | * queue was created, so this many bytes will be copied from the queue into |
| fep | 0:5ff20db10a96 | 657 | * pvBuffer. |
| fep | 0:5ff20db10a96 | 658 | * |
| fep | 0:5ff20db10a96 | 659 | * @param pxCoRoutineWoken A co-routine may be blocked waiting for space to become |
| fep | 0:5ff20db10a96 | 660 | * available on the queue. If crQUEUE_RECEIVE_FROM_ISR causes such a |
| fep | 0:5ff20db10a96 | 661 | * co-routine to unblock *pxCoRoutineWoken will get set to pdTRUE, otherwise |
| fep | 0:5ff20db10a96 | 662 | * *pxCoRoutineWoken will remain unchanged. |
| fep | 0:5ff20db10a96 | 663 | * |
| fep | 0:5ff20db10a96 | 664 | * @return pdTRUE an item was successfully received from the queue, otherwise |
| fep | 0:5ff20db10a96 | 665 | * pdFALSE. |
| fep | 0:5ff20db10a96 | 666 | * |
| fep | 0:5ff20db10a96 | 667 | * Example usage: |
| fep | 0:5ff20db10a96 | 668 | <pre> |
| fep | 0:5ff20db10a96 | 669 | // A co-routine that posts a character to a queue then blocks for a fixed |
| fep | 0:5ff20db10a96 | 670 | // period. The character is incremented each time. |
| fep | 0:5ff20db10a96 | 671 | static void vSendingCoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex ) |
| fep | 0:5ff20db10a96 | 672 | { |
| fep | 0:5ff20db10a96 | 673 | // cChar holds its value while this co-routine is blocked and must therefore |
| fep | 0:5ff20db10a96 | 674 | // be declared static. |
| fep | 0:5ff20db10a96 | 675 | static char cCharToTx = 'a'; |
| fep | 0:5ff20db10a96 | 676 | BaseType_t xResult; |
| fep | 0:5ff20db10a96 | 677 | |
| fep | 0:5ff20db10a96 | 678 | // All co-routines must start with a call to crSTART(). |
| fep | 0:5ff20db10a96 | 679 | crSTART( xHandle ); |
| fep | 0:5ff20db10a96 | 680 | |
| fep | 0:5ff20db10a96 | 681 | for( ;; ) |
| fep | 0:5ff20db10a96 | 682 | { |
| fep | 0:5ff20db10a96 | 683 | // Send the next character to the queue. |
| fep | 0:5ff20db10a96 | 684 | crQUEUE_SEND( xHandle, xCoRoutineQueue, &cCharToTx, NO_DELAY, &xResult ); |
| fep | 0:5ff20db10a96 | 685 | |
| fep | 0:5ff20db10a96 | 686 | if( xResult == pdPASS ) |
| fep | 0:5ff20db10a96 | 687 | { |
| fep | 0:5ff20db10a96 | 688 | // The character was successfully posted to the queue. |
| fep | 0:5ff20db10a96 | 689 | } |
| fep | 0:5ff20db10a96 | 690 | else |
| fep | 0:5ff20db10a96 | 691 | { |
| fep | 0:5ff20db10a96 | 692 | // Could not post the character to the queue. |
| fep | 0:5ff20db10a96 | 693 | } |
| fep | 0:5ff20db10a96 | 694 | |
| fep | 0:5ff20db10a96 | 695 | // Enable the UART Tx interrupt to cause an interrupt in this |
| fep | 0:5ff20db10a96 | 696 | // hypothetical UART. The interrupt will obtain the character |
| fep | 0:5ff20db10a96 | 697 | // from the queue and send it. |
| fep | 0:5ff20db10a96 | 698 | ENABLE_RX_INTERRUPT(); |
| fep | 0:5ff20db10a96 | 699 | |
| fep | 0:5ff20db10a96 | 700 | // Increment to the next character then block for a fixed period. |
| fep | 0:5ff20db10a96 | 701 | // cCharToTx will maintain its value across the delay as it is |
| fep | 0:5ff20db10a96 | 702 | // declared static. |
| fep | 0:5ff20db10a96 | 703 | cCharToTx++; |
| fep | 0:5ff20db10a96 | 704 | if( cCharToTx > 'x' ) |
| fep | 0:5ff20db10a96 | 705 | { |
| fep | 0:5ff20db10a96 | 706 | cCharToTx = 'a'; |
| fep | 0:5ff20db10a96 | 707 | } |
| fep | 0:5ff20db10a96 | 708 | crDELAY( 100 ); |
| fep | 0:5ff20db10a96 | 709 | } |
| fep | 0:5ff20db10a96 | 710 | |
| fep | 0:5ff20db10a96 | 711 | // All co-routines must end with a call to crEND(). |
| fep | 0:5ff20db10a96 | 712 | crEND(); |
| fep | 0:5ff20db10a96 | 713 | } |
| fep | 0:5ff20db10a96 | 714 | |
| fep | 0:5ff20db10a96 | 715 | // An ISR that uses a queue to receive characters to send on a UART. |
| fep | 0:5ff20db10a96 | 716 | void vUART_ISR( void ) |
| fep | 0:5ff20db10a96 | 717 | { |
| fep | 0:5ff20db10a96 | 718 | char cCharToTx; |
| fep | 0:5ff20db10a96 | 719 | BaseType_t xCRWokenByPost = pdFALSE; |
| fep | 0:5ff20db10a96 | 720 | |
| fep | 0:5ff20db10a96 | 721 | while( UART_TX_REG_EMPTY() ) |
| fep | 0:5ff20db10a96 | 722 | { |
| fep | 0:5ff20db10a96 | 723 | // Are there any characters in the queue waiting to be sent? |
| fep | 0:5ff20db10a96 | 724 | // xCRWokenByPost will automatically be set to pdTRUE if a co-routine |
| fep | 0:5ff20db10a96 | 725 | // is woken by the post - ensuring that only a single co-routine is |
| fep | 0:5ff20db10a96 | 726 | // woken no matter how many times we go around this loop. |
| fep | 0:5ff20db10a96 | 727 | if( crQUEUE_RECEIVE_FROM_ISR( pxQueue, &cCharToTx, &xCRWokenByPost ) ) |
| fep | 0:5ff20db10a96 | 728 | { |
| fep | 0:5ff20db10a96 | 729 | SEND_CHARACTER( cCharToTx ); |
| fep | 0:5ff20db10a96 | 730 | } |
| fep | 0:5ff20db10a96 | 731 | } |
| fep | 0:5ff20db10a96 | 732 | }</pre> |
| fep | 0:5ff20db10a96 | 733 | * \defgroup crQUEUE_RECEIVE_FROM_ISR crQUEUE_RECEIVE_FROM_ISR |
| fep | 0:5ff20db10a96 | 734 | * \ingroup Tasks |
| fep | 0:5ff20db10a96 | 735 | */ |
| fep | 0:5ff20db10a96 | 736 | #define crQUEUE_RECEIVE_FROM_ISR( pxQueue, pvBuffer, pxCoRoutineWoken ) xQueueCRReceiveFromISR( ( pxQueue ), ( pvBuffer ), ( pxCoRoutineWoken ) ) |
| fep | 0:5ff20db10a96 | 737 | |
| fep | 0:5ff20db10a96 | 738 | /* |
| fep | 0:5ff20db10a96 | 739 | * This function is intended for internal use by the co-routine macros only. |
| fep | 0:5ff20db10a96 | 740 | * The macro nature of the co-routine implementation requires that the |
| fep | 0:5ff20db10a96 | 741 | * prototype appears here. The function should not be used by application |
| fep | 0:5ff20db10a96 | 742 | * writers. |
| fep | 0:5ff20db10a96 | 743 | * |
| fep | 0:5ff20db10a96 | 744 | * Removes the current co-routine from its ready list and places it in the |
| fep | 0:5ff20db10a96 | 745 | * appropriate delayed list. |
| fep | 0:5ff20db10a96 | 746 | */ |
| fep | 0:5ff20db10a96 | 747 | void vCoRoutineAddToDelayedList( TickType_t xTicksToDelay, List_t *pxEventList ); |
| fep | 0:5ff20db10a96 | 748 | |
| fep | 0:5ff20db10a96 | 749 | /* |
| fep | 0:5ff20db10a96 | 750 | * This function is intended for internal use by the queue implementation only. |
| fep | 0:5ff20db10a96 | 751 | * The function should not be used by application writers. |
| fep | 0:5ff20db10a96 | 752 | * |
| fep | 0:5ff20db10a96 | 753 | * Removes the highest priority co-routine from the event list and places it in |
| fep | 0:5ff20db10a96 | 754 | * the pending ready list. |
| fep | 0:5ff20db10a96 | 755 | */ |
| fep | 0:5ff20db10a96 | 756 | BaseType_t xCoRoutineRemoveFromEventList( const List_t *pxEventList ); |
| fep | 0:5ff20db10a96 | 757 | |
| fep | 0:5ff20db10a96 | 758 | #ifdef __cplusplus |
| fep | 0:5ff20db10a96 | 759 | } |
| fep | 0:5ff20db10a96 | 760 | #endif |
| fep | 0:5ff20db10a96 | 761 | |
| fep | 0:5ff20db10a96 | 762 | #endif /* CO_ROUTINE_H */ |
| fep | 0:5ff20db10a96 | 763 |