File syn_dma.h¶

FileList > drivers > syn_dma.h

Bare-Metal Safe DMA Transaction Engine. More...

#include "../common/syn_defs.h"
#include "../port/syn_port_dma.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Classes¶

Type	Name
struct	SYN_DMA DMA Channel instance object.
struct	SYN_DMA_Config Configuration parameters for a DMA channel.
struct	SYN_DMA_RingBuf Continuous circular DMA reception stream controller.

Public Types¶

Type	Name
typedef void(*	SYN_DMA_Callback Callback for DMA transfer events.
enum	SYN_DMA_Event DMA ISR event flags.
enum	SYN_DMA_State DMA channel execution state.

Public Functions¶

Type	Name
SYN_DMA_State	syn_dma_get_state (const SYN_DMA * dma) Get current state of DMA channel.
SYN_Status	syn_dma_init (SYN_DMA * dma, const SYN_DMA_Config * cfg) Initialize a DMA channel object.
void	syn_dma_isr_handler (SYN_DMA * dma, SYN_DMA_Event event) Hardware ISR event handler entry point.
size_t	syn_dma_ringbuf_bytes_available (const SYN_DMA_RingBuf * r) Get total bytes available to read from the circular DMA stream.
SYN_Status	syn_dma_ringbuf_init (SYN_DMA_RingBuf * r, SYN_DMA * dma, uint8_t * buf, size_t capacity) Initialize a circular DMA ring buffer receiver.
size_t	syn_dma_ringbuf_read (SYN_DMA_RingBuf * r, uint8_t * dest, size_t len) Read bytes from the circular DMA reception buffer into destination.
SYN_Status	syn_dma_ringbuf_start (SYN_DMA_RingBuf * r, const void * periph_src) Start continuous circular DMA stream reception.
SYN_Status	syn_dma_start (SYN_DMA * dma, const void * src, void * dst, size_t count) Submit and trigger a DMA transfer.
SYN_Status	syn_dma_stop (SYN_DMA * dma) Stop/abort an active DMA transfer.

Detailed Description¶

Provides safe DMA transaction submission with memory alignment verification, data cache maintenance, re-entrancy locking, and ISR event callbacks.

Public Types Documentation¶

typedef SYN_DMA_Callback¶

Callback for DMA transfer events.

typedef void(* SYN_DMA_Callback) (struct SYN_DMA *dma, SYN_DMA_Event event, void *user_ctx);

enum SYN_DMA_Event¶

DMA ISR event flags.

enum SYN_DMA_Event {
    SYN_DMA_EVENT_HALF_COMPLETE = 0x01,
    SYN_DMA_EVENT_COMPLETE = 0x02,
    SYN_DMA_EVENT_ERROR = 0x04
};

enum SYN_DMA_State¶

DMA channel execution state.

enum SYN_DMA_State {
    SYN_DMA_STATE_IDLE = 0,
    SYN_DMA_STATE_BUSY = 1,
    SYN_DMA_STATE_COMPLETE = 2,
    SYN_DMA_STATE_ERROR = 3
};

Public Functions Documentation¶

function syn_dma_get_state¶

Get current state of DMA channel.

SYN_DMA_State syn_dma_get_state (
    const SYN_DMA * dma
)

Parameters:

dma Pointer to DMA channel.

Returns:

Current SYN_DMA_State.

function syn_dma_init¶

Initialize a DMA channel object.

SYN_Status syn_dma_init (
    SYN_DMA * dma,
    const SYN_DMA_Config * cfg
)

Parameters:

dma Pointer to DMA instance.
cfg Configuration structure.

Returns:

SYN_OK on success, or SYN_INVALID_PARAM if dma/cfg is NULL.

function syn_dma_isr_handler¶

Hardware ISR event handler entry point.

void syn_dma_isr_handler (
    SYN_DMA * dma,
    SYN_DMA_Event event
)

Call this function from the MCU hardware DMA interrupt handler when a channel fires a half-transfer, complete, or error interrupt.

Parameters:

dma Pointer to DMA channel.
event Event bitmask (SYN_DMA_EVENT_*).

function syn_dma_ringbuf_bytes_available¶

Get total bytes available to read from the circular DMA stream.

size_t syn_dma_ringbuf_bytes_available (
    const SYN_DMA_RingBuf * r
)

Parameters:

r Ring buffer instance.

Returns:

Number of unread bytes.

function syn_dma_ringbuf_init¶

Initialize a circular DMA ring buffer receiver.

SYN_Status syn_dma_ringbuf_init (
    SYN_DMA_RingBuf * r,
    SYN_DMA * dma,
    uint8_t * buf,
    size_t capacity
)

Parameters:

r Ring buffer instance.
dma Initialized DMA channel instance.
buf Reception buffer (aligned to dma data size).
capacity Buffer capacity in bytes.

Returns:

SYN_OK on success.

function syn_dma_ringbuf_read¶

Read bytes from the circular DMA reception buffer into destination.

size_t syn_dma_ringbuf_read (
    SYN_DMA_RingBuf * r,
    uint8_t * dest,
    size_t len
)

Parameters:

r Ring buffer instance.
dest Output data buffer.
len Maximum bytes to read.

Returns:

Actual bytes read.

function syn_dma_ringbuf_start¶

Start continuous circular DMA stream reception.

SYN_Status syn_dma_ringbuf_start (
    SYN_DMA_RingBuf * r,
    const void * periph_src
)

Parameters:

r Ring buffer instance.
periph_src Peripheral data register source address.

Returns:

SYN_OK on success.

function syn_dma_start¶

Submit and trigger a DMA transfer.

SYN_Status syn_dma_start (
    SYN_DMA * dma,
    const void * src,
    void * dst,
    size_t count
)

Verifies address alignment against data element size (8/16/32-bit), cleans D-cache for source region, invalidates D-cache for destination region, and launches hardware transfer.

Parameters:

dma Pointer to initialized DMA channel instance.
src Source buffer address.
dst Destination buffer address.
count Number of elements to transfer (must be > 0).

Returns:

SYN_OK on success.

Returns:

SYN_INVALID_PARAM if buffer address is unaligned to data_size or parameters invalid.

Returns:

SYN_BUSY if channel is actively transferring.

function syn_dma_stop¶

Stop/abort an active DMA transfer.

SYN_Status syn_dma_stop (
    SYN_DMA * dma
)

Parameters:

dma Pointer to DMA channel.

Returns:

SYN_OK on success.

The documentation for this class was generated from the following file src/syntropic/drivers/syn_dma.h