k_pipe: add-ons to the k_pipe API rewrite

doc/kernel/services/data_passing/pipes.rst

@@ -19,20 +19,25 @@ is referenced by its memory address.
 
 A pipe has the following key property:
 
-* A **size** that indicates the capacity of the pipe's ring buffer.
+* A **size** that indicates the capacity of the pipe's ring buffer. Note that a
+  size of zero defines a pipe with no ring buffer.
 
 A pipe must be initialized before it can be used. When initialized, the pipe
 is empty.
 
 Threads interact with the pipe as follows:
 
 - **Writing**: Data is synchronously written, either in whole or in part, to
-  a pipe by a thread. If the pipe's ring buffer is full, the operation blocks
-  until sufficient space becomes available or the specified timeout expires.
+  a pipe by a thread. Accepted data is either copied directly to the waiting
+  reader(s) or to the pipe's ring buffer. If the ring buffer is full or simply
+  absent, the operation blocks until sufficient space becomes available or
+  the specified timeout expires.
 
 - **Reading**: Data is synchronously read, either in whole or in part, from a
-  pipe by a thread. If the pipe's ring buffer is empty, the operation blocks
-  until data becomes available or the specified timeout expires.
+  pipe by a thread. Accepted data is either copied from the pipe's ring buffer
+  or directly from the waiting sender(s). If the ring buffer is empty or simply
+  absent, the operation blocks until data becomes available or the specified
+  timeout expires.
 
 - **Resetting**: A thread can reset a pipe, which resets its internal state and
   ends all pending read and write operations with an error code.
@@ -66,6 +71,9 @@ ring buffer:
 
 This has the same effect as the code above.
 
+When no ring buffer is used, the buffer pointer argument should be NULL and
+the size argument should be 0.
+
 Writing to a Pipe
 =================
 

include/zephyr/kernel.h

@@ -4998,8 +4998,8 @@ void k_mbox_data_get(struct k_mbox_msg *rx_msg, void *buffer);
  * This routine initializes a pipe object, prior to its first use.
  *
  * @param pipe Address of the pipe.
- * @param buffer Address of the pipe's buffer.
- * @param buffer_size Size of the pipe's buffer.
+ * @param buffer Address of the pipe's buffer, or NULL if no ring buffer is used.
+ * @param buffer_size Size of the pipe's buffer, or zero if no ring buffer is used.
  */
 __syscall void k_pipe_init(struct k_pipe *pipe, uint8_t *buffer, size_t buffer_size);
 
@@ -5247,7 +5247,8 @@ struct k_pipe {
  * @code extern struct k_pipe <name>; @endcode
  *
  * @param name Name of the pipe.
- * @param pipe_buffer_size Size of the pipe's ring buffer (in bytes).
+ * @param pipe_buffer_size Size of the pipe's ring buffer (in bytes)
+ *                         or zero if no ring buffer is used.
  * @param pipe_align Alignment of the pipe's ring buffer (power of 2).
  *
  */