4. HAL3核心数据结构：camera3_device_t、camera3_callback_ops_t、camera3_stream_t详解

在HAL3架构中，camera3_device_t、camera3_callback_ops_t和camera3_stream_t是驱动与框架交互的三大核心数据结构。它们分别定义了设备操作接口、异步回调契约以及数据流配置规范。理解这三者的关系与字段含义，是进行高通平台HAL3适配的首要前提。

4.1 camera3_device_t：设备操作接口

camera3_device_t 是HAL3中代表单个Camera设备的结构体，它继承自 hw_device_t，并扩展了HAL3特有的操作函数指针。框架通过该结构体调用底层驱动完成初始化、配置流、捕获请求等核心操作。

4.1.1 结构体定义与关键字段

typedef struct camera3_device {
    hw_device_t common;                     // 继承自硬件抽象层基础结构
    camera3_device_ops_t *ops;              // 操作函数指针集合
    void *priv;                             // 私有数据指针，指向高通平台的自定义设备上下文
} camera3_device_t;

4.1.2 camera3_device_ops_t 核心函数指针

camera3_device_ops_t 是实际干活的地方，包含以下关键函数指针：

• initialize：传入 camera3_callback_ops_t，建立框架到HAL的回调通道。
• configure_streams：接收 camera3_stream_configuration_t，配置数据流管道。
• process_capture_request：接收 camera3_capture_request_t，下发拍照/预览请求。
• flush：清空所有未处理的请求，用于快速停止。
• dump：导出设备调试信息。

4.2 camera3_callback_ops_t：异步回调契约

camera3_callback_ops_t 是框架注册给HAL3设备的回调函数集合。HAL3驱动通过这些回调将结果数据、事件和缓冲区异步通知给框架。它是HAL3“异步管道”模型的核心纽带。

4.2.1 结构体定义与回调函数

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

4.2.2 回调调用流程

以下SVG图展示了从请求下发到回调返回的完整异步流程：

4.3 camera3_stream_t：数据流配置

camera3_stream_t 描述单个数据流的属性，包括图像格式、分辨率、使用方向等。在 configure_streams 调用中，框架会传入一个 camera3_stream_t 数组，HAL3驱动需要根据这些配置分配内部缓冲区并设置ISP管道。

4.3.1 结构体定义与关键字段

typedef struct camera3_stream {
    int stream_type;                        // CAMERA3_STREAM_OUTPUT / INPUT / BIDIRECTIONAL
    uint32_t width;                         // 图像宽度（像素）
    uint32_t height;                        // 图像高度（像素）
    int format;                             // 像素格式（HAL_PIXEL_FORMAT_xxx）
    uint32_t usage;                         // 使用标志（GRALLOC_USAGE_xxx）
    uint32_t max_buffers;                   // HAL3驱动请求的最大缓冲区数
    const char *physical_camera_id;         // 物理Camera ID（多摄场景）
    void *priv;                             // 私有数据，高通用于存储stream句柄
    uint64_t reserved[7];                   // 保留字段
} camera3_stream_t;

4.3.2 流配置与管道关系

以下SVG图展示了一个典型预览+拍照场景下的流配置结构：

4.4 三者协作关系

在HAL3运行时，camera3_device_t、camera3_callback_ops_t和camera3_stream_t通过以下方式协作：

1. 初始化阶段：框架调用 camera3_device_t->ops->initialize()，传入 camera3_callback_ops_t 指针，HAL3驱动保存该指针用于后续回调。
2. 配置阶段：框架调用 configure_streams()，传入 camera3_stream_configuration_t（包含 camera3_stream_t 数组），HAL3驱动解析流参数并配置ISP。
3. 运行阶段：框架下发 process_capture_request，HAL3驱动填充输出缓冲区，通过 process_capture_result 回调返回结果。

4.5 常见适配问题与排查