stream_buffer.h 39 KB

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