4.11 DMA - Direct Memory Access

4.11.1 Introduction

The MPLAB® Code Configurator (MCC) Melody Direct Memory Access Peripheral Library (PLIBs) drivers generates APIs to support DMA-specific peripheral functionality on target MCUs.

The Direct Memory Access (DMA) module is designed to service data transfers between different memory regions directly, without intervention from the CPU. By eliminating the need for CPU-intensive management of handling interrupts intended for data transfers, the CPU now can spend more time on other tasks. The DMA modules can be independently programmed to transfer data between different memory locations, move different data sizes, and use a wide range of hardware triggers to initiate transfers. The DMA modules can even be programmed to work together and to carry out more complex data transfers without CPU overhead.

4.11.2 Supported Device Families

PIC18F-K42 PIC18F-K83 PIC18F-Q20
PIC18F-Q24 PIC18F-Q40 PIC18F-Q41
PIC18F-Q43 PIC18F-Q71 PIC18F-Q83
PIC18F-Q84

4.11.3 Required header files


#include "mcc_generated_files/dma/dma[X].h"
Note: Replace [X] with instance number of selected DMA module

4.11.4 Module Documentation

4.11.4.1 DMAx

This file contains the API prototypes for the Direct Memory Access (DMA) driver.

4.11.4.1.1 Module description

This file contains the API prototypes for the Direct Memory Access (DMA) driver.

Version: DMAx Driver Version 2.12.0
Functions

4.11.4.1.2 Function Documentation

DMAx_AbortTriggerSet()

void DMAx_AbortTriggerSet (uint8_t airq)

Sets the Abort Trigger for the DMA. It does not start the transfer.

Parameters:
in airq

- Abort trigger source.

Returns:

None.

DMAx_AIInterruptHandlerSet()

void DMAx_AIInterruptHandlerSet (void(*)(void) InterruptHandler)

Sets the Callback function for the abort interrupt request event.

Parameters:
*InterruptHandler

- Callback function for the abort interrupt event.

Returns:

None.

DMAx_DCNTIInterruptHandlerSet()

void DMAx_DCNTIInterruptHandlerSet (void(*)(void) InterruptHandler)

Sets the Callback function for the destination count interrupt event.

Parameters:
*InterruptHandler

- Callback function for the destination count interrupt event.

Returns:

None.

DMAx_DefaultInterruptHandler()

void DMAx_DefaultInterruptHandler (void )

Default interrupt handler for all interrupt events.

Parameters:
None.
Returns:

None.

DMAx_DestinationAddressGet()

uint16_t DMAx_DestinationAddressGet (void )

Returns the DMA destination address.

Parameters:
None.
Returns:

16-bit DMA destination address.

DMAx_DestinationAddressSet()

void DMAx_DestinationAddressSet (uint16_t address)

Sets the destination address for the DMA packet.

Parameters:
in address

- Desired destination address.

Returns:

None.

DMAx_DestinationCountGet()

uint16_t DMAx_DestinationCountGet (void )

Returns the DMA destination count value.

Parameters:
None.
Returns:

Current 16-bit destination counter value.

DMAx_DestinationPointerGet()

uint16_t DMAx_DestinationPointerGet (void )

Returns the current location written by the DMA.

Parameters:
None.
Returns:

Current address pointer to the destination.

DMAx_DestinationSizeGet()

uint16_t DMAx_DestinationSizeGet (void )

Returns the size of the DMA destination message.

Parameters:
None.
Returns:

16-bit DMA destination message size value.

DMAx_DestinationSizeSet()

void DMAx_DestinationSizeSet (uint16_t size)

Sets the size of the destination array.

Parameters:
in size

- Size of the destination array in bytes.

Returns:

None.

DMAx_Disable()

void DMAx_Disable (void )

Disables the DMAx.

Parameters:
None.
Returns:

None.

DMAx_DMAAI_ISR()

void DMAx_DMAAI_ISR (void )

Implements the ISR for the DMAX Abort Trigger interrupt events.

Parameters:
None.
Returns:

None.

DMAx_DMADCNTI_ISR()

void DMAx_DMADCNTI_ISR (void )

Implements the ISR for the DMAX destination count interrupt events.

Parameters:
None.
Returns:

None.

DMAx_DMAORI_ISR()

void DMAx_DMAORI_ISR (void )

Implements the ISR for the DMAX overrun interrupt events.

Parameters:
None.
Returns:

None.

DMAx_DMAPrioritySet()

void DMAx_DMAPrioritySet (uint8_t priority)

Sets the priority of the arbiter.

Parameters:
in priority

- Priority of the DMA.

Returns:

None.

NOTE: This function is dependent on the PR1WAY CONFIG bit.

DMAx_DMASCNTI_ISR()

void DMAx_DMASCNTI_ISR (void )

Implements the Interrupt Service Routine (ISR) for the DMAX source count interrupt.

Parameters:
None.
Returns:

None.

DMAx_Enable()

void DMAx_Enable (void )

Enables the DMAx.

Parameters:
None.
Returns:

None.

DMAx_Initialize()

void DMAx_Initialize (void )

Initializes the DMAX module. This is called only once before calling other DMAX APIs.

Parameters:
None.
Returns:

None.

DMAx_ORIInterruptHandlerSet()

void DMAx_ORIInterruptHandlerSet (void(*)(void) InterruptHandler)

Sets the callback function for the overrun interrupt event.

Parameters:
*InterruptHandler

- Callback function for the overrun interrupt event.

Returns:

None.

DMAx_SCNTIInterruptHandlerSet()

void DMAx_SCNTIInterruptHandlerSet (void(*)(void) InterruptHandler)

Sets the Callback function for the source count interrupt event.

Parameters:
*InterruptHandler

- Callback function for the source count interrupt event.

Returns:

None.

DMAx_SourceAddressGet()

uint24_t DMAx_SourceAddressGet (void )

Returns the DMA source address.

Parameters:
None.
Returns:

24-bit DMA source address.

DMAx_SourceAddressSet()

void DMAx_SourceAddressSet (uint24_t address)

Sets the source address for the DMA packet.

Parameters:
in address

- Desired source address.

Returns:

None.

DMAx_SourceCountGet()

uint16_t DMAx_SourceCountGet (void )

Returns the DMA source count value.

Parameters:
None.
Returns:

Current 16-bit source counter value.

DMAx_SourcePointerGet()

uint24_t DMAx_SourcePointerGet (void )

Returns the current location read by the DMA.

Parameters:
None.
Returns:

Current address pointer to the source.

DMAx_SourceRegionSelect()

void DMAx_SourceRegionSelect (uint8_t region)

Sets the source region.

Parameters:
in region

- Desired source region.

Returns:

None.

DMAx_SourceSizeGet()

uint16_t DMAx_SourceSizeGet (void )

Returns the size of the DMA source message.

Parameters:
None.
Returns:

16-bit DMA source message size value.

DMAx_SourceSizeSet()

void DMAx_SourceSizeSet (uint16_t size)

Sets the size of the source array.

Parameters:
in size

- Size of the source array in bytes.

Returns:

None.

DMAx_StartTriggerSet()

void DMAx_StartTriggerSet (uint8_t sirq)

Sets the Start Trigger for the DMA. It does not start the transfer.

Parameters:
in sirq

- Start trigger source.

Returns:

None.

DMAx_TransferStart()

void DMAx_TransferStart (void )

Starts the DMA Transfer.

Parameters:
None.
Returns:

None.

DMAx_TransferStop()

void DMAx_TransferStop (void )

Stops the DMA transfer.

Parameters:
None.
Returns:

None.

DMAx_TransferWithTriggerStart()

void DMAx_TransferWithTriggerStart (void )

Starts the DMA transfer based on the requested interrupt source.

Parameters:
None.
Returns:

None.

4.11.5 File Documentation

4.11.5.1 source/dmax.c File Reference

This file contains the API implementations for the DMAx driver.

#include <xc.h>
#include "../dmax.h"

4.11.5.1.1 Functions

4.11.5.1.3 Detailed Description

This file contains the API implementations for the DMAx driver.

DMAx Generated Driver File.

Version: DMA1 Driver Version 2.12.0

4.11.5.1.4 Function Documentation

DMAx_SetDCNTIInterruptHandler()

void DMAx_SetDCNTIInterruptHandler (void(*)(void) InterruptHandler)

4.11.5.1.5 Variable Documentation

DMAx_AI_InterruptHandler

void(* DMAx_AI_InterruptHandler) (void)

DMAx_DCNTI_InterruptHandler

void(* DMAx_DCNTI_InterruptHandler) (void)

DMAx_ORI_InterruptHandler

void(* DMAx_ORI_InterruptHandler) (void)

DMAx_SCNTI_InterruptHandler

void(* DMAx_SCNTI_InterruptHandler) (void)

Section: Included Files

4.11.5.2 source/dmax.h File Reference

#include <stdint.h>

4.11.5.2.1 Functions

4.11.5.2.2 Macros

API Name Macros

Section: Included Files

Macros used to map the APIs to the custom API names:

4.11.5.2.3 Classic API Name Macros

4.11.5.2.4 Detailed Description

DMAx Generated Driver API Header File.

4.11.5.2.5 Macro Definition Documentation

DMAx_GetDestinationPointer

#define DMAx_GetDestinationPointer DMAx_DestinationPointerGet

DMAx_GetSourcePointer

#define DMAx_GetSourcePointer DMAx_SourcePointerGet

DMAx_SelectSourceRegion

#define DMAx_SelectSourceRegion DMAx_SourceRegionSelect

DMAx_SetAbortTrigger

#define DMAx_SetAbortTrigger DMAx_AbortTriggerSet

DMAx_SetAIInterruptHandler

#define DMAx_SetAIInterruptHandler DMAx_AIInterruptHandlerSet

DMAx_SetDCNTIInterruptHandler

#define DMAx_SetDCNTIInterruptHandler DMAx_DCNTIInterruptHandlerSet

DMAx_SetDestinationAddress

#define DMAx_SetDestinationAddress DMAx_DestinationAddressSet

DMAx_SetDestinationSize

#define DMAx_SetDestinationSize DMAx_DestinationSizeSet

DMAx_SetDMAPriority

#define DMAx_SetDMAPriority DMAx_DMAPrioritySet

DMAx_SetORIInterruptHandler

#define DMAx_SetORIInterruptHandler DMAx_ORIInterruptHandlerSet

DMAx_SetSCNTIInterruptHandler

#define DMAx_SetSCNTIInterruptHandler DMAx_SCNTIInterruptHandlerSet

DMAx_SetSourceAddress

#define DMAx_SetSourceAddress DMAx_SourceAddressSet

DMAx_SetSourceSize

#define DMAx_SetSourceSize DMAx_SourceSizeSet

DMAx_SetStartTrigger

#define DMAx_SetStartTrigger DMAx_StartTriggerSet

DMAx_StartTransfer

#define DMAx_StartTransfer DMAx_TransferStart

DMAx_StartTransferWithTrigger

#define DMAx_StartTransferWithTrigger DMAx_TransferWithTriggerStart

DMAx_StopTransfer

#define DMAx_StopTransfer DMAx_TransferStop

myDMAx_AbortTriggerSet

#define myDMAx_AbortTriggerSet DMAx_AbortTriggerSet

myDMAx_AIInterruptHandlerSet

#define myDMAx_AIInterruptHandlerSet DMAx_AIInterruptHandlerSet

myDMAx_DCNTIInterruptHandlerSet

#define myDMAx_DCNTIInterruptHandlerSet DMAx_DCNTIInterruptHandlerSet

myDMAx_DestinationAddressGet

#define myDMAx_DestinationAddressGet DMAx_DestinationAddressGet

myDMAx_DestinationAddressSet

#define myDMAx_DestinationAddressSet DMAx_DestinationAddressSet

myDMAx_DestinationCountGet

#define myDMAx_DestinationCountGet DMAx_DestinationCountGet

myDMAx_DestinationPointerGet

#define myDMAx_DestinationPointerGet DMAx_DestinationPointerGet

myDMAx_DestinationSizeGet

#define myDMAx_DestinationSizeGet DMAx_DestinationSizeGet

myDMAx_DestinationSizeSet

#define myDMAx_DestinationSizeSet DMAx_DestinationSizeSet

myDMAx_Disable

#define myDMAx_Disable DMAx_Disable

myDMAx_DMAAI_ISR

#define myDMAx_DMAAI_ISR DMAx_DMAAI_ISR

myDMAx_DMADCNTI_ISR

#define myDMAx_DMADCNTI_ISR DMAx_DMADCNTI_ISR

myDMAx_DMAORI_ISR

#define myDMAx_DMAORI_ISR DMAx_DMAORI_ISR

myDMAx_DMAPrioritySet

#define myDMAx_DMAPrioritySet DMAx_DMAPrioritySet

myDMAx_DMASCNTI_ISR

#define myDMAx_DMASCNTI_ISR DMAx_DMASCNTI_ISR

myDMAx_Enable

#define myDMAx_Enable DMAx_Enable

myDMAx_Initialize

#define myDMAx_Initialize DMAx_Initialize

myDMAx_ORIInterruptHandlerSet

#define myDMAx_ORIInterruptHandlerSet DMAx_ORIInterruptHandlerSet

myDMAx_SCNTIInterruptHandlerSet

#define myDMAx_SCNTIInterruptHandlerSet DMAx_SCNTIInterruptHandlerSet

myDMAx_SourceAddressGet

#define myDMAx_SourceAddressGet DMAx_SourceAddressGet

myDMAx_SourceAddressSet

#define myDMAx_SourceAddressSet DMAx_SourceAddressSet

myDMAx_SourceCountGet

#define myDMAx_SourceCountGet DMAx_SourceCountGet

myDMAx_SourcePointerGet

#define myDMAx_SourcePointerGet DMAx_SourcePointerGet

myDMAx_SourceRegionSelect

#define myDMAx_SourceRegionSelect DMAx_SourceRegionSelect

myDMAx_SourceSizeGet

#define myDMAx_SourceSizeGet DMAx_SourceSizeGet

myDMAx_SourceSizeSet

#define myDMAx_SourceSizeSet DMAx_SourceSizeSet

myDMAx_StartTriggerSet

#define myDMAx_StartTriggerSet DMAx_StartTriggerSet

myDMAx_TransferStart

#define myDMAx_TransferStart DMAx_TransferStart

myDMAx_TransferStop

#define myDMAx_TransferStop DMAx_TransferStop

myDMAx_TransferWithTriggerStart

#define myDMAx_TransferWithTriggerStart DMAx_TransferWithTriggerStart