dma.h File Reference

G4 DMA Peripheral public API implementation. More...

#include <stdint.h>
#include "stm32g474xx.h"
#include "common/phal_G4/dma/dma_wiring.h"

Include dependency graph for dma.h:

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

Go to the source code of this file.

Classes
struct	PHAL_DMA_Params_t
	Per-transfer parameters (user can configure) More...
struct	PHAL_DMA_Callback_t
	A DMA channel interrupt callback and the context passed to it. More...
struct	PHAL_DMA_Handle_t
	A configured DMA transfer: fixed wiring + chosen parameters. More...

Typedefs
typedef void(*	PHAL_DMA_IRQCallbackFn_t) (void *ctx)
	Signature for a DMA channel interrupt callback.

Enumerations
enum	PHAL_DMA_Priority_t { DMA_PRIORITY_LOW = 0 , DMA_PRIORITY_MEDIUM = 1 , DMA_PRIORITY_HIGH = 2 , DMA_PRIORITY_VERY_HIGH = 3 }
	Relative priority when multiple DMA requests are pending at once. More...
enum	PHAL_DMA_Mode_t { DMA_MODE_NORMAL = 0 , DMA_MODE_CIRCULAR = 1 , DMA_MODE_MEM2MEM = 2 }
	What a channel does once its transfer count reaches zero. More...

Functions
bool	PHAL_DMA_init (PHAL_DMA_Handle_t *handle)
	Claim a DMA channel and configure it from handle->wiring and handle->params.
bool	PHAL_DMA_initWithCallback (PHAL_DMA_Handle_t *handle, PHAL_DMA_IRQCallbackFn_t irq_fn, void *ctx)
	Setup DMA callback then call PHAL_DMA_init()
void	PHAL_DMA_deinit (PHAL_DMA_Handle_t *handle)
	Disable the channel and release its claim/handle so another handle can use the periph/channel_idx afterward. Also disables the NVIC line if a callback was registered.
void	PHAL_DMA_start (PHAL_DMA_Handle_t *handle)
	Enable the channel, starting the transfer configured by PHAL_DMA_init()
void	PHAL_DMA_stop (PHAL_DMA_Handle_t *handle)
	Disable the channel, stopping the transfer immediately.
void	PHAL_DMA_restart (PHAL_DMA_Handle_t *handle)
	Reload the transfer count from handle->params.tx_size and start again.
bool	PHAL_DMA_setMemAddress (PHAL_DMA_Handle_t *handle, uint32_t address)
	Change the memory address for the next transfer.
bool	PHAL_DMA_setLength (PHAL_DMA_Handle_t *handle, uint16_t length)
	Change the transfer length (element count) for the next transfer.
void	PHAL_DMA_setMemInc (PHAL_DMA_Handle_t *handle, bool mem_inc)
	Set whether the memory address increments after each transfer and rebuild the channel configuration.
uint16_t	PHAL_DMA_getRemaining (PHAL_DMA_Handle_t *handle)
	Number of elements still left to transfer on this channel.
bool	PHAL_DMA_isBusy (const PHAL_DMA_Handle_t *handle)
	Check whether the channel is currently enabled (transfer in progress, or in circular mode, running continuously)
bool	PHAL_DMA_isComplete (const PHAL_DMA_Handle_t *handle)
	Check whether the channel has finished its transfer (TC flag set)
bool	PHAL_DMA_isError (const PHAL_DMA_Handle_t *handle)
	Check whether the channel reported a transfer error (TE flag set)
void	PHAL_DMA_clearFlags (PHAL_DMA_Handle_t *handle)
	Clear every latched status flag (complete/error/global) for the channel, so a finished transfer can be reused.
DMA_TypeDef *	PHAL_DMA_getPeriph (PHAL_DMA_Handle_t *handle)
	Get the DMA peripheral (DMA1 or DMA2) for a given handle.
uint8_t	PHAL_DMA_getChannelIdx (PHAL_DMA_Handle_t *handle)
	Get the channel number (1-8) for a given handle.

Detailed Description

G4 DMA Peripheral public API implementation.

Author

Shriya Balu (balu@.nosp@m.purd.nosp@m.ue.ed.nosp@m.u)

Millan Kumar (kumar.nosp@m.798@.nosp@m.purdu.nosp@m.e.ed.nosp@m.u)

Typedef Documentation

PHAL_DMA_IRQCallbackFn_t

typedef void(* PHAL_DMA_IRQCallbackFn_t) (void *ctx)

Signature for a DMA channel interrupt callback.

Invoked from the DMA PHAL's own ISR when the channel bound to this callback fires. Runs in interrupt context.

Parameters

ctx	Opaque pointer supplied to PHAL_DMA_initWithCallback(), passed back unexamined. Must remain valid for as long as the channel could still raise an interrupt referencing it.

Enumeration Type Documentation

PHAL_DMA_Mode_t

enum PHAL_DMA_Mode_t

What a channel does once its transfer count reaches zero.

Enumerator
DMA_MODE_NORMAL	Stops (call PHAL_DMA_restart() to re-run)
DMA_MODE_CIRCULAR	Automatically reload the count and restart
DMA_MODE_MEM2MEM	Copy memory-to-memory (no DMAMUX request involved)

PHAL_DMA_Priority_t

enum PHAL_DMA_Priority_t

Relative priority when multiple DMA requests are pending at once.

Enumerator
DMA_PRIORITY_LOW
DMA_PRIORITY_MEDIUM
DMA_PRIORITY_HIGH
DMA_PRIORITY_VERY_HIGH

Function Documentation

PHAL_DMA_clearFlags()

void PHAL_DMA_clearFlags

(

PHAL_DMA_Handle_t *

handle

)

Clear every latched status flag (complete/error/global) for the channel, so a finished transfer can be reused.

Parameters

handle

initialized DMA handle

Here is the call graph for this function:

Here is the caller graph for this function:

PHAL_DMA_deinit()

void PHAL_DMA_deinit

(

PHAL_DMA_Handle_t *

handle

)

Disable the channel and release its claim/handle so another handle can use the periph/channel_idx afterward. Also disables the NVIC line if a callback was registered.

Here is the call graph for this function:

PHAL_DMA_getChannelIdx()

uint8_t PHAL_DMA_getChannelIdx

(

PHAL_DMA_Handle_t *

handle

)

Get the channel number (1-8) for a given handle.

Returns

the channel number for the given handle

PHAL_DMA_getPeriph()

DMA_TypeDef * PHAL_DMA_getPeriph

(

PHAL_DMA_Handle_t *

handle

)

Get the DMA peripheral (DMA1 or DMA2) for a given handle.

Returns

the DMA peripheral for the given handle

PHAL_DMA_getRemaining()

uint16_t PHAL_DMA_getRemaining

(

PHAL_DMA_Handle_t *

handle

)

Number of elements still left to transfer on this channel.

Returns

Elements outstanding

Here is the call graph for this function:

Here is the caller graph for this function:

PHAL_DMA_init()

bool PHAL_DMA_init

(

PHAL_DMA_Handle_t *

handle

)

Claim a DMA channel and configure it from handle->wiring and handle->params.

Does not start the transfer (call PHAL_DMA_start() afterward).

Does not register an interrupt callback, handle->callback is left untouched (and should be zeroed).

Parameters

handle

wiring + params to configure. handle->channel is populated on success

Returns

true on success; false if handle/wiring invalid (NULL, channel_idx is outside 1-8, periph isn't DMA1/DMA2, or that periph/channel_idx is already claimed by another live handle)

Here is the call graph for this function:

Here is the caller graph for this function:

PHAL_DMA_initWithCallback()

bool PHAL_DMA_initWithCallback	(	PHAL_DMA_Handle_t *	handle,
		PHAL_DMA_IRQCallbackFn_t	irq_fn,
		void *	ctx )

Setup DMA callback then call PHAL_DMA_init()

Additional behavior: On success, handle->callback is set and this channel's NVIC line is enabled

Parameters

handle	wiring + params to configure. handle->channel and handle->callback are populated on success
irq_fn	callback to invoke when this channel's interrupt fires; must not be nullptr
ctx	opaque pointer passed to irq_fn unexamined. See PHAL_DMA_IRQCallbackFn_t for its lifetime requirement

Returns

true on success; false under the same conditions as PHAL_DMA_init(), or if irq_fn is nullptr

Here is the call graph for this function:

Here is the caller graph for this function:

PHAL_DMA_isBusy()

bool PHAL_DMA_isBusy

(

const PHAL_DMA_Handle_t *

handle

)

Check whether the channel is currently enabled (transfer in progress, or in circular mode, running continuously)

Returns

true if the channel is enabled, false if disabled

Here is the call graph for this function:

PHAL_DMA_isComplete()

bool PHAL_DMA_isComplete

(

const PHAL_DMA_Handle_t *

handle

)

Check whether the channel has finished its transfer (TC flag set)

A normal-mode channel clears EN and latches this flag on its own when the transfer count reaches zero, so this is the flag a blocking wrapper should busy-wait on.

Parameters

handle

initialized DMA handle

Returns

true if the transfer-complete flag is set, false otherwise

Here is the call graph for this function:

Here is the caller graph for this function:

PHAL_DMA_isError()

bool PHAL_DMA_isError

(

const PHAL_DMA_Handle_t *

handle

)

Check whether the channel reported a transfer error (TE flag set)

A bus error during the transfer latches this flag and stops the channel.

Parameters

handle

initialized DMA handle

Returns

true if the transfer-error flag is set, false otherwise

Here is the call graph for this function:

Here is the caller graph for this function:

PHAL_DMA_restart()

void PHAL_DMA_restart

(

PHAL_DMA_Handle_t *

handle

)

Reload the transfer count from handle->params.tx_size and start again.

Safe to call regardless of whether the channel state (enabled, mid-transfer, or stopped on an error), it always disables first.

Here is the call graph for this function:

Here is the caller graph for this function:

PHAL_DMA_setLength()

bool PHAL_DMA_setLength	(	PHAL_DMA_Handle_t *	handle,
		uint16_t	length )

Change the transfer length (element count) for the next transfer.

Returns

true on success, false if the channel is currently enabled

Here is the call graph for this function:

Here is the caller graph for this function:

PHAL_DMA_setMemAddress()

bool PHAL_DMA_setMemAddress	(	PHAL_DMA_Handle_t *	handle,
		uint32_t	address )

Change the memory address for the next transfer.

Returns

true on success, false if the channel is currently enabled

Here is the call graph for this function:

PHAL_DMA_setMemInc()

void PHAL_DMA_setMemInc	(	PHAL_DMA_Handle_t *	handle,
		bool	mem_inc )

Set whether the memory address increments after each transfer and rebuild the channel configuration.

If the channel is currently enabled, this function will not change the configuration

Parameters

mem_inc

true to increment memory address after each transfer, false to keep it constant

Here is the call graph for this function:

Here is the caller graph for this function:

PHAL_DMA_start()

void PHAL_DMA_start

(

PHAL_DMA_Handle_t *

handle

)

Enable the channel, starting the transfer configured by PHAL_DMA_init()

Here is the call graph for this function:

PHAL_DMA_stop()

void PHAL_DMA_stop

(

PHAL_DMA_Handle_t *

handle

)

Disable the channel, stopping the transfer immediately.

Whatever hasn't transferred yet is left un-transferred

Here is the call graph for this function:

Here is the caller graph for this function: