RIOT-OS/RIOT
RIOT-OS/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2024-12-29 04:50:03 +01:00
Code Releases Activity

Merge pull request #14278 from bergzand/pr/sam0_common/dma_clarify

Browse Source 
sam0_common: Add additional documentation on DMA usage
This commit is contained in:
benpicco 2020-06-14 13:56:25 +02:00 committed by GitHub
commit a019c95190
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 102 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
cpu/sam0_common/include/periph_cpu_common.h
View File

@ -670,6 +670,9 @@ typedef struct {
#define WDT_HAS_INIT (1) #define WDT_HAS_INIT (1)
/** /**
* @name sam0 DMA peripheral
* @{
*
* The sam0 DMA peripheral has a number of channels. Each channel is a separate * 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 * 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 * 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 * 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 * triggered. On the SAML21 platform, these descriptors must reside in the LP
* SRAM. * 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 * @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 #define DMA_DESCRIPTOR_IN_LPSRAM
#endif #endif
/**
* @brief Extra attributes required for instantiating DMA descriptors.
*/
#ifdef DMA_DESCRIPTOR_IN_LPSRAM #ifdef DMA_DESCRIPTOR_IN_LPSRAM
#define DMA_DESCRIPTOR_ATTRS __attribute__((section(".backup.bss"))) #define DMA_DESCRIPTOR_ATTRS __attribute__((section(".backup.bss")))
#else #else
@ -753,15 +788,18 @@ void dma_setup(dma_t dma, unsigned trigger, uint8_t prio, bool irq);
/** /**
* @brief Prepare the DMA channel for an individual transfer. * @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 dma DMA channel reference
* @param width Transfer beat size to use * @param width Transfer beat size to use
* @param src Source address for the transfer * @param src Source address for the transfer
* @param dst Destination address for the transfer * @param dst Destination address for the transfer
* @param len Number of beats to transfer * @param num Number of beats to transfer
* @param incr Which of the addresses to increment after a beat * @param incr Which of the addresses to increment after a beat
*/ */
void dma_prepare(dma_t dma, uint8_t width, const void *src, void *dst, void dma_prepare(dma_t dma, uint8_t width, const void *src, void *dst,
size_t len, dma_incr_t incr); size_t num, dma_incr_t incr);
/** /**
* @brief Prepare a transfer without modifying the destination address * @brief Prepare a transfer without modifying the destination address
@ -771,16 +809,19 @@ void dma_prepare(dma_t dma, uint8_t width, const void *src, void *dst,
* peripheral address, leaving the destination address and related settings * peripheral address, leaving the destination address and related settings
* untouched * untouched
* *
* @note This only touches the source address, length and source increment * @note This only touches the source address, number of transfers and source
* settings. Be sure to initialize the full descriptor beforehand with * increment settings. Be sure to initialize the full descriptor
* @ref dma_prepare * 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 dma DMA channel reference
* @param src Source address for the transfer * @param src Source address for the transfer
* @param len Number of beats to transfer * @param num Number of beats to transfer
* @param incr Whether to increment the source address after a beat * @param incr Whether to increment the source address after a beat
*/ */
void dma_prepare_src(dma_t dma, const void *src, size_t len, bool incr); void dma_prepare_src(dma_t dma, const void *src, size_t num, bool incr);
/** /**
* @brief Prepare a transfer without modifying the source address * @brief Prepare a transfer without modifying the source address
@ -790,67 +831,82 @@ void dma_prepare_src(dma_t dma, const void *src, size_t len, bool incr);
* peripheral address, leaving the source address and related settings * peripheral address, leaving the source address and related settings
* untouched * untouched
* *
* @note This only touches the destination address, length and destination * @note This only touches the destination address, the number of transfers
* increment settings. Be sure to initialize the full descriptor beforehand with * and destination increment settings. Be sure to initialize the full
* @ref dma_prepare * 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 dma DMA channel reference
* @param dst Destination address for the transfer * @param dst Destination address for the transfer
* @param len Number of beats to transfer * @param num Number of beats to transfer
* @param incr Whether to increment the destination address after a beat * @param incr Whether to increment the destination address after a beat
*/ */
void dma_prepare_dst(dma_t dma, void *dst, size_t len, bool incr); void dma_prepare_dst(dma_t dma, void *dst, size_t num, bool incr);
/** /**
* @brief Append a second transfer descriptor after the default channel * @brief Append a second transfer descriptor after the default channel
* descriptor. * descriptor.
* *
* @note Only a single extra transfer descriptor is supported for now. * @note Only a single extra transfer descriptor is supported for now.
* @note @p descriptor must remain valid throughout the full transfer duration *
* @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 dma DMA channel reference to add the descriptor to
* @param descriptor Extra transfer descriptor to append * @param descriptor Extra transfer descriptor to append
* @param width Transfer beat size to use * @param width Transfer beat size to use
* @param src Source address for the transfer * @param src Source address for the transfer
* @param dst Destination address for the transfer * @param dst Destination address for the transfer
* @param len Number of beats to transfer * @param num Number of beats to transfer
* @param incr Which of the addresses to increment after a beat * @param incr Which of the addresses to increment after a beat
*/ */
void dma_append(dma_t dma, DmacDescriptor *descriptor, uint8_t width, void dma_append(dma_t dma, DmacDescriptor *descriptor, uint8_t width,
const void *src, void *dst, size_t len, dma_incr_t incr); const void *src, void *dst, size_t num, dma_incr_t incr);
/** /**
* @brief Append a second transfer descriptor after the default channel * @brief Append a second transfer descriptor after the default channel
* descriptor, copying destination and block size from the initial * descriptor, copying destination and block size from the initial
* descriptor. * descriptor.
* *
* @note Only a single extra transfer descriptor is supported for now. * @note Only a single extra transfer descriptor is supported for now.
* @note @p descriptor must remain valid throughout the full transfer duration *
* @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 dma DMA channel reference to add the descriptor to
* @param next Extra transfer descriptor to append * @param next Extra transfer descriptor to append
* @param src Source address for the transfer * @param src Source address for the transfer
* @param len Number of beats to transfer * @param num Number of beats to transfer
* @param incr Whether to increment the source address after a beat * @param incr Whether to increment the source address after a beat
*/ */
void dma_append_src(dma_t dma, DmacDescriptor *next, const void *src, void dma_append_src(dma_t dma, DmacDescriptor *next, const void *src,
size_t len, bool incr); size_t num, bool incr);
/** /**
* @brief Append a second transfer descriptor after the default channel * @brief Append a second transfer descriptor after the default channel
* descriptor, copying source and block size from the initial * descriptor, copying source and block size from the initial
* descriptor. * descriptor.
* *
* @note Only a single extra transfer descriptor is supported for now. * @note Only a single extra transfer descriptor is supported for now.
* @note @p descriptor must remain valid throughout the full transfer duration *
* @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 dma DMA channel reference to add the descriptor to
* @param next Extra transfer descriptor to append * @param next Extra transfer descriptor to append
* @param dst Destination address for the transfer * @param dst Destination address for the transfer
* @param len Number of beats to transfer * @param num Number of beats to transfer
* @param incr Whether to increment the source address after a beat * @param incr Whether to increment the source address after a beat
*/ */
void dma_append_dst(dma_t dma, DmacDescriptor *next, void *dst, size_t len, void dma_append_dst(dma_t dma, DmacDescriptor *next, void *dst, size_t num,
bool incr); bool incr);
/** /**
@ -880,6 +936,7 @@ void dma_wait(dma_t dma);
* @param dma DMA channel reference * @param dma DMA channel reference
*/ */
void dma_cancel(dma_t dma); void dma_cancel(dma_t dma);
/** @} */
#ifdef __cplusplus #ifdef __cplusplus
} }

42
cpu/sam0_common/periph/dma.c
View File

@ -134,9 +134,9 @@ static inline void _set_destination(DmacDescriptor *descr, void *dst)
descr->DSTADDR.reg = (uint32_t)dst; descr->DSTADDR.reg = (uint32_t)dst;
} }
static inline void _set_len(DmacDescriptor *descr, size_t len) static inline void _set_num(DmacDescriptor *descr, size_t num)
{ {
descr->BTCNT.reg = len; descr->BTCNT.reg = num;
} }
static inline void _set_next_descriptor(DmacDescriptor *descr, void *next) static inline void _set_next_descriptor(DmacDescriptor *descr, void *next)
@ -170,12 +170,12 @@ void dma_setup(dma_t dma, unsigned trigger, uint8_t prio, bool irq)
#endif #endif
} }
void dma_prepare(dma_t dma, uint8_t width, const void *src, void *dst, size_t len, void dma_prepare(dma_t dma, uint8_t width, const void *src, void *dst,
uint8_t incr) size_t num, uint8_t incr)
{ {
DEBUG("[DMA]: Prepare %u, len: %u\n", dma, (unsigned)len); DEBUG("[DMA]: Prepare %u, num: %u\n", dma, (unsigned)num);
DmacDescriptor *descr = &descriptors[dma]; DmacDescriptor *descr = &descriptors[dma];
_set_len(descr, len); _set_num(descr, num);
_set_source(descr, src); _set_source(descr, src);
_set_destination(descr, dst); _set_destination(descr, dst);
descr->DESCADDR.reg = (uint32_t)NULL; descr->DESCADDR.reg = (uint32_t)NULL;
@ -184,24 +184,22 @@ void dma_prepare(dma_t dma, uint8_t width, const void *src, void *dst, size_t le
DMAC_BTCTRL_VALID; DMAC_BTCTRL_VALID;
} }
void dma_prepare_src(dma_t dma, const void *src, size_t len, void dma_prepare_src(dma_t dma, const void *src, size_t num, bool incr)
bool incr)
{ {
DEBUG("[dma]: %u: prep src %p, %u, %u\n", dma, src, (unsigned)len, incr); DEBUG("[dma]: %u: prep src %p, %u, %u\n", dma, src, (unsigned)num, incr);
DmacDescriptor *descr = &descriptors[dma]; DmacDescriptor *descr = &descriptors[dma];
_set_len(descr, len); _set_num(descr, num);
_set_source(descr, src); _set_source(descr, src);
descr->BTCTRL.reg = (descr->BTCTRL.reg & ~DMAC_BTCTRL_SRCINC) | descr->BTCTRL.reg = (descr->BTCTRL.reg & ~DMAC_BTCTRL_SRCINC) |
(incr << DMAC_BTCTRL_SRCINC_Pos); (incr << DMAC_BTCTRL_SRCINC_Pos);
_set_next_descriptor(descr, NULL); _set_next_descriptor(descr, NULL);
} }
void dma_prepare_dst(dma_t dma, void *dst, size_t len, void dma_prepare_dst(dma_t dma, void *dst, size_t num, bool incr)
bool incr)
{ {
DEBUG("[dma]: %u: prep dst %p, %u, %u\n", dma, dst, (unsigned)len, incr); DEBUG("[dma]: %u: prep dst %p, %u, %u\n", dma, dst, (unsigned)num, incr);
DmacDescriptor *descr = &descriptors[dma]; DmacDescriptor *descr = &descriptors[dma];
_set_len(descr, len); _set_num(descr, num);
_set_destination(descr, dst); _set_destination(descr, dst);
descr->BTCTRL.reg = (descr->BTCTRL.reg & ~DMAC_BTCTRL_DSTINC) | descr->BTCTRL.reg = (descr->BTCTRL.reg & ~DMAC_BTCTRL_DSTINC) |
(incr << DMAC_BTCTRL_DSTINC_Pos); (incr << DMAC_BTCTRL_DSTINC_Pos);
@ -209,39 +207,39 @@ void dma_prepare_dst(dma_t dma, void *dst, size_t len,
} }
void _fmt_append(DmacDescriptor *descr, DmacDescriptor *next, void _fmt_append(DmacDescriptor *descr, DmacDescriptor *next,
const void *src, void *dst, size_t len) const void *src, void *dst, size_t num)
{ {
/* Configure the full descriptor besides the BTCTRL data */ /* Configure the full descriptor besides the BTCTRL data */
_set_next_descriptor(descr, next); _set_next_descriptor(descr, next);
_set_next_descriptor(next, NULL); _set_next_descriptor(next, NULL);
_set_source(next, src); _set_source(next, src);
_set_len(next, len); _set_num(next, num);
_set_destination(next, dst); _set_destination(next, dst);
} }
void dma_append(dma_t dma, DmacDescriptor *next, uint8_t width, void dma_append(dma_t dma, DmacDescriptor *next, uint8_t width,
const void *src, void *dst, size_t len, dma_incr_t incr) const void *src, void *dst, size_t num, dma_incr_t incr)
{ {
DmacDescriptor *descr = &descriptors[dma]; DmacDescriptor *descr = &descriptors[dma];
next->BTCTRL.reg = width << DMAC_BTCTRL_BEATSIZE_Pos | next->BTCTRL.reg = width << DMAC_BTCTRL_BEATSIZE_Pos |
incr << DMAC_BTCTRL_SRCINC_Pos | incr << DMAC_BTCTRL_SRCINC_Pos |
DMAC_BTCTRL_VALID; DMAC_BTCTRL_VALID;
_fmt_append(descr, next, src, dst, len); _fmt_append(descr, next, src, dst, num);
} }
void dma_append_src(dma_t dma, DmacDescriptor *next, const void *src, void dma_append_src(dma_t dma, DmacDescriptor *next, const void *src,
size_t len, bool incr) size_t num, bool incr)
{ {
DmacDescriptor *descr = &descriptors[dma]; DmacDescriptor *descr = &descriptors[dma];
/* Copy the original descriptor config and modify the increment */ /* Copy the original descriptor config and modify the increment */
next->BTCTRL.reg = (descr->BTCTRL.reg & ~DMAC_BTCTRL_SRCINC) | next->BTCTRL.reg = (descr->BTCTRL.reg & ~DMAC_BTCTRL_SRCINC) |
(incr << DMAC_BTCTRL_SRCINC_Pos); (incr << DMAC_BTCTRL_SRCINC_Pos);
_fmt_append(descr, next, src, (void *)descr->DSTADDR.reg, len); _fmt_append(descr, next, src, (void *)descr->DSTADDR.reg, num);
} }
void dma_append_dst(dma_t dma, DmacDescriptor *next, void *dst, size_t len, void dma_append_dst(dma_t dma, DmacDescriptor *next, void *dst, size_t num,
bool incr) bool incr)
{ {
DmacDescriptor *descr = &descriptors[dma]; DmacDescriptor *descr = &descriptors[dma];
@ -249,7 +247,7 @@ void dma_append_dst(dma_t dma, DmacDescriptor *next, void *dst, size_t len,
/* Copy the original descriptor config and modify the increment */ /* Copy the original descriptor config and modify the increment */
next->BTCTRL.reg = (descr->BTCTRL.reg & ~DMAC_BTCTRL_DSTINC) | next->BTCTRL.reg = (descr->BTCTRL.reg & ~DMAC_BTCTRL_DSTINC) |
(incr << DMAC_BTCTRL_DSTINC_Pos); (incr << DMAC_BTCTRL_DSTINC_Pos);
_fmt_append(descr, next, (void *)descr->SRCADDR.reg, dst, len); _fmt_append(descr, next, (void *)descr->SRCADDR.reg, dst, num);
} }
void dma_start(dma_t dma) void dma_start(dma_t dma)