doc: Document pipe flush routines

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

Signed-off-by: Peter Mitsis <[email protected]>

Author: peter-mitsis

doc/reference/kernel/data_passing/pipes.rst

@@ -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,16 +164,57 @@ process data items generated by one or more producing threads.
         }
     }
 
-Suggested uses
-**************
-
 Use a pipe to send streams of data between threads.
 
 .. note::
     A pipe can be used to transfer long streams of data if desired.  However
     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
 *********************