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.
38 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
39 * implementation (so also the message buffer implementation, as message buffers
41 * interrupt that will write to the buffer (the writer), and only one task or
42 * interrupt that will read from the buffer (the reader). It is safe for the
46 * then the application writer must place each call to a writing API function
47 * (such as xMessageBufferSend()) inside a critical section and set the send
49 * then the application writer must place each call to a reading API function
50 * (such as xMessageBufferRead()) inside a critical section and set the receive
54 * message is written to the message buffer an additional sizeof( size_t ) bytes
55 * are also written to store the message's length (that happens internally, with
56 * the API function). sizeof( size_t ) is typically 4 bytes on a 32-bit
58 * architecture will actually reduce the available space in the message buffer
59 * by 14 bytes (10 byte are used by the message, and 4 bytes to hold the length
60 * of the message).
104 * @param xBufferSizeBytes The total number of bytes (not messages) the message
106 * the message buffer an additional sizeof( size_t ) bytes are also written to
107 * store the message's length. sizeof( size_t ) is typically 4 bytes on a
111 * @param pxSendCompletedCallback Callback invoked when a send operation to the
112 * message buffer is complete. If the parameter is NULL or xMessageBufferCreate()
113 * is called without the parameter, then it will use the default implementation
114 * provided by sbSEND_COMPLETED macro. To enable the callback,
118 * the message buffer is complete. If the parameter is NULL or xMessageBufferCreate()
119 * is called without the parameter, it will use the default implementation provided
120 * by sbRECEIVE_COMPLETED macro. To enable the callback,
123 * @return If NULL is returned, then the message buffer cannot be created
125 * the message buffer data structures and storage area. A non-NULL value being
126 * returned indicates that the message buffer has been created successfully -
127 * the returned value should be stored as the handle to the created message
138 * // Create a message buffer that can hold 100 bytes. The memory used to hold
139 * // both the message buffer structure and the messages themselves is allocated
140 * // dynamically. Each message added to the buffer consumes an additional 4
141 * // bytes which are used to hold the length of the message.
146 * // There was not enough heap memory space available to create the
151 * // The message buffer was created successfully and can now be used.
177 * @param xBufferSizeBytes The size, in bytes, of the buffer pointed to by the
178 * pucMessageBufferStorageArea parameter. When a message is written to the
180 * the message's length. sizeof( size_t ) is typically 4 bytes on a 32-bit
182 * 14 bytes of message buffer space. The maximum number of bytes that can be
183 * stored in the message buffer is actually (xBufferSizeBytes - 1).
186 * least xBufferSizeBytes big. This is the array to which messages are
187 * copied when they are written to the message buffer.
190 * StaticMessageBuffer_t, which will be used to hold the message buffer's data
193 * @param pxSendCompletedCallback Callback invoked when a new message is sent to the message buffer.
194 …* If the parameter is NULL or xMessageBufferCreate() is called without the parameter, then it will…
195 * implementation provided by sbSEND_COMPLETED macro. To enable the callback,
199 …* message buffer. If the parameter is NULL or xMessageBufferCreate() is called without the paramet…
200 * use the default implementation provided by sbRECEIVE_COMPLETED macro. To enable the callback,
203 * @return If the message buffer is created successfully then a handle to the
210 * // Used to dimension the array used to hold the messages. The available space
214 * // Defines the memory that will actually hold the messages within the message
218 * // The variable used to hold the message buffer structure.
229 * // As neither the pucMessageBufferStorageArea or pxStaticMessageBuffer
231 * // reference the created message buffer in other message buffer API calls.
233 * // Other code that uses the message buffer can go here.
258 * buffer and storage area buffer. These are the same buffers that are supplied
259 * at the time of creation.
261 * @param xMessageBuffer The message buffer for which to retrieve the buffers.
263 * @param ppucMessageBufferStorageArea Used to return a pointer to the
266 * @param ppxStaticMessageBuffer Used to return a pointer to the message
289 * Sends a discrete message to the message buffer. The message can be any
290 * length that fits within the buffer's free space, and is copied into the
293 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
294 * implementation (so also the message buffer implementation, as message buffers
296 * interrupt that will write to the buffer (the writer), and only one task or
297 * interrupt that will read from the buffer (the reader). It is safe for the
301 * then the application writer must place each call to a writing API function
302 * (such as xMessageBufferSend()) inside a critical section and set the send
304 * then the application writer must place each call to a reading API function
305 * (such as xMessageBufferRead()) inside a critical section and set the receive
312 * @param xMessageBuffer The handle of the message buffer to which a message is
315 * @param pvTxData A pointer to the message that is to be copied into the
318 * @param xDataLengthBytes The length of the message. That is, the number of
319 * bytes to copy from pvTxData into the message buffer. When a message is
320 * written to the message buffer an additional sizeof( size_t ) bytes are also
321 * written to store the message's length. sizeof( size_t ) is typically 4 bytes
323 * xDataLengthBytes to 20 will reduce the free space in the message buffer by 24
324 * bytes (20 bytes of message data and 4 bytes to hold the message length).
326 * @param xTicksToWait The maximum amount of time the calling task should remain
327 * in the Blocked state to wait for enough space to become available in the
328 * message buffer, should the message buffer have insufficient space when
329 * xMessageBufferSend() is called. The calling task will never block if
330 * xTicksToWait is zero. The block time is specified in tick periods, so the
331 * absolute time it represents is dependent on the tick frequency. The macro
334 * the task to wait indefinitely (without timing out), provided
336 * CPU time when they are in the Blocked state.
338 * @return The number of bytes written to the message buffer. If the call to
339 * xMessageBufferSend() times out before there was enough space to write the
340 * message into the message buffer then zero is returned. If the call did not
352 * // Send an array to the message buffer, blocking for a maximum of 100ms to
353 * // wait for enough space to be available in the message buffer.
358 * // The call to xMessageBufferSend() times out before there was enough
359 * // space in the buffer for the data to be written.
362 * // Send the string to the message buffer. Return immediately if there is
363 * // not enough space in the buffer.
368 * // The string could not be added to the message buffer because there was
369 * // not enough free space in the buffer.
389 * Interrupt safe version of the API function that sends a discrete message to
390 * the message buffer. The message can be any length that fits within the
391 * buffer's free space, and is copied into the buffer.
393 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
394 * implementation (so also the message buffer implementation, as message buffers
396 * interrupt that will write to the buffer (the writer), and only one task or
397 * interrupt that will read from the buffer (the reader). It is safe for the
401 * then the application writer must place each call to a writing API function
402 * (such as xMessageBufferSend()) inside a critical section and set the send
404 * then the application writer must place each call to a reading API function
405 * (such as xMessageBufferRead()) inside a critical section and set the receive
412 * @param xMessageBuffer The handle of the message buffer to which a message is
415 * @param pvTxData A pointer to the message that is to be copied into the
418 * @param xDataLengthBytes The length of the message. That is, the number of
419 * bytes to copy from pvTxData into the message buffer. When a message is
420 * written to the message buffer an additional sizeof( size_t ) bytes are also
421 * written to store the message's length. sizeof( size_t ) is typically 4 bytes
423 * xDataLengthBytes to 20 will reduce the free space in the message buffer by 24
424 * bytes (20 bytes of message data and 4 bytes to hold the message length).
429 * was waiting for data to leave the Blocked state. If calling
430 * xMessageBufferSendFromISR() causes a task to leave the Blocked state, and the
431 * unblocked task has a priority higher than the currently executing task (the
435 * context switch should be performed before the interrupt is exited. This will
436 * ensure that the interrupt returns directly to the highest priority Ready
438 * is passed into the function. See the code example below for an example.
440 * @return The number of bytes actually written to the message buffer. If the
441 * message buffer didn't have enough free space for the message to be stored
455 * // Attempt to send the string to the message buffer.
463 * // The string could not be added to the message buffer because there was
464 * // not enough free space in the buffer.
468 * // xMessageBufferSendFromISR() then a task that has a priority above the
469 * // priority of the currently executing task was unblocked and a context
470 * // switch should be performed to ensure the ISR returns to the unblocked
472 * // xHigherPriorityTaskWoken into portYIELD_FROM_ISR(), which will test the
473 * // variables value, and perform the context switch if necessary. Check the
474 * // documentation for the port in use for port specific instructions.
495 * variable length and are copied out of the buffer.
497 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
498 * implementation (so also the message buffer implementation, as message buffers
500 * interrupt that will write to the buffer (the writer), and only one task or
501 * interrupt that will read from the buffer (the reader). It is safe for the
505 * then the application writer must place each call to a writing API function
506 * (such as xMessageBufferSend()) inside a critical section and set the send
508 * then the application writer must place each call to a reading API function
509 * (such as xMessageBufferRead()) inside a critical section and set the receive
516 * @param xMessageBuffer The handle of the message buffer from which a message
519 * @param pvRxData A pointer to the buffer into which the received message is
522 * @param xBufferLengthBytes The length of the buffer pointed to by the pvRxData
523 * parameter. This sets the maximum length of the message that can be received.
524 * If xBufferLengthBytes is too small to hold the next message then the message
525 * will be left in the message buffer and 0 will be returned.
527 * @param xTicksToWait The maximum amount of time the task should remain in the
528 * Blocked state to wait for a message, should the message buffer be empty.
530 * the message buffer is empty. The block time is specified in tick periods, so
531 * the absolute time it represents is dependent on the tick frequency. The
534 * cause the task to wait indefinitely (without timing out), provided
536 * CPU time when they are in the Blocked state.
538 * @return The length, in bytes, of the message read from the message buffer, if
540 * then zero is returned. If the length of the message is greater than
541 * xBufferLengthBytes then the message will be left in the message buffer and
552 * // Receive the next message from the message buffer. Wait in the Blocked
563 * // the message here....
584 * An interrupt safe version of the API function that receives a discrete
586 * copied out of the buffer.
588 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
589 * implementation (so also the message buffer implementation, as message buffers
591 * interrupt that will write to the buffer (the writer), and only one task or
592 * interrupt that will read from the buffer (the reader). It is safe for the
596 * then the application writer must place each call to a writing API function
597 * (such as xMessageBufferSend()) inside a critical section and set the send
599 * then the application writer must place each call to a reading API function
600 * (such as xMessageBufferRead()) inside a critical section and set the receive
607 * @param xMessageBuffer The handle of the message buffer from which a message
610 * @param pvRxData A pointer to the buffer into which the received message is
613 * @param xBufferLengthBytes The length of the buffer pointed to by the pvRxData
614 * parameter. This sets the maximum length of the message that can be received.
615 * If xBufferLengthBytes is too small to hold the next message then the message
616 * will be left in the message buffer and 0 will be returned.
621 * that is waiting for space to leave the Blocked state. If calling
622 * xMessageBufferReceiveFromISR() causes a task to leave the Blocked state, and
623 * the unblocked task has a priority higher than the currently executing task
624 * (the task that was interrupted), then, internally,
627 * context switch should be performed before the interrupt is exited. That will
628 * ensure the interrupt returns directly to the highest priority Ready state
630 * passed into the function. See the code example below for an example.
632 * @return The length, in bytes, of the message read from the message buffer, if
646 * // Receive the next message from the message buffer.
655 * // the message here....
659 * // xMessageBufferReceiveFromISR() then a task that has a priority above the
660 * // priority of the currently executing task was unblocked and a context
661 * // switch should be performed to ensure the ISR returns to the unblocked
663 * // xHigherPriorityTaskWoken into portYIELD_FROM_ISR(), which will test the
664 * // variables value, and perform the context switch if necessary. Check the
665 * // documentation for the port in use for port specific instructions.
683 * xMessageBufferCreate() or xMessageBufferCreateStatic(). If the message
685 * then the allocated memory is freed.
687 * A message buffer handle must not be used after the message buffer has been
690 * @param xMessageBuffer The handle of the message buffer to be deleted.
704 * by a message being removed from the message buffer.
706 * @param xMessageBuffer The handle of the message buffer being queried.
708 * @return If the message buffer referenced by xMessageBuffer is full then
722 * @param xMessageBuffer The handle of the message buffer being queried.
724 * @return If the message buffer referenced by xMessageBuffer is empty then
742 * @param xMessageBuffer The handle of the message buffer being reset.
744 * @return If the message buffer was reset then pdPASS is returned. If the
746 * the message queue to wait for space to become available, or to wait for a
761 * Returns the number of bytes of free space in the message buffer.
763 * @param xMessageBuffer The handle of the message buffer being queried.
765 * @return The number of bytes that can be written to the message buffer before
766 * the message buffer would be full. When a message is written to the message
767 * buffer an additional sizeof( size_t ) bytes are also written to store the
769 * architecture, so if xMessageBufferSpacesAvailable() returns 10, then the size
770 * of the largest message that can be written to the message buffer is 6 bytes.
785 * Returns the length (in bytes) of the next message in a message buffer.
786 * Useful if xMessageBufferReceive() returned 0 because the size of the buffer
787 * passed into xMessageBufferReceive() was too small to hold the next message.
789 * @param xMessageBuffer The handle of the message buffer being queried.
791 * @return The length (in bytes) of the next message in the message buffer, or 0
792 * if the message buffer is empty.
809 * The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when
811 * was blocked on the message or stream buffer waiting for data to arrive then
812 * the sbSEND_COMPLETED() macro sends a notification to the task to remove it
813 * from the Blocked state. xMessageBufferSendCompletedFromISR() does the same
817 * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
820 * @param xMessageBuffer The handle of the stream buffer to which data was
826 * xMessageBufferSendCompletedFromISR() removes a task from the Blocked state,
827 * and the task has a priority above the priority of the currently running task,
829 * context switch should be performed before exiting the ISR.
831 * @return If a task was removed from the Blocked state then pdTRUE is returned.
849 * The sbRECEIVE_COMPLETED() macro is called from within the FreeRTOS APIs when
851 * that was blocked on the message or stream buffer waiting for data to arrive
852 * then the sbRECEIVE_COMPLETED() macro sends a notification to the task to
853 * remove it from the Blocked state. xMessageBufferReceiveCompletedFromISR()
854 * does the same thing. It is provided to enable application writers to
858 * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
861 * @param xMessageBuffer The handle of the stream buffer from which data was
867 * xMessageBufferReceiveCompletedFromISR() removes a task from the Blocked state,
868 * and the task has a priority above the priority of the currently running task,
870 * context switch should be performed before exiting the ISR.
872 * @return If a task was removed from the Blocked state then pdTRUE is returned.