Utils_SharedBufferState

SharedBufferState API 文档

概述

SharedBufferState 是 utilsCore 核心模块的关键结构体，提供跨线程共享的缓冲区状态管理，支持多种缓冲区类型（MMAP、DMA-BUF fd、DmaBufferPtr）。

职责

• 管理缓冲区的生命周期
• 提供跨线程共享的缓冲区状态
• 支持多种缓冲区类型
• 缓冲区有效性标志管理

适用场景

• 多线程间共享缓冲区
• 跨硬件模块的零拷贝数据传输
• Frame 数据的共享和传递
• MMAP 和 DMA-BUF 混合使用

依赖关系

• 依赖: DmaBuffer（DMA-BUF 创建）
• 被依赖: Frame, DmaBuffer, VisionPipeline 等上层模块

---

结构体分析

SharedBufferState 结构体

职责与用途

SharedBufferState 是共享缓冲区状态的封装结构体，提供：

• 三种缓冲区类型支持（MMAP、DMABUF_FD、DMABUF_OBJ）
• DMA-BUF fd 的生命周期管理
• 有效性标志管理（原子操作）
• 支持移动语义

设计模式

• RAII: 自动管理资源生命周期
• 原子操作: 使用 atomic 保证线程安全
• 移动语义: 支持移动，禁止拷贝

---

BufferBacking 枚举

缓冲区类型枚举，定义缓冲区的所有权类型。

enum class BufferBacking {
    NONE,         // 无缓冲区
    MMAP,         // 仅映射到用户态的指针，fd 归外部/驱动管理
    DMABUF_FD,    // 由本对象拥有的 dma-buf 裸 fd
    DMABUF_OBJ    // 由本对象拥有的 DmaBufferPtr（包含相关信息）
};

---

公共成员变量

backing - 缓冲区类型

BufferBacking backing = BufferBacking::NONE;

说明: 缓冲区的所有权类型

---

rawFd - DMA-BUF 裸文件描述符

int rawFd = -1;  // 当 backing == DMABUF_FD

说明: DMA-BUF 文件描述符，由 SharedBufferState 管理

---

dmabuf_ptr - DmaBuffer 智能指针

DmaBufferPtr dmabuf_ptr = nullptr;  // 当 backing == DMABUF_OBJ

说明: DmaBuffer 智能指针，由 SharedBufferState 管理

---

start - 映射地址

void* start = nullptr;  // 当 backing == MMAP

说明: 映射到用户态的地址

---

length - 缓冲区长度

size_t length = 0;

说明: 缓冲区的字节长度

---

valid - 有效性标志

std::atomic<bool> valid{false};

说明: 跨线程可读的有效性标志，使用原子操作保证线程安全

---

构造函数

私有默认构造函数

private:
SharedBufferState();

参数说明: 无

返回值: 无

所有权归属: 创建一个无效的 SharedBufferState 对象

注意事项:

1. 私有构造函数，只能由类内部使用
2. 创建一个无效的 SharedBufferState 对象（valid = false）
3. 用于内部实现，外部不应直接调用

裸指针/裸 fd 构造函数

SharedBufferState(int fd = -1, void* ptr = nullptr, size_t len = 0);

参数说明:

• fd (输入): DMA-BUF 文件描述符
• ptr (输入): 映射地址
• len (输入): 缓冲区长度

返回值: 无

所有权归属:

• 如果 ptr 不为空且 fd 为 -1，类型为 MMAP
• 如果 fd > 0 且 ptr 为空，类型为 DMABUF_FD，SharedBufferState 管理 fd

注意事项:

1. 自动设置 backing 类型
2. valid 初始化为 true

---

DmaBufferPtr 构造函数

SharedBufferState(DmaBufferPtr dmabuf_ptr_ = nullptr, void* ptr = nullptr, size_t len = 0);

参数说明:

• dmabuf_ptr_ (输入): DmaBuffer 智能指针
• ptr (输入): 映射地址
• len (输入): 缓冲区长度

返回值: 无

所有权归属:

• 如果 ptr 不为空且 dmabuf_ptr_ 为空，类型为 MMAP
• 如果 dmabuf_ptr_ 不为空且 ptr 为空，类型为 DMABUF_OBJ，SharedBufferState 管理 dmabuf_ptr

注意事项:

1. 如果 len 为 0，自动从 dmabuf_ptr 获取长度
2. 自动设置 backing 类型
3. valid 初始化为 true

---

公共 API 方法

dmabuf_fd() - 获取 DMA-BUF 文件描述符

int dmabuf_fd();

参数说明: 无

返回值:

• 成功: 返回 DMA-BUF 文件描述符
• 失败: 返回 -1

所有权归属:

• 返回的 fd 由 SharedBufferState 管理
• 不要手动关闭返回的 fd

注意事项:

1. 如果 dmabuf_ptr 不为空，返回 dmabuf_ptr->fd()
2. 否则返回 rawFd
3. 线程安全

使用例程:

// 获取 fd
int dma_fd = shared_state->dmabuf_fd();

if (dma_fd >= 0) {
    // 使用 fd 进行 RGA 处理
    rga_process(dma_fd, width, height);
}

---

析构函数

~SharedBufferState();

行为:

1. 将 valid 置为 false（使用 std::memory_order_release）
2. 根据 backing 类型释放对应资源：
   • MMAP: 调用 munmap(start, length)
   • DMABUF_FD: 调用 close(rawFd)
   • DMABUF_OBJ: 调用 dmabuf_ptr.reset()
3. 重置所有字段

---

所有权管理

移动语义

SharedBufferState(SharedBufferState&&) = default;
SharedBufferState& operator=(SharedBufferState&&) = default;

支持: 移动构造和移动赋值

禁止:

SharedBufferState(const SharedBufferState&) = delete;
SharedBufferState& operator=(const SharedBufferState&) = delete;

说明: 禁止拷贝，只能移动

---

线程安全说明

同步机制

• valid 标志: 使用 std::atomic<bool> 保证线程安全
• fd 访问: 只读访问，不需要额外同步

线程安全建议

• 跨线程传递: 使用 std::shared_ptr 跨线程传递
• valid 检查: 使用前检查 valid.load()
• 原子操作: valid 标志是线程安全的

---

典型使用场景

场景 1: MMAP 类型

// 映射 DMA-BUF 到用户空间
void* ptr = mmap(nullptr, size, PROT_READ | PROT_WRITE, MAP_SHARED, dma_fd, 0);

// 创建 SharedBufferState（MMAP 类型）
auto shared_state = std::make_shared<SharedBufferState>(-1, ptr, size);

// 使用
if (shared_state->valid.load()) {
    process_buffer(shared_state->start, shared_state->length);
}

// 析构时自动 munmap

场景 2: DMA-BUF fd 类型

// 创建 SharedBufferState（DMABUF_FD 类型）
auto shared_state = std::make_shared<SharedBufferState>(dma_fd);

// 使用
if (shared_state->valid.load()) {
    int fd = shared_state->dmabuf_fd();
    rga_process(fd, width, height);
}

// 析构时自动 close(dma_fd)

场景 3: DmaBufferPtr 类型

// 创建 DmaBuffer
auto dma_buffer = DmaBuffer::create(1920, 1080, DRM_FORMAT_NV12);

// 创建 SharedBufferState（DMABUF_OBJ 类型）
auto shared_state = std::make_shared<SharedBufferState>(dma_buffer);

// 使用
if (shared_state->valid.load()) {
    int fd = shared_state->dmabuf_fd();
    rga_process(fd, width, height);
}

// 析构时自动释放 dma_buffer

场景 4: Frame 使用

// CameraController 创建 Frame
Frame frame(shared_state);

// 检查有效性
if (frame.sharedState(0) && frame.sharedState(0)->valid.load()) {
    int fd = frame.dmabuf_fd(0);
    rga_process(fd, width, height);
}

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

场景 5: 跨线程传递

// 线程 1: 创建 SharedBufferState
auto shared_state = std::make_shared<SharedBufferState>(dma_fd);

// 传递给线程 2
std::thread t1([shared_state]() {
    if (shared_state->valid.load()) {
        int fd = shared_state->dmabuf_fd();
        process_buffer(fd);
    }
});

t1.join();

---

注意事项

1. 三种类型: 支持 MMAP、DMABUF_FD、DMABUF_OBJ 三种类型
2. 禁止拷贝: 只支持移动，禁止拷贝
3. valid 标志: 使用前检查 valid.load()
4. 资源管理: 析构时自动释放对应资源
5. 线程安全: valid 标志使用原子操作
6. 跨线程传递: 使用 std::shared_ptr 跨线程传递
7. dmabuf_fd(): 根据 backing 类型返回对应的 fd
8. RAII: 自动管理资源生命周期

---

相关文档

• DmaBuffer - DMA-BUF 缓冲区
• Frame - 帧数据接口
• Utils 模块总览

---

参考资料

• Linux DMA-BUF
• Linux mmap