lib: os: spsc_pbuf: Clarify using cache management in the module

Packet buffer can be used for sharing data between cores. In that
case when any core has data cache then data cache handling must
be enabled in the module. However, it shall never be enabled when
the packet buffer is used on a single core. Adding that information
to the documentation.

Signed-off-by: Krzysztof Chruściński <[email protected]>

Author: nordic-krch

include/zephyr/sys/spsc_pbuf.h

@@ -25,7 +25,11 @@ extern "C" {
  * @{
  */
 
-/** @brief Flag indicating that cache shall be handled. */
+/** @brief Flag indicating that cache shall be handled.
+ *
+ * It shall be used only when packet buffer is shared between two cores as on a single
+ * core cache shall not be handled manually because it results in data corruption.
+ */
 #define SPSC_PBUF_CACHE BIT(0)
 
 /** @brief Size of the field which stores maximum utilization. */

lib/os/Kconfig

@@ -60,7 +60,9 @@ config SPSC_PBUF_CACHE_ALWAYS
 	bool "Always handle cache"
 	help
 	  Handle cache writeback and invalidation for all instances. Option used
-	  to avoid runtime check and thus reduce memory footprint.
+	  to avoid runtime check and thus reduce memory footprint. Beware! It shall
+	  be used only if all packet buffer instances are used for data sharing
+	  between cores.
 
 config SPSC_PBUF_CACHE_NEVER
 	bool "Never handle cache"