LDMA - Linked DMA#

Linked Direct Memory Access (LDMA) Peripheral API.

• Introduction

• Example

Introduction#

LDMA API functions provide full support for the LDMA peripheral.

LDMA supports these LDMA transfer types:

• Memory to memory.

• Memory to peripheral.

• Peripheral to memory.

• Peripheral to peripheral.

• Constant value to memory.

LDMA supports linked lists of LDMA descriptors allowing:

• Circular and ping-pong buffer transfers.

• Scatter-gather transfers.

• Looped transfers.

LDMA has some advanced features:

• Intra-channel synchronization (SYNC), allowing hardware events to pause and restart a LDMA sequence.

• Immediate-write (WRI), allowing LDMA to write a constant anywhere in the memory map.

• Complex flow control allowing if-else constructs.

Basic understanding of LDMA controller is assumed. Please refer to the reference manual for further details. The LDMA examples described in the reference manual are particularly helpful in understanding LDMA operations.

In order to use the LDMA controller, the initialization function sl_hal_ldma_init() must have been executed once (normally during system initialization).

LDMA transfers are initialized by a call to sl_hal_ldma_init_transfer(), transfer properties are controlled by the contents of sl_hal_ldma_transfer_init_t and sl_hal_ldma_descriptor_t structure parameters. The LDMA transfers can then be initiated by calling sl_hal_ldma_start_transfer(). The sl_hal_ldma_descriptor_t structure parameter may be a pointer to an array of descriptors, descriptors in array should be linked together as needed.

Transfer and descriptor initialization macros are provided for the most common transfer types. Due to the flexibility of LDMA peripheral, only a small subset of all possible initializer macros are provided, users should create new ones when needed.

Example#

A simple memory to memory transfer:

{
  // Enable bus clock.
  sl_clock_manager_enable_bus_clock(SL_BUS_CLOCK_LDMA0);

  // Two buffers used in the memory-to-memory transfers.
  static volatile uint32_t src[4];
  static volatile uint32_t dst[4];

  static const sl_hal_ldma_transfer_init_t transferCfg = SL_HAL_LDMA_TRANSFER_CFG_MEMORY();
  static const sl_hal_ldma_descriptor_t desc = SL_HAL_LDMA_DESCRIPTOR_SINGLE_M2M(SL_HAL_LDMA_CTRL_SIZE_WORD, src, dst, 4);

  // Initialize the LDMA with default values.
  sl_hal_ldma_init_t initCfg = SL_HAL_LDMA_INIT_DEFAULT;
  sl_hal_ldma_init(LDMA0, &initCfg);

  // Start the memory transfer.
  uint8_t channel = 0;
  sl_hal_ldma_init_transfer(LDMA0, channel, &transferCfg, &desc);
  sl_hal_ldma_start_transfer(LDMA0, channel);

   while (!sl_hal_ldma_transfer_is_done(LDMA0, channel)) {
     // Wait until the transfer is over.
   }
}

A linked list of three memory-to-memory transfers:

{
  // Enable bus clock.
  sl_clock_manager_enable_bus_clock(SL_BUS_CLOCK_LDMA0);

  // Two buffers used in the memory-to-memory transfers.
  static volatile uint32_t src[12];
  static volatile uint32_t dst[12];

  // A transfer consisting of 3 descriptors linked together and each descriptor
  // transfers 4 words from the source to the destination.
  static const sl_hal_ldma_transfer_init_t transferCfg = SL_HAL_LDMA_TRANSFER_CFG_MEMORY();
  static const sl_hal_ldma_descriptor_t descList[] =
  {
    SL_HAL_LDMA_DESCRIPTOR_LINKREL_M2M(SL_HAL_LDMA_CTRL_SIZE_WORD, src, dst, 4, 1),
    SL_HAL_LDMA_DESCRIPTOR_LINKREL_M2M(SL_HAL_LDMA_CTRL_SIZE_WORD, src + 4, dst + 4, 4, 1),
    SL_HAL_LDMA_DESCRIPTOR_SINGLE_M2M(SL_HAL_LDMA_CTRL_SIZE_WORD, src + 8, dst + 8, 4)
  };

  // Initialize the LDMA with default values.
  sl_hal_ldma_init_t initCfg = SL_HAL_LDMA_INIT_DEFAULT;
  sl_hal_ldma_init(LDMA0, &initCfg);

  // Start the linked memory transfer.
  uint8_t channel = 0;
  sl_hal_ldma_init_transfer(LDMA0, channel, &transferCfg, descList);
  sl_hal_ldma_start_transfer(LDMA0, channel);

   while (!sl_hal_ldma_transfer_is_done(LDMA0, channel)) {
     // Wait until the transfer is over.
   }
}

LDMA from serial port peripheral to memory:

{
  // Enable bus clock.
  sl_clock_manager_enable_bus_clock(SL_BUS_CLOCK_LDMA0);

  // Two buffer used in the transfer from EUSART0.
  static volatile uint8_t dst[4];

  // The LDMA transfer should be triggered by the EUSART0 RX data available signal.
  static const sl_hal_ldma_transfer_init_t eusart0RxTransfer =
  SL_HAL_LDMA_TRANSFER_CFG_PERIPHERAL(SL_HAL_LDMA_PERIPHERAL_SIGNAL_EUSART0_RXFL);

  // Transfer 4 bytes from the EUSART0 RX FIFO to memory.
  static const sl_hal_ldma_descriptor_t eusart0RxDesc =
  SL_HAL_LDMA_DESCRIPTOR_SINGLE_P2M(SL_HAL_LDMA_CTRL_SIZE_BYTE,  // Transfer size
                                  &EUSART0->RXDATA,              // Peripheral address
                                  dst,                           // Destination (SRAM)
                                  4);                            // Number of byte transfers

  // Initialize the LDMA with default values.
  sl_hal_ldma_init_t initCfg = SL_HAL_LDMA_INIT_DEFAULT;
  sl_hal_ldma_init(LDMA0, &initCfg);

  // Start the peripheral transfer which is triggered by the EUSART0
  // peripheral RXFL signal.
  uint8_t channel = 0;
  sl_hal_ldma_init_transfer(LDMA0, channel, &eusart0RxTransfer, &eusart0RxDesc);
  sl_hal_ldma_start_transfer(LDMA0, channel);

   while (!sl_hal_ldma_transfer_is_done(LDMA0, channel)) {
     // Wait until the transfer is over.
   }
}

Ping-pong LDMA from serial port peripheral to memory:

{
  // Enable bus clock.
  sl_clock_manager_enable_bus_clock(SL_BUS_CLOCK_LDMA0);

  // Two buffers used in the ping-pong transfer from EUSART0.
  static volatile uint8_t buffer0[5];
  static volatile uint8_t buffer1[5];

  // The LDMA transfer should be triggered by the EUSART0 RX data available signal.
  static const sl_hal_ldma_transfer_init_t eusart0RxTransfer =
  SL_HAL_LDMA_TRANSFER_CFG_PERIPHERAL(SL_HAL_LDMA_PERIPHERAL_SIGNAL_EUSART0_RXFL);

  // Both descriptors transfer 5 bytes from the EUSART0 RX data register into
  // one of the buffers. Note that the first descriptor uses a relative address
  // of 1 to link to the next descriptor, while the last descriptor uses a
  // relative address of -1 to link to the first descriptor.
  static const sl_hal_ldma_descriptor_t rxLoopDesc[] =
  {
    SL_HAL_LDMA_DESCRIPTOR_LINKREL_P2M(SL_HAL_LDMA_CTRL_SIZE_BYTE, &EUSART0->RXDATA, buffer0, 5, 1),
    SL_HAL_LDMA_DESCRIPTOR_LINKREL_P2M(SL_HAL_LDMA_CTRL_SIZE_BYTE, &EUSART0->RXDATA, buffer1, 5, -1)
  };

  // Initialize the LDMA with default values.
  sl_hal_ldma_init_t initCfg = SL_HAL_LDMA_INIT_DEFAULT;
  sl_hal_ldma_init(LDMA0, &initCfg);

  // Start the peripheral transfer which is triggered by the EUSART0
  // peripheral RXFL signal.
  uint8_t channel = 0;
  sl_hal_ldma_init_transfer(LDMA0, channel, &eusart0RxTransfer, rxLoopDesc);
  sl_hal_ldma_start_transfer(LDMA0, channel);
}

Note

• LDMA peripheral module does not implement LDMA interrupt handler. A template for an LDMA IRQ handler is included here as an example. For series 2, a single IRQ handler is shared by all channels.

  void LDMA_IRQHandler(void)
  {
    //Get all pending and enabled interrupts.
    uint32_t pending = sl_hal_ldma_get_enabled_pending_interrupts(LDMA);
  
    while (pending & LDMA_IF_ERROR) {
      // Loop here on an LDMA error to enable debugging.
    }
  
    // Iterate over all LDMA channels.
    for (uint32_t channel = 0; channel < DMA_CHAN_COUNT; channel++) {
      uint32_t mask = 0x1 << channel;
      if (pending & mask) {
        // Clear interrupt flag.
        sl_hal_ldma_clear_interrupts(LDMA, mask);
  
        // Do more stuff here, execute callbacks, etc.
      }
    }
  }
  

• For series 3, every channel has its own IRQ handler. Here is an example handler for channel 0.

  void LDMA0_CHNL0_IRQHandler(void)
  {
    // Get all pending and enabled interrupts.
    uint32_t pending = sl_hal_ldma_get_enabled_pending_interrupts(LDMA0);
  
    while (pending & LDMA_IF_ERROR0) {
      // Loop here on an LDMA error to enable debugging.
    }
  
    if (pending & LDMA_IF_DONE0) {
      // Clear interrupt flag.
      sl_hal_ldma_clear_interrupts(LDMA0, LDMA_IF_DONE0);
  
      // Do more stuff here, execute callbacks, etc.
    }
  }
  

Modules#

sl_hal_ldma_descriptor_t

sl_hal_ldma_init_t

sl_hal_ldma_transfer_init_t