message_buffer.h 38 KB

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