3. HAL3 核心数据结构详解

Camera HAL3 接口围绕三个核心数据结构构建：camera3_device_t、camera3_callback_ops_t 和 camera3_stream_t。它们是 HAL 层与 Camera Service 之间通信的契约基础，理解其内存布局、生命周期和线程安全模型，是进行 Vendor 层适配与调试的前提。

3.1 camera3_device_t：HAL 设备抽象

camera3_device_t 是 HAL 层暴露给 Framework 的唯一设备句柄。它封装了所有操作相机设备的函数指针，其定义位于 hardware/libhardware/include/hardware/camera3.h。

// camera3_device_t 典型定义（简化）
typedef struct camera3_device {
    hw_device_t             common;
    camera3_device_ops_t    *ops;
    void                    *priv;
} camera3_device_t;

下图展示了 camera3_device_t 在 HAL 层与 Framework 之间的桥梁作用：

3.2 camera3_callback_ops_t：异步回调契约

camera3_callback_ops_t 是 HAL 层向 Framework 发送异步消息的唯一通道。它由 Camera Service 在 initialize() 时传入，HAL 层必须保存此指针并在合适的线程中调用其函数。

// camera3_callback_ops_t 定义
typedef struct camera3_callback_ops {
    void (*process_capture_result)(const struct camera3_callback_ops *,
                                    const camera3_capture_result_t *result);
    void (*notify)(const struct camera3_callback_ops *,
                   const camera3_notify_msg_t *msg);
} camera3_callback_ops_t;

下图展示了回调的异步数据流：

3.3 camera3_stream_t：数据流管道

camera3_stream_t 描述了一条从 HAL 到 Framework 的数据流。它定义了图像的格式、分辨率、使用场景以及 buffer 管理方式。在 configure_streams() 中，Framework 会传入一个 camera3_stream_t 数组，HAL 需要验证并设置 usage、max_buffers 等字段。

// camera3_stream_t 关键字段
typedef struct camera3_stream {
    int         stream_type;    // 输入/输出/双向
    uint32_t    width;
    uint32_t    height;
    int         format;         // 像素格式
    uint32_t    usage;          // Gralloc 使用标志（HAL 设置）
    uint32_t    max_buffers;    // HAL 请求的 buffer 数量
    void        *priv;          // Vendor 私有数据
    // ... 其他字段
} camera3_stream_t;

下图展示了多个 stream 在 HAL 中的配置关系：

3.4 三者协作关系总结

在 HAL3 的运行时模型中，这三个结构体构成了一个稳定的三角关系：

• camera3_device_t 是入口，通过 ops 接收 Framework 的同步调用（如 configure_streams、process_capture_request）。
• camera3_callback_ops_t 是出口，HAL 通过它异步返回结果和事件。
• camera3_stream_t 是数据通道，在 configure_streams 中建立，在每次 process_capture_result 中携带 buffer 返回。