DMA_README

DMA 模块 API 文档

概述

DMA 模块提供 DMA-BUF（Direct Memory Access Buffer）的管理功能，支持跨硬件模块的零拷贝数据传输。

模块组成

核心类

类	文档	说明
DmaBuffer	DmaBuffer	DMA-BUF 缓冲区

功能特性

DMA-BUF 管理

• 创建 DMA-BUF
• 导入现有 DMA-BUF
• 映射到用户空间
• 导出 fd 跨设备共享

零拷贝传输

• 跨硬件模块零拷贝
• fd 共享机制
• 引用计数管理

内存管理

• 自动生命周期管理
• 引用计数
• RAII

使用示例

创建 DMA-BUF

// 创建 DMA-BUF
auto buffer = DmaBuffer::create(1920, 1080, DRM_FORMAT_NV12);

if (!buffer) {
    fprintf(stderr, "Failed to create DMA-BUF\n");
}

// 获取 fd
int fd = buffer->fd();

// 获取 handle
uint32_t handle = buffer->handle();

// 获取尺寸
uint32_t width = buffer->width();
uint32_t height = buffer->height();

导入现有 DMA-BUF

// 导入现有 DMA-BUF
auto buffer = DmaBuffer::importFromFD(fd, width, height, format);

if (!buffer) {
    fprintf(stderr, "Failed to import DMA-BUF\n");
}
// 注意: 导入的 fd 设计上不受 DmaBuffer 控制, 需要手动close

映射到用户空间

// 映射 DMA-BUF
auto buffer = DmaBuffer::importFromFD(fd, width, height, format);

if (buffer) {
    // 访问数据
    uint8_t* data = buffer->map();

    size_t size = buffer->size();
    
    // 修改数据
    memset(data, 0, size);
    
    // 解除映射(RAII 析构时自动 unmap)
    buffer->unmap();
}

跨设备共享(伪代码)

// 创建 DMA-BUF
auto buffer = DmaBuffer::create(1920, 1080, DRM_FORMAT_NV12);
auto width  = buffer->width();
auto height = buffer->height();

// 传递给 V4L2
camera.setBuffer(buffer);

// 传递给 RGA
rga_process(buffer->fd(), width, height);

// 传递给 DRM
drm_display(buffer->fd(), width, height);

使用 SharedBufferState

// 创建 DMA-BUF
auto buffer = DmaBuffer::create(1920, 1080, DRM_FORMAT_NV12);

// 创建 SharedBufferState
auto shared_state = std::make_shared<SharedBufferState>(buffer->fd(), 2);

// 设置有效
shared_state->setValid(true);

// 传递给多个 Frame
Frame frame1(shared_state);
Frame frame2(shared_state);  // 共享同一个 fd

// Frame 析构时，引用计数自动减少

数据流

零拷贝流程

V4L2 → DMA-BUF → RGA → DMA-BUF → DRM

fd 共享流程

DmaBuffer → fd → 跨设备共享 → 引用计数管理

线程安全

• DmaBuffer 内部使用互斥锁保护 drm-fd 操作
• DmaBuffer 本身为只读对象, 仅在创建时修改
• 内存访问时非线程安全(需要通过fence同步)

性能优化

• 使用 DMA-BUF 实现零拷贝
• 使用引用计数管理生命周期
• 避免频繁创建和销毁 DMA-BUF
• 使用对象池管理 DMA-BUF

错误处理

• 检查创建函数的返回值(失败时返回nullptr)
• 检查 fd 是否有效
• 处理内存分配失败

相关模块

• Utils 模块 - 共享缓冲区状态
• V4L2 模块 - V4L2 设备采集
• RGA 模块 - RGA 图像处理
• DRM 模块 - DRM 显示

参考资料

• Linux DMA-BUF
• Rockchip DMA-BUF Guide

注意事项

1. fd 管理: fd 由 DmaBuffer 管理，不要手动关闭
2. 映射/解映射: 使用完毕后要解除映射
3. 生命周期: 使用 SharedBufferState 管理生命周期
4. 线程安全: fd 可以跨线程共享
5. 格式支持: 确保硬件支持对应的格式
6. 对齐要求: 注意 DMA-BUF 的对齐要求
7. 引用计数: 使用引用计数管理 fd 生命周期
8. 内存限制: 注意 DMA-BUF 的内存使用

版本历史

• v1.0 - 初始版本，支持基本 DMA-BUF 管理