STM32 DMA subsystem driver header. More...

#include <ch.h>
#include <hal.h>

Include dependency graph for hal_stm32_dma.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	DMAConfig
	DMA stream configuration structure. More...

struct	DMADriver
	Structure representing a DMA driver. More...

Macros
#define	STM32_DMA_USE_WAIT TRUE
	Enables synchronous APIs. More...

#define	STM32_DMA_USE_MUTUAL_EXCLUSION FALSE
	Enables the `dmaAcquireBus()` and `dmaReleaseBus()` APIs. More...

#define	STM32_DMA_SUPPORTS_CSELR FALSE

Typedefs
typedef struct DMADriver	DMADriver
	Type of a structure representing an DMA driver. More...

typedef void(*	dmacallback_t) (DMADriver dmap, void buffer, const size_t n)
	DMA notification callback type. More...

typedef void(*	dmaerrorcallback_t) (DMADriver *dmap, dmaerrormask_t err)
	DMA error callback type. More...

Enumerations
enum	dmastate_t { DMA_UNINIT = 0, DMA_STOP = 1, DMA_READY = 2, DMA_ACTIVE = 3, DMA_COMPLETE = 4, DMA_ERROR = 5 }
	Driver state machine possible states. More...

enum	dmaerrormask_t { DMA_ERR_TRANSFER_ERROR = 1U << 0U, DMA_ERR_DIRECTMODE_ERROR = 1U << 1U, DMA_ERR_FIFO_ERROR = 1U << 2U, DMA_ERR_FIFO_FULL = 1U << 3U, DMA_ERR_FIFO_EMPTY = 1U << 4U }
	Possible DMA failure causes. More...

enum	dmadirection_t { DMA_DIR_P2M = 1, DMA_DIR_M2P = 2, DMA_DIR_M2M = 3 }
	DMA transfert direction. More...

Low level driver helper macros
#define	_dma_reset_i(dmap) osalThreadResumeI(&(dmap)->thread, MSG_RESET)
	Resumes a thread waiting for a dma transfert completion. More...

#define	_dma_reset_s(dmap) osalThreadResumeS(&(dmap)->thread, MSG_RESET)
	Resumes a thread waiting for a dma transfert completion. More...

#define	_dma_wakeup_isr(dmap)
	Wakes up the waiting thread. More...

#define	_dma_timeout_isr(dmap)
	Wakes up the waiting thread with a timeout message. More...

static void	_dma_isr_half_code (DMADriver *dmap)
	Common ISR code, half buffer event. More...

static void	_dma_isr_full_code (DMADriver *dmap)
	Common ISR code, full buffer event. More...

static void	_dma_isr_error_code (DMADriver *dmap, dmaerrormask_t err)
	Common ISR code, error event. More...

void	dmaObjectInit (DMADriver *dmap)

bool	dmaStart (DMADriver dmap, const DMAConfig cfg)
	Configures and activates the DMA peripheral. More...

void	dmaStop (DMADriver *dmap)
	Deactivates the DMA peripheral. More...

msg_t	dmaTransfertTimeout (DMADriver dmap, volatile void periphp, void *mem0p, const size_t size, sysinterval_t timeout)
	Performs a DMA transaction. More...

static msg_t	dmaTransfert (DMADriver dmap, volatile void periphp, void *mem0p, const size_t size)

void	dmaAcquireBus (DMADriver *dmap)
	Gains exclusive access to the DMA peripheral. More...

void	dmaReleaseBus (DMADriver *dmap)
	Releases exclusive access to the DMA peripheral. More...

bool	dmaStartTransfert (DMADriver dmap, volatile void periphp, void *mem0p, const size_t size)
	Starts a DMA transaction. More...

void	dmaStopTransfert (DMADriver *dmap)
	Stops an ongoing transaction. More...

bool	dmaStartTransfertI (DMADriver dmap, volatile void periphp, void *mem0p, const size_t size)
	Starts a DMA transaction. More...

void	dmaStopTransfertI (DMADriver *dmap)
	Stops an ongoing transaction. More...

static dmastate_t	dmaGetState (DMADriver *dmap)

bool	dma_lld_start (DMADriver *dmap)
	Configures and activates the DMA peripheral. More...

void	dma_lld_stop (DMADriver *dmap)
	Deactivates the DMA peripheral. More...

bool	dma_lld_start_transfert (DMADriver dmap, volatile void periphp, void *mem0p, const size_t size)
	Starts a DMA transaction. More...

void	dma_lld_stop_transfert (DMADriver *dmap)
	Stops an ongoing transaction. More...

Detailed Description

STM32 DMA subsystem driver header.

Author: Alexandre Bustico @maintainer Gautier Hattenberger gauti.nosp@m.er.h.nosp@m.atten.nosp@m.berg.nosp@m.er@en.nosp@m.ac.f.nosp@m.r

Definition in file hal_stm32_dma.h.

Data Structure Documentation

◆ DMAConfig

struct DMAConfig

DMA stream configuration structure.

This implementation-dependent structure describes a DMA operation.

Note: The use of this configuration structure requires knowledge of STM32 DMA registers interface, please refer to the STM32 reference manual for details.

Definition at line 241 of file hal_stm32_dma.h.

Collaboration diagram for DMAConfig:

Data Fields
bool	circular	Enables the circular buffer mode for the stream.
dmadirection_t	direction	DMA transaction direction.
uint8_t	dma_priority	DMA priority (1 . . 4)
dmacallback_t	end_cb	Callback function associated to the stream or `NULL`.
dmaerrorcallback_t	error_cb	Error callback or `NULL`.
bool	inc_memory_addr	Enable increment of memory address after each transfert.
bool	inc_peripheral_addr	Enable increment of peripheral address after each transfert.
uint8_t	irq_priority	DMA IRQ priority (2 . . 7)
uint8_t	msize	DMA memory data granurality in bytes (1,2,4)
uint8_t	psize	DMA peripheral data granurality in bytes (1,2,4)
uint32_t	stream	stream associated with transaction Note use STM32_DMA_STREAM_ID macro

◆ DMADriver

struct DMADriver

Structure representing a DMA driver.

Definition at line 365 of file hal_stm32_dma.h.

Collaboration diagram for DMADriver:

Data Fields
const DMAConfig *	config	Current configuration data.
uint8_t	controller	controller associated with stream
uint32_t	dmamode	hold DMA CR register for the stream
const stm32_dma_stream_t *	dmastream	DMA stream associated with peripheral or memory.
void *	mem0p	memory address Note for now, only half buffer with one memory pointer is managed mem1p not yet interfaced
size_t	size	hold size of current transaction
volatile dmastate_t	state	Driver state.

Macro Definition Documentation

◆ _dma_reset_i

#define _dma_reset_i ( dmap ) osalThreadResumeI(&(dmap)->thread, MSG_RESET)

Resumes a thread waiting for a dma transfert completion.

Parameters

[in] dmap pointer to the DMADriver object

@notapi

Definition at line 136 of file hal_stm32_dma.h.

◆ _dma_reset_s

#define _dma_reset_s ( dmap ) osalThreadResumeS(&(dmap)->thread, MSG_RESET)

Resumes a thread waiting for a dma transfert completion.

Parameters

[in] dmap pointer to the DMADriver object

@notapi

Definition at line 146 of file hal_stm32_dma.h.

◆ _dma_timeout_isr

#define _dma_timeout_isr ( dmap )

Value:

    {                                            \
    osalSysLockFromISR();                                                     \
    osalThreadResumeI(&(dmap)->thread, MSG_TIMEOUT);                          \
    osalSysUnlockFromISR();                                                   \
  }

Wakes up the waiting thread with a timeout message.

Parameters

[in] dmap pointer to the DMADriver object

@notapi

Definition at line 169 of file hal_stm32_dma.h.

◆ _dma_wakeup_isr

#define _dma_wakeup_isr ( dmap )

Value:

    {                                             \
    osalSysLockFromISR();                                                     \
    osalThreadResumeI(&(dmap)->thread, MSG_OK);                               \
    osalSysUnlockFromISR();                                                   \
  }

Wakes up the waiting thread.

Parameters

[in] dmap pointer to the DMADriver object

@notapi

Definition at line 156 of file hal_stm32_dma.h.

◆ STM32_DMA_SUPPORTS_CSELR

#define STM32_DMA_SUPPORTS_CSELR FALSE

Definition at line 55 of file hal_stm32_dma.h.

◆ STM32_DMA_USE_MUTUAL_EXCLUSION

#define STM32_DMA_USE_MUTUAL_EXCLUSION FALSE

Enables the dmaAcquireBus() and dmaReleaseBus() APIs.

Note: Disabling this option saves both code and data space.

Definition at line 51 of file hal_stm32_dma.h.

◆ STM32_DMA_USE_WAIT

#define STM32_DMA_USE_WAIT TRUE

Enables synchronous APIs.

Note: Disabling this option saves both code and data space.

Definition at line 43 of file hal_stm32_dma.h.

Typedef Documentation

◆ dmacallback_t

typedef void(* dmacallback_t) (DMADriver *dmap, void *buffer, const size_t n)

DMA notification callback type.

Parameters

[in]	dmap	pointer to the `DMADriver` object triggering the callback
[in]	buffer	pointer to the most recent samples data
[in]	n	number of buffer rows available starting from `buffer`

Definition at line 106 of file hal_stm32_dma.h.

◆ DMADriver

typedef struct DMADriver DMADriver

Type of a structure representing an DMA driver.

Definition at line 96 of file hal_stm32_dma.h.

◆ dmaerrorcallback_t

typedef void(* dmaerrorcallback_t) (DMADriver *dmap, dmaerrormask_t err)

DMA error callback type.

Parameters

[in]	dmap	pointer to the `DMADriver` object triggering the callback
[in]	err	DMA error code

Definition at line 116 of file hal_stm32_dma.h.

Enumeration Type Documentation

◆ dmadirection_t

enum dmadirection_t

DMA transfert direction.

Enumerator
DMA_DIR_P2M	PERIPHERAL to MEMORY
DMA_DIR_M2P	MEMORY to PERIPHERAL
DMA_DIR_M2M	MEMORY to MEMORY

Definition at line 87 of file hal_stm32_dma.h.

◆ dmaerrormask_t

enum dmaerrormask_t

Possible DMA failure causes.

Note: Error codes are architecture dependent and should not relied upon.

Enumerator
DMA_ERR_TRANSFER_ERROR	DMA transfer failure.
DMA_ERR_DIRECTMODE_ERROR	DMA Direct Mode failure.
DMA_ERR_FIFO_ERROR	DMA FIFO error.
DMA_ERR_FIFO_FULL	DMA FIFO overrun.
DMA_ERR_FIFO_EMPTY	DMA FIFO underrun.

Definition at line 76 of file hal_stm32_dma.h.

◆ dmastate_t

enum dmastate_t

Driver state machine possible states.

Enumerator
DMA_UNINIT	Not initialized.
DMA_STOP	Stopped.
DMA_READY	Ready.
DMA_ACTIVE	Transfering.
DMA_COMPLETE	Transfert complete.
DMA_ERROR	Transfert error.

Definition at line 62 of file hal_stm32_dma.h.

Function Documentation

◆ _dma_isr_error_code()

static void _dma_isr_error_code	(	DMADriver *	dmap,
		dmaerrormask_t	err
	)

inlinestatic

Common ISR code, error event.

This code handles the portable part of the ISR code:

Callback invocation.
Waiting thread timeout signaling, if any.
Driver state transitions.

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in]	adcp	pointer to the `ADCDriver` object
[in]	err	platform dependent error code

@notapi

Definition at line 611 of file hal_stm32_dma.h.

References _dma_timeout_isr, DMADriver::config, DMA_ERR_DIRECTMODE_ERROR, DMA_ERR_FIFO_EMPTY, DMA_ERR_FIFO_ERROR, DMA_ERR_FIFO_FULL, DMA_ERR_TRANSFER_ERROR, DMA_ERROR, dma_lld_stop_transfert(), DMA_READY, DMAConfig::error_cb, and DMADriver::state.

Referenced by dma_lld_serve_interrupt().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _dma_isr_full_code()

static void _dma_isr_full_code ( DMADriver * dmap )

inlinestatic

Common ISR code, full buffer event.

This code handles the portable part of the ISR code:

Callback invocation.
Waiting thread wakeup, if any.
Driver state transitions.

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in] adcp pointer to the ADCDriver object

@notapi

Definition at line 557 of file hal_stm32_dma.h.

References _dma_wakeup_isr, DMAConfig::circular, DMADriver::config, DMA_COMPLETE, dma_lld_stop_transfert(), DMA_READY, DMAConfig::end_cb, DMADriver::mem0p, DMAConfig::msize, DMADriver::size, and DMADriver::state.

Referenced by dma_lld_serve_interrupt().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _dma_isr_half_code()

static void _dma_isr_half_code ( DMADriver * dmap )

inlinestatic

Common ISR code, half buffer event.

This code handles the portable part of the ISR code:

Callback invocation.

Note: This macro is meant to be used in the low level drivers implementation only.

Parameters

[in] adcp pointer to the ADCDriver object

@notapi

Definition at line 540 of file hal_stm32_dma.h.

References DMADriver::config, DMAConfig::end_cb, DMADriver::mem0p, and DMADriver::size.

Referenced by dma_lld_serve_interrupt().

Here is the caller graph for this function:

◆ dma_lld_start()

bool dma_lld_start ( DMADriver * dmap )

Configures and activates the DMA peripheral.

Parameters

[in] dmap pointer to the DMADriver object

@notapi

Definition at line 409 of file hal_stm32_dma.c.

References DMAConfig::circular, DMADriver::config, DMADriver::controller, DMAConfig::direction, DMA_DIR_M2M, DMA_DIR_M2P, DMA_DIR_P2M, dma_lld_serve_interrupt(), DMAConfig::dma_priority, DMADriver::dmamode, DMADriver::dmastream, DMAConfig::end_cb, DMAConfig::error_cb, DMAConfig::inc_memory_addr, DMAConfig::inc_peripheral_addr, DMAConfig::irq_priority, DMAConfig::msize, DMAConfig::psize, STM32_DMA_SUPPORTS_CSELR, and DMAConfig::stream.

Referenced by dmaStart().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dma_lld_start_transfert()

bool dma_lld_start_transfert	(	DMADriver *	dmap,
		volatile void *	periphp,
		void *	mem0p,
		const size_t	size
	)

Starts a DMA transaction.

Parameters

[in] dmap pointer to the DMADriver object

@notapi

Definition at line 691 of file hal_stm32_dma.c.

References DMADriver::config, DMAConfig::direction, DMA_DIR_P2M, DMADriver::dmamode, DMADriver::dmastream, DMADriver::mem0p, DMAConfig::msize, and DMADriver::size.

Referenced by dmaStartTransfertI().

Here is the caller graph for this function:

◆ dma_lld_stop()

void dma_lld_stop ( DMADriver * dmap )

Deactivates the DMA peripheral.

Parameters

[in] dmap pointer to the DMADriver object

@notapi

Definition at line 735 of file hal_stm32_dma.c.

References DMADriver::dmastream.

Referenced by dmaStop().

Here is the caller graph for this function:

◆ dma_lld_stop_transfert()

void dma_lld_stop_transfert ( DMADriver * dmap )

Stops an ongoing transaction.

Parameters

[in] dmap pointer to the DMADriver object

@notapi

Definition at line 723 of file hal_stm32_dma.c.

References DMADriver::dmastream.

Referenced by _dma_isr_error_code(), _dma_isr_full_code(), dmaStopTransfert(), and dmaStopTransfertI().

Here is the caller graph for this function:

◆ dmaAcquireBus()

void dmaAcquireBus ( DMADriver * dmap )

Gains exclusive access to the DMA peripheral.

This function tries to gain ownership to the DMA bus, if the bus is already being used then the invoking thread is queued.

Precondition: In order to use this function the option DMA_USE_MUTUAL_EXCLUSION must be enabled.

Parameters

[in] dmap pointer to the DMADriver object

@api

Definition at line 358 of file hal_stm32_dma.c.

◆ dmaGetState()

static dmastate_t dmaGetState ( DMADriver * dmap )

inlinestatic

Definition at line 475 of file hal_stm32_dma.h.

References DMADriver::state.

◆ dmaObjectInit()

void dmaObjectInit ( DMADriver * dmap )

Definition at line 56 of file hal_stm32_dma.c.

References DMADriver::config, DMA_STOP, DMADriver::mem0p, and DMADriver::state.

Referenced by dshotStart(), and light_ws2812_arch_init().

Here is the caller graph for this function:

◆ dmaReleaseBus()

void dmaReleaseBus ( DMADriver * dmap )

Releases exclusive access to the DMA peripheral.

Precondition: In order to use this function the option DMA_USE_MUTUAL_EXCLUSION must be enabled.

Parameters

[in] dmap pointer to the DMADriver object

@api

Definition at line 375 of file hal_stm32_dma.c.

◆ dmaStart()

bool dmaStart	(	DMADriver *	dmap,
		const DMAConfig *	cfg
	)

Configures and activates the DMA peripheral.

Parameters

[in]	dmap	pointer to the `DMADriver` object
[in]	config	pointer to the `DMAConfig` object.

Returns: The operation result.

Return values

true	dma driver is OK
false	incoherencies has been found in config @api

Definition at line 92 of file hal_stm32_dma.c.

References DMADriver::config, dma_lld_start(), DMA_READY, DMA_STOP, and DMADriver::state.

Referenced by dshotStart(), and light_ws2812_arch_init().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dmaStartTransfert()

bool dmaStartTransfert	(	DMADriver *	dmap,
		volatile void *	periphp,
		void *	mem0p,
		const size_t	size
	)

Starts a DMA transaction.

Starts one or many asynchronous dma transaction(s) depending on continuous field

Postcondition: The callbacks associated to the DMA config will be invoked on buffer fill and error events, and timeout events in case STM32_DMA_USE_ASYNC_TIMOUT == TRUE

Note: The datas are sequentially written into the buffer with no gaps.

Parameters

[in]	dmap	pointer to the `DMADriver` object
[in,out]	periphp	pointer to a `peripheral` register address
[in,out]	mem0p	pointer to the data buffer
[in]	size	buffer size. The buffer size must be one or an even number.

@api

Definition at line 149 of file hal_stm32_dma.c.

References dmaStartTransfertI().

Referenced by dshotSendFrame(), and light_ws2812_arch_init().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dmaStartTransfertI()

bool dmaStartTransfertI	(	DMADriver *	dmap,
		volatile void *	periphp,
		void *	mem0p,
		const size_t	size
	)

Starts a DMA transaction.

Starts one or many asynchronous dma transaction(s) depending on continuous field

Postcondition: The callbacks associated to the DMA config will be invoked on buffer fill and error events, and timeout events in case STM32_DMA_USE_ASYNC_TIMOUT == TRUE

Note: The datas are sequentially written into the buffer with no gaps.

Parameters

[in]	dmap	pointer to the `DMADriver` object
[in,out]	periphp	pointer to a `peripheral` register address
[in,out]	mem0p	pointer to the data buffer
[in]	size	buffer size. The buffer size must be one or an even number.

@iclass

Definition at line 174 of file hal_stm32_dma.c.

References DMADriver::config, DMA_ACTIVE, DMA_COMPLETE, DMA_ERROR, dma_lld_start_transfert(), DMA_READY, DMAConfig::msize, DMAConfig::psize, DMADriver::size, and DMADriver::state.

Referenced by dmaStartTransfert(), and dmaTransfertTimeout().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dmaStop()

void dmaStop ( DMADriver * dmap )

Deactivates the DMA peripheral.

Parameters

[in] dmap pointer to the DMADriver object

@api

Definition at line 114 of file hal_stm32_dma.c.

References DMADriver::config, dma_lld_stop(), DMA_READY, DMA_STOP, DMADriver::mem0p, and DMADriver::state.

Here is the call graph for this function:

◆ dmaStopTransfert()

void dmaStopTransfert ( DMADriver * dmap )

Stops an ongoing transaction.

This function stops the currently ongoing transaction and returns the driver in the DMA_READY state. If there was no transaction being processed then the function does nothing.

Parameters

[in] dmap pointer to the DMADriver object

@api

Definition at line 257 of file hal_stm32_dma.c.

References _dma_reset_s, DMA_ACTIVE, dma_lld_stop_transfert(), DMA_READY, and DMADriver::state.

Here is the call graph for this function:

◆ dmaStopTransfertI()

void dmaStopTransfertI ( DMADriver * dmap )

Stops an ongoing transaction.

This function stops the currently ongoing transaction and returns the driver in the DMA_READY state. If there was no transaction being processed then the function does nothing.

Parameters

[in] dmap pointer to the DMADriver object

@iclass

Definition at line 285 of file hal_stm32_dma.c.

References _dma_reset_i, DMA_ACTIVE, DMA_COMPLETE, dma_lld_stop_transfert(), DMA_READY, and DMADriver::state.

Referenced by dmaTransfertTimeout().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dmaTransfert()

static msg_t dmaTransfert	(	DMADriver *	dmap,
		volatile void *	periphp,
		void *	mem0p,
		const size_t	size
	)

inlinestatic

Definition at line 460 of file hal_stm32_dma.h.

References dmaTransfertTimeout().

Here is the call graph for this function:

◆ dmaTransfertTimeout()

msg_t dmaTransfertTimeout	(	DMADriver *	dmap,
		volatile void *	periphp,
		void *	mem0p,
		const size_t	size,
		sysinterval_t	timeout
	)

Performs a DMA transaction.

Performs one synchronous dma transaction

Note: The datas are sequentially written into the buffer with no gaps.

Parameters

[in]	dmap	pointer to the `DMADriver` object
[in,out]	periphp	pointer to a `peripheral` register address
[in,out]	mem0p	pointer to the data buffer
[in]	size	buffer size. The buffer size must be one or an even number.
[in]	timeout	function will exit after timeout is transaction is not done can be TIME_INFINITE (but not TIME_IMMEDIATE)

Returns: The operation result.

Return values

MSG_OK	Transaction finished.
MSG_RESET	The transaction has been stopped using `dmaStopTransaction()` or `dmaStopTransactionI()`, the result buffer may contain incorrect data.
MSG_TIMEOUT	The transaction has been stopped because of hardware error or timeout limit reach

@api

Definition at line 328 of file hal_stm32_dma.c.

References DMAConfig::circular, DMADriver::config, dmaStartTransfertI(), dmaStopTransfertI(), msg, and timeout.

Referenced by dmaTransfert().

Here is the call graph for this function:

Here is the caller graph for this function:

Data Structures

Macros

Typedefs

Enumerations

Low level driver helper macros

Detailed Description

Data Structure Documentation

◆ DMAConfig

◆ DMADriver

Macro Definition Documentation

◆ _dma_reset_i

◆ _dma_reset_s

◆ _dma_timeout_isr

◆ _dma_wakeup_isr

◆ STM32_DMA_SUPPORTS_CSELR

◆ STM32_DMA_USE_MUTUAL_EXCLUSION

◆ STM32_DMA_USE_WAIT

Typedef Documentation

◆ dmacallback_t

◆ DMADriver

◆ dmaerrorcallback_t

Enumeration Type Documentation

◆ dmadirection_t

◆ dmaerrormask_t

◆ dmastate_t

Function Documentation

◆ _dma_isr_error_code()

◆ _dma_isr_full_code()

◆ _dma_isr_half_code()

◆ dma_lld_start()

◆ dma_lld_start_transfert()

◆ dma_lld_stop()

◆ dma_lld_stop_transfert()

◆ dmaAcquireBus()

◆ dmaGetState()

◆ dmaObjectInit()

◆ dmaReleaseBus()

◆ dmaStart()

◆ dmaStartTransfert()

◆ dmaStartTransfertI()

◆ dmaStop()

◆ dmaStopTransfert()

◆ dmaStopTransfertI()

◆ dmaTransfert()

◆ dmaTransfertTimeout()