message_buffer.h 36 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780
  1. /*
  2. * FreeRTOS Kernel V10.0.0
  3. * Copyright (C) 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
  4. *
  5. * Permission is hereby granted, free of charge, to any person obtaining a copy of
  6. * this software and associated documentation files (the "Software"), to deal in
  7. * the Software without restriction, including without limitation the rights to
  8. * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
  9. * the Software, and to permit persons to whom the Software is furnished to do so,
  10. * subject to the following conditions:
  11. *
  12. * The above copyright notice and this permission notice shall be included in all
  13. * copies or substantial portions of the Software. If you wish to use our Amazon
  14. * FreeRTOS name, please do so in a fair use way that does not cause confusion.
  15. *
  16. * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17. * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
  18. * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
  19. * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  20. * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  21. * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  22. *
  23. * http://www.FreeRTOS.org
  24. * http://aws.amazon.com/freertos
  25. *
  26. * 1 tab == 4 spaces!
  27. */
  28. /*
  29. * Message buffers build functionality on top of FreeRTOS stream buffers.
  30. * Whereas stream buffers are used to send a continuous stream of data from one
  31. * task or interrupt to another, message buffers are used to send variable
  32. * length discrete messages from one task or interrupt to another. Their
  33. * implementation is light weight, making them particularly suited for interrupt
  34. * to task and core to core communication scenarios.
  35. *
  36. * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
  37. * implementation (so also the message buffer implementation, as message buffers
  38. * are built on top of stream buffers) assumes there is only one task or
  39. * interrupt that will write to the buffer (the writer), and only one task or
  40. * interrupt that will read from the buffer (the reader). It is safe for the
  41. * writer and reader to be different tasks or interrupts, but, unlike other
  42. * FreeRTOS objects, it is not safe to have multiple different writers or
  43. * multiple different readers. If there are to be multiple different writers
  44. * then the application writer must place each call to a writing API function
  45. * (such as xMessageBufferSend()) inside a critical section and set the send
  46. * block time to 0. Likewise, if there are to be multiple different readers
  47. * then the application writer must place each call to a reading API function
  48. * (such as xMessageBufferRead()) inside a critical section and set the receive
  49. * timeout to 0.
  50. *
  51. * Message buffers hold variable length messages. To enable that, when a
  52. * message is written to the message buffer an additional sizeof( size_t ) bytes
  53. * are also written to store the message's length (that happens internally, with
  54. * the API function). sizeof( size_t ) is typically 4 bytes on a 32-bit
  55. * architecture, so writing a 10 byte message to a message buffer on a 32-bit
  56. * architecture will actually reduce the available space in the message buffer
  57. * by 14 bytes (10 byte are used by the message, and 4 bytes to hold the length
  58. * of the message).
  59. */
  60. #ifndef FREERTOS_MESSAGE_BUFFER_H
  61. #define FREERTOS_MESSAGE_BUFFER_H
  62. /* Message buffers are built onto of stream buffers. */
  63. #include "stream_buffer.h"
  64. #if defined( __cplusplus )
  65. extern "C" {
  66. #endif
  67. /**
  68. * Type by which message buffers are referenced. For example, a call to
  69. * xMessageBufferCreate() returns an MessageBufferHandle_t variable that can
  70. * then be used as a parameter to xMessageBufferSend(), xMessageBufferReceive(),
  71. * etc.
  72. */
  73. typedef void * MessageBufferHandle_t;
  74. /*-----------------------------------------------------------*/
  75. /**
  76. * message_buffer.h
  77. *
  78. <pre>
  79. MessageBufferHandle_t xMessageBufferCreate( size_t xBufferSizeBytes );
  80. </pre>
  81. *
  82. * Creates a new message buffer using dynamically allocated memory. See
  83. * xMessageBufferCreateStatic() for a version that uses statically allocated
  84. * memory (memory that is allocated at compile time).
  85. *
  86. * configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 or left undefined in
  87. * FreeRTOSConfig.h for xMessageBufferCreate() to be available.
  88. *
  89. * @param xBufferSizeBytes The total number of bytes (not messages) the message
  90. * buffer will be able to hold at any one time. When a message is written to
  91. * the message buffer an additional sizeof( size_t ) bytes are also written to
  92. * store the message's length. sizeof( size_t ) is typically 4 bytes on a
  93. * 32-bit architecture, so on most 32-bit architectures a 10 byte message will
  94. * take up 14 bytes of message buffer space.
  95. *
  96. * @return If NULL is returned, then the message buffer cannot be created
  97. * because there is insufficient heap memory available for FreeRTOS to allocate
  98. * the message buffer data structures and storage area. A non-NULL value being
  99. * returned indicates that the message buffer has been created successfully -
  100. * the returned value should be stored as the handle to the created message
  101. * buffer.
  102. *
  103. * Example use:
  104. <pre>
  105. void vAFunction( void )
  106. {
  107. MessageBufferHandle_t xMessageBuffer;
  108. const size_t xMessageBufferSizeBytes = 100;
  109. // Create a message buffer that can hold 100 bytes. The memory used to hold
  110. // both the message buffer structure and the messages themselves is allocated
  111. // dynamically. Each message added to the buffer consumes an additional 4
  112. // bytes which are used to hold the lengh of the message.
  113. xMessageBuffer = xMessageBufferCreate( xMessageBufferSizeBytes );
  114. if( xMessageBuffer == NULL )
  115. {
  116. // There was not enough heap memory space available to create the
  117. // message buffer.
  118. }
  119. else
  120. {
  121. // The message buffer was created successfully and can now be used.
  122. }
  123. </pre>
  124. * \defgroup xMessageBufferCreate xMessageBufferCreate
  125. * \ingroup MessageBufferManagement
  126. */
  127. #define xMessageBufferCreate( xBufferSizeBytes ) ( MessageBufferHandle_t ) xStreamBufferGenericCreate( xBufferSizeBytes, ( size_t ) 0, pdTRUE )
  128. /**
  129. * message_buffer.h
  130. *
  131. <pre>
  132. MessageBufferHandle_t xMessageBufferCreateStatic( size_t xBufferSizeBytes,
  133. uint8_t *pucMessageBufferStorageArea,
  134. StaticMessageBuffer_t *pxStaticMessageBuffer );
  135. </pre>
  136. * Creates a new message buffer using statically allocated memory. See
  137. * xMessageBufferCreate() for a version that uses dynamically allocated memory.
  138. *
  139. * @param xBufferSizeBytes The size, in bytes, of the buffer pointed to by the
  140. * pucMessageBufferStorageArea parameter. When a message is written to the
  141. * message buffer an additional sizeof( size_t ) bytes are also written to store
  142. * the message's length. sizeof( size_t ) is typically 4 bytes on a 32-bit
  143. * architecture, so on most 32-bit architecture a 10 byte message will take up
  144. * 14 bytes of message buffer space. The maximum number of bytes that can be
  145. * stored in the message buffer is actually (xBufferSizeBytes - 1).
  146. *
  147. * @param pucMessageBufferStorageArea Must point to a uint8_t array that is at
  148. * least xBufferSizeBytes + 1 big. This is the array to which messages are
  149. * copied when they are written to the message buffer.
  150. *
  151. * @param pxStaticMessageBuffer Must point to a variable of type
  152. * StaticMessageBuffer_t, which will be used to hold the message buffer's data
  153. * structure.
  154. *
  155. * @return If the message buffer is created successfully then a handle to the
  156. * created message buffer is returned. If either pucMessageBufferStorageArea or
  157. * pxStaticmessageBuffer are NULL then NULL is returned.
  158. *
  159. * Example use:
  160. <pre>
  161. // Used to dimension the array used to hold the messages. The available space
  162. // will actually be one less than this, so 999.
  163. #define STORAGE_SIZE_BYTES 1000
  164. // Defines the memory that will actually hold the messages within the message
  165. // buffer.
  166. static uint8_t ucStorageBuffer[ STORAGE_SIZE_BYTES ];
  167. // The variable used to hold the message buffer structure.
  168. StaticMessageBuffer_t xMessageBufferStruct;
  169. void MyFunction( void )
  170. {
  171. MessageBufferHandle_t xMessageBuffer;
  172. xMessageBuffer = xMessageBufferCreateStatic( sizeof( ucBufferStorage ),
  173. ucBufferStorage,
  174. &xMessageBufferStruct );
  175. // As neither the pucMessageBufferStorageArea or pxStaticMessageBuffer
  176. // parameters were NULL, xMessageBuffer will not be NULL, and can be used to
  177. // reference the created message buffer in other message buffer API calls.
  178. // Other code that uses the message buffer can go here.
  179. }
  180. </pre>
  181. * \defgroup xMessageBufferCreateStatic xMessageBufferCreateStatic
  182. * \ingroup MessageBufferManagement
  183. */
  184. #define xMessageBufferCreateStatic( xBufferSizeBytes, pucMessageBufferStorageArea, pxStaticMessageBuffer ) ( MessageBufferHandle_t ) xStreamBufferGenericCreateStatic( xBufferSizeBytes, 0, pdTRUE, pucMessageBufferStorageArea, pxStaticMessageBuffer )
  185. /**
  186. * message_buffer.h
  187. *
  188. <pre>
  189. size_t xMessageBufferSend( MessageBufferHandle_t xMessageBuffer,
  190. const void *pvTxData,
  191. size_t xDataLengthBytes,
  192. TickType_t xTicksToWait );
  193. <pre>
  194. *
  195. * Sends a discrete message to the message buffer. The message can be any
  196. * length that fits within the buffer's free space, and is copied into the
  197. * buffer.
  198. *
  199. * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
  200. * implementation (so also the message buffer implementation, as message buffers
  201. * are built on top of stream buffers) assumes there is only one task or
  202. * interrupt that will write to the buffer (the writer), and only one task or
  203. * interrupt that will read from the buffer (the reader). It is safe for the
  204. * writer and reader to be different tasks or interrupts, but, unlike other
  205. * FreeRTOS objects, it is not safe to have multiple different writers or
  206. * multiple different readers. If there are to be multiple different writers
  207. * then the application writer must place each call to a writing API function
  208. * (such as xMessageBufferSend()) inside a critical section and set the send
  209. * block time to 0. Likewise, if there are to be multiple different readers
  210. * then the application writer must place each call to a reading API function
  211. * (such as xMessageBufferRead()) inside a critical section and set the receive
  212. * block time to 0.
  213. *
  214. * Use xMessageBufferSend() to write to a message buffer from a task. Use
  215. * xMessageBufferSendFromISR() to write to a message buffer from an interrupt
  216. * service routine (ISR).
  217. *
  218. * @param xMessageBuffer The handle of the message buffer to which a message is
  219. * being sent.
  220. *
  221. * @param pvTxData A pointer to the message that is to be copied into the
  222. * message buffer.
  223. *
  224. * @param xDataLengthBytes The length of the message. That is, the number of
  225. * bytes to copy from pvTxData into the message buffer. When a message is
  226. * written to the message buffer an additional sizeof( size_t ) bytes are also
  227. * written to store the message's length. sizeof( size_t ) is typically 4 bytes
  228. * on a 32-bit architecture, so on most 32-bit architecture setting
  229. * xDataLengthBytes to 20 will reduce the free space in the message buffer by 24
  230. * bytes (20 bytes of message data and 4 bytes to hold the message length).
  231. *
  232. * @param xTicksToWait The maximum amount of time the calling task should remain
  233. * in the Blocked state to wait for enough space to become available in the
  234. * message buffer, should the message buffer have insufficient space when
  235. * xMessageBufferSend() is called. The calling task will never block if
  236. * xTicksToWait is zero. The block time is specified in tick periods, so the
  237. * absolute time it represents is dependent on the tick frequency. The macro
  238. * pdMS_TO_TICKS() can be used to convert a time specified in milliseconds into
  239. * a time specified in ticks. Setting xTicksToWait to portMAX_DELAY will cause
  240. * the task to wait indefinitely (without timing out), provided
  241. * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. Tasks do not use any
  242. * CPU time when they are in the Blocked state.
  243. *
  244. * @return The number of bytes written to the message buffer. If the call to
  245. * xMessageBufferSend() times out before there was enough space to write the
  246. * message into the message buffer then zero is returned. If the call did not
  247. * time out then xDataLengthBytes is returned.
  248. *
  249. * Example use:
  250. <pre>
  251. void vAFunction( MessageBufferHandle_t xMessageBuffer )
  252. {
  253. size_t xBytesSent;
  254. uint8_t ucArrayToSend[] = { 0, 1, 2, 3 };
  255. char *pcStringToSend = "String to send";
  256. const TickType_t x100ms = pdMS_TO_TICKS( 100 );
  257. // Send an array to the message buffer, blocking for a maximum of 100ms to
  258. // wait for enough space to be available in the message buffer.
  259. xBytesSent = xMessageBufferSend( xMessageBuffer, ( void * ) ucArrayToSend, sizeof( ucArrayToSend ), x100ms );
  260. if( xBytesSent != sizeof( ucArrayToSend ) )
  261. {
  262. // The call to xMessageBufferSend() times out before there was enough
  263. // space in the buffer for the data to be written.
  264. }
  265. // Send the string to the message buffer. Return immediately if there is
  266. // not enough space in the buffer.
  267. xBytesSent = xMessageBufferSend( xMessageBuffer, ( void * ) pcStringToSend, strlen( pcStringToSend ), 0 );
  268. if( xBytesSent != strlen( pcStringToSend ) )
  269. {
  270. // The string could not be added to the message buffer because there was
  271. // not enough free space in the buffer.
  272. }
  273. }
  274. </pre>
  275. * \defgroup xMessageBufferSend xMessageBufferSend
  276. * \ingroup MessageBufferManagement
  277. */
  278. #define xMessageBufferSend( xMessageBuffer, pvTxData, xDataLengthBytes, xTicksToWait ) xStreamBufferSend( ( StreamBufferHandle_t ) xMessageBuffer, pvTxData, xDataLengthBytes, xTicksToWait )
  279. /**
  280. * message_buffer.h
  281. *
  282. <pre>
  283. size_t xMessageBufferSendFromISR( MessageBufferHandle_t xMessageBuffer,
  284. const void *pvTxData,
  285. size_t xDataLengthBytes,
  286. BaseType_t *pxHigherPriorityTaskWoken );
  287. <pre>
  288. *
  289. * Interrupt safe version of the API function that sends a discrete message to
  290. * the message buffer. The message can be any length that fits within the
  291. * buffer's free space, and is copied into the buffer.
  292. *
  293. * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
  294. * implementation (so also the message buffer implementation, as message buffers
  295. * are built on top of stream buffers) assumes there is only one task or
  296. * interrupt that will write to the buffer (the writer), and only one task or
  297. * interrupt that will read from the buffer (the reader). It is safe for the
  298. * writer and reader to be different tasks or interrupts, but, unlike other
  299. * FreeRTOS objects, it is not safe to have multiple different writers or
  300. * multiple different readers. If there are to be multiple different writers
  301. * then the application writer must place each call to a writing API function
  302. * (such as xMessageBufferSend()) inside a critical section and set the send
  303. * block time to 0. Likewise, if there are to be multiple different readers
  304. * then the application writer must place each call to a reading API function
  305. * (such as xMessageBufferRead()) inside a critical section and set the receive
  306. * block time to 0.
  307. *
  308. * Use xMessageBufferSend() to write to a message buffer from a task. Use
  309. * xMessageBufferSendFromISR() to write to a message buffer from an interrupt
  310. * service routine (ISR).
  311. *
  312. * @param xMessageBuffer The handle of the message buffer to which a message is
  313. * being sent.
  314. *
  315. * @param pvTxData A pointer to the message that is to be copied into the
  316. * message buffer.
  317. *
  318. * @param xDataLengthBytes The length of the message. That is, the number of
  319. * bytes to copy from pvTxData into the message buffer. When a message is
  320. * written to the message buffer an additional sizeof( size_t ) bytes are also
  321. * written to store the message's length. sizeof( size_t ) is typically 4 bytes
  322. * on a 32-bit architecture, so on most 32-bit architecture setting
  323. * xDataLengthBytes to 20 will reduce the free space in the message buffer by 24
  324. * bytes (20 bytes of message data and 4 bytes to hold the message length).
  325. *
  326. * @param pxHigherPriorityTaskWoken It is possible that a message buffer will
  327. * have a task blocked on it waiting for data. Calling
  328. * xMessageBufferSendFromISR() can make data available, and so cause a task that
  329. * was waiting for data to leave the Blocked state. If calling
  330. * xMessageBufferSendFromISR() causes a task to leave the Blocked state, and the
  331. * unblocked task has a priority higher than the currently executing task (the
  332. * task that was interrupted), then, internally, xMessageBufferSendFromISR()
  333. * will set *pxHigherPriorityTaskWoken to pdTRUE. If
  334. * xMessageBufferSendFromISR() sets this value to pdTRUE, then normally a
  335. * context switch should be performed before the interrupt is exited. This will
  336. * ensure that the interrupt returns directly to the highest priority Ready
  337. * state task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it
  338. * is passed into the function. See the code example below for an example.
  339. *
  340. * @return The number of bytes actually written to the message buffer. If the
  341. * message buffer didn't have enough free space for the message to be stored
  342. * then 0 is returned, otherwise xDataLengthBytes is returned.
  343. *
  344. * Example use:
  345. <pre>
  346. // A message buffer that has already been created.
  347. MessageBufferHandle_t xMessageBuffer;
  348. void vAnInterruptServiceRoutine( void )
  349. {
  350. size_t xBytesSent;
  351. char *pcStringToSend = "String to send";
  352. BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.
  353. // Attempt to send the string to the message buffer.
  354. xBytesSent = xMessageBufferSendFromISR( xMessageBuffer,
  355. ( void * ) pcStringToSend,
  356. strlen( pcStringToSend ),
  357. &xHigherPriorityTaskWoken );
  358. if( xBytesSent != strlen( pcStringToSend ) )
  359. {
  360. // The string could not be added to the message buffer because there was
  361. // not enough free space in the buffer.
  362. }
  363. // If xHigherPriorityTaskWoken was set to pdTRUE inside
  364. // xMessageBufferSendFromISR() then a task that has a priority above the
  365. // priority of the currently executing task was unblocked and a context
  366. // switch should be performed to ensure the ISR returns to the unblocked
  367. // task. In most FreeRTOS ports this is done by simply passing
  368. // xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the
  369. // variables value, and perform the context switch if necessary. Check the
  370. // documentation for the port in use for port specific instructions.
  371. taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );
  372. }
  373. </pre>
  374. * \defgroup xMessageBufferSendFromISR xMessageBufferSendFromISR
  375. * \ingroup MessageBufferManagement
  376. */
  377. #define xMessageBufferSendFromISR( xMessageBuffer, pvTxData, xDataLengthBytes, pxHigherPriorityTaskWoken ) xStreamBufferSendFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pvTxData, xDataLengthBytes, pxHigherPriorityTaskWoken )
  378. /**
  379. * message_buffer.h
  380. *
  381. <pre>
  382. size_t xMessageBufferReceive( MessageBufferHandle_t xMessageBuffer,
  383. void *pvRxData,
  384. size_t xBufferLengthBytes,
  385. TickType_t xTicksToWait );
  386. </pre>
  387. *
  388. * Receives a discrete message from a message buffer. Messages can be of
  389. * variable length and are copied out of the buffer.
  390. *
  391. * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
  392. * implementation (so also the message buffer implementation, as message buffers
  393. * are built on top of stream buffers) assumes there is only one task or
  394. * interrupt that will write to the buffer (the writer), and only one task or
  395. * interrupt that will read from the buffer (the reader). It is safe for the
  396. * writer and reader to be different tasks or interrupts, but, unlike other
  397. * FreeRTOS objects, it is not safe to have multiple different writers or
  398. * multiple different readers. If there are to be multiple different writers
  399. * then the application writer must place each call to a writing API function
  400. * (such as xMessageBufferSend()) inside a critical section and set the send
  401. * block time to 0. Likewise, if there are to be multiple different readers
  402. * then the application writer must place each call to a reading API function
  403. * (such as xMessageBufferRead()) inside a critical section and set the receive
  404. * block time to 0.
  405. *
  406. * Use xMessageBufferReceive() to read from a message buffer from a task. Use
  407. * xMessageBufferReceiveFromISR() to read from a message buffer from an
  408. * interrupt service routine (ISR).
  409. *
  410. * @param xMessageBuffer The handle of the message buffer from which a message
  411. * is being received.
  412. *
  413. * @param pvRxData A pointer to the buffer into which the received message is
  414. * to be copied.
  415. *
  416. * @param xBufferLengthBytes The length of the buffer pointed to by the pvRxData
  417. * parameter. This sets the maximum length of the message that can be received.
  418. * If xBufferLengthBytes is too small to hold the next message then the message
  419. * will be left in the message buffer and 0 will be returned.
  420. *
  421. * @param xTicksToWait The maximum amount of time the task should remain in the
  422. * Blocked state to wait for a message, should the message buffer be empty.
  423. * xMessageBufferReceive() will return immediately if xTicksToWait is zero and
  424. * the message buffer is empty. The block time is specified in tick periods, so
  425. * the absolute time it represents is dependent on the tick frequency. The
  426. * macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds
  427. * into a time specified in ticks. Setting xTicksToWait to portMAX_DELAY will
  428. * cause the task to wait indefinitely (without timing out), provided
  429. * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. Tasks do not use any
  430. * CPU time when they are in the Blocked state.
  431. *
  432. * @return The length, in bytes, of the message read from the message buffer, if
  433. * any. If xMessageBufferReceive() times out before a message became available
  434. * then zero is returned. If the length of the message is greater than
  435. * xBufferLengthBytes then the message will be left in the message buffer and
  436. * zero is returned.
  437. *
  438. * Example use:
  439. <pre>
  440. void vAFunction( MessageBuffer_t xMessageBuffer )
  441. {
  442. uint8_t ucRxData[ 20 ];
  443. size_t xReceivedBytes;
  444. const TickType_t xBlockTime = pdMS_TO_TICKS( 20 );
  445. // Receive the next message from the message buffer. Wait in the Blocked
  446. // state (so not using any CPU processing time) for a maximum of 100ms for
  447. // a message to become available.
  448. xReceivedBytes = xMessageBufferReceive( xMessageBuffer,
  449. ( void * ) ucRxData,
  450. sizeof( ucRxData ),
  451. xBlockTime );
  452. if( xReceivedBytes > 0 )
  453. {
  454. // A ucRxData contains a message that is xReceivedBytes long. Process
  455. // the message here....
  456. }
  457. }
  458. </pre>
  459. * \defgroup xMessageBufferReceive xMessageBufferReceive
  460. * \ingroup MessageBufferManagement
  461. */
  462. #define xMessageBufferReceive( xMessageBuffer, pvRxData, xBufferLengthBytes, xTicksToWait ) xStreamBufferReceive( ( StreamBufferHandle_t ) xMessageBuffer, pvRxData, xBufferLengthBytes, xTicksToWait )
  463. /**
  464. * message_buffer.h
  465. *
  466. <pre>
  467. size_t xMessageBufferReceiveFromISR( MessageBufferHandle_t xMessageBuffer,
  468. void *pvRxData,
  469. size_t xBufferLengthBytes,
  470. BaseType_t *pxHigherPriorityTaskWoken );
  471. </pre>
  472. *
  473. * An interrupt safe version of the API function that receives a discrete
  474. * message from a message buffer. Messages can be of variable length and are
  475. * copied out of the buffer.
  476. *
  477. * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
  478. * implementation (so also the message buffer implementation, as message buffers
  479. * are built on top of stream buffers) assumes there is only one task or
  480. * interrupt that will write to the buffer (the writer), and only one task or
  481. * interrupt that will read from the buffer (the reader). It is safe for the
  482. * writer and reader to be different tasks or interrupts, but, unlike other
  483. * FreeRTOS objects, it is not safe to have multiple different writers or
  484. * multiple different readers. If there are to be multiple different writers
  485. * then the application writer must place each call to a writing API function
  486. * (such as xMessageBufferSend()) inside a critical section and set the send
  487. * block time to 0. Likewise, if there are to be multiple different readers
  488. * then the application writer must place each call to a reading API function
  489. * (such as xMessageBufferRead()) inside a critical section and set the receive
  490. * block time to 0.
  491. *
  492. * Use xMessageBufferReceive() to read from a message buffer from a task. Use
  493. * xMessageBufferReceiveFromISR() to read from a message buffer from an
  494. * interrupt service routine (ISR).
  495. *
  496. * @param xMessageBuffer The handle of the message buffer from which a message
  497. * is being received.
  498. *
  499. * @param pvRxData A pointer to the buffer into which the received message is
  500. * to be copied.
  501. *
  502. * @param xBufferLengthBytes The length of the buffer pointed to by the pvRxData
  503. * parameter. This sets the maximum length of the message that can be received.
  504. * If xBufferLengthBytes is too small to hold the next message then the message
  505. * will be left in the message buffer and 0 will be returned.
  506. *
  507. * @param pxHigherPriorityTaskWoken It is possible that a message buffer will
  508. * have a task blocked on it waiting for space to become available. Calling
  509. * xMessageBufferReceiveFromISR() can make space available, and so cause a task
  510. * that is waiting for space to leave the Blocked state. If calling
  511. * xMessageBufferReceiveFromISR() causes a task to leave the Blocked state, and
  512. * the unblocked task has a priority higher than the currently executing task
  513. * (the task that was interrupted), then, internally,
  514. * xMessageBufferReceiveFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE.
  515. * If xMessageBufferReceiveFromISR() sets this value to pdTRUE, then normally a
  516. * context switch should be performed before the interrupt is exited. That will
  517. * ensure the interrupt returns directly to the highest priority Ready state
  518. * task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it is
  519. * passed into the function. See the code example below for an example.
  520. *
  521. * @return The length, in bytes, of the message read from the message buffer, if
  522. * any.
  523. *
  524. * Example use:
  525. <pre>
  526. // A message buffer that has already been created.
  527. MessageBuffer_t xMessageBuffer;
  528. void vAnInterruptServiceRoutine( void )
  529. {
  530. uint8_t ucRxData[ 20 ];
  531. size_t xReceivedBytes;
  532. BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.
  533. // Receive the next message from the message buffer.
  534. xReceivedBytes = xMessageBufferReceiveFromISR( xMessageBuffer,
  535. ( void * ) ucRxData,
  536. sizeof( ucRxData ),
  537. &xHigherPriorityTaskWoken );
  538. if( xReceivedBytes > 0 )
  539. {
  540. // A ucRxData contains a message that is xReceivedBytes long. Process
  541. // the message here....
  542. }
  543. // If xHigherPriorityTaskWoken was set to pdTRUE inside
  544. // xMessageBufferReceiveFromISR() then a task that has a priority above the
  545. // priority of the currently executing task was unblocked and a context
  546. // switch should be performed to ensure the ISR returns to the unblocked
  547. // task. In most FreeRTOS ports this is done by simply passing
  548. // xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the
  549. // variables value, and perform the context switch if necessary. Check the
  550. // documentation for the port in use for port specific instructions.
  551. taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );
  552. }
  553. </pre>
  554. * \defgroup xMessageBufferReceiveFromISR xMessageBufferReceiveFromISR
  555. * \ingroup MessageBufferManagement
  556. */
  557. #define xMessageBufferReceiveFromISR( xMessageBuffer, pvRxData, xBufferLengthBytes, pxHigherPriorityTaskWoken ) xStreamBufferReceiveFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pvRxData, xBufferLengthBytes, pxHigherPriorityTaskWoken )
  558. /**
  559. * message_buffer.h
  560. *
  561. <pre>
  562. void vMessageBufferDelete( MessageBufferHandle_t xMessageBuffer );
  563. </pre>
  564. *
  565. * Deletes a message buffer that was previously created using a call to
  566. * xMessageBufferCreate() or xMessageBufferCreateStatic(). If the message
  567. * buffer was created using dynamic memory (that is, by xMessageBufferCreate()),
  568. * then the allocated memory is freed.
  569. *
  570. * A message buffer handle must not be used after the message buffer has been
  571. * deleted.
  572. *
  573. * @param xMessageBuffer The handle of the message buffer to be deleted.
  574. *
  575. */
  576. #define vMessageBufferDelete( xMessageBuffer ) vStreamBufferDelete( ( StreamBufferHandle_t ) xMessageBuffer )
  577. /**
  578. * message_buffer.h
  579. <pre>
  580. BaseType_t xMessageBufferIsFull( MessageBufferHandle_t xMessageBuffer ) );
  581. </pre>
  582. *
  583. * Tests to see if a message buffer is full. A message buffer is full if it
  584. * cannot accept any more messages, of any size, until space is made available
  585. * by a message being removed from the message buffer.
  586. *
  587. * @param xMessageBuffer The handle of the message buffer being queried.
  588. *
  589. * @return If the message buffer referenced by xMessageBuffer is full then
  590. * pdTRUE is returned. Otherwise pdFALSE is returned.
  591. */
  592. #define xMessageBufferIsFull( xMessageBuffer ) xStreamBufferIsFull( ( StreamBufferHandle_t ) xMessageBuffer )
  593. /**
  594. * message_buffer.h
  595. <pre>
  596. BaseType_t xMessageBufferIsEmpty( MessageBufferHandle_t xMessageBuffer ) );
  597. </pre>
  598. *
  599. * Tests to see if a message buffer is empty (does not contain any messages).
  600. *
  601. * @param xMessageBuffer The handle of the message buffer being queried.
  602. *
  603. * @return If the message buffer referenced by xMessageBuffer is empty then
  604. * pdTRUE is returned. Otherwise pdFALSE is returned.
  605. *
  606. */
  607. #define xMessageBufferIsEmpty( xMessageBuffer ) xStreamBufferIsEmpty( ( StreamBufferHandle_t ) xMessageBuffer )
  608. /**
  609. * message_buffer.h
  610. <pre>
  611. BaseType_t xMessageBufferReset( MessageBufferHandle_t xMessageBuffer );
  612. </pre>
  613. *
  614. * Resets a message buffer to its initial empty state, discarding any message it
  615. * contained.
  616. *
  617. * A message buffer can only be reset if there are no tasks blocked on it.
  618. *
  619. * @param xMessageBuffer The handle of the message buffer being reset.
  620. *
  621. * @return If the message buffer was reset then pdPASS is returned. If the
  622. * message buffer could not be reset because either there was a task blocked on
  623. * the message queue to wait for space to become available, or to wait for a
  624. * a message to be available, then pdFAIL is returned.
  625. *
  626. * \defgroup xMessageBufferReset xMessageBufferReset
  627. * \ingroup MessageBufferManagement
  628. */
  629. #define xMessageBufferReset( xMessageBuffer ) xStreamBufferReset( ( StreamBufferHandle_t ) xMessageBuffer )
  630. /**
  631. * message_buffer.h
  632. <pre>
  633. size_t xMessageBufferSpaceAvailable( MessageBufferHandle_t xMessageBuffer ) );
  634. </pre>
  635. * Returns the number of bytes of free space in the message buffer.
  636. *
  637. * @param xMessageBuffer The handle of the message buffer being queried.
  638. *
  639. * @return The number of bytes that can be written to the message buffer before
  640. * the message buffer would be full. When a message is written to the message
  641. * buffer an additional sizeof( size_t ) bytes are also written to store the
  642. * message's length. sizeof( size_t ) is typically 4 bytes on a 32-bit
  643. * architecture, so if xMessageBufferSpacesAvailable() returns 10, then the size
  644. * of the largest message that can be written to the message buffer is 6 bytes.
  645. *
  646. * \defgroup xMessageBufferSpaceAvailable xMessageBufferSpaceAvailable
  647. * \ingroup MessageBufferManagement
  648. */
  649. #define xMessageBufferSpaceAvailable( xMessageBuffer ) xStreamBufferSpacesAvailable( ( StreamBufferHandle_t ) xMessageBuffer )
  650. /**
  651. * message_buffer.h
  652. *
  653. <pre>
  654. BaseType_t xMessageBufferSendCompletedFromISR( MessageBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );
  655. </pre>
  656. *
  657. * For advanced users only.
  658. *
  659. * The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when
  660. * data is sent to a message buffer or stream buffer. If there was a task that
  661. * was blocked on the message or stream buffer waiting for data to arrive then
  662. * the sbSEND_COMPLETED() macro sends a notification to the task to remove it
  663. * from the Blocked state. xMessageBufferSendCompletedFromISR() does the same
  664. * thing. It is provided to enable application writers to implement their own
  665. * version of sbSEND_COMPLETED(), and MUST NOT BE USED AT ANY OTHER TIME.
  666. *
  667. * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
  668. * additional information.
  669. *
  670. * @param xStreamBuffer The handle of the stream buffer to which data was
  671. * written.
  672. *
  673. * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be
  674. * initialised to pdFALSE before it is passed into
  675. * xMessageBufferSendCompletedFromISR(). If calling
  676. * xMessageBufferSendCompletedFromISR() removes a task from the Blocked state,
  677. * and the task has a priority above the priority of the currently running task,
  678. * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a
  679. * context switch should be performed before exiting the ISR.
  680. *
  681. * @return If a task was removed from the Blocked state then pdTRUE is returned.
  682. * Otherwise pdFALSE is returned.
  683. *
  684. * \defgroup xMessageBufferSendCompletedFromISR xMessageBufferSendCompletedFromISR
  685. * \ingroup StreamBufferManagement
  686. */
  687. #define xMessageBufferSendCompletedFromISR( xMessageBuffer, pxHigherPriorityTaskWoken ) xStreamBufferSendCompletedFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pxHigherPriorityTaskWoken )
  688. /**
  689. * message_buffer.h
  690. *
  691. <pre>
  692. BaseType_t xMessageBufferReceiveCompletedFromISR( MessageBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );
  693. </pre>
  694. *
  695. * For advanced users only.
  696. *
  697. * The sbRECEIVE_COMPLETED() macro is called from within the FreeRTOS APIs when
  698. * data is read out of a message buffer or stream buffer. If there was a task
  699. * that was blocked on the message or stream buffer waiting for data to arrive
  700. * then the sbRECEIVE_COMPLETED() macro sends a notification to the task to
  701. * remove it from the Blocked state. xMessageBufferReceiveCompletedFromISR()
  702. * does the same thing. It is provided to enable application writers to
  703. * implement their own version of sbRECEIVE_COMPLETED(), and MUST NOT BE USED AT
  704. * ANY OTHER TIME.
  705. *
  706. * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
  707. * additional information.
  708. *
  709. * @param xStreamBuffer The handle of the stream buffer from which data was
  710. * read.
  711. *
  712. * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be
  713. * initialised to pdFALSE before it is passed into
  714. * xMessageBufferReceiveCompletedFromISR(). If calling
  715. * xMessageBufferReceiveCompletedFromISR() removes a task from the Blocked state,
  716. * and the task has a priority above the priority of the currently running task,
  717. * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a
  718. * context switch should be performed before exiting the ISR.
  719. *
  720. * @return If a task was removed from the Blocked state then pdTRUE is returned.
  721. * Otherwise pdFALSE is returned.
  722. *
  723. * \defgroup xMessageBufferReceiveCompletedFromISR xMessageBufferReceiveCompletedFromISR
  724. * \ingroup StreamBufferManagement
  725. */
  726. #define xMessageBufferReceiveCompletedFromISR( xMessageBuffer, pxHigherPriorityTaskWoken ) xStreamBufferReceiveCompletedFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pxHigherPriorityTaskWoken )
  727. #if defined( __cplusplus )
  728. } /* extern "C" */
  729. #endif
  730. #endif /* !defined( FREERTOS_MESSAGE_BUFFER_H ) */