Lines Matching full:the
8 * this software and associated documentation files (the "Software"), to deal in
9 * the Software without restriction, including without limitation the rights to
11 * the Software, and to permit persons to whom the Software is furnished to do so,
12 * subject to the following conditions:
14 * The above copyright notice and this permission notice shall be included in all
15 * copies or substantial portions of the Software.
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
22 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
35 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
36 * implementation (so also the message buffer implementation, as message buffers
38 * interrupt that will write to the buffer (the writer), and only one task or
39 * interrupt that will read from the buffer (the reader). It is safe for the
43 * then the application writer must place each call to a writing API function
44 * (such as xStreamBufferSend()) inside a critical section and set the send
46 * then the application writer must place each call to a reading API function
47 * (such as xStreamBufferReceive()) inside a critical section section and set the
95 * @param xBufferSizeBytes The total number of bytes the stream buffer will be
98 * @param xTriggerLevelBytes The number of bytes that must be in the stream
99 * buffer before a task that is blocked on the stream buffer to wait for data is
100 * moved out of the blocked state. For example, if a task is blocked on a read
101 * of an empty stream buffer that has a trigger level of 1 then the task will be
102 * unblocked when a single byte is written to the buffer or the task's block
104 * stream buffer that has a trigger level of 10 then the task will not be
105 * unblocked until the stream buffer contains at least 10 bytes or the task's
106 * block time expires. If a reading task's block time expires before the
107 * trigger level is reached then the task will still receive however many bytes
110 * that is greater than the buffer size.
113 * trigger level is sent to the stream buffer. If the parameter is NULL, it will use the default
114 * implementation provided by sbSEND_COMPLETED macro. To enable the callback,
118 * stream buffer. If the parameter is NULL, it will use the default
119 * implementation provided by sbRECEIVE_COMPLETED macro. To enable the callback,
122 * @return If NULL is returned, then the stream buffer cannot be created
124 * the stream buffer data structures and storage area. A non-NULL value being
125 * returned indicates that the stream buffer has been created successfully -
126 * the returned value should be stored as the handle to the created stream
137 * // Create a stream buffer that can hold 100 bytes. The memory used to hold
138 * // both the stream buffer structure and the data in the stream buffer is
144 * // There was not enough heap memory space available to create the
149 * // The stream buffer was created successfully and can now be used.
180 * @param xBufferSizeBytes The size, in bytes, of the buffer pointed to by the
183 * @param xTriggerLevelBytes The number of bytes that must be in the stream
184 * buffer before a task that is blocked on the stream buffer to wait for data is
185 * moved out of the blocked state. For example, if a task is blocked on a read
186 * of an empty stream buffer that has a trigger level of 1 then the task will be
187 * unblocked when a single byte is written to the buffer or the task's block
189 * stream buffer that has a trigger level of 10 then the task will not be
190 * unblocked until the stream buffer contains at least 10 bytes or the task's
191 * block time expires. If a reading task's block time expires before the
192 * trigger level is reached then the task will still receive however many bytes
195 * that is greater than the buffer size.
198 * least xBufferSizeBytes big. This is the array to which streams are
199 * copied when they are written to the stream buffer.
202 * StaticStreamBuffer_t, which will be used to hold the stream buffer's data
206 * trigger level is sent to the stream buffer. If the parameter is NULL, it will use the default
207 * implementation provided by sbSEND_COMPLETED macro. To enable the callback,
211 * stream buffer. If the parameter is NULL, it will use the default
212 * implementation provided by sbRECEIVE_COMPLETED macro. To enable the callback,
215 * @return If the stream buffer is created successfully then a handle to the
222 * // Used to dimension the array used to hold the streams. The available space
226 * // Defines the memory that will actually hold the streams within the stream
230 * // The variable used to hold the stream buffer structure.
243 * // As neither the pucStreamBufferStorageArea or pxStaticStreamBuffer
245 * // reference the created stream buffer in other stream buffer API calls.
247 * // Other code that uses the stream buffer can go here.
273 * buffer and storage area buffer. These are the same buffers that are supplied
274 * at the time of creation.
276 * @param xStreamBuffer The stream buffer for which to retrieve the buffers.
278 * @param ppucStreamBufferStorageArea Used to return a pointer to the stream
281 * @param ppxStaticStreamBuffer Used to return a pointer to the stream
305 * Sends bytes to a stream buffer. The bytes are copied into the stream buffer.
307 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
308 * implementation (so also the message buffer implementation, as message buffers
310 * interrupt that will write to the buffer (the writer), and only one task or
311 * interrupt that will read from the buffer (the reader). It is safe for the
315 * then the application writer must place each call to a writing API function
316 * (such as xStreamBufferSend()) inside a critical section and set the send
318 * then the application writer must place each call to a reading API function
319 * (such as xStreamBufferReceive()) inside a critical section and set the receive
326 * @param xStreamBuffer The handle of the stream buffer to which a stream is
329 * @param pvTxData A pointer to the buffer that holds the bytes to be copied
330 * into the stream buffer.
332 * @param xDataLengthBytes The maximum number of bytes to copy from pvTxData
333 * into the stream buffer.
335 * @param xTicksToWait The maximum amount of time the task should remain in the
336 * Blocked state to wait for enough space to become available in the stream
337 * buffer, should the stream buffer contain too little space to hold the
338 * another xDataLengthBytes bytes. The block time is specified in tick periods,
339 * so the absolute time it represents is dependent on the tick frequency. The
342 * cause the task to wait indefinitely (without timing out), provided
344 * before it can write all xDataLengthBytes into the buffer it will still write
346 * the blocked state.
348 * @return The number of bytes written to the stream buffer. If a task times
349 * out before it can write all xDataLengthBytes into the buffer it will still
361 * // Send an array to the stream buffer, blocking for a maximum of 100ms to
362 * // wait for enough space to be available in the stream buffer.
367 * // The call to xStreamBufferSend() times out before there was enough
368 * // space in the buffer for the data to be written, but it did
372 * // Send the string to the stream buffer. Return immediately if there is not
373 * // enough space in the buffer.
378 * // The entire string could not be added to the stream buffer because
379 * // there was not enough free space in the buffer, but xBytesSent bytes
380 * // were sent. Could try again to send the remaining bytes.
402 * Interrupt safe version of the API function that sends a stream of bytes to
403 * the stream buffer.
405 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
406 * implementation (so also the message buffer implementation, as message buffers
408 * interrupt that will write to the buffer (the writer), and only one task or
409 * interrupt that will read from the buffer (the reader). It is safe for the
413 * then the application writer must place each call to a writing API function
414 * (such as xStreamBufferSend()) inside a critical section and set the send
416 * then the application writer must place each call to a reading API function
417 * (such as xStreamBufferReceive()) inside a critical section and set the receive
424 * @param xStreamBuffer The handle of the stream buffer to which a stream is
427 * @param pvTxData A pointer to the data that is to be copied into the stream
430 * @param xDataLengthBytes The maximum number of bytes to copy from pvTxData
431 * into the stream buffer.
436 * was waiting for data to leave the Blocked state. If calling
437 * xStreamBufferSendFromISR() causes a task to leave the Blocked state, and the
438 * unblocked task has a priority higher than the currently executing task (the
442 * context switch should be performed before the interrupt is exited. This will
443 * ensure that the interrupt returns directly to the highest priority Ready
445 * is passed into the function. See the example code below for an example.
447 * @return The number of bytes actually written to the stream buffer, which will
448 * be less than xDataLengthBytes if the stream buffer didn't have enough free
449 * space for all the bytes to be written.
462 * // Attempt to send the string to the stream buffer.
470 * // There was not enough free space in the stream buffer for the entire
475 * // xStreamBufferSendFromISR() then a task that has a priority above the
476 * // priority of the currently executing task was unblocked and a context
477 * // switch should be performed to ensure the ISR returns to the unblocked
479 * // xHigherPriorityTaskWoken into portYIELD_FROM_ISR(), which will test the
480 * // variables value, and perform the context switch if necessary. Check the
481 * // documentation for the port in use for port specific instructions.
505 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
506 * implementation (so also the message buffer implementation, as message buffers
508 * interrupt that will write to the buffer (the writer), and only one task or
509 * interrupt that will read from the buffer (the reader). It is safe for the
513 * then the application writer must place each call to a writing API function
514 * (such as xStreamBufferSend()) inside a critical section and set the send
516 * then the application writer must place each call to a reading API function
517 * (such as xStreamBufferReceive()) inside a critical section and set the receive
524 * @param xStreamBuffer The handle of the stream buffer from which bytes are to
527 * @param pvRxData A pointer to the buffer into which the received bytes will be
530 * @param xBufferLengthBytes The length of the buffer pointed to by the
531 * pvRxData parameter. This sets the maximum number of bytes to receive in one
535 * @param xTicksToWait The maximum amount of time the task should remain in the
536 * Blocked state to wait for data to become available if the stream buffer is
538 * zero. The block time is specified in tick periods, so the absolute time it
539 * represents is dependent on the tick frequency. The macro pdMS_TO_TICKS() can
541 * ticks. Setting xTicksToWait to portMAX_DELAY will cause the task to wait
543 * in FreeRTOSConfig.h. A task does not use any CPU time when it is in the
546 * @return The number of bytes actually read from the stream buffer, which will
547 * be less than xBufferLengthBytes if the call to xStreamBufferReceive() timed
558 * // Receive up to another sizeof( ucRxData ) bytes from the stream buffer.
559 * // Wait in the Blocked state (so not using any CPU processing time) for a
560 * // maximum of 100ms for the full sizeof( ucRxData ) number of bytes to be
592 * An interrupt safe version of the API function that receives bytes from a
599 * @param xStreamBuffer The handle of the stream buffer from which a stream
602 * @param pvRxData A pointer to the buffer into which the received bytes are
605 * @param xBufferLengthBytes The length of the buffer pointed to by the
606 * pvRxData parameter. This sets the maximum number of bytes to receive in one
613 * that is waiting for space to leave the Blocked state. If calling
614 * xStreamBufferReceiveFromISR() causes a task to leave the Blocked state, and
615 * the unblocked task has a priority higher than the currently executing task
616 * (the task that was interrupted), then, internally,
619 * context switch should be performed before the interrupt is exited. That will
620 * ensure the interrupt returns directly to the highest priority Ready state
622 * passed into the function. See the code example below for an example.
624 * @return The number of bytes read from the stream buffer, if any.
637 * // Receive the next stream from the stream buffer.
645 * // ucRxData contains xReceivedBytes read from the stream buffer.
646 * // Process the stream here....
650 * // xStreamBufferReceiveFromISR() then a task that has a priority above the
651 * // priority of the currently executing task was unblocked and a context
652 * // switch should be performed to ensure the ISR returns to the unblocked
654 * // xHigherPriorityTaskWoken into portYIELD_FROM_ISR(), which will test the
655 * // variables value, and perform the context switch if necessary. Check the
656 * // documentation for the port in use for port specific instructions.
676 * xStreamBufferCreate() or xStreamBufferCreateStatic(). If the stream
678 * then the allocated memory is freed.
680 * A stream buffer handle must not be used after the stream buffer has been
683 * @param xStreamBuffer The handle of the stream buffer to be deleted.
700 * @param xStreamBuffer The handle of the stream buffer being queried.
702 * @return If the stream buffer is full then pdTRUE is returned. Otherwise
720 * @param xStreamBuffer The handle of the stream buffer being queried.
722 * @return If the stream buffer is empty then pdTRUE is returned. Otherwise
738 * the stream buffer is discarded. A stream buffer can only be reset if there
739 * are no tasks blocked waiting to either send to or receive from the stream
742 * @param xStreamBuffer The handle of the stream buffer being reset.
744 * @return If the stream buffer is reset then pdPASS is returned. If there was
745 * a task blocked waiting to send to or read from the stream buffer then the
761 * equal to the amount of data that can be sent to the stream buffer before it
764 * @param xStreamBuffer The handle of the stream buffer being queried.
766 * @return The number of bytes that can be written to the stream buffer before
767 * the stream buffer would be full.
782 * the number of bytes that can be read from the stream buffer before the stream
785 * @param xStreamBuffer The handle of the stream buffer being queried.
787 * @return The number of bytes that can be read from the stream buffer before
788 * the stream buffer would be empty.
802 * A stream buffer's trigger level is the number of bytes that must be in the
803 * stream buffer before a task that is blocked on the stream buffer to
804 * wait for data is moved out of the blocked state. For example, if a task is
806 * then the task will be unblocked when a single byte is written to the buffer
807 * or the task's block time expires. As another example, if a task is blocked
808 * on a read of an empty stream buffer that has a trigger level of 10 then the
809 * task will not be unblocked until the stream buffer contains at least 10 bytes
810 * or the task's block time expires. If a reading task's block time expires
811 * before the trigger level is reached then the task will still receive however
814 * level that is greater than the buffer size.
816 * A trigger level is set when the stream buffer is created, and can be modified
819 * @param xStreamBuffer The handle of the stream buffer being updated.
821 * @param xTriggerLevel The new trigger level for the stream buffer.
823 * @return If xTriggerLevel was less than or equal to the stream buffer's length
824 * then the trigger level will be updated and pdTRUE is returned. Otherwise
842 * The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when
844 * was blocked on the message or stream buffer waiting for data to arrive then
845 * the sbSEND_COMPLETED() macro sends a notification to the task to remove it
846 * from the Blocked state. xStreamBufferSendCompletedFromISR() does the same
850 * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
853 * @param xStreamBuffer The handle of the stream buffer to which data was
859 * xStreamBufferSendCompletedFromISR() removes a task from the Blocked state,
860 * and the task has a priority above the priority of the currently running task,
862 * context switch should be performed before exiting the ISR.
864 * @return If a task was removed from the Blocked state then pdTRUE is returned.
882 * The sbRECEIVE_COMPLETED() macro is called from within the FreeRTOS APIs when
884 * that was blocked on the message or stream buffer waiting for data to arrive
885 * then the sbRECEIVE_COMPLETED() macro sends a notification to the task to
886 * remove it from the Blocked state. xStreamBufferReceiveCompletedFromISR()
887 * does the same thing. It is provided to enable application writers to
891 * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
894 * @param xStreamBuffer The handle of the stream buffer from which data was
900 * xStreamBufferReceiveCompletedFromISR() removes a task from the Blocked state,
901 * and the task has a priority above the priority of the currently running task,
903 * context switch should be performed before exiting the ISR.
905 * @return If a task was removed from the Blocked state then pdTRUE is returned.
914 /* Functions below here are not part of the public API. */