Skip to main content

DMA Transfer

Generic DMA transfer APIs between host and DPU memory. There are three types of memory for DMA transfer:

  • Host memory
  • DPU internal memory (e.g., FPGA DRAM)
  • DPU external memory (e.g., SoC DRAM)

Example​

Here is an example of submitting a DMA transfer from host memory to DPU internal memory.

example_dma_xfer.cc
#include <libmango.h>

#define SZ_2MB (2 * 1024 * 1024)

int main() {
  // Create a context for the first DPU device
  mango_context_h context;
  mango_context_create (&context);
  mango_context_set_hw_accel (context, MANGO_HW_ACCEL_DPU, 0);

  // Create a DMA core
  mango_dma_h dma;
  mango_dma_create (context, &dma);

  // Create a DMA channel
  mango_dma_channel_h channel;
  mango_dma_channel_create (dma, &channel);

  // Create a host huge page and get its data pointer
  mango_memory_create (MANGO_MEMORY_HUGE_MEM, SZ_2MB, SZ_2MB, &host_mem);
  mango_memory_get_data (host_mem, &host_data);

  // Create a DPU internal memory
  mango_memory_create (MANGO_MEMORY_DPU_MEM, SZ_2MB, SZ_2MB, &dpu_mem);

  // Manipulate host data
  ...

  // Submit host to DPU DMA transfer
  mango_dma_task_h task;
  mango_dma_task_alloc (dpu_mem, host_mem, SZ_2MB, &task);

  // Submit the task to the channel
  mango_dma_channel_submit (channel, task);
  ...

  // Cleanup
  mango_dma_task_free (task);
  mango_dma_channel_destroy (channel);
  mango_dma_destroy (dma);
  mango_context_destroy (context);

  return 0;
}

Datatypes​

mango_dma_h​

typedef void * mango_dma_h;

A handle of mango dma core.

mango_dma_channel_h​

typedef void * mango_dma_channel_h;

A handle of mango dma channel.

mango_dma_task_h​

typedef void * mango_dma_task_h;

A handle of mango dma task.

mango_dma_task_state_e​

typedef enum _mango_dma_task_state mango_dma_task_state_e;

Define DMA task states compatible with libmango DMA APIs.

Values

MANGO_DMA_TASK_STATE_IDLEDMA task is idle
MANGO_DMA_TASK_STATE_SUBMITTEDDMA task is submitted to channel
MANGO_DMA_TASK_STATE_COMPLETEDDMA task is completed
MANGO_DMA_TASK_STATE_ERRORDMA task has error

mango_dma_task_cb​

typedef void(*)(mango_dma_task_h dma, void *data) mango_dma_task_cb;

Define DMA task callbacks compatible with libmango DMA APIs.

Functions​

mango_dma_create​

mango_status_e mango_dma_create(mango_context_h context, mango_dma_h *dma)

Create a DMA handle.

Parameters

  • in context The context handle.
  • out dma The output DMA handle.

Returns 0 on success, Otherwise, a negative error value.

mango_dma_destroy​

mango_status_e mango_dma_destroy(mango_dma_h dma)

Destroy the DMA handle.

Parameters

  • in dma The DMA handle to be destroyed.

Returns 0 on success, Otherwise, a negative error value.

mango_dma_num_channels​

unsigned int mango_dma_num_channels(mango_dma_h dma)

Get the available number of DMA channels.

Parameters

  • in dma The DMA handle.

Returns The number of available DMA channels.

note

Multi-channel DMA engines return a value greater than 1, which provides concurrent DMA transfers as well as isolated performance per channel.

mango_dma_channel_create​

mango_status_e mango_dma_channel_create(mango_dma_h dma,
                                        mango_dma_channel_h *channel)

Create a DMA channel.

Parameters

  • in dma The DMA handle.
  • out channel The associated DMA channel handle.

Returns 0 on success, Otherwise, a negative error value.

mango_dma_channel_destroy​

mango_status_e mango_dma_channel_destroy(mango_dma_channel_h channel)

Destroy the DMA channel.

Parameters

  • in channel The DMA channel handle.

Returns 0 on success, Otherwise, a negative error value.

mango_dma_channel_submit​

mango_status_e mango_dma_channel_submit(mango_dma_channel_h channel,
                                        mango_dma_task_h task)

Submit a DMA memcpy task.

Parameters

  • in channel The DMA channel handle.
  • in task The DMA task handle.

Returns 0 on success, Otherwise, a negative error value.

note

This API guarantees that a DMA task has been successfully committed.

mango_dma_channel_submit_async​

mango_status_e mango_dma_channel_submit_async(mango_dma_channel_h channel,
                                              mango_dma_task_h task)

Submit a DMA memcpy task asynchronously.

Parameters

  • in channel The DMA channel handle.
  • in task The DMA task handle.

Returns 0 on success, Otherwise, a negative error value.

note

This API does NOT guarantee that a DMA task has been successfully committed. The API caller should check its DMA state or register proper callbacks.

mango_dma_channel_flush​

mango_status_e mango_dma_channel_flush(mango_dma_channel_h channel)

Flush all tasks in the DMA channel.

Parameters

  • in channel The DMA channel handle.

Returns 0 on success, Otherwise, a negative error value.

note

This API is a blocking call until all submitted DMA tasks are properly handled.

mango_dma_task_alloc​

mango_status_e mango_dma_task_alloc(mango_memory_h dst,
                                    mango_memory_h src,
                                    size_t size,
                                    mango_dma_task_h *task)

Allocate a DMA task.

Parameters

  • in dst The destination memory handle.
  • in src The source memory handle.
  • in size The number of bytes to be copied.
  • out task The allocated DMA task handle.

Returns 0 on success, Otherwise, a negative error value.

mango_dma_task_free​

mango_status_e mango_dma_task_free(mango_dma_task_h task)

Free a DMA task.

Parameters

  • in task The DMA task handle.

Returns 0 on success, Otherwise, a negative error value.

note

This API doesn't cancel a task already scheduled, but its callbacks will not be invoked.

mango_dma_task_get_state​

mango_status_e mango_dma_task_get_state(mango_dma_task_h task,
                                        mango_dma_task_state_e *state)

Get a DMA task state.

Parameters

  • in task The DMA task handle.
  • out state The current DMA state.

Returns 0 on success, Otherwise, a negative error value.

mango_dma_task_set_callbacks​

mango_status_e mango_dma_task_set_callbacks(mango_dma_task_h task,
                                            mango_dma_task_cb success,
                                            mango_dma_task_cb error,
                                            void *data)

Set DMA task callbacks.

Parameters

  • in task The DMA task handle.
  • in success The callback to be called when completed.
  • in error The callback to be called upon an error.
  • in data The callback data.

Returns 0 on success, Otherwise, a negative error value.

mango_dma_task_set_offsets​

mango_status_e mango_dma_task_set_offsets(mango_dma_task_h task,
                                          off_t dst_off,
                                          off_t src_off)

Set memory offsets of a DMA task.

Parameters

  • in task The DMA task handle.
  • in dst_off The offset of destination memory.
  • in src_off The offset of source memory.

Returns 0 on success, Otherwise, a negative error value.