DMA Manager#

Overview#

The DMA Manager is a platform service module responsible for initializing and enabling the DMA peripheral(s) on the device, managing DMA interrupts, configuring channel prioritization (for example round-robin arbitration), and dynamically allocating DMA channels and sync bits at runtime.

Each DMA peripheral managed by the DMA Manager is associated with an ::sl_dma_handle_t variable. A default handle is provided and can be retrieved through sl_dma_manager_get_default_handle().

The DMA Manager is the single entry point for DMA channel ownership: any application or driver that needs a DMA channel must request it from the DMA Manager rather than touching the DMA peripheral directly. Once a channel has been allocated, the application is free to drive transfers on it through the DMA Channel Driver (its companion higher-level API) or directly through the low level sl_hal_ldma HAL, depending on the level of control needed. In either case the channel itself must always come from the DMA Manager.

Initialization#

When the dma_manager_init component is included in the project, all configured DMA peripheral instances are initialized automatically during system initialization through sl_dma_manager_instances_init(). Applications that do not use the SL Main component to auto-init can call sl_dma_manager_init() directly, passing either a user-allocated handle or NULL to let the DMA Manager allocate one internally.

The following snippet shows a manual initialization of the default DMA peripheral exposed by the HAL, with a caller-allocated handle:

static sl_dma_handle_t my_dma_handle;
sl_status_t status;

// Pass NULL as DMA peripheral to use the device's default DMA peripheral.
status = sl_dma_manager_init(&my_dma_handle, NULL);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}
static sl_dma_handle_t my_dma_handle;
sl_status_t status;

// Pass NULL as DMA peripheral to use the device's default DMA peripheral.
status = sl_dma_manager_init(&my_dma_handle, NULL);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

Examples#

Channel Allocation and Release#

The most common pattern is to allocate a channel from the default DMA Manager handle, use it, and release it once the transfer is done. Passing NULL as the DMA handle automatically targets the default handle of the default DMA peripheral:

uint8_t channel_nbr;
sl_status_t status;

status = sl_dma_manager_allocate_channel(NULL, &channel_nbr);
if (status != SL_STATUS_OK) {
  // Process the error condition (for example SL_STATUS_NO_MORE_RESOURCE).
}

// Use the channel, e.g. through the DMA Channel Driver or sl_hal_ldma.
// ...

status = sl_dma_manager_free_channel(NULL, channel_nbr);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}
uint8_t channel_nbr;
sl_status_t status;

status = sl_dma_manager_allocate_channel(NULL, &channel_nbr);
if (status != SL_STATUS_OK) {
  // Process the error condition (for example SL_STATUS_NO_MORE_RESOURCE).
}

// Use the channel, e.g. through the DMA Channel Driver or sl_hal_ldma.
// ...

status = sl_dma_manager_free_channel(NULL, channel_nbr);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

If the application needs to operate on an explicit handle (for example to query or share it with another module), the default handle can be retrieved with sl_dma_manager_get_default_handle():

sl_dma_handle_t *dma_handle = NULL;
uint8_t channel_nbr;
sl_status_t status;

status = sl_dma_manager_get_default_handle(&dma_handle);
if (status != SL_STATUS_OK || dma_handle == NULL) {
  // Process the error condition (no default handle initialized yet).
}

status = sl_dma_manager_allocate_channel(dma_handle, &channel_nbr);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

// ... use the channel ...

sl_dma_manager_free_channel(dma_handle, channel_nbr);
sl_dma_handle_t *dma_handle = NULL;
uint8_t channel_nbr;
sl_status_t status;

status = sl_dma_manager_get_default_handle(&dma_handle);
if (status != SL_STATUS_OK || dma_handle == NULL) {
  // Process the error condition (no default handle initialized yet).
}

status = sl_dma_manager_allocate_channel(dma_handle, &channel_nbr);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

// ... use the channel ...

sl_dma_manager_free_channel(dma_handle, channel_nbr);

Channel Allocation with Properties#

sl_dma_manager_allocate_channel_with_properties() lets the caller request specific channel features. The example below requests a high-priority channel that supports interleaved transfers:

uint8_t channel_nbr;
uint32_t properties = SL_DMA_CHANNEL_HIGH_PRIORITY
                    | SL_DMA_CHANNEL_SUPPORTS_INTERLEAVING;
sl_status_t status;

status = sl_dma_manager_allocate_channel_with_properties(NULL,
                                                         properties,
                                                         &channel_nbr);
if (status != SL_STATUS_OK) {
  // No channel matching the requested properties is available.
}
uint8_t channel_nbr;
uint32_t properties = SL_DMA_CHANNEL_HIGH_PRIORITY
                    | SL_DMA_CHANNEL_SUPPORTS_INTERLEAVING;
sl_status_t status;

status = sl_dma_manager_allocate_channel_with_properties(NULL,
                                                         properties,
                                                         &channel_nbr);
if (status != SL_STATUS_OK) {
  // No channel matching the requested properties is available.
}

Note that ::SL_DMA_CHANNEL_HIGH_PRIORITY and ::SL_DMA_CHANNEL_USES_ROUND_ROBIN are mutually exclusive.

Reserving a Specific Channel#

When a deterministic channel number is required (for example to match a fixed peripheral signal mapping), sl_dma_manager_reserve_channel() locks a specific channel out of the dynamic allocation pool. The channel is released with the same sl_dma_manager_free_channel() call as an allocated channel:

sl_status_t status;

status = sl_dma_manager_reserve_channel(NULL, 3);
if (status == SL_STATUS_NOT_AVAILABLE) {
  // Channel 3 is already reserved or allocated by someone else.
} else if (status != SL_STATUS_OK) {
  // Process the error condition.
}

// ... use channel 3 ...

sl_dma_manager_free_channel(NULL, 3);
sl_status_t status;

status = sl_dma_manager_reserve_channel(NULL, 3);
if (status == SL_STATUS_NOT_AVAILABLE) {
  // Channel 3 is already reserved or allocated by someone else.
} else if (status != SL_STATUS_OK) {
  // Process the error condition.
}

// ... use channel 3 ...

sl_dma_manager_free_channel(NULL, 3);

SYNC Bit Allocation#

SYNC bits used to synchronize DMA channels with peripheral or software events are managed the same way as channels:

uint8_t sync_nbr;
sl_status_t status;

status = sl_dma_manager_allocate_sync(NULL, &sync_nbr);
if (status != SL_STATUS_OK) {
  // Process the error condition (for example SL_STATUS_NO_MORE_RESOURCE).
}

// ... use the SYNC bit ...

sl_dma_manager_free_sync(NULL, sync_nbr);
uint8_t sync_nbr;
sl_status_t status;

status = sl_dma_manager_allocate_sync(NULL, &sync_nbr);
if (status != SL_STATUS_OK) {
  // Process the error condition (for example SL_STATUS_NO_MORE_RESOURCE).
}

// ... use the SYNC bit ...

sl_dma_manager_free_sync(NULL, sync_nbr);

IRQ Callback and User Data#

When driving a channel directly through the sl_hal_ldma HAL, the application can register a per-channel IRQ callback so the DMA Manager dispatches the IRQ to it on Series 2 (and forwards the registration to the Interrupt Manager on Series 3). A user-data pointer can be associated with the channel and retrieved from inside the callback through sl_dma_manager_retrieve_current_channel_user_data():

static volatile bool transfer_done;

static void my_dma_irq_callback(void)
{
  uint8_t channel_nbr;
  void *user_data;

  if (sl_dma_manager_retrieve_current_channel_user_data(&channel_nbr,
                                                        &user_data)
      == SL_STATUS_OK) {
    // 'user_data' is the pointer registered for 'channel_nbr'.
    *((volatile bool *)user_data) = true;
  }
}

void start_dma_transfer(void)
{
  uint8_t channel_nbr;

  sl_dma_manager_allocate_channel(NULL, &channel_nbr);
  sl_dma_manager_register_channel_user_data(NULL,
                                            channel_nbr,
                                            (void *)&transfer_done);
  sl_dma_manager_register_channel_irq_callback(NULL,
                                               channel_nbr,
                                               my_dma_irq_callback);

  // Configure and start the transfer through sl_hal_ldma.
  // ...
}
static volatile bool transfer_done;

static void my_dma_irq_callback(void)
{
  uint8_t channel_nbr;
  void *user_data;

  if (sl_dma_manager_retrieve_current_channel_user_data(&channel_nbr,
                                                        &user_data)
      == SL_STATUS_OK) {
    // 'user_data' is the pointer registered for 'channel_nbr'.
    *((volatile bool *)user_data) = true;
  }
}

void start_dma_transfer(void)
{
  uint8_t channel_nbr;

  sl_dma_manager_allocate_channel(NULL, &channel_nbr);
  sl_dma_manager_register_channel_user_data(NULL,
                                            channel_nbr,
                                            (void *)&transfer_done);
  sl_dma_manager_register_channel_irq_callback(NULL,
                                               channel_nbr,
                                               my_dma_irq_callback);

  // Configure and start the transfer through sl_hal_ldma.
  // ...
}

The DMA Channel Driver registers and dispatches its own per-channel callbacks; this flow is therefore only needed for users that drive the channel directly through the sl_hal_ldma HAL.

Modules#

sl_dma_handle