3.6 DMA Driver

Overview

The Direct Memory Access (DMA) Controller is designed to service high-data-throughput peripherals operating on the SFR bus, allowing them to access data memory directly and eliminating the need for CPU-intensive management.

Features

Multiple Independent and Independently-Programmable Channels.
Four Programmable Transfer Modes.
8 bit, 16 bit and 32 bit transfer modes.
32-Bit Source and Destination Address Register for Each Channel, Dynamically Updated and Reloadable.
Upper and Lower Address Limit Registers.

3.6.1 Module Documentation

3.6.1.1 DMA Driver

Direct Memory Access driver to service high data throughput peripherals allowing them to access data memory directly using dsPIC MCUs.

3.6.1.1.1 Module description

Direct Memory Access driver to service high data throughput peripherals allowing them to access data memory directly using dsPIC MCUs.

Data structures

struct DMA_INTERFACE

Structure containing the function pointers of DMA driver.

Enumerations

enum DMA_CHANNEL { DMA_CHANNEL_0 = 0, DMA_CHANNEL_1 = 1, DMA_CHANNEL_2 = 2, DMA_CHANNEL_3 = 3, DMA_CHANNEL_4 = 4, DMA_CHANNEL_5 = 5, DMA_NUMBER_OF_CHANNELS = 6 }

Defines the DMA channles that are selected from the MCC Melody User Interface for the DMA transfers. The below are the custom names given in the MCC Melody User Interface.
enum DMA_EVENT { DMA_OVERRUN, DMA_TRANSFER_DONE }

Defines the DMA interrupt events.

Functions

void DMA_Initialize (void)

Initializes the DMA module.
void DMA_Deinitialize (void)

Deinitializes the DMA to POR values.
static void DMA_ChannelEnable (enum DMA_CHANNEL channel)

This inline function enables the DMA channel.
static void DMA_ChannelDisable (enum DMA_CHANNEL channel)

This inline function disables the DMA channel.
static void DMA_TransferCountSet (enum DMA_CHANNEL channel, uint16_t transferCount)

This inline function sets the number of transfer counts to DMA channel.
static uint16_t DMA_TransferCountGet (enum DMA_CHANNEL channel)

This inline function returns the number of transfer counts from DMA channel.
static void DMA_SoftwareTriggerEnable (enum DMA_CHANNEL channel)

This inline function sets the software trigger of the DMA channel.
static void DMA_SourceAddressSet (enum DMA_CHANNEL channel, size_t address)

This inline function sets the source address to specified DMA channel.
static void DMA_DestinationAddressSet (enum DMA_CHANNEL channel, size_t address)

This inline function sets the destination address to specified DMA channel.
static bool DMA_IsSoftwareRequestPending (enum DMA_CHANNEL channel)

This inline function returns the status of the software request of the DMA channel.
void DMA_ChannelTasks (void)

This function is used to implement the tasks for polled implementations of DMA Channel.
void DMA_ChannelCallbackRegister (enum DMA_CHANNEL channel, void(*callback)(enum DMA_EVENT event))

This function can be used to override default callback and to define custom callback for DMA Channel event.
void DMA_Channel0Callback (enum DMA_EVENT event)

This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using DMA_ChannelCallbackRegister.
void DMA_Channel1Callback (enum DMA_EVENT event)

This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using DMA_ChannelCallbackRegister.
void DMA_Channel2Callback (enum DMA_EVENT event)

This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using DMA_ChannelCallbackRegister.
void DMA_Channel3Callback (enum DMA_EVENT event)

This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using DMA_ChannelCallbackRegister.
void DMA_Channel4Callback (enum DMA_EVENT event)

This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using DMA_ChannelCallbackRegister.
void DMA_Channel5Callback (enum DMA_EVENT event)

This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using DMA_ChannelCallbackRegister.

Variables

const struct DMA_INTERFACE DMA

Structure object of type DMA_INTERFACE with the custom name given by the user in the Melody Driver User interface. The default name e.g. DMA can be changed by the user in the DMA user interface. This allows defining a structure with application specific name using the 'Custom Name' field. Application specific name allows the API Portability.

3.6.1.1.2 Function Documentation

DMA_Channel0Callback()

void DMA_Channel0Callback (enum DMA_EVENT event)

This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using DMA_ChannelCallbackRegister.

Parameters:
in	channel	- Selected channel for the Callback handling
in	event	- DMA interrupt event DMA_EVENT

Returns:
none

DMA_Channel1Callback()

void DMA_Channel1Callback (enum DMA_EVENT event)

Parameters:
in	channel	- Selected channel for the Callback handling
in	event	- DMA interrupt event DMA_EVENT

Returns:
none

DMA_Channel2Callback()

void DMA_Channel2Callback (enum DMA_EVENT event)

Parameters:
in	channel	- Selected channel for the Callback handling
in	event	- DMA interrupt event DMA_EVENT

Returns:
none

DMA_Channel3Callback()

void DMA_Channel3Callback (enum DMA_EVENT event)

Parameters:
in	channel	- Selected channel for the Callback handling
in	event	- DMA interrupt event DMA_EVENT

Returns:
none

DMA_Channel4Callback()

void DMA_Channel4Callback (enum DMA_EVENT event)

Parameters:
in	channel	- Selected channel for the Callback handling
in	event	- DMA interrupt event DMA_EVENT

Returns:
none

DMA_Channel5Callback()

void DMA_Channel5Callback (enum DMA_EVENT event)

Parameters:
in	channel	- Selected channel for the Callback handling
in	event	- DMA interrupt event DMA_EVENT

Returns:
none

DMA_ChannelCallbackRegister()

void DMA_ChannelCallbackRegister (enum DMA_CHANNEL channel, void(*)(enum DMA_EVENT event) callback)

This function can be used to override default callback and to define custom callback for DMA Channel event.

Parameters:
in	channel	- DMA Channel from enum DMA_CHANNEL
in	callback	- Address of the callback function

Returns:
none

DMA_ChannelDisable()

inline static void DMA_ChannelDisable (enum DMA_CHANNEL channel)

This inline function disables the DMA channel.

Precondition:
DMA_Initialize must be called.

Parameters:
in	channel	- DMA channel number

Returns:
none

DMA_ChannelEnable()

inline static void DMA_ChannelEnable (enum DMA_CHANNEL channel)

This inline function enables the DMA channel.

Precondition:
DMA_Initialize must be called

Parameters:
in	channel	- DMA channel number

Returns:
none

DMA_ChannelTasks()

void DMA_ChannelTasks (void )

This function is used to implement the tasks for polled implementations of DMA Channel.

Precondition:
DMA_Initialize must be called

Parameters:
none

Returns:
none

DMA_Deinitialize()

void DMA_Deinitialize (void )

Deinitializes the DMA to POR values.

Parameters:
none

Returns:
none

DMA_DestinationAddressSet()

inline static void DMA_DestinationAddressSet (enum DMA_CHANNEL channel, size_t address)

This inline function sets the destination address to specified DMA channel.

Precondition:
DMA_Initialize must be called

Parameters:
in	channel	- DMA channel number
in	address	- Destination address

Returns:
none

DMA_Initialize()

void DMA_Initialize (void )

Initializes the DMA module.

Parameters:
none

Returns:
none

DMA_IsSoftwareRequestPending()

inline static bool DMA_IsSoftwareRequestPending (enum DMA_CHANNEL channel)

This inline function returns the status of the software request of the DMA channel.

Precondition:
DMA_Initialize must be called

Parameters:
in	channel	- DMA channel number

Returns:
true - DMA request is pending false - DMA request is not pending

DMA_SoftwareTriggerEnable()

inline static void DMA_SoftwareTriggerEnable (enum DMA_CHANNEL channel)

This inline function sets the software trigger of the DMA channel.

Precondition:
DMA_Initialize must be called

Parameters:
in	channel	- DMA channel number

Returns:
none

DMA_SourceAddressSet()

inline static void DMA_SourceAddressSet (enum DMA_CHANNEL channel, size_t address)

This inline function sets the source address to specified DMA channel.

Precondition:
DMA_Initialize must be called

Parameters:
in	channel	- DMA channel number
in	address	- Source address

Returns:
none

DMA_TransferCountGet()

inline static uint16_t DMA_TransferCountGet (enum DMA_CHANNEL channel)

This inline function returns the number of transfer counts from DMA channel.

Precondition:
DMA_Initialize must be called

Parameters:
in	channel	- DMA channel number

Returns:
Returns the transfer count value

DMA_TransferCountSet()

inline static void DMA_TransferCountSet (enum DMA_CHANNEL channel, uint16_t transferCount)

This inline function sets the number of transfer counts to DMA channel.

Precondition:
DMA_Initialize must be called

Parameters:
in	channel	- DMA channel number
in	transferCount	- Transfer count Value

Returns:
none

3.6.1.1.3 Enumeration Type Documentation

DMA_CHANNEL

enum DMA_CHANNEL

Defines the DMA channles that are selected from the MCC Melody User Interface for the DMA transfers. The below are the custom names given in the MCC Melody User Interface.


DMA_CHANNEL_0	DMA channel 0
DMA_CHANNEL_1	DMA channel 1
DMA_CHANNEL_2	DMA channel 2
DMA_CHANNEL_3	DMA channel 3
DMA_CHANNEL_4	DMA channel 4
DMA_CHANNEL_5	DMA channel 5
DMA_NUMBER_OF_CHANNELS	Maximum number of Channels supported by hardware : 6

DMA_EVENT

enum DMA_EVENT

Defines the DMA interrupt events.


DMA_OVERRUN	Channel transfer is being requested before its current transaction is finished
DMA_TRANSFER_DONE	DMA transfer count is zero indicating completion of transfer

3.6.1.1.4 Variable Documentation

DMA

const struct DMA_INTERFACE DMA

Structure object of type DMA_INTERFACE with the custom name given by the user in the Melody Driver User interface. The default name e.g. DMA can be changed by the user in the DMA user interface. This allows defining a structure with application specific name using the 'Custom Name' field. Application specific name allows the API Portability.

3.6.2 Data Structure Documentation

3.6.2.1 DMA_INTERFACE Struct Reference

Structure containing the function pointers of DMA driver.

3.6.2.1.1 Detailed Description

Structure containing the function pointers of DMA driver.

#include <dma_interface.h>

Data Fields

void(* Initialize )(void)

Pointer to DMA_Initialize.
void(* Deinitialize )(void)

Pointer to DMA_Deinitialize.
void(* ChannelEnable )(enum DMA_CHANNEL channel)

Pointer to DMA_ChannelEnable.
void(* ChannelDisable )(enum DMA_CHANNEL channel)

Pointer to DMA_ChannelDisable.
void(* TransferCountSet )(enum DMA_CHANNEL channel, uint16_t transferCount)

Pointer to DMA_TransferCountSet.
uint16_t(* TransferCountGet )(enum DMA_CHANNEL channel)

Pointer to DMA_TransferCountGet.
void(* SoftwareTriggerEnable )(enum DMA_CHANNEL channel)

Pointer to DMA_SoftwareTriggerEnable.
void(* SourceAddressSet )(enum DMA_CHANNEL channel, size_t address)

Pointer to DMA_SourceAddressSet.
void(* DestinationAddressSet )(enum DMA_CHANNEL channel, size_t address)

Pointer to DMA_DestinationAddressSet.
bool(* IsSoftwareRequestPending )(enum DMA_CHANNEL channel)

Pointer to DMA_IsSoftwareRequestPending.
void(* ChannelCallbackRegister )(enum DMA_CHANNEL channel, void(*callback)(enum DMA_EVENT event))

Pointer to DMA_ChannelCallbackRegister.
void(* ChannelTasks )(void)

Pointer to DMA_ChannelTasks (Supported only in polling mode)

3.6.2.1.2 Field Documentation

The documentation for this struct was generated from the following file:

source/

dma_interface.h

ChannelCallbackRegister

void(* ChannelCallbackRegister) (enum DMA_CHANNEL channel, void(*callback)(enum DMA_EVENT event))

Pointer to DMA_ChannelCallbackRegister.

ChannelDisable

void(* ChannelDisable) (enum DMA_CHANNEL channel)

Pointer to DMA_ChannelDisable.

ChannelEnable

void(* ChannelEnable) (enum DMA_CHANNEL channel)

Pointer to DMA_ChannelEnable.

ChannelTasks

void(* ChannelTasks) (void)

Pointer to DMA_ChannelTasks (Supported only in polling mode)

Deinitialize

void(* Deinitialize) (void)

Pointer to DMA_Deinitialize.

DestinationAddressSet

void(* DestinationAddressSet) (enum DMA_CHANNEL channel, size_t address)

Pointer to DMA_DestinationAddressSet.

Initialize

void(* Initialize) (void)

Pointer to DMA_Initialize.

IsSoftwareRequestPending

bool(* IsSoftwareRequestPending) (enum DMA_CHANNEL channel)

Pointer to DMA_IsSoftwareRequestPending.

SoftwareTriggerEnable

void(* SoftwareTriggerEnable) (enum DMA_CHANNEL channel)

Pointer to DMA_SoftwareTriggerEnable.

SourceAddressSet

void(* SourceAddressSet) (enum DMA_CHANNEL channel, size_t address)

Pointer to DMA_SourceAddressSet.

TransferCountGet

uint16_t(* TransferCountGet) (enum DMA_CHANNEL channel)

Pointer to DMA_TransferCountGet.

TransferCountSet

void(* TransferCountSet) (enum DMA_CHANNEL channel, uint16_t transferCount)

Pointer to DMA_TransferCountSet.

3.6.3 File Documentation

3.6.3.1 source/dma.h File Reference

This is the generated driver header file for the DMA driver.

#include <xc.h>
#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
#include "dma_types.h"
#include "dma_interface.h"

3.6.3.1.1 Functions

void DMA_Initialize (void)

Initializes the DMA module.
void DMA_Deinitialize (void)

Deinitializes the DMA to POR values.
static void DMA_ChannelEnable (enum DMA_CHANNEL channel)

This inline function enables the DMA channel.
static void DMA_ChannelDisable (enum DMA_CHANNEL channel)

This inline function disables the DMA channel.
static void DMA_TransferCountSet (enum DMA_CHANNEL channel, uint16_t transferCount)

This inline function sets the number of transfer counts to DMA channel.
static uint16_t DMA_TransferCountGet (enum DMA_CHANNEL channel)

This inline function returns the number of transfer counts from DMA channel.
static void DMA_SoftwareTriggerEnable (enum DMA_CHANNEL channel)

This inline function sets the software trigger of the DMA channel.
static void DMA_SourceAddressSet (enum DMA_CHANNEL channel, size_t address)

This inline function sets the source address to specified DMA channel.
static void DMA_DestinationAddressSet (enum DMA_CHANNEL channel, size_t address)

This inline function sets the destination address to specified DMA channel.
static bool DMA_IsSoftwareRequestPending (enum DMA_CHANNEL channel)

This inline function returns the status of the software request of the DMA channel.
void DMA_ChannelTasks (void)

This function is used to implement the tasks for polled implementations of DMA Channel.
void DMA_ChannelCallbackRegister (enum DMA_CHANNEL channel, void(*callback)(enum DMA_EVENT event))

This function can be used to override default callback and to define custom callback for DMA Channel event.
void DMA_Channel0Callback (enum DMA_EVENT event)

This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using DMA_ChannelCallbackRegister.
void DMA_Channel1Callback (enum DMA_EVENT event)

This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using DMA_ChannelCallbackRegister.
void DMA_Channel2Callback (enum DMA_EVENT event)

This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using DMA_ChannelCallbackRegister.
void DMA_Channel3Callback (enum DMA_EVENT event)

This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using DMA_ChannelCallbackRegister.
void DMA_Channel4Callback (enum DMA_EVENT event)

This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using DMA_ChannelCallbackRegister.
void DMA_Channel5Callback (enum DMA_EVENT event)

This is the default callback with weak attribute. The user can override and implement the default callback without weak attribute or can register a custom callback function using DMA_ChannelCallbackRegister.

3.6.3.1.2 Variables

const struct DMA_INTERFACE DMA

Structure object of type DMA_INTERFACE with the custom name given by the user in the Melody Driver User interface. The default name e.g. DMA can be changed by the user in the DMA user interface. This allows defining a structure with application specific name using the 'Custom Name' field. Application specific name allows the API Portability.

3.6.3.1.3 Detailed Description

This is the generated driver header file for the DMA driver.

DMA Generated Driver Header File

3.6.3.2 source/dma_interface.h File Reference

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include "dma_types.h"

3.6.3.2.1 Data structures

struct DMA_INTERFACE

Structure containing the function pointers of DMA driver.

3.6.3.2.2 Detailed Description

DMA Generated Driver Interface Header File

3.6.3.3 source/dma_types.h File Reference

This is the generated driver types header file for the DMA driver.

3.6.3.3.1 Enumerations

enum DMA_CHANNEL { DMA_CHANNEL_0 = 0, DMA_CHANNEL_1 = 1, DMA_CHANNEL_2 = 2, DMA_CHANNEL_3 = 3, DMA_CHANNEL_4 = 4, DMA_CHANNEL_5 = 5, DMA_NUMBER_OF_CHANNELS = 6 }

Defines the DMA channles that are selected from the MCC Melody User Interface for the DMA transfers. The below are the custom names given in the MCC Melody User Interface.
enum DMA_EVENT { DMA_OVERRUN, DMA_TRANSFER_DONE }

Defines the DMA interrupt events.

3.6.3.3.2 Detailed Description

This is the generated driver types header file for the DMA driver.

DMA Generated Driver Types Header File