2. HAL3接口标准详解：核心结构体定义与职责

Android Camera HAL3 接口是 CameraProvider 与底层硬件驱动之间的核心契约。理解 camera3_device_ops_t 和 camera3_callback_ops_t 等关键结构体，是掌握 HAL3 通信原理和进行故障排查的基础。本章将深入剖析这些结构体的字段定义、职责以及它们在相机流水线中的交互关系。

2.1 核心结构体总览

HAL3 接口围绕几个关键结构体展开，它们共同定义了 Camera HAL 设备的行为和与框架的通信方式。下表列出了最核心的结构体及其主要职责：

2.2 camera3_device_ops_t：HAL 设备操作接口

camera3_device_ops_t 是 HAL 设备向 CameraService 提供的函数指针表。CameraService 通过调用这些函数来配置 HAL 设备、下发捕获请求、以及控制设备状态。该结构体是 HAL3 接口中最重要的“下行”通道。

2.2.1 关键函数指针定义与职责

2.2.2 结构体定义示例

typedef struct camera3_device_ops {
    int (*initialize)(const struct camera3_device *,
                      const camera3_callback_ops_t *callback_ops);

    int (*configure_streams)(const struct camera3_device *,
                             camera3_stream_configuration_t *stream_list);

    const camera_metadata_t* (*construct_default_request_settings)(
            const struct camera3_device *, int type);

    int (*process_capture_request)(const struct camera3_device *,
                                   camera3_capture_request_t *request);

    void (*get_metadata_vendor_tag_ops)(const struct camera3_device *,
                                        vendor_tag_query_ops_t *ops);

    void (*dump)(const struct camera3_device *, int fd);

    int (*flush)(const struct camera3_device *);

    /* ... 其他函数指针 ... */
} camera3_device_ops_t;

2.3 camera3_callback_ops_t：框架回调接口

camera3_callback_ops_t 是 CameraService 提供给 HAL 设备的回调函数指针表。HAL 设备通过调用这些回调函数，将处理结果、事件通知和错误信息异步地返回给框架。这是 HAL3 接口中最重要的“上行”通道。

2.3.1 关键函数指针定义与职责

2.3.2 结构体定义示例

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;

2.4 camera3_stream_t：数据流描述

camera3_stream_t 用于描述一个数据流，例如预览流、拍照流或录像流。在 configure_streams 调用中，框架会传入一个 camera3_stream_t 数组，HAL 需要根据硬件能力确认或修改每个流的配置。

2.4.1 关键字段

2.5 camera3_capture_request_t 与 camera3_capture_result_t：请求与结果

这两个结构体构成了 HAL3 流水线的核心数据单元。框架通过 camera3_capture_request_t 下发请求，HAL 通过 camera3_capture_result_t 返回结果。

2.5.1 camera3_capture_request_t 关键字段

2.5.2 camera3_capture_result_t 关键字段

2.6 结构体交互流程总结

理解这些核心结构体的交互流程，是掌握 HAL3 通信原理的关键。以下是一个典型的请求-响应流程：

1. 初始化： CameraService 调用 camera3_device_ops_t->initialize，传入 camera3_callback_ops_t 指针。HAL 保存此指针。
2. 配置流： CameraService 调用 camera3_device_ops_t->configure_streams，传入包含 camera3_stream_t 数组的配置。HAL 确认或修改流配置。
3. 下发请求： CameraService 调用 camera3_device_ops_t->process_capture_request，传入 camera3_capture_request_t。
4. 异步处理： HAL 处理请求，可能涉及 ISP、3A 算法等。
5. 回调结果： HAL 通过保存的 camera3_callback_ops_t->process_capture_result 返回 camera3_capture_result_t。同时，通过 camera3_callback_ops_t->notify 发送事件通知（如快门事件）。
6. 重复步骤 3-5： 持续进行，直到设备关闭或发生错误。