Skip to content

Linux DMA Engine Framework

Note

This topic introduces the overall Linux DMA Engine architecture and explains the role of the DMA Engine Framework.

Detailed discussions of DMA controller drivers, DMA channels, descriptors, transactions, callbacks, and driver integration are covered in the following chapters of the DMA Engine series.

Overview

The Linux DMA Engine Framework provides a hardware-independent interface for client drivers to perform DMA transfers.

Instead of directly accessing DMA controller registers, client drivers communicate with the DMA Engine Framework, which delegates hardware-specific operations to DMA controller drivers.

This abstraction allows the same client driver to operate across different SoCs without modification.

Why DMA Engine Exists

Different SoCs implement different DMA controllers.

For example:

  • Broadcom DMA
  • ARM PL330
  • DesignWare DMA
  • Xilinx DMA

Each controller has different:

  • Registers
  • Channel organization
  • Descriptor format
  • Interrupt handling
  • Hardware capabilities

Without a common framework, every client driver would require controller-specific implementations.

The DMA Engine Framework provides a unified programming interface that hides these hardware differences.

Coming Soon

Add the following overview diagrams after completing the DMA Engine series:

  • Linux DMA Engine Architecture (English)
  • Linux DMA Engine Architecture (Traditional Chinese)

These diagrams illustrate the layered architecture and responsibilities of:

  • Userspace
  • Client Driver
  • DMA Engine Framework
  • DMA Controller Driver
  • DMA Hardware

Architecture

The Linux DMA subsystem is organized into multiple layers.

Userspace
        │
        ▼
Client Driver
        │
        ▼
DMA Engine Framework
        │
        ▼
DMA Controller Driver
        │
        ▼
DMA Hardware

Responsibilities of each layer:

Layer Responsibility
Userspace Requests device I/O
Client Driver Requests DMA operations
DMA Engine Framework Provides common DMA APIs
DMA Controller Driver Controls DMA hardware
DMA Hardware Performs data transfers

Coming Soon

Add the following workflow diagrams after completing the DMA Engine series:

  • Linux DMA Engine Workflow Timeline (English)
  • Linux DMA Engine Workflow Timeline (Traditional Chinese)

These diagrams illustrate the execution timeline across:

  • Userspace
  • Client Driver
  • DMA Engine Framework
  • DMA Controller Driver
  • Peripheral

including:

  • Request Channel
  • Prepare Descriptor
  • Submit
  • Issue Pending
  • DMA Transfer
  • Completion IRQ
  • Callback

DMA Workflow

A typical DMA transfer follows the workflow below.

Request Channel
        │
        ▼
Prepare Descriptor
        │
        ▼
Submit
        │
        ▼
Issue Pending
        │
        ▼
DMA Running
        │
        ▼
Transfer Complete
        │
        ▼
Callback

Important observations:

  • Preparing a descriptor does not start DMA.
  • Submitting a descriptor only queues a transaction.
  • dma_async_issue_pending() starts DMA execution.
  • Completion is reported asynchronously through callbacks.

Major Objects

Three kernel objects appear throughout the DMA Engine Framework.

Object Purpose
struct dma_device Represents a DMA controller
struct dma_chan Represents one DMA channel
struct dma_async_tx_descriptor Describes one DMA transaction

The client driver normally interacts only with dma_chan and DMA Engine APIs.

Common DMA Engine APIs

Typical client driver workflow:

Stage API
Request Channel dma_request_chan()
Prepare Descriptor dmaengine_prep_xxx()
Submit Transaction dmaengine_submit()
Start DMA dma_async_issue_pending()
Stop DMA dmaengine_terminate_sync()
Release Channel dma_release_channel()

Detailed API usage is introduced in the following chapters.

Linux Source Layout

Important source files include:

Location Purpose
include/linux/dmaengine.h Public DMA Engine objects, callbacks, and APIs
drivers/dma/dmaengine.c DMA Engine Framework implementation
drivers/dma/of-dma.c Device Tree DMA provider support
drivers/dma/virt-dma.c Generic virtual DMA helper framework
drivers/dma/ Hardware-specific DMA controller drivers

Learning Path

The DMA Engine series is organized as follows:

Day Topic
Day99 DMA Engine Framework Overview
Day100 DMA Controller and DMA Channel
Day101 DMA Descriptor
Day102 DMA Transaction
Day103 DMA Completion and Callback
Day104 Async DMA
Day105 Linux Driver Integration
Day106 Practical DMA Driver