croutine.h 28 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753
  1. /*
  2. * FreeRTOS Kernel V10.4.4
  3. * Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
  4. *
  5. * SPDX-License-Identifier: MIT
  6. *
  7. * Permission is hereby granted, free of charge, to any person obtaining a copy of
  8. * this software and associated documentation files (the "Software"), to deal in
  9. * the Software without restriction, including without limitation the rights to
  10. * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
  11. * the Software, and to permit persons to whom the Software is furnished to do so,
  12. * subject to the following conditions:
  13. *
  14. * The above copyright notice and this permission notice shall be included in all
  15. * copies or substantial portions of the Software.
  16. *
  17. * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18. * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
  19. * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
  20. * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  21. * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  22. * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23. *
  24. * https://www.FreeRTOS.org
  25. * https://github.com/FreeRTOS
  26. *
  27. */
  28. #ifndef CO_ROUTINE_H
  29. #define CO_ROUTINE_H
  30. #ifndef INC_FREERTOS_H
  31. #error "include FreeRTOS.h must appear in source files before include croutine.h"
  32. #endif
  33. #include "list.h"
  34. /* *INDENT-OFF* */
  35. #ifdef __cplusplus
  36. extern "C" {
  37. #endif
  38. /* *INDENT-ON* */
  39. /* Used to hide the implementation of the co-routine control block. The
  40. * control block structure however has to be included in the header due to
  41. * the macro implementation of the co-routine functionality. */
  42. typedef void * CoRoutineHandle_t;
  43. /* Defines the prototype to which co-routine functions must conform. */
  44. typedef void (* crCOROUTINE_CODE)( CoRoutineHandle_t,
  45. UBaseType_t );
  46. typedef struct corCoRoutineControlBlock
  47. {
  48. crCOROUTINE_CODE pxCoRoutineFunction;
  49. ListItem_t xGenericListItem; /*< List item used to place the CRCB in ready and blocked queues. */
  50. ListItem_t xEventListItem; /*< List item used to place the CRCB in event lists. */
  51. UBaseType_t uxPriority; /*< The priority of the co-routine in relation to other co-routines. */
  52. UBaseType_t uxIndex; /*< Used to distinguish between co-routines when multiple co-routines use the same co-routine function. */
  53. uint16_t uxState; /*< Used internally by the co-routine implementation. */
  54. } CRCB_t; /* Co-routine control block. Note must be identical in size down to uxPriority with TCB_t. */
  55. /**
  56. * croutine. h
  57. * <pre>
  58. * BaseType_t xCoRoutineCreate(
  59. * crCOROUTINE_CODE pxCoRoutineCode,
  60. * UBaseType_t uxPriority,
  61. * UBaseType_t uxIndex
  62. * );
  63. * </pre>
  64. *
  65. * Create a new co-routine and add it to the list of co-routines that are
  66. * ready to run.
  67. *
  68. * @param pxCoRoutineCode Pointer to the co-routine function. Co-routine
  69. * functions require special syntax - see the co-routine section of the WEB
  70. * documentation for more information.
  71. *
  72. * @param uxPriority The priority with respect to other co-routines at which
  73. * the co-routine will run.
  74. *
  75. * @param uxIndex Used to distinguish between different co-routines that
  76. * execute the same function. See the example below and the co-routine section
  77. * of the WEB documentation for further information.
  78. *
  79. * @return pdPASS if the co-routine was successfully created and added to a ready
  80. * list, otherwise an error code defined with ProjDefs.h.
  81. *
  82. * Example usage:
  83. * <pre>
  84. * // Co-routine to be created.
  85. * void vFlashCoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )
  86. * {
  87. * // Variables in co-routines must be declared static if they must maintain value across a blocking call.
  88. * // This may not be necessary for const variables.
  89. * static const char cLedToFlash[ 2 ] = { 5, 6 };
  90. * static const TickType_t uxFlashRates[ 2 ] = { 200, 400 };
  91. *
  92. * // Must start every co-routine with a call to crSTART();
  93. * crSTART( xHandle );
  94. *
  95. * for( ;; )
  96. * {
  97. * // This co-routine just delays for a fixed period, then toggles
  98. * // an LED. Two co-routines are created using this function, so
  99. * // the uxIndex parameter is used to tell the co-routine which
  100. * // LED to flash and how int32_t to delay. This assumes xQueue has
  101. * // already been created.
  102. * vParTestToggleLED( cLedToFlash[ uxIndex ] );
  103. * crDELAY( xHandle, uxFlashRates[ uxIndex ] );
  104. * }
  105. *
  106. * // Must end every co-routine with a call to crEND();
  107. * crEND();
  108. * }
  109. *
  110. * // Function that creates two co-routines.
  111. * void vOtherFunction( void )
  112. * {
  113. * uint8_t ucParameterToPass;
  114. * TaskHandle_t xHandle;
  115. *
  116. * // Create two co-routines at priority 0. The first is given index 0
  117. * // so (from the code above) toggles LED 5 every 200 ticks. The second
  118. * // is given index 1 so toggles LED 6 every 400 ticks.
  119. * for( uxIndex = 0; uxIndex < 2; uxIndex++ )
  120. * {
  121. * xCoRoutineCreate( vFlashCoRoutine, 0, uxIndex );
  122. * }
  123. * }
  124. * </pre>
  125. * \defgroup xCoRoutineCreate xCoRoutineCreate
  126. * \ingroup Tasks
  127. */
  128. BaseType_t xCoRoutineCreate( crCOROUTINE_CODE pxCoRoutineCode,
  129. UBaseType_t uxPriority,
  130. UBaseType_t uxIndex );
  131. /**
  132. * croutine. h
  133. * <pre>
  134. * void vCoRoutineSchedule( void );
  135. * </pre>
  136. *
  137. * Run a co-routine.
  138. *
  139. * vCoRoutineSchedule() executes the highest priority co-routine that is able
  140. * to run. The co-routine will execute until it either blocks, yields or is
  141. * preempted by a task. Co-routines execute cooperatively so one
  142. * co-routine cannot be preempted by another, but can be preempted by a task.
  143. *
  144. * If an application comprises of both tasks and co-routines then
  145. * vCoRoutineSchedule should be called from the idle task (in an idle task
  146. * hook).
  147. *
  148. * Example usage:
  149. * <pre>
  150. * // This idle task hook will schedule a co-routine each time it is called.
  151. * // The rest of the idle task will execute between co-routine calls.
  152. * void vApplicationIdleHook( void )
  153. * {
  154. * vCoRoutineSchedule();
  155. * }
  156. *
  157. * // Alternatively, if you do not require any other part of the idle task to
  158. * // execute, the idle task hook can call vCoRoutineSchedule() within an
  159. * // infinite loop.
  160. * void vApplicationIdleHook( void )
  161. * {
  162. * for( ;; )
  163. * {
  164. * vCoRoutineSchedule();
  165. * }
  166. * }
  167. * </pre>
  168. * \defgroup vCoRoutineSchedule vCoRoutineSchedule
  169. * \ingroup Tasks
  170. */
  171. void vCoRoutineSchedule( void );
  172. /**
  173. * croutine. h
  174. * <pre>
  175. * crSTART( CoRoutineHandle_t xHandle );
  176. * </pre>
  177. *
  178. * This macro MUST always be called at the start of a co-routine function.
  179. *
  180. * Example usage:
  181. * <pre>
  182. * // Co-routine to be created.
  183. * void vACoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )
  184. * {
  185. * // Variables in co-routines must be declared static if they must maintain value across a blocking call.
  186. * static int32_t ulAVariable;
  187. *
  188. * // Must start every co-routine with a call to crSTART();
  189. * crSTART( xHandle );
  190. *
  191. * for( ;; )
  192. * {
  193. * // Co-routine functionality goes here.
  194. * }
  195. *
  196. * // Must end every co-routine with a call to crEND();
  197. * crEND();
  198. * }
  199. * </pre>
  200. * \defgroup crSTART crSTART
  201. * \ingroup Tasks
  202. */
  203. #define crSTART( pxCRCB ) \
  204. switch( ( ( CRCB_t * ) ( pxCRCB ) )->uxState ) { \
  205. case 0:
  206. /**
  207. * croutine. h
  208. * <pre>
  209. * crEND();
  210. * </pre>
  211. *
  212. * This macro MUST always be called at the end of a co-routine function.
  213. *
  214. * Example usage:
  215. * <pre>
  216. * // Co-routine to be created.
  217. * void vACoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )
  218. * {
  219. * // Variables in co-routines must be declared static if they must maintain value across a blocking call.
  220. * static int32_t ulAVariable;
  221. *
  222. * // Must start every co-routine with a call to crSTART();
  223. * crSTART( xHandle );
  224. *
  225. * for( ;; )
  226. * {
  227. * // Co-routine functionality goes here.
  228. * }
  229. *
  230. * // Must end every co-routine with a call to crEND();
  231. * crEND();
  232. * }
  233. * </pre>
  234. * \defgroup crSTART crSTART
  235. * \ingroup Tasks
  236. */
  237. #define crEND() }
  238. /*
  239. * These macros are intended for internal use by the co-routine implementation
  240. * only. The macros should not be used directly by application writers.
  241. */
  242. #define crSET_STATE0( xHandle ) \
  243. ( ( CRCB_t * ) ( xHandle ) )->uxState = ( __LINE__ * 2 ); return; \
  244. case ( __LINE__ * 2 ):
  245. #define crSET_STATE1( xHandle ) \
  246. ( ( CRCB_t * ) ( xHandle ) )->uxState = ( ( __LINE__ * 2 ) + 1 ); return; \
  247. case ( ( __LINE__ * 2 ) + 1 ):
  248. /**
  249. * croutine. h
  250. * <pre>
  251. * crDELAY( CoRoutineHandle_t xHandle, TickType_t xTicksToDelay );
  252. * </pre>
  253. *
  254. * Delay a co-routine for a fixed period of time.
  255. *
  256. * crDELAY can only be called from the co-routine function itself - not
  257. * from within a function called by the co-routine function. This is because
  258. * co-routines do not maintain their own stack.
  259. *
  260. * @param xHandle The handle of the co-routine to delay. This is the xHandle
  261. * parameter of the co-routine function.
  262. *
  263. * @param xTickToDelay The number of ticks that the co-routine should delay
  264. * for. The actual amount of time this equates to is defined by
  265. * configTICK_RATE_HZ (set in FreeRTOSConfig.h). The constant portTICK_PERIOD_MS
  266. * can be used to convert ticks to milliseconds.
  267. *
  268. * Example usage:
  269. * <pre>
  270. * // Co-routine to be created.
  271. * void vACoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )
  272. * {
  273. * // Variables in co-routines must be declared static if they must maintain value across a blocking call.
  274. * // This may not be necessary for const variables.
  275. * // We are to delay for 200ms.
  276. * static const xTickType xDelayTime = 200 / portTICK_PERIOD_MS;
  277. *
  278. * // Must start every co-routine with a call to crSTART();
  279. * crSTART( xHandle );
  280. *
  281. * for( ;; )
  282. * {
  283. * // Delay for 200ms.
  284. * crDELAY( xHandle, xDelayTime );
  285. *
  286. * // Do something here.
  287. * }
  288. *
  289. * // Must end every co-routine with a call to crEND();
  290. * crEND();
  291. * }
  292. * </pre>
  293. * \defgroup crDELAY crDELAY
  294. * \ingroup Tasks
  295. */
  296. #define crDELAY( xHandle, xTicksToDelay ) \
  297. if( ( xTicksToDelay ) > 0 ) \
  298. { \
  299. vCoRoutineAddToDelayedList( ( xTicksToDelay ), NULL ); \
  300. } \
  301. crSET_STATE0( ( xHandle ) );
  302. /**
  303. * <pre>
  304. * crQUEUE_SEND(
  305. * CoRoutineHandle_t xHandle,
  306. * QueueHandle_t pxQueue,
  307. * void *pvItemToQueue,
  308. * TickType_t xTicksToWait,
  309. * BaseType_t *pxResult
  310. * )
  311. * </pre>
  312. *
  313. * The macro's crQUEUE_SEND() and crQUEUE_RECEIVE() are the co-routine
  314. * equivalent to the xQueueSend() and xQueueReceive() functions used by tasks.
  315. *
  316. * crQUEUE_SEND and crQUEUE_RECEIVE can only be used from a co-routine whereas
  317. * xQueueSend() and xQueueReceive() can only be used from tasks.
  318. *
  319. * crQUEUE_SEND can only be called from the co-routine function itself - not
  320. * from within a function called by the co-routine function. This is because
  321. * co-routines do not maintain their own stack.
  322. *
  323. * See the co-routine section of the WEB documentation for information on
  324. * passing data between tasks and co-routines and between ISR's and
  325. * co-routines.
  326. *
  327. * @param xHandle The handle of the calling co-routine. This is the xHandle
  328. * parameter of the co-routine function.
  329. *
  330. * @param pxQueue The handle of the queue on which the data will be posted.
  331. * The handle is obtained as the return value when the queue is created using
  332. * the xQueueCreate() API function.
  333. *
  334. * @param pvItemToQueue A pointer to the data being posted onto the queue.
  335. * The number of bytes of each queued item is specified when the queue is
  336. * created. This number of bytes is copied from pvItemToQueue into the queue
  337. * itself.
  338. *
  339. * @param xTickToDelay The number of ticks that the co-routine should block
  340. * to wait for space to become available on the queue, should space not be
  341. * available immediately. The actual amount of time this equates to is defined
  342. * by configTICK_RATE_HZ (set in FreeRTOSConfig.h). The constant
  343. * portTICK_PERIOD_MS can be used to convert ticks to milliseconds (see example
  344. * below).
  345. *
  346. * @param pxResult The variable pointed to by pxResult will be set to pdPASS if
  347. * data was successfully posted onto the queue, otherwise it will be set to an
  348. * error defined within ProjDefs.h.
  349. *
  350. * Example usage:
  351. * <pre>
  352. * // Co-routine function that blocks for a fixed period then posts a number onto
  353. * // a queue.
  354. * static void prvCoRoutineFlashTask( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )
  355. * {
  356. * // Variables in co-routines must be declared static if they must maintain value across a blocking call.
  357. * static BaseType_t xNumberToPost = 0;
  358. * static BaseType_t xResult;
  359. *
  360. * // Co-routines must begin with a call to crSTART().
  361. * crSTART( xHandle );
  362. *
  363. * for( ;; )
  364. * {
  365. * // This assumes the queue has already been created.
  366. * crQUEUE_SEND( xHandle, xCoRoutineQueue, &xNumberToPost, NO_DELAY, &xResult );
  367. *
  368. * if( xResult != pdPASS )
  369. * {
  370. * // The message was not posted!
  371. * }
  372. *
  373. * // Increment the number to be posted onto the queue.
  374. * xNumberToPost++;
  375. *
  376. * // Delay for 100 ticks.
  377. * crDELAY( xHandle, 100 );
  378. * }
  379. *
  380. * // Co-routines must end with a call to crEND().
  381. * crEND();
  382. * }
  383. * </pre>
  384. * \defgroup crQUEUE_SEND crQUEUE_SEND
  385. * \ingroup Tasks
  386. */
  387. #define crQUEUE_SEND( xHandle, pxQueue, pvItemToQueue, xTicksToWait, pxResult ) \
  388. { \
  389. *( pxResult ) = xQueueCRSend( ( pxQueue ), ( pvItemToQueue ), ( xTicksToWait ) ); \
  390. if( *( pxResult ) == errQUEUE_BLOCKED ) \
  391. { \
  392. crSET_STATE0( ( xHandle ) ); \
  393. *pxResult = xQueueCRSend( ( pxQueue ), ( pvItemToQueue ), 0 ); \
  394. } \
  395. if( *pxResult == errQUEUE_YIELD ) \
  396. { \
  397. crSET_STATE1( ( xHandle ) ); \
  398. *pxResult = pdPASS; \
  399. } \
  400. }
  401. /**
  402. * croutine. h
  403. * <pre>
  404. * crQUEUE_RECEIVE(
  405. * CoRoutineHandle_t xHandle,
  406. * QueueHandle_t pxQueue,
  407. * void *pvBuffer,
  408. * TickType_t xTicksToWait,
  409. * BaseType_t *pxResult
  410. * )
  411. * </pre>
  412. *
  413. * The macro's crQUEUE_SEND() and crQUEUE_RECEIVE() are the co-routine
  414. * equivalent to the xQueueSend() and xQueueReceive() functions used by tasks.
  415. *
  416. * crQUEUE_SEND and crQUEUE_RECEIVE can only be used from a co-routine whereas
  417. * xQueueSend() and xQueueReceive() can only be used from tasks.
  418. *
  419. * crQUEUE_RECEIVE can only be called from the co-routine function itself - not
  420. * from within a function called by the co-routine function. This is because
  421. * co-routines do not maintain their own stack.
  422. *
  423. * See the co-routine section of the WEB documentation for information on
  424. * passing data between tasks and co-routines and between ISR's and
  425. * co-routines.
  426. *
  427. * @param xHandle The handle of the calling co-routine. This is the xHandle
  428. * parameter of the co-routine function.
  429. *
  430. * @param pxQueue The handle of the queue from which the data will be received.
  431. * The handle is obtained as the return value when the queue is created using
  432. * the xQueueCreate() API function.
  433. *
  434. * @param pvBuffer The buffer into which the received item is to be copied.
  435. * The number of bytes of each queued item is specified when the queue is
  436. * created. This number of bytes is copied into pvBuffer.
  437. *
  438. * @param xTickToDelay The number of ticks that the co-routine should block
  439. * to wait for data to become available from the queue, should data not be
  440. * available immediately. The actual amount of time this equates to is defined
  441. * by configTICK_RATE_HZ (set in FreeRTOSConfig.h). The constant
  442. * portTICK_PERIOD_MS can be used to convert ticks to milliseconds (see the
  443. * crQUEUE_SEND example).
  444. *
  445. * @param pxResult The variable pointed to by pxResult will be set to pdPASS if
  446. * data was successfully retrieved from the queue, otherwise it will be set to
  447. * an error code as defined within ProjDefs.h.
  448. *
  449. * Example usage:
  450. * <pre>
  451. * // A co-routine receives the number of an LED to flash from a queue. It
  452. * // blocks on the queue until the number is received.
  453. * static void prvCoRoutineFlashWorkTask( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )
  454. * {
  455. * // Variables in co-routines must be declared static if they must maintain value across a blocking call.
  456. * static BaseType_t xResult;
  457. * static UBaseType_t uxLEDToFlash;
  458. *
  459. * // All co-routines must start with a call to crSTART().
  460. * crSTART( xHandle );
  461. *
  462. * for( ;; )
  463. * {
  464. * // Wait for data to become available on the queue.
  465. * crQUEUE_RECEIVE( xHandle, xCoRoutineQueue, &uxLEDToFlash, portMAX_DELAY, &xResult );
  466. *
  467. * if( xResult == pdPASS )
  468. * {
  469. * // We received the LED to flash - flash it!
  470. * vParTestToggleLED( uxLEDToFlash );
  471. * }
  472. * }
  473. *
  474. * crEND();
  475. * }
  476. * </pre>
  477. * \defgroup crQUEUE_RECEIVE crQUEUE_RECEIVE
  478. * \ingroup Tasks
  479. */
  480. #define crQUEUE_RECEIVE( xHandle, pxQueue, pvBuffer, xTicksToWait, pxResult ) \
  481. { \
  482. *( pxResult ) = xQueueCRReceive( ( pxQueue ), ( pvBuffer ), ( xTicksToWait ) ); \
  483. if( *( pxResult ) == errQUEUE_BLOCKED ) \
  484. { \
  485. crSET_STATE0( ( xHandle ) ); \
  486. *( pxResult ) = xQueueCRReceive( ( pxQueue ), ( pvBuffer ), 0 ); \
  487. } \
  488. if( *( pxResult ) == errQUEUE_YIELD ) \
  489. { \
  490. crSET_STATE1( ( xHandle ) ); \
  491. *( pxResult ) = pdPASS; \
  492. } \
  493. }
  494. /**
  495. * croutine. h
  496. * <pre>
  497. * crQUEUE_SEND_FROM_ISR(
  498. * QueueHandle_t pxQueue,
  499. * void *pvItemToQueue,
  500. * BaseType_t xCoRoutinePreviouslyWoken
  501. * )
  502. * </pre>
  503. *
  504. * The macro's crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() are the
  505. * co-routine equivalent to the xQueueSendFromISR() and xQueueReceiveFromISR()
  506. * functions used by tasks.
  507. *
  508. * crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() can only be used to
  509. * pass data between a co-routine and and ISR, whereas xQueueSendFromISR() and
  510. * xQueueReceiveFromISR() can only be used to pass data between a task and and
  511. * ISR.
  512. *
  513. * crQUEUE_SEND_FROM_ISR can only be called from an ISR to send data to a queue
  514. * that is being used from within a co-routine.
  515. *
  516. * See the co-routine section of the WEB documentation for information on
  517. * passing data between tasks and co-routines and between ISR's and
  518. * co-routines.
  519. *
  520. * @param xQueue The handle to the queue on which the item is to be posted.
  521. *
  522. * @param pvItemToQueue A pointer to the item that is to be placed on the
  523. * queue. The size of the items the queue will hold was defined when the
  524. * queue was created, so this many bytes will be copied from pvItemToQueue
  525. * into the queue storage area.
  526. *
  527. * @param xCoRoutinePreviouslyWoken This is included so an ISR can post onto
  528. * the same queue multiple times from a single interrupt. The first call
  529. * should always pass in pdFALSE. Subsequent calls should pass in
  530. * the value returned from the previous call.
  531. *
  532. * @return pdTRUE if a co-routine was woken by posting onto the queue. This is
  533. * used by the ISR to determine if a context switch may be required following
  534. * the ISR.
  535. *
  536. * Example usage:
  537. * <pre>
  538. * // A co-routine that blocks on a queue waiting for characters to be received.
  539. * static void vReceivingCoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )
  540. * {
  541. * char cRxedChar;
  542. * BaseType_t xResult;
  543. *
  544. * // All co-routines must start with a call to crSTART().
  545. * crSTART( xHandle );
  546. *
  547. * for( ;; )
  548. * {
  549. * // Wait for data to become available on the queue. This assumes the
  550. * // queue xCommsRxQueue has already been created!
  551. * crQUEUE_RECEIVE( xHandle, xCommsRxQueue, &uxLEDToFlash, portMAX_DELAY, &xResult );
  552. *
  553. * // Was a character received?
  554. * if( xResult == pdPASS )
  555. * {
  556. * // Process the character here.
  557. * }
  558. * }
  559. *
  560. * // All co-routines must end with a call to crEND().
  561. * crEND();
  562. * }
  563. *
  564. * // An ISR that uses a queue to send characters received on a serial port to
  565. * // a co-routine.
  566. * void vUART_ISR( void )
  567. * {
  568. * char cRxedChar;
  569. * BaseType_t xCRWokenByPost = pdFALSE;
  570. *
  571. * // We loop around reading characters until there are none left in the UART.
  572. * while( UART_RX_REG_NOT_EMPTY() )
  573. * {
  574. * // Obtain the character from the UART.
  575. * cRxedChar = UART_RX_REG;
  576. *
  577. * // Post the character onto a queue. xCRWokenByPost will be pdFALSE
  578. * // the first time around the loop. If the post causes a co-routine
  579. * // to be woken (unblocked) then xCRWokenByPost will be set to pdTRUE.
  580. * // In this manner we can ensure that if more than one co-routine is
  581. * // blocked on the queue only one is woken by this ISR no matter how
  582. * // many characters are posted to the queue.
  583. * xCRWokenByPost = crQUEUE_SEND_FROM_ISR( xCommsRxQueue, &cRxedChar, xCRWokenByPost );
  584. * }
  585. * }
  586. * </pre>
  587. * \defgroup crQUEUE_SEND_FROM_ISR crQUEUE_SEND_FROM_ISR
  588. * \ingroup Tasks
  589. */
  590. #define crQUEUE_SEND_FROM_ISR( pxQueue, pvItemToQueue, xCoRoutinePreviouslyWoken ) \
  591. xQueueCRSendFromISR( ( pxQueue ), ( pvItemToQueue ), ( xCoRoutinePreviouslyWoken ) )
  592. /**
  593. * croutine. h
  594. * <pre>
  595. * crQUEUE_SEND_FROM_ISR(
  596. * QueueHandle_t pxQueue,
  597. * void *pvBuffer,
  598. * BaseType_t * pxCoRoutineWoken
  599. * )
  600. * </pre>
  601. *
  602. * The macro's crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() are the
  603. * co-routine equivalent to the xQueueSendFromISR() and xQueueReceiveFromISR()
  604. * functions used by tasks.
  605. *
  606. * crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() can only be used to
  607. * pass data between a co-routine and and ISR, whereas xQueueSendFromISR() and
  608. * xQueueReceiveFromISR() can only be used to pass data between a task and and
  609. * ISR.
  610. *
  611. * crQUEUE_RECEIVE_FROM_ISR can only be called from an ISR to receive data
  612. * from a queue that is being used from within a co-routine (a co-routine
  613. * posted to the queue).
  614. *
  615. * See the co-routine section of the WEB documentation for information on
  616. * passing data between tasks and co-routines and between ISR's and
  617. * co-routines.
  618. *
  619. * @param xQueue The handle to the queue on which the item is to be posted.
  620. *
  621. * @param pvBuffer A pointer to a buffer into which the received item will be
  622. * placed. The size of the items the queue will hold was defined when the
  623. * queue was created, so this many bytes will be copied from the queue into
  624. * pvBuffer.
  625. *
  626. * @param pxCoRoutineWoken A co-routine may be blocked waiting for space to become
  627. * available on the queue. If crQUEUE_RECEIVE_FROM_ISR causes such a
  628. * co-routine to unblock *pxCoRoutineWoken will get set to pdTRUE, otherwise
  629. * *pxCoRoutineWoken will remain unchanged.
  630. *
  631. * @return pdTRUE an item was successfully received from the queue, otherwise
  632. * pdFALSE.
  633. *
  634. * Example usage:
  635. * <pre>
  636. * // A co-routine that posts a character to a queue then blocks for a fixed
  637. * // period. The character is incremented each time.
  638. * static void vSendingCoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )
  639. * {
  640. * // cChar holds its value while this co-routine is blocked and must therefore
  641. * // be declared static.
  642. * static char cCharToTx = 'a';
  643. * BaseType_t xResult;
  644. *
  645. * // All co-routines must start with a call to crSTART().
  646. * crSTART( xHandle );
  647. *
  648. * for( ;; )
  649. * {
  650. * // Send the next character to the queue.
  651. * crQUEUE_SEND( xHandle, xCoRoutineQueue, &cCharToTx, NO_DELAY, &xResult );
  652. *
  653. * if( xResult == pdPASS )
  654. * {
  655. * // The character was successfully posted to the queue.
  656. * }
  657. * else
  658. * {
  659. * // Could not post the character to the queue.
  660. * }
  661. *
  662. * // Enable the UART Tx interrupt to cause an interrupt in this
  663. * // hypothetical UART. The interrupt will obtain the character
  664. * // from the queue and send it.
  665. * ENABLE_RX_INTERRUPT();
  666. *
  667. * // Increment to the next character then block for a fixed period.
  668. * // cCharToTx will maintain its value across the delay as it is
  669. * // declared static.
  670. * cCharToTx++;
  671. * if( cCharToTx > 'x' )
  672. * {
  673. * cCharToTx = 'a';
  674. * }
  675. * crDELAY( 100 );
  676. * }
  677. *
  678. * // All co-routines must end with a call to crEND().
  679. * crEND();
  680. * }
  681. *
  682. * // An ISR that uses a queue to receive characters to send on a UART.
  683. * void vUART_ISR( void )
  684. * {
  685. * char cCharToTx;
  686. * BaseType_t xCRWokenByPost = pdFALSE;
  687. *
  688. * while( UART_TX_REG_EMPTY() )
  689. * {
  690. * // Are there any characters in the queue waiting to be sent?
  691. * // xCRWokenByPost will automatically be set to pdTRUE if a co-routine
  692. * // is woken by the post - ensuring that only a single co-routine is
  693. * // woken no matter how many times we go around this loop.
  694. * if( crQUEUE_RECEIVE_FROM_ISR( pxQueue, &cCharToTx, &xCRWokenByPost ) )
  695. * {
  696. * SEND_CHARACTER( cCharToTx );
  697. * }
  698. * }
  699. * }
  700. * </pre>
  701. * \defgroup crQUEUE_RECEIVE_FROM_ISR crQUEUE_RECEIVE_FROM_ISR
  702. * \ingroup Tasks
  703. */
  704. #define crQUEUE_RECEIVE_FROM_ISR( pxQueue, pvBuffer, pxCoRoutineWoken ) \
  705. xQueueCRReceiveFromISR( ( pxQueue ), ( pvBuffer ), ( pxCoRoutineWoken ) )
  706. /*
  707. * This function is intended for internal use by the co-routine macros only.
  708. * The macro nature of the co-routine implementation requires that the
  709. * prototype appears here. The function should not be used by application
  710. * writers.
  711. *
  712. * Removes the current co-routine from its ready list and places it in the
  713. * appropriate delayed list.
  714. */
  715. void vCoRoutineAddToDelayedList( TickType_t xTicksToDelay,
  716. List_t * pxEventList );
  717. /*
  718. * This function is intended for internal use by the queue implementation only.
  719. * The function should not be used by application writers.
  720. *
  721. * Removes the highest priority co-routine from the event list and places it in
  722. * the pending ready list.
  723. */
  724. BaseType_t xCoRoutineRemoveFromEventList( const List_t * pxEventList );
  725. /* *INDENT-OFF* */
  726. #ifdef __cplusplus
  727. }
  728. #endif
  729. /* *INDENT-ON* */
  730. #endif /* CO_ROUTINE_H */