sam0_common: Add additional documentation on DMA usage

cpu/sam0_common/include/periph_cpu_common.h

@@ -670,6 +670,9 @@ typedef struct {
 #define WDT_HAS_INIT                   (1)
 
 /**
+ * @name sam0 DMA peripheral
+ * @{
+ *
  * The sam0 DMA peripheral has a number of channels. Each channel is a separate
  * data stream, triggered by a configurable trigger when enabled, or triggered
  * by software (not yet supported). In theory each DMA channel is equal and can
@@ -680,6 +683,35 @@ typedef struct {
  * destination, are kept in RAM and are read when the channel is enabled and
  * triggered. On the SAML21 platform, these descriptors must reside in the LP
  * SRAM.
+ *
+ * The DMA addresses supplied must point to the **end** of the array to be
+ * transferred. When address increment is enabled this means that the supplied
+ * src or dst argument must point to array + length. When increment is disabled,
+ * the source or destination address can be used directly. The calculation of
+ * the end of the array must be done by the calling function, because the
+ * beatsize and the increment can usually be hardcoded there and doesn't have to
+ * be retrieved from the DMA register configuration.
+ * See also section 20.6.2.7 of the SAM D21/DA1 Family Data Sheet.
+ *
+ * Example:
+ * ```
+ * void transfer_data(void *src, void *dst, size_t len)
+ * {
+ *      dma_t channel = dma_acquire_channel()
+ *      if (channel == 0xff) {
+ *          return -E_BUSY;
+ *      }
+ *
+ *      dma_setup(channel, DMA_TRIGGER_MY_PERIH, 0, true);
+ *      dma_prepare(channel, DMAC_BTCTRL_BEATSIZE_BYTE_Val,
+ *                  (uint8_t*)src + len, (uint8_t*)dst + len, len);
+ *
+ *      dma_start(channel);
+ *      dma_wait(channel);
+ *
+ *      dma_release_channel(channel);
+ * }
+ * ```
  */
 
 /**
@@ -691,10 +723,13 @@ typedef struct {
 /**
  * @brief Move the DMA descriptors to the LP SRAM. Required on the SAML21
  */
-#if defined(CPU_FAM_SAML21)
+#if defined(CPU_FAM_SAML21) || defined(DOXYGEN)
 #define DMA_DESCRIPTOR_IN_LPSRAM
 #endif
 
+/**
+ * @brief Extra attributes required for instantiating DMA descriptors.
+ */
 #ifdef DMA_DESCRIPTOR_IN_LPSRAM
 #define DMA_DESCRIPTOR_ATTRS    __attribute__((section(".backup.bss")))
 #else
@@ -753,6 +788,9 @@ void dma_setup(dma_t dma, unsigned trigger, uint8_t prio, bool irq);
 /**
  * @brief   Prepare the DMA channel for an individual transfer.
  *
+ * @note    When increment is enabled for source or destination, the @p src
+ *          and/or @p dst must point to the **end** of the array.
+ *
  * @param   dma     DMA channel reference
  * @param   width   Transfer beat size to use
  * @param   src     Source address for the transfer
@@ -771,9 +809,12 @@ void dma_prepare(dma_t dma, uint8_t width, const void *src, void *dst,
  * peripheral address, leaving the destination address and related settings
  * untouched
  *
- * @note This only touches the source address, length and source increment
- * settings. Be sure to initialize the full descriptor beforehand with
- * @ref dma_prepare
+ * @note    This only touches the source address, length and source increment
+ *          settings. Be sure to initialize the full descriptor beforehand with
+ *          @ref dma_prepare
+ *
+ * @note    When increment is enabled for source, the @p src must point to the
+ *          **end** of the array.
  *
  * @param   dma     DMA channel reference
  * @param   src     Source address for the transfer
@@ -790,9 +831,12 @@ void dma_prepare_src(dma_t dma, const void *src, size_t len, bool incr);
  * peripheral address, leaving the source address and related settings
  * untouched
  *
- * @note This only touches the destination address, length and destination
- * increment settings. Be sure to initialize the full descriptor beforehand with
- * @ref dma_prepare
+ * @note    This only touches the destination address, length and destination
+ *          increment settings. Be sure to initialize the full descriptor
+ *          beforehand with @ref dma_prepare
+ *
+ * @note    When increment is enabled for destination, @p dst must point to the
+ *          **end** of the array.
  *
  * @param   dma     DMA channel reference
  * @param   dst     Destination address for the transfer
@@ -805,8 +849,12 @@ void dma_prepare_dst(dma_t dma, void *dst, size_t len, bool incr);
  * @brief   Append a second transfer descriptor after the default channel
  *          descriptor.
  *
- * @note Only a single extra transfer descriptor is supported for now.
- * @note @p descriptor must remain valid throughout the full transfer duration
+ * @note    Only a single extra transfer descriptor is supported for now.
+ *
+ * @note    @p next must remain valid throughout the full transfer duration
+ *
+ * @note    When increment is enabled for source or destination, @p src
+ *          and/or @p dst must point to the **end** of the array.
  *
  * @param   dma         DMA channel reference to add the descriptor to
  * @param   descriptor  Extra transfer descriptor to append
@@ -824,8 +872,12 @@ void dma_append(dma_t dma, DmacDescriptor *descriptor, uint8_t width,
  *          descriptor, copying destination and block size from the initial
  *          descriptor.
  *
- * @note Only a single extra transfer descriptor is supported for now.
- * @note @p descriptor must remain valid throughout the full transfer duration
+ * @note    Only a single extra transfer descriptor is supported for now.
+ *
+ * @note    @p next must remain valid throughout the full transfer duration
+ *
+ * @note    When increment is enabled for source, @p src must point to the
+ *          **end** of the array.
  *
  * @param   dma     DMA channel reference to add the descriptor to
  * @param   next    Extra transfer descriptor to append
@@ -841,8 +893,12 @@ void dma_append_src(dma_t dma, DmacDescriptor *next, const void *src,
  *          descriptor, copying source and block size from the initial
  *          descriptor.
  *
- * @note Only a single extra transfer descriptor is supported for now.
- * @note @p descriptor must remain valid throughout the full transfer duration
+ * @note    Only a single extra transfer descriptor is supported for now.
+ *
+ * @note    @p next must remain valid throughout the full transfer duration
+ *
+ * @note    When increment is enabled for destination, @p dst must point to the
+ *          **end** of the array.
  *
  * @param   dma     DMA channel reference to add the descriptor to
  * @param   next    Extra transfer descriptor to append
@@ -880,6 +936,7 @@ void dma_wait(dma_t dma);
  * @param   dma     DMA channel reference
  */
 void dma_cancel(dma_t dma);
+/** @} */
 
 #ifdef __cplusplus
 }