From d13a2544f7e89637eb1b5c52258b291d6b4727e1 Mon Sep 17 00:00:00 2001 From: Peter Mitsis Date: Thu, 14 Jul 2022 22:38:10 -0400 Subject: [PATCH] doc: Update documentation related to pipes The pipes implementation has been updated to allow ISRs to both send and receive data to/from pipes provided the K_NO_WAIT timeout option is used. Signed-off-by: Peter Mitsis --- doc/kernel/services/data_passing/pipes.rst | 12 ++++++++---- doc/kernel/services/index.rst | 5 ++++- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/doc/kernel/services/data_passing/pipes.rst b/doc/kernel/services/data_passing/pipes.rst index e7538ce5f1f..62c4f8f0223 100644 --- a/doc/kernel/services/data_passing/pipes.rst +++ b/doc/kernel/services/data_passing/pipes.rst @@ -54,8 +54,9 @@ pended writer to fill the ring buffer. 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 or flush even if it does not attempt to wait for space/data. + The kernel does allow for an ISR to flush a pipe from an ISR. It also + allows it to send/receive data to/from one provided it does not attempt + to wait for space/data. Implementation ************** @@ -219,7 +220,10 @@ 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. + 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. Copying large data items will negatively impact interrupt latency + as a spinlock is held while copying that data. Configuration Options @@ -227,7 +231,7 @@ Configuration Options Related configuration options: -* None. +* CONFIG_PIPES API Reference ************* diff --git a/doc/kernel/services/index.rst b/doc/kernel/services/index.rst index 01d2243595d..82c49ba3b7e 100644 --- a/doc/kernel/services/index.rst +++ b/doc/kernel/services/index.rst @@ -61,7 +61,7 @@ LIFO No Queue Arbitrary [1] Stack No Array Word Word Yes [3] Yes Undefined behavior Message queue No Ring buffer Power of two Power of two Yes [3] Yes Pend thread or return -errno Mailbox Yes Queue Arbitrary [1] Arbitrary No No N/A -Pipe No Ring buffer [4] Arbitrary Arbitrary No No Pend thread or return -errno +Pipe No Ring buffer [4] Arbitrary Arbitrary Yes [5] Yes [5] Pend thread or return -errno =============== ============== =================== ============== ============== ================= ============== =============================== [1] Callers allocate space for queue overhead in the data @@ -76,6 +76,9 @@ argument. [4] Optional. +[5] ISRS can send and/or receive only when passing K_NO_WAIT as the +timeout argument. + .. toctree:: :maxdepth: 1