From 816b143452725456ea50fa7b3ff23fafd1d43ab1 Mon Sep 17 00:00:00 2001 From: Kai Vehmanen Date: Wed, 9 Oct 2024 15:01:42 +0300 Subject: [PATCH] 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 --- zephyr/include/sof/lib/dma.h | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/zephyr/include/sof/lib/dma.h b/zephyr/include/sof/lib/dma.h index 862b9324b7ed..652c345979e3 100644 --- a/zephyr/include/sof/lib/dma.h +++ b/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 */