# DMA Module

The direct memory access (DMA) API provides a set of functions to configure transfers of data between peripherals or memory using the device’s six-channel DMA module. Functions are provided to configure which event triggers a DMA transfer, to configure the locations, sizes, and behaviors of the transfers, and to set up and handle interrupts.

group `dma_api`

  This module is used for DMA configurations.

  Defines

  `DMA_CFG_ONESHOT_DISABLE` 0U

    Only one burst transfer performed per trigger.

  `DMA_CFG_ONESHOT_ENABLE` DMA_MODE_ONESHOT

    Burst transfers occur without additional event triggers after the first.

  `DMA_CFG_CONTINUOUS_DISABLE` 0U

    DMA channel will be disabled at the end of a transfer.

  `DMA_CFG_CONTINUOUS_ENABLE` DMA_MODE_CONTINUOUS

    DMA reinitializes when the transfer count is zero and waits for a trigger.

  `DMA_CFG_SIZE_16BIT` 0U

    DMA transfers 16 bits at a time.

  `DMA_CFG_SIZE_32BIT` DMA_MODE_DATASIZE

    DMA transfers 32 bits at a time.

  Enums

  enum `DMA_Trigger`

    Values that can be passed to DMA_configMode() as the trigger parameter.

    Values:

    enumerator `DMA_TRIGGER_SOFTWARE` = 0
    enumerator `DMA_TRIGGER_ADCA1` = 1
    enumerator `DMA_TRIGGER_ADCA2` = 2
    enumerator `DMA_TRIGGER_ADCA3` = 3
    enumerator `DMA_TRIGGER_ADCA4` = 4
    enumerator `DMA_TRIGGER_ADCAEVT` = 5
    enumerator `DMA_TRIGGER_ADCB1` = 6
    enumerator `DMA_TRIGGER_ADCB2` = 7
    enumerator `DMA_TRIGGER_ADCB3` = 8
    enumerator `DMA_TRIGGER_ADCB4` = 9
    enumerator `DMA_TRIGGER_ADCBEVT` = 10
    enumerator `DMA_TRIGGER_ADCC1` = 11
    enumerator `DMA_TRIGGER_ADCC2` = 12
    enumerator `DMA_TRIGGER_ADCC3` = 13
    enumerator `DMA_TRIGGER_ADCC4` = 14
    enumerator `DMA_TRIGGER_ADCCEVT` = 15
    enumerator `DMA_TRIGGER_ADCD1` = 16
    enumerator `DMA_TRIGGER_ADCD2` = 17
    enumerator `DMA_TRIGGER_ADCD3` = 18
    enumerator `DMA_TRIGGER_ADCD4` = 19
    enumerator `DMA_TRIGGER_ADCDEVT` = 20
    enumerator `DMA_TRIGGER_XINT1` = 29
    enumerator `DMA_TRIGGER_XINT2` = 30
    enumerator `DMA_TRIGGER_XINT3` = 31
    enumerator `DMA_TRIGGER_XINT4` = 32
    enumerator `DMA_TRIGGER_XINT5` = 33
    enumerator `DMA_TRIGGER_EPWM1SOCA` = 36
    enumerator `DMA_TRIGGER_EPWM1SOCB` = 37
    enumerator `DMA_TRIGGER_EPWM2SOCA` = 38
    enumerator `DMA_TRIGGER_EPWM2SOCB` = 39
    enumerator `DMA_TRIGGER_EPWM3SOCA` = 40
    enumerator `DMA_TRIGGER_EPWM3SOCB` = 41
    enumerator `DMA_TRIGGER_EPWM4SOCA` = 42
    enumerator `DMA_TRIGGER_EPWM4SOCB` = 43
    enumerator `DMA_TRIGGER_EPWM5SOCA` = 44
    enumerator `DMA_TRIGGER_EPWM5SOCB` = 45
    enumerator `DMA_TRIGGER_EPWM6SOCA` = 46
    enumerator `DMA_TRIGGER_EPWM6SOCB` = 47
    enumerator `DMA_TRIGGER_EPWM7SOCA` = 48
    enumerator `DMA_TRIGGER_EPWM7SOCB` = 49
    enumerator `DMA_TRIGGER_EPWM8SOCA` = 50
    enumerator `DMA_TRIGGER_EPWM8SOCB` = 51
    enumerator `DMA_TRIGGER_EPWM9SOCA` = 52
    enumerator `DMA_TRIGGER_EPWM9SOCB` = 53
    enumerator `DMA_TRIGGER_EPWM10SOCA` = 54
    enumerator `DMA_TRIGGER_EPWM10SOCB` = 55
    enumerator `DMA_TRIGGER_EPWM11SOCA` = 56
    enumerator `DMA_TRIGGER_EPWM11SOCB` = 57
    enumerator `DMA_TRIGGER_EPWM12SOCA` = 58
    enumerator `DMA_TRIGGER_EPWM12SOCB` = 59
    enumerator `DMA_TRIGGER_TINT0` = 68
    enumerator `DMA_TRIGGER_TINT1` = 69
    enumerator `DMA_TRIGGER_TINT2` = 70
    enumerator `DMA_TRIGGER_MCBSPAMXEVT` = 71
    enumerator `DMA_TRIGGER_MCBSPAMREVT` = 72
    enumerator `DMA_TRIGGER_MCBSPBMXEVT` = 73
    enumerator `DMA_TRIGGER_MCBSPBMREVT` = 74
    enumerator `DMA_TRIGGER_SDFM1FLT1` = 95
    enumerator `DMA_TRIGGER_SDFM1FLT2` = 96
    enumerator `DMA_TRIGGER_SDFM1FLT3` = 97
    enumerator `DMA_TRIGGER_SDFM1FLT4` = 98
    enumerator `DMA_TRIGGER_SDFM2FLT1` = 99
    enumerator `DMA_TRIGGER_SDFM2FLT2` = 100
    enumerator `DMA_TRIGGER_SDFM2FLT3` = 101
    enumerator `DMA_TRIGGER_SDFM2FLT4` = 102
    enumerator `DMA_TRIGGER_SPIATX` = 109
    enumerator `DMA_TRIGGER_SPIARX` = 110
    enumerator `DMA_TRIGGER_SPIBTX` = 111
    enumerator `DMA_TRIGGER_SPIBRX` = 112
    enumerator `DMA_TRIGGER_SPICTX` = 113
    enumerator `DMA_TRIGGER_SPICRX` = 114
    enumerator `DMA_TRIGGER_CLB1INT` = 127
    enumerator `DMA_TRIGGER_CLB2INT` = 128
    enumerator `DMA_TRIGGER_CLB3INT` = 129
    enumerator `DMA_TRIGGER_CLB4INT` = 130
  enum `DMA_InterruptMode`

    Values that can be passed to DMA_setInterruptMode() as the mode parameter.

    Values:

    enumerator `DMA_INT_AT_BEGINNING`

      DMA interrupt is generated at the beginning of a transfer.

    enumerator `DMA_INT_AT_END`

      DMA interrupt is generated at the end of a transfer.

  enum `DMA_EmulationMode`

    Values that can be passed to DMA_setEmulationMode() as the mode parameter.

    Values:

    enumerator `DMA_EMULATION_STOP`

      Transmission stops after current read-write access is completed.

    enumerator `DMA_EMULATION_FREE_RUN`

      Continue DMA operation regardless of emulation suspend.

  Functions

  void `DMA_initController`(void)

    Initializes the DMA controller to a known state.

    This function configures does a hard reset of the DMA controller in order to put it into a known state. The function also sets the DMA to run free during an emulation suspend (see the field DEBUGCTRL.FREE for more info).

    Return

      None.

  void `DMA_triggerSoftReset`(uint32_t base)

    Channel Soft Reset

    This function does a soft reset to place the channel into its default state

    Parameters

      - `base`: is the base address of the DMA channel control registers.

    Return

      None.

  void `DMA_setEmulationMode`(DMA_EmulationMode mode)

    Sets DMA emulation mode.

    This function sets the behavior of the DMA operation when an emulation suspend occurs. The

    mode parameter can be one of the following:
    Parameters

      - `mode`: is the emulation mode to be selected.

    - DMA_EMULATION_STOP - DMA runs until the current read-write access is completed.

    - DMA_EMULATION_FREE_RUN - DMA operation continues regardless of a the suspend.

    Return

      None.

  void `DMA_enableTrigger`(uint32_t base)

    Enables peripherals to trigger a DMA transfer.

    This function enables the selected peripheral trigger to start a DMA transfer on the specified channel.

    Parameters

      - `base`: is the base address of the DMA channel control registers.

    Return

      None.

  void `DMA_disableTrigger`(uint32_t base)

    Disables peripherals from triggering a DMA transfer.

    This function disables the selected peripheral trigger from starting a DMA transfer on the specified channel. This also disables the use of the software force using the

    DMA_forceTrigger() API.
    Parameters

      - `base`: is the base address of the DMA channel control registers.

    Return

      None.

  void `DMA_forceTrigger`(uint32_t base)

    Force a peripheral trigger to a DMA channel.

    This function sets the peripheral trigger flag and if triggering a DMA burst is enabled (see

    DMA_enableTrigger()), a DMA burst transfer will be forced.
    Parameters

      - `base`: is the base address of the DMA channel control registers.

    Return

      None.

  void `DMA_clearTriggerFlag`(uint32_t base)

    Clears a DMA channel’s peripheral trigger flag.

    This function clears the peripheral trigger flag. Normally, you would use this function when initializing the DMA for the first time. The flag is cleared automatically when the DMA starts the first burst of a transfer.

    Parameters

      - `base`: is the base address of the DMA channel control registers.

    Return

      None.

  bool `DMA_getTransferStatusFlag`(uint32_t base)

    Gets the status of a DMA channel’s Transfer Status Flag.

    This function returns

    true if the Transfer Status Flag is set, which means a DMA transfer has begun. This flag is cleared when TRANSFER_COUNT reaches zero, or when the HARDRESET or SOFTRESET bit is set.
    Parameters

      - `base`: is the base address of the DMA channel control registers.

    Return

      Returns true if the Transfer Status Flag is set. Returns false otherwise.

  bool `DMA_getBurstStatusFlag`(uint32_t base)

    Gets the status of a DMA channel’s Burst Status Flag.

    This function returns

    true if the Burst Status Flag is set, which means a DMA burst has begun. This flag is cleared when BURST_COUNT reaches zero, or when the HARDRESET or SOFTRESET bit is set.
    Parameters

      - `base`: is the base address of the DMA channel control registers.

    Return

      Returns true if the Burst Status Flag is set. Returns false otherwise.

  bool `DMA_getRunStatusFlag`(uint32_t base)

    Gets the status of a DMA channel’s Run Status Flag.

    This function returns

    true if the Run Status Flag is set, which means the DMA channel is enabled. This flag is cleared when a transfer completes (TRANSFER_COUNT = 0) and continuous mode is disabled, or when the HARDRESET, SOFTRESET, or HALT bit is set.
    Parameters

      - `base`: is the base address of the DMA channel control registers.

    Return

      Returns true if the channel is enabled. Returns false otherwise.

  bool `DMA_getOverflowFlag`(uint32_t base)

    Gets the status of a DMA channel’s Overflow Flag.

    This function returns

    true if the Overflow Flag is set, which means peripheral event trigger was received while Peripheral Event Trigger Flag was already set. This flag can be cleared by writing to ERRCLR bit, using the function DMA_clearErrorFlag().
    Parameters

      - `base`: is the base address of the DMA channel control registers.

    Return

      Returns true if the channel is enabled. Returns false otherwise.

  bool `DMA_getTriggerFlagStatus`(uint32_t base)

    Gets the status of a DMA channel’s peripheral trigger flag.

    This function returns

    true if a peripheral trigger event has occurred The flag is automatically cleared when the first burst transfer begins, but if needed, it can be cleared using DMA_clearTriggerFlag().
    Parameters

      - `base`: is the base address of the DMA channel control registers.

    Return

      Returns true if a peripheral trigger event has occurred and its flag is set. Returns false otherwise.

  void `DMA_startChannel`(uint32_t base)

    Starts a DMA channel.

    This function starts the DMA running, typically after you have configured it. It will wait for the first trigger event to start operation. To halt the channel use

    DMA_stopChannel().
    Parameters

      - `base`: is the base address of the DMA channel control registers.

    Return

      None.

  void `DMA_stopChannel`(uint32_t base)

    Halts a DMA channel.

    This function halts the DMA at its current state and any current read-write access is completed. To start the channel again use

    DMA_startChannel().
    Parameters

      - `base`: is the base address of the DMA channel control registers.

    Return

      None.

  void `DMA_enableInterrupt`(uint32_t base)

    Enables a DMA channel interrupt source.

    This function enables the indicated DMA channel interrupt source.

    Parameters

      - `base`: is the base address of the DMA channel control registers.

    Return

      None.

  void `DMA_disableInterrupt`(uint32_t base)

    Disables a DMA channel interrupt source.

    This function disables the indicated DMA channel interrupt source.

    Parameters

      - `base`: is the base address of the DMA channel control registers.

    Return

      None.

  void `DMA_enableOverrunInterrupt`(uint32_t base)

    Enables the DMA channel overrun interrupt.

    This function enables the indicated DMA channel’s ability to generate an interrupt upon the detection of an overrun. An overrun is when a peripheral event trigger is received by the DMA before a previous trigger on that channel had been serviced and its flag had been cleared.

    Parameters

      - `base`: is the base address of the DMA channel control registers.

    Note that this is the same interrupt signal as the interrupt that gets generated at the beginning/end of a transfer. That interrupt must first be enabled using DMA_enableInterrupt() in order for the overrun interrupt to be generated.

    Return

      None.

  void `DMA_disableOverrunInterrupt`(uint32_t base)

    Disables the DMA channel overrun interrupt.

    This function disables the indicated DMA channel’s ability to generate an interrupt upon the detection of an overrun.

    Parameters

      - `base`: is the base address of the DMA channel control registers.

    Return

      None.

  void `DMA_clearErrorFlag`(uint32_t base)

    Clears the DMA channel error flags.

    This function clears both the DMA channel’s sync error flag and its overrun error flag.

    Parameters

      - `base`: is the base address of the DMA channel control registers.

    Return

      None.

  void `DMA_setInterruptMode`(uint32_t base, DMA_InterruptMode mode)

    Sets the interrupt generation mode of a DMA channel interrupt.

    This function sets the channel interrupt mode. When the

    mode parameter is DMA_INT_AT_END, the DMA channel interrupt will be generated at the end of the transfer. If DMA_INT_AT_BEGINNING, the interrupt will be generated at the beginning of a new transfer. Generating at the beginning of a new transfer is the default behavior.
    Parameters

      - `base`: is the base address of the DMA channel control registers.

      - `mode`: is a flag to indicate the channel interrupt mode.

    Return

      None.

  void `DMA_setPriorityMode`(bool ch1IsHighPri)

    Sets the DMA channel priority mode.

    This function sets the channel interrupt mode. When the

    ch1IsHighPri parameter is false, the DMA channels are serviced in round-robin mode. This is the default behavior.
    Parameters

      - `ch1IsHighPri`: is a flag to indicate the channel interrupt mode.

    If true, channel 1 will be given higher priority than the other channels. This means that if a channel 1 trigger occurs, the current word transfer on any other channel is completed and channel 1 is serviced for the complete burst count. The lower-priority channel’s interrupted transfer will then resume.

    Return

      None.

  void `DMA_configSourceAddress`(uint32_t base, const void *srcAddr)

    Configures the source address for the DMA channel

    This function configures the source address of a DMA channel.

    Parameters

      - `base`: is the base address of the DMA channel control registers.

      - `*srcAddr`: is a source address.

    Return

      None.

  void `DMA_configDestAddress`(uint32_t base, const void *destAddr)

    Configures the destination address for the DMA channel

    This function configures the destinaton address of a DMA channel.

    Parameters

      - `base`: is the base address of the DMA channel control registers.

      - `*destAddr`: is the destination address.

    Return

      None.

  void `DMA_configAddresses`(uint32_t base, const void *destAddr, const void *srcAddr)

    Configures the DMA channel

    This function configures the source and destination addresses of a DMA channel. The parameters are pointers to the data to be transferred.

    Parameters

      - `base`: is the base address of the DMA channel control registers.

      - `*destAddr`: is the destination address.

      - `*srcAddr`: is a source address.

    Return

      None.

  void `DMA_configBurst`(uint32_t base, uint16_t size, int16_t srcStep, int16_t destStep)

    Configures the DMA channel’s burst settings.

    This function configures the size of each burst and the address step size.

    Parameters

      - `base`: is the base address of the DMA channel control registers.

      - `size`: is the number of words transferred per burst.

      - `srcStep`: is the amount to increment or decrement the source address after each word of a burst.

      - `destStep`: is the amount to increment or decrement the destination address after each word of a burst.

    The size parameter is the number of words that will be transferred during a single burst. Possible amounts range from 1 word to 32 words.

    The srcStep and destStep parameters specify the address step that should be added to the source and destination addresses after each transferred word of a burst. Only signed values from -4096 to 4095 are valid.

    Note

      Note that regardless of what data size (configured by DMA_configMode()) is used, parameters are in terms of 16-bits words.

    Return

      None.

  void `DMA_configTransfer`(uint32_t base, uint32_t transferSize, int16_t srcStep, int16_t destStep)

    Configures the DMA channel’s transfer settings.

    This function configures the transfer size and the address step that is made after each burst.

    Parameters

      - `base`: is the base address of the DMA channel control registers.

      - `transferSize`: is the number of bursts per transfer.

      - `srcStep`: is the amount to increment or decrement the source address after each burst of a transfer unless a wrap occurs.

      - `destStep`: is the amount to increment or decrement the destination address after each burst of a transfer unless a wrap occurs.

    The transferSize parameter is the number of bursts per transfer. If DMA channel interrupts are enabled, they will occur after this number of bursts have completed. The maximum number of bursts is 65536.

    The srcStep and destStep parameters specify the address step that should be added to the source and destination addresses after each transferred burst of a transfer. Only signed values from -4096 to 4095 are valid. If a wrap occurs, these step values will be ignored. Wrapping is configured with DMA_configWrap().

    Note

      Note that regardless of what data size (configured by DMA_configMode()) is used, parameters are in terms of 16-bits words.

    Return

      None.

  void `DMA_configWrap`(uint32_t base, uint32_t srcWrapSize, int16_t srcStep, uint32_t destWrapSize, int16_t destStep)

    Configures the DMA channel’s wrap settings.

    This function configures the DMA channel’s wrap settings.

    Parameters

      - `base`: is the base address of the DMA channel control registers.

      - `srcWrapSize`: is the number of bursts to be transferred before a wrap of the source address occurs.

      - `srcStep`: is the amount to increment or decrement the source address after each burst of a transfer unless a wrap occurs.

      - `destWrapSize`: is the number of bursts to be transferred before a wrap of the destination address occurs.

      - `destStep`: is the amount to increment or decrement the destination address after each burst of a transfer unless a wrap occurs.

    The srcWrapSize and destWrapSize parameters are the number of bursts that are to be transferred before their respective addresses are wrapped. The maximum wrap size is 65536 bursts.

    The srcStep and destStep parameters specify the address step that should be added to the source and destination addresses when the wrap occurs. Only signed values from -4096 to 4095 are valid.

    Note

      Note that regardless of what data size (configured by DMA_configMode()) is used, parameters are in terms of 16-bits words.

    Return

      None.

  void `DMA_configMode`(uint32_t base, DMA_Trigger trigger, uint32_t config)

    Configures the DMA channel trigger and mode.

    This function configures the DMA channel’s trigger and mode.

    Parameters

      - `base`: is the base address of the DMA channel control registers.

      - `trigger`: is the interrupt source that triggers a DMA transfer.

      - `config`: is a bit field of several configuration selections.

    The trigger parameter is the interrupt source that will trigger the start of a DMA transfer.

    The config parameter is the logical OR of the following values:

    - DMA_CFG_ONESHOT_DISABLE or DMA_CFG_ONESHOT_ENABLE. If enabled, the subsequent burst transfers occur without additional event triggers after the first event trigger. If disabled, only one burst transfer is performed per event trigger.

    - DMA_CFG_CONTINUOUS_DISABLE or DMA_CFG_CONTINUOUS_ENABLE. If enabled the DMA reinitializes when the transfer count is zero and waits for the next interrupt event trigger. If disabled, the DMA stops and clears the run status bit.

    - DMA_CFG_SIZE_16BIT or DMA_CFG_SIZE_32BIT. This setting selects whether the databus width is 16 or 32 bits.

    Return

      None.

The DMA API includes functions that configure the module as a whole and functions that configure the individual channels. Functions that fall into the former category are DMA_initController(), DMA_setEmulationMode(), and DMA_setPriorityMode(). The functions that can be configured by channel can easily be identified as they take a base address as their first parameter.

The DMA_configMode() function is used to configure the event that triggers a DMA transfer as well as several other properties of a transfer for the specified channel. Other functions that can be used to control the trigger from within the DMA module are DMA_enableTrigger(), DMA_disableTrigger(), DMA_forceTrigger(), DMA_clearTriggerFlag(), and DMA_getTriggerFlagStatus(). Note that DMA_forceTrigger() is used to trigger a transfer from software.

DMA_configAddresses() is used to write to both the beginning and current address pointer registers. The manner in which these addresses are incremented and decremented as bursts and transfers complete is configured using DMA_configBurst(), DMA_configTransfer(), and DMA_configWrap(). All sizes are in terms of 16-bit words.

DMA_enableInterrupt(), DMA_disableInterrupt(), and DMA_setInterruptMode() configure a channel interrupt that will be generated either at the beginning or the end of a transfer. An additional overrun error interrupt that is ORed into the channel interrupt signal can be configured using DMA_enableOverrunInterrupt(), and DMA_disableOverrunInterrupt(). This error can be cleared using DMA_clearErrorFlag().

When configuration is complete, DMA_startChannel() can be called to start the DMA channel running and it will wait for the first trigger. To halt the operation of the channel DMA_stopChannel() may be used.

The code for this module is contained in driverlib/dma.c, with driverlib/dma.h containing the API declarations for use by applications.