dma.h

Direct Memory Access (DMA) support.

Types

struct stm32f1::dma_reg_map

STM32F1 DMA register map type.

Note that DMA controller 2 (register map base pointer DMA2_BASE) only supports channels 15.

struct stm32f2_f4::dma_reg_map

STM32F2-F4 DMA register map type.

struct dma_dev

DMA device type.

struct dma_handler_config
enum stm32f1::dma_mode_flags

Deprecated STM32F1 mode flags for dma_setup_xfer().

Use dma_tube_cfg() instead.

See
dma_tube_cfg()

Values:

DMA_MEM_2_MEM = 1 << 14

Memory to memory mode.

DMA_MINC_MODE = 1 << 7

Auto-increment memory address.

DMA_PINC_MODE = 1 << 6

Auto-increment peripheral address.

DMA_CIRC_MODE = 1 << 5

Circular mode.

DMA_FROM_MEM = 1 << 4

Read from memory to peripheral.

DMA_TRNS_ERR = 1 << 3

Interrupt on transfer error.

DMA_HALF_TRNS = 1 << 2

Interrupt on half-transfer.

DMA_TRNS_CMPLT = 1 << 1

Interrupt on transfer completion.

enum dma_xfer_size

Source and destination transfer sizes.

Use these when initializing a struct dma_tube_config.

See

struct dma_tube_config

dma_tube_cfg

Values:

DMA_SIZE_8BITS = 0

8-bit transfers

DMA_SIZE_16BITS = 1

16-bit transfers

DMA_SIZE_32BITS = 2

32-bit transfers

enum dma_channel

DMA channels.

Notes:

  • This is also the dma_tube type for STM32F1.
  • Channel 0 is not available on all STM32 series.

See
dma_tube

Values:

DMA_CH0 = 0

Channel 0.

DMA_CH1 = 1

Channel 1.

DMA_CH2 = 2

Channel 2.

DMA_CH3 = 3

Channel 3.

DMA_CH4 = 4

Channel 4.

DMA_CH5 = 5

Channel 5.

DMA_CH6 = 6

Channel 6.

DMA_CH7 = 7

Channel 7.

enum dma_priority

DMA transfer priority.

Values:

DMA_PRIORITY_LOW = 0

Low priority.

DMA_PRIORITY_MEDIUM = 1

Medium priority.

DMA_PRIORITY_HIGH = 2

High priority.

DMA_PRIORITY_VERY_HIGH = 3

Very high priority.

enum dma_irq_cause

Encodes the reason why a DMA interrupt was called.

See
dma_get_irq_cause()

Values:

DMA_TRANSFER_COMPLETE

Transfer is complete.

DMA_TRANSFER_HALF_COMPLETE

Transfer is half complete.

DMA_TRANSFER_ERROR

Error occurred during transfer.

DMA_TRANSFER_DME_ERROR

Direct mode error occurred during transfer.

DMA_TRANSFER_FIFO_ERROR

FIFO error occurred during transfer.

dma_channel_reg_map

On STM32F1, dma_channel_reg_map is an alias for dma_tube_reg_map.

This is for backwards compatibility.

Devices

dma_dev *stm32f1::DMA1

STM32F1 DMA1 device.

dma_dev *stm32f1::DMA2

STM32F1 DMA2 device.

Functions

void dma_init(dma_dev *dev)

Initialize a DMA device.

Parameters
  • dev -

    Device to initialize.

void stm32f1::dma_setup_transfer(dma_dev * dev, dma_channel channel, __io void * peripheral_address, dma_xfer_size peripheral_size, __io void * memory_address, dma_xfer_size memory_size, uint32 mode)

Deprecated.

Use dma_tube_cfg() instead.

Set up a DMA transfer.

The channel will be disabled before being reconfigured. The transfer will have low priority by default. You may choose another priority before the transfer begins using dma_set_priority(), as well as performing any other configuration you desire. When the channel is configured to your liking, enable it using dma_enable().

See
dma_tube_cfg()
Side Effects:
Disables the given DMA channel.
See

dma_xfer_size

dma_mode_flags

dma_set_num_transfers()

dma_set_priority()

dma_attach_interrupt()

dma_enable()

Parameters
  • dev -

    DMA device.

  • channel -

    DMA channel.

  • peripheral_address -

    Base address of peripheral data register involved in the transfer.

  • peripheral_size -

    Peripheral data transfer size.

  • memory_address -

    Base memory address involved in the transfer.

  • memory_size -

    Memory data transfer size.

  • mode -

    Logical OR of dma_mode_flags

void dma_set_num_transfers(dma_dev *dev, dma_tube tube, uint16 num_transfers)

Set the number of data transfers on a DMA tube.

You may not call this function while the tube is enabled.

Parameters
  • dev -

    DMA device

  • tube -

    Tube through which the transfer will occur.

  • num_transfers -

    Number of DMA transactions to set.

void dma_set_priority(dma_dev *dev, dma_tube tube, dma_priority priority)

Set the priority of a DMA transfer.

You may not call this function while the tube is enabled.

Parameters
  • dev -

    DMA device

  • tube -

    DMA tube

  • priority -

    priority to set.

void dma_attach_interrupt(dma_dev * dev, dma_tube tube, void(*)(void) handler)

Attach an interrupt to a DMA transfer.

Interrupts are enabled using series-specific mode flags in dma_tube_cfg().

See

dma_tube_cfg()

dma_get_irq_cause()

dma_detach_interrupt()

Parameters
  • dev -

    DMA device

  • tube -

    Tube to attach handler to

  • handler -

    Interrupt handler to call when tube interrupt fires.

void dma_detach_interrupt(dma_dev *dev, dma_tube tube)

Detach a DMA transfer interrupt handler.

After calling this function, the given tube’s interrupts will be disabled.

Side Effects:
Clears the tube’s interrupt enable bits.
See
dma_attach_interrupt()
Parameters
  • dev -

    DMA device

  • tube -

    Tube whose handler to detach

dma_irq_cause dma_get_irq_cause(dma_dev *dev, dma_tube tube)

Discover the reason why a DMA interrupt was called.

You may only call this function within an attached interrupt handler for the given channel.

This function resets the internal DMA register state which encodes the cause of the interrupt; consequently, it can only be called once per interrupt handler invocation.

Return
Reason why the interrupt fired.
Side Effects:
Clears flags in dev’s interrupt status registers.
See

dma_attach_interrupt()

dma_irq_cause

Parameters
  • dev -

    DMA device

  • tube -

    Tube whose interrupt is being handled.

void dma_enable(dma_dev *dev, dma_tube tube)

Enable a DMA tube.

If the tube has been properly configured, calling this function allows it to start serving DMA requests.

See
dma_tube_cfg()
Parameters
  • dev -

    DMA device

  • tube -

    Tube to enable

void dma_disable(dma_dev *dev, dma_tube tube)

Disable a DMA channel.

Calling this function makes the tube stop serving DMA requests.

Parameters
  • dev -

    DMA device

  • tube -

    Tube to disable

Warning

doxygenfunction: Unable to resolve multiple matches for function “dma_set_mem_addr” with arguments (dma_dev *, dma_tube, __io void *) in doxygen xml output for project “project0” from directory: /home/docs/checkouts/readthedocs.org/user_builds/librambutan/checkouts/latest/docs/../doxygen/xml. Potential matches: 

- void dma_set_mem_addr(dma_dev  *, dma_tube, __io void *)
- static void stm32f2_f4::dma_set_mem_addr(dma_dev  *, dma_tube, __io void *)
void dma_set_per_addr(dma_dev * dev, dma_tube tube, __io void * address)

Set the base peripheral address where data will be read from or written to.

You must not call this function while the channel is enabled.

If the DMA peripheral size is 16 bits, the address is automatically aligned to a half-word. If the DMA peripheral size is 32 bits, the address is aligned to a word.

Parameters
  • dev -

    DMA Device

  • tube -

    Tube whose peripheral data register base address to set.

  • address -

    Peripheral memory base address to use.

dma_channel_regs(dev, ch)

On STM32F1, dma_channel_regs() is an alias for dma_tube_regs().

This is for backwards compatibility.

dma_is_channel_enabled

On STM32F1, dma_is_channel_enabled() is an alias for dma_is_enabled().

This is for backwards compatibility.

static uint8 stm32f1::dma_get_isr_bits(dma_dev *dev, dma_tube tube)
static void stm32f1::dma_clear_isr_bits(dma_dev *dev, dma_tube tube)

Register Map Base Pointers

DMA1_BASE

DMA controller 1 register map base pointer.

DMA2_BASE

DMA controller 2 register map base pointer.

Register Bit Definitions

Interrupt status register

DMA_ISR_TEIF7_BIT
DMA_ISR_HTIF7_BIT
DMA_ISR_TCIF7_BIT
DMA_ISR_GIF7_BIT
DMA_ISR_TEIF6_BIT
DMA_ISR_HTIF6_BIT
DMA_ISR_TCIF6_BIT
DMA_ISR_GIF6_BIT
DMA_ISR_TEIF5_BIT
DMA_ISR_HTIF5_BIT
DMA_ISR_TCIF5_BIT
DMA_ISR_GIF5_BIT
DMA_ISR_TEIF4_BIT
DMA_ISR_HTIF4_BIT
DMA_ISR_TCIF4_BIT
DMA_ISR_GIF4_BIT
DMA_ISR_TEIF3_BIT
DMA_ISR_HTIF3_BIT
DMA_ISR_TCIF3_BIT
DMA_ISR_GIF3_BIT
DMA_ISR_TEIF2_BIT
DMA_ISR_HTIF2_BIT
DMA_ISR_TCIF2_BIT
DMA_ISR_GIF2_BIT
DMA_ISR_TEIF1_BIT
DMA_ISR_HTIF1_BIT
DMA_ISR_TCIF1_BIT
DMA_ISR_GIF1_BIT
DMA_ISR_TEIF7
DMA_ISR_HTIF7
DMA_ISR_TCIF7
DMA_ISR_GIF7
DMA_ISR_TEIF6
DMA_ISR_HTIF6
DMA_ISR_TCIF6
DMA_ISR_GIF6
DMA_ISR_TEIF5
DMA_ISR_HTIF5
DMA_ISR_TCIF5
DMA_ISR_GIF5
DMA_ISR_TEIF4
DMA_ISR_HTIF4
DMA_ISR_TCIF4
DMA_ISR_GIF4
DMA_ISR_TEIF3
DMA_ISR_HTIF3
DMA_ISR_TCIF3
DMA_ISR_GIF3
DMA_ISR_TEIF2
DMA_ISR_HTIF2
DMA_ISR_TCIF2
DMA_ISR_GIF2
DMA_ISR_TEIF1
DMA_ISR_HTIF1
DMA_ISR_TCIF1
DMA_ISR_GIF1

Interrupt flag clear register

DMA_IFCR_CTEIF7_BIT
DMA_IFCR_CHTIF7_BIT
DMA_IFCR_CTCIF7_BIT
DMA_IFCR_CGIF7_BIT
DMA_IFCR_CTEIF6_BIT
DMA_IFCR_CHTIF6_BIT
DMA_IFCR_CTCIF6_BIT
DMA_IFCR_CGIF6_BIT
DMA_IFCR_CTEIF5_BIT
DMA_IFCR_CHTIF5_BIT
DMA_IFCR_CTCIF5_BIT
DMA_IFCR_CGIF5_BIT
DMA_IFCR_CTEIF4_BIT
DMA_IFCR_CHTIF4_BIT
DMA_IFCR_CTCIF4_BIT
DMA_IFCR_CGIF4_BIT
DMA_IFCR_CTEIF3_BIT
DMA_IFCR_CHTIF3_BIT
DMA_IFCR_CTCIF3_BIT
DMA_IFCR_CGIF3_BIT
DMA_IFCR_CTEIF2_BIT
DMA_IFCR_CHTIF2_BIT
DMA_IFCR_CTCIF2_BIT
DMA_IFCR_CGIF2_BIT
DMA_IFCR_CTEIF1_BIT
DMA_IFCR_CHTIF1_BIT
DMA_IFCR_CTCIF1_BIT
DMA_IFCR_CGIF1_BIT
DMA_IFCR_CTEIF7
DMA_IFCR_CHTIF7
DMA_IFCR_CTCIF7
DMA_IFCR_CGIF7
DMA_IFCR_CTEIF6
DMA_IFCR_CHTIF6
DMA_IFCR_CTCIF6
DMA_IFCR_CGIF6
DMA_IFCR_CTEIF5
DMA_IFCR_CHTIF5
DMA_IFCR_CTCIF5
DMA_IFCR_CGIF5
DMA_IFCR_CTEIF4
DMA_IFCR_CHTIF4
DMA_IFCR_CTCIF4
DMA_IFCR_CGIF4
DMA_IFCR_CTEIF3
DMA_IFCR_CHTIF3
DMA_IFCR_CTCIF3
DMA_IFCR_CGIF3
DMA_IFCR_CTEIF2
DMA_IFCR_CHTIF2
DMA_IFCR_CTCIF2
DMA_IFCR_CGIF2
DMA_IFCR_CTEIF1
DMA_IFCR_CHTIF1
DMA_IFCR_CTCIF1
DMA_IFCR_CGIF1

Channel configuration register

DMA_CCR_MEM2MEM_BIT
DMA_CCR_MINC_BIT
DMA_CCR_PINC_BIT
DMA_CCR_CIRC_BIT
DMA_CCR_DIR_BIT
DMA_CCR_TEIE_BIT
DMA_CCR_HTIE_BIT
DMA_CCR_TCIE_BIT
DMA_CCR_EN_BIT
DMA_CCR_MEM2MEM
DMA_CCR_PL
DMA_CCR_PL_LOW
DMA_CCR_PL_MEDIUM
DMA_CCR_PL_HIGH
DMA_CCR_PL_VERY_HIGH
DMA_CCR_MSIZE
DMA_CCR_MSIZE_8BITS
DMA_CCR_MSIZE_16BITS
DMA_CCR_MSIZE_32BITS
DMA_CCR_PSIZE
DMA_CCR_PSIZE_8BITS
DMA_CCR_PSIZE_16BITS
DMA_CCR_PSIZE_32BITS
DMA_CCR_MINC
DMA_CCR_PINC
DMA_CCR_CIRC
DMA_CCR_DIR
DMA_CCR_TEIE
DMA_CCR_HTIE
DMA_CCR_TCIE
DMA_CCR_EN