michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Document pipe flush routines

Browse source 
Adds documentation for the two new flush routines:
   k_pipe_buffer_flush()
   k_pipe_flush()

Signed-off-by: Peter Mitsis <peter.mitsis@intel.com>
This commit is contained in:
Peter Mitsis 2021-10-19 12:35:25 -04:00 • committed by Anas Nashif
commit 3b235e37e1
1 changed files with 57 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

61
doc/reference/kernel/data_passing/pipes.rst
View file

@ -41,9 +41,21 @@ and then pend in the hope that the receive can be completed later. Accepted
data is either copied from the pipe's ring buffer or directly from the
waiting sender(s).
Data may also be **flushed** from a pipe by a thread. Flushing can be performed
either on the entire pipe or on only its ring buffer. Flushing the entire pipe
is equivalent to reading all the information in the ring buffer **and** waiting
to be written into a giant temporary buffer which is then discarded. Flushing
the ring buffer is equivalent to reading **only** the data in the ring buffer
into a temporary buffer which is then discarded. Flushing the ring buffer does
not guarantee that the ring buffer will stay empty; flushing it may allow a
pended writer to fill the ring buffer.
.. note::
Flushing does not in practice allocate or use additional buffers.
.. note::
The kernel does NOT allow for an ISR to send or receive data to/from a
pipe even if it does not attempt to wait for space/data.
pipe or flush even if it does not attempt to wait for space/data.
Implementation
**************
@ -152,9 +164,6 @@ process data items generated by one or more producing threads.
}
}
Suggested uses
**************
Use a pipe to send streams of data between threads.
.. note::
@ -162,6 +171,50 @@ Use a pipe to send streams of data between threads.
it is often preferable to send pointers to large data items to avoid
copying the data.
Flushing a Pipe's Buffer
========================
Data is flushed from the pipe's ring buffer by calling
:c:func:`k_pipe_buffer_flush`.
The following code builds on the examples above, and flushes the pipe's
buffer.
.. code-block:: c
void monitor_thread(void)
{
while (1) {
...
/* Pipe buffer contains stale data. Flush it. */
k_pipe_buffer_flush(&my_pipe);
...
}
}
Flushing a Pipe
===============
All data in the pipe is flushed by calling :c:func:`k_pipe_flush`.
The following code builds on the examples above, and flushes all the
data in the pipe.
Suggested uses
**************
.. code-block:: c
void monitor_thread(void)
{
while (1) {
...
/* Critical error detected. Flush the entire pipe to reset it. */
k_pipe_flush(&my_pipe);
...
}
}
Configuration Options
*********************