3. Camera HAL 关键数据结构详解

Camera HAL 层通过一组标准化的数据结构实现 Framework 与硬件驱动的解耦。理解这些结构体是定位 HAL 层问题的前提。本章逐一拆解 camera_module_t、camera_device_t、camera3_device_t 和 camera3_callback_ops_t 的核心字段、生命周期与常见故障点。

3.1 数据结构总览与层级关系

四个结构体在 HAL 架构中分别承担模块加载、设备抽象、Camera 3 设备接口、回调通知的角色。其调用关系如下：

3.2 camera_module_t —— HAL 模块入口

camera_module_t 定义在 hardware/libhardware/include/hardware/camera_common.h 中，是 HAL 模块的顶层接口。Framework 通过 hw_get_module() 获取该结构体指针。

3.3 camera_device_t —— Camera 1.x 设备接口

camera_device_t 是 Camera 1.x HAL 的设备抽象层，在 Camera 3 HAL 中作为遗留兼容路径存在。其核心字段如下：

typedef struct camera_device {
    hw_device_t common;                    // 标准设备头
    camera_device_ops_t *ops;              // 操作函数表
    void *priv;                            // HAL 私有数据指针
} camera_device_t;

camera_device_ops_t 包含约 30 个函数指针，覆盖预览、拍照、参数设置、内存管理等。调试中重点关注：

• set_preview_window：绑定 Surface 到 HAL，失败会导致预览黑屏。
• start_preview / stop_preview：预览启停，未正确实现会导致 ANR。
• take_picture：拍照触发，返回 JPEG 数据。
• set_parameters：参数设置入口，格式错误会静默失败。

3.4 camera3_device_t —— Camera 3 核心设备接口

camera3_device_t 是 Camera 3.x HAL 的设备抽象，定义在 camera3.h 中。它替代了 camera_device_ops_t 的庞大函数表，采用精简的 ops 结构：

typedef struct camera3_device {
    hw_device_t common;                    // 标准设备头
    camera3_device_ops_t *ops;             // Camera 3 操作函数表
    void *priv;                            // HAL 私有数据
} camera3_device_t;

camera3_device_ops_t 包含以下关键函数：

3.5 camera3_callback_ops_t —— 结果回调通道

camera3_callback_ops_t 是 Framework 注册给 HAL 的回调接口，HAL 通过它返回捕获结果和通知事件。定义如下：

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;

两个回调函数的作用与故障模式：

• process_capture_result：返回一帧的 metadata 和图像缓冲区。如果 HAL 不调用此回调，Framework 会一直等待，导致预览超时 ANR。
• notify：发送错误、快门、请求完成等事件。例如 CAMERA3_MSG_ERROR_REQUEST 表示某请求处理失败。

3.6 数据结构对比总结

3.7 调试 Checklist

当遇到 Camera HAL 相关问题时，按以下顺序检查数据结构：

1. camera_module_t：确认 get_number_of_cameras 返回值 > 0，get_camera_info 填充了正确的设备方向。
2. camera3_device_t：确认 ops 指针非空，initialize 被调用且 callback_ops 已保存。
3. configure_streams：检查流格式、分辨率、usage 标志是否在 HAL 支持范围内。
4. process_capture_request：确认 HAL 在收到请求后调用了 process_capture_result。
5. camera3_callback_ops_t：确认 notify 回调在错误时被正确调用，且 process_capture_result 中的 status 字段为 OK。