4. Camera HAL 核心数据结构详解

Camera HAL 的架构围绕一组核心数据结构展开，它们定义了 HAL 模块的加载方式、设备生命周期、以及数据流的传输协议。理解这些结构体是进行 HAL 移植、调试和性能优化的基础。本章将深入剖析 camera_module_t、camera_device_t、camera3_device_t 和 camera3_stream_t 等关键结构体。

4.1 模块入口：camera_module_t

camera_module_t 是 HAL 层与 Android 框架交互的起点。它定义在 hardware/libhardware/include/hardware/camera_common.h 中，是 HAL 模块的标准接口。

4.2 设备抽象：camera_device_t 与 camera3_device_t

这两个结构体分别对应 Camera HAL v1 和 v3 的设备抽象。v1 是旧版接口，v3 是当前主流接口，支持更复杂的 pipeline 和 metadata 控制。

4.2.1 camera_device_t (HAL v1)

定义在 hardware/libhardware/include/hardware/camera.h，是 v1 接口的设备句柄。

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

其中 camera_device_ops_t 包含了 start_preview、stop_preview、take_picture 等传统操作函数。

4.2.2 camera3_device_t (HAL v3)

定义在 hardware/libhardware/include/hardware/camera3.h，是 v3 接口的核心设备结构体。

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

camera3_device_ops_t 是 v3 接口的灵魂，包含以下关键函数：

• initialize：初始化设备，传入框架回调 camera3_callback_ops_t。
• configure_streams：配置数据流，是 pipeline 建立的核心入口。
• register_stream_buffers：注册 stream 的 buffer 句柄（Android N 后已废弃）。
• process_capture_request：提交一次 capture 请求，包含 metadata 和 buffer 信息。
• flush：异步刷新所有正在处理的请求。
• dump：导出设备调试信息。

4.3 数据流核心：camera3_stream_t

camera3_stream_t 定义了单个数据流的属性，是 configure_streams 中传递的基本单元。它描述了框架期望 HAL 输出的图像格式、分辨率、使用场景等。

4.4 结构体关系总览

下图展示了 Camera HAL v3 中核心结构体的层次关系与数据流向：

4.5 实战：从结构体到代码实现

在 HAL 实现中，通常会将核心结构体封装到自定义的上下文对象中。以下是一个典型的 HAL v3 设备初始化片段：

// 自定义 HAL 设备上下文
typedef struct my_camera_device {
    camera3_device_t base;          // 必须作为第一个字段
    camera3_device_ops_t ops;       // 操作函数表
    int camera_id;
    void *sensor_handle;            // 传感器驱动句柄
    // ... 其他私有成员
} my_camera_device_t;

// 实现 open 函数
int my_camera_device_open(const struct hw_module_t* module,
                          const char* id,
                          struct hw_device_t** device) {
    my_camera_device_t *dev = malloc(sizeof(my_camera_device_t));
    memset(dev, 0, sizeof(*dev));

    // 填充标准设备头
    dev->base.common.tag = HARDWARE_DEVICE_TAG;
    dev->base.common.version = CAMERA_DEVICE_API_VERSION_3_5;
    dev->base.common.module = (hw_module_t*)module;
    dev->base.common.close = my_camera_device_close;

    // 绑定操作函数表
    dev->ops.initialize = my_initialize;
    dev->ops.configure_streams = my_configure_streams;
    dev->ops.process_capture_request = my_process_capture_request;
    dev->ops.flush = my_flush;
    dev->ops.dump = my_dump;
    dev->base.ops = &dev->ops;

    dev->camera_id = atoi(id);
    // ... 初始化硬件

    *device = &dev->base.common;
    return 0;
}

4.6 关键结构体对比总结