gossamer 0.0.1
a very lightweight app framework for SAMD and SAML chips
Loading...
Searching...
No Matches
Direct Memory Access Controller

WIP functions for configuring and using the Direct Memory Access controller. More...

Data Structures

struct  gossamer_dma_job_t
 

Functions

void dma_init (void)
 Initializes the DMA system (clocks, descriptor memory, interrupts), but does not enable it.
 
void dma_enable (void)
 Enables the DMA controller.
 
void dma_disable (void)
 Disables the DMA controller.
 
bool dma_configure (gossamer_dma_job_t *dmaJob, uint8_t peripheralTrigger, dma_trigger_action_t triggerAction, dma_configuration_flags_t flags)
 Allocates a DMA channel and configures a job.
 
void dma_set_priority (gossamer_dma_job_t *dmaJob, dma_priority_t priority)
 Sets the priority level for a DMA channel.
 
DmacDescriptor * dma_add_descriptor (gossamer_dma_job_t *dmaJob, void *src, void *dst, uint32_t count)
 Adds a transfer descriptor to a DMA job.
 
bool dma_start_job (gossamer_dma_job_t *dmaJob)
 Starts a configured DMA job.
 
void dma_stop_job (gossamer_dma_job_t *dmaJob)
 Stops a running DMA job and aborts the transfer.
 
void dma_suspend_job (gossamer_dma_job_t *dmaJob)
 Suspends a running DMA job.
 
void dma_resume_job (gossamer_dma_job_t *dmaJob)
 Resumes a suspended DMA job.
 
void dma_trigger (gossamer_dma_job_t *dmaJob)
 Issues a software trigger to a DMA channel.
 
void dma_set_event_input (gossamer_dma_job_t *dmaJob, dma_event_input_action_t action)
 Configures event input action for a DMA channel.
 
void dma_set_event_output (gossamer_dma_job_t *dmaJob, bool enabled)
 Enables or disables event output for a DMA channel.
 

Detailed Description

WIP functions for configuring and using the Direct Memory Access controller.

Function Documentation

◆ dma_add_descriptor()

DmacDescriptor * dma_add_descriptor ( gossamer_dma_job_t * dmaJob,
void * src,
void * dst,
uint32_t count )

Adds a transfer descriptor to a DMA job.

Creates a DMA descriptor using the beat size, address increment, and step size fields on the job struct (set these before calling). The first descriptor is stored in the channel's static descriptor table; subsequent descriptors are heap-allocated and linked automatically.

Parameters
dmaJobPointer to a configured DMA job.
srcSource address. When source incrementing is enabled, this must point one past the end of the source buffer (e.g. buf + count for byte-sized beats). This matches the hardware SRCADDR convention; the DMA controller calculates the start address internally.
dstDestination address. Same end-address convention applies when destination incrementing is enabled.
countNumber of beats to transfer.
Returns
Pointer to the DMA descriptor, or NULL if the job is busy or no channel is allocated. You can use this pointer to modify the descriptor at runtime (e.g. swapping SRCADDR in an interrupt handler).
Note
When modifying SRCADDR or DSTADDR directly on the returned descriptor, use the same end-address convention: the address must point one past the last beat of the buffer.

◆ dma_configure()

bool dma_configure ( gossamer_dma_job_t * dmaJob,
uint8_t peripheralTrigger,
dma_trigger_action_t triggerAction,
dma_configuration_flags_t flags )

Allocates a DMA channel and configures a job.

Call this first when setting up a DMA transfer. It allocates the next available channel, configures the peripheral trigger and trigger action, and sets default values for the job's descriptor settings (byte beats, no address increment, step size 1). After configuring, set fields on the job struct directly (e.g. beatSize, addressIncrement) before calling dma_add_descriptor() to create the transfer descriptor.

Parameters
dmaJobPointer to a gossamer_dma_job_t struct that will hold the job state.
peripheralTriggerThe peripheral trigger source (e.g. DAC_DMAC_ID_EMPTY). Use 0 for software-triggered transfers.
triggerActionWhether a trigger starts a beat, block, or full transaction transfer.
flagsConfiguration flags: DMA_CONFIG_LOOP to loop the descriptor list, DMA_CONFIG_RUNSTDBY to keep the channel active in standby (L21/L22/D51 only).
Returns
true if a channel was allocated, false if all channels are in use.
Note
SAM D51 erratum DS80000748F §2.10.1: when linked descriptors are in use, a newly enabled channel's number must be GREATER than any already-active channel's, or descriptor fetch errors can occur. gossamer allocates channels in ascending order, so configuring jobs in the order you start them satisfies this. §2.10.2: mixing channel priority levels can stall the highest-priority channel; leave all channels at the default priority unless you've read the erratum.

◆ dma_resume_job()

void dma_resume_job ( gossamer_dma_job_t * dmaJob)

Resumes a suspended DMA job.

Parameters
dmaJobPointer to a configured DMA job.

◆ dma_set_event_input()

void dma_set_event_input ( gossamer_dma_job_t * dmaJob,
dma_event_input_action_t action )

Configures event input action for a DMA channel.

Parameters
dmaJobPointer to a configured DMA job.
actionThe action to take on an incoming event. DMA_EVENT_INPUT_NOACT disables event input.

◆ dma_set_event_output()

void dma_set_event_output ( gossamer_dma_job_t * dmaJob,
bool enabled )

Enables or disables event output for a DMA channel.

Parameters
dmaJobPointer to a configured DMA job.
enabledtrue to enable event output, false to disable.

◆ dma_set_priority()

void dma_set_priority ( gossamer_dma_job_t * dmaJob,
dma_priority_t priority )

Sets the priority level for a DMA channel.

Parameters
dmaJobPointer to a configured DMA job.
priorityThe priority level (DMA_PRIORITY_0 lowest through DMA_PRIORITY_3 highest).

◆ dma_start_job()

bool dma_start_job ( gossamer_dma_job_t * dmaJob)

Starts a configured DMA job.

Enables the channel and begins transfers. The job must have at least one descriptor with a nonzero beat count. Callbacks set in the job's callbacks array will be armed.

Parameters
dmaJobPointer to a configured DMA job.
Returns
true if the job started, false if the job is already busy, has no channel, or has no valid descriptors.

◆ dma_stop_job()

void dma_stop_job ( gossamer_dma_job_t * dmaJob)

Stops a running DMA job and aborts the transfer.

Parameters
dmaJobPointer to a configured DMA job.

◆ dma_suspend_job()

void dma_suspend_job ( gossamer_dma_job_t * dmaJob)

Suspends a running DMA job.

The channel will complete its current beat transfer and then pause.

Parameters
dmaJobPointer to a configured DMA job.

◆ dma_trigger()

void dma_trigger ( gossamer_dma_job_t * dmaJob)

Issues a software trigger to a DMA channel.

Use this to manually start a transfer when the job was configured with a software trigger (peripheralTrigger = 0).

Parameters
dmaJobPointer to a configured DMA job.