zephyr: sof/lib/dma: add inline documentation to dma.h

Add a note to Zephyr sof/lib/dma.h explaining the relation of
SOF and Zephyr DMA interfaces and warn about the name space overlaps
that exist. Also enumerate the main usage scenarios that have
to be handled in this file.

Signed-off-by: Kai Vehmanen <[email protected]>

zephyr/include/sof/lib/dma.h

@@ -24,10 +24,31 @@
 struct comp_buffer;
 
 /** \addtogroup sof_dma_drivers DMA Drivers
- *  DMA Drivers API specification.
+ *  SOF DMA Drivers API specification (deprecated interface, to be
+ *  replaced by Zephyr zephyr/drivers/dma.h interface).
  *  @{
  */
 
+/*
+ * There is significant overlap with SOF DMA interface and
+ * Zephyr zephyr/drivers/dma.h. Neither uses a unique namespace
+ * prefix, leading to at times confusing mix of DMA_ and dma_
+ * definitions, some coming from legacy SOF definitions, while
+ * some from Zephyr.
+ *
+ * Definitions in this file are used by following SOF code:
+ *  - Some use of SOF DMA data types and definitions exists in
+ *    generic application code (in IPC, host handling and a few other
+ *    places). To support both XTOS and Zephyr builds, these
+ *    definitions must be provided by the RTOS layer.
+ *  - SOF builds where Zephyr is used but platform has not yet
+ *    moved to native Zephyr drivers, so legacy/XTOS DMA are used.
+ *  - Linking DMA resources to audio usages. Even SOF builds with
+ *    native Zephyr build still use some SOF side DMA definitions
+ *    to describe system DMA resources in terms of their capabilities
+ *    for audio use. See sof/zephyr/lib/dma.c for most of this logic.
+ */
+
 /* DMA direction bitmasks used to define DMA copy direction */
 #define DMA_DIR_MEM_TO_MEM	BIT(0) /**< local memory copy */
 #define DMA_DIR_HMEM_TO_LMEM	BIT(1) /**< host memory to local mem copy */