4. Camera设备枚举与静态信息：static_camera_metadata的构建与关键Tag配置

在Camera HAL平台移植过程中，设备枚举与静态元数据（static_camera_metadata）的正确构建是上层Framework发现摄像头能力的基础。本章聚焦于HAL层如何向系统报告摄像头设备、如何填充static_camera_metadata，以及android.control.availableCapabilities等关键Tag的配置要点。

4.1 设备枚举流程与HAL接口

Android Camera HAL3 通过 camera_module_t 结构体中的 get_number_of_cameras() 和 get_camera_info() 完成设备枚举。平台移植时，必须确保这两个接口返回正确的摄像头数量和ID。

// HAL 模块定义示例
static camera_module_t HAL_MODULE_INFO_SYM = {
    .common = {
        .tag           = HARDWARE_MODULE_TAG,
        .module_api_version = CAMERA_MODULE_API_VERSION_2_4,
        .hal_api_version   = HARDWARE_HAL_API_VERSION,
        .id            = CAMERA_HARDWARE_MODULE_ID,
        .name          = "Example Camera HAL",
        .author        = "Platform Vendor",
        .methods       = &hal_module_methods,
    },
    .get_number_of_cameras = hal_get_number_of_cameras,
    .get_camera_info       = hal_get_camera_info,
    .set_callbacks         = hal_set_callbacks,
    .get_vendor_tag_ops    = NULL,
    .open_legacy           = NULL,
    .set_torch_mode        = hal_set_torch_mode,
    .init                  = NULL,
    .reserved              = {0},
};

4.2 static_camera_metadata 的构建策略

static_camera_metadata 是描述摄像头固定能力的只读数据块，在 HAL 的 getCameraCharacteristics() 中构建并返回。构建方式通常有两种：

以下是一个使用 android::CameraMetadata 工具类动态构建的代码片段：

// 在 getCameraCharacteristics() 中构建 static metadata
status_t getCameraCharacteristics(int32_t cameraId,
                                  camera_metadata_t **characteristics) {
    android::CameraMetadata metadata;

    // 1. 设置基本信息
    uint8_t facing = ANDROID_LENS_FACING_BACK;
    metadata.update(ANDROID_LENS_FACING, &facing, 1);

    // 2. 设置可用能力
    std::vector<uint8_t> capabilities = {
        ANDROID_REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE,
        ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR,
        ANDROID_REQUEST_AVAILABLE_CAPABILITIES_RAW,
    };
    metadata.update(ANDROID_REQUEST_AVAILABLE_CAPABILITIES,
                    capabilities.data(), capabilities.size());

    // 3. 设置输出流配置
    std::vector<int32_t> formats = {
        HAL_PIXEL_FORMAT_YCbCr_420_888,
        HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED,
        HAL_PIXEL_FORMAT_BLOB,
    };
    metadata.update(ANDROID_SCALER_AVAILABLE_FORMATS,
                    formats.data(), formats.size());

    // 4. 设置传感器信息
    android::Rect sensorInfoActiveArraySize = {0, 0, 1920, 1080};
    metadata.update(ANDROID_SENSOR_INFO_ACTIVE_ARRAY_SIZE,
                    &sensorInfoActiveArraySize, 1);

    *characteristics = metadata.release();
    return OK;
}

4.3 android.control.availableCapabilities 关键Tag详解

android.control.availableCapabilities 是 Framework 判断摄像头高级功能支持的核心依据。该Tag是一个枚举数组，每个枚举值代表一种能力。平台移植时，必须根据硬件实际能力精确声明。

4.4 关键Tag配置清单与依赖关系

除了 availableCapabilities，以下Tag在平台移植中极易出错，需要重点检查：

• ANDROID_SENSOR_INFO_PIXEL_ARRAY_SIZE：传感器有效像素阵列尺寸，必须与硬件实际分辨率一致。
• ANDROID_SENSOR_INFO_ACTIVE_ARRAY_SIZE：有效成像区域，通常小于等于像素阵列尺寸。
• ANDROID_SCALER_AVAILABLE_STREAM_CONFIGURATIONS：支持的输出流配置（分辨率+格式），必须覆盖所有应用场景。
• ANDROID_SCALER_AVAILABLE_MIN_FRAME_DURATIONS：各分辨率下的最小帧时长，直接影响帧率表现。
• ANDROID_CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES：自动曝光支持的FPS范围，与高速视频能力关联。
• ANDROID_STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES：人脸检测模式，需与ISP能力匹配。

4.5 设备枚举与元数据构建流程图

以下SVG图展示了从HAL设备枚举到static_metadata返回的完整流程：

4.6 平台移植常见兼容性问题排查

在平台移植过程中，以下问题出现频率最高，建议作为排查清单：

4.7 静态元数据验证工具与自动化测试

为减少人工排查的工作量，建议在平台移植阶段引入自动化验证工具：

• CTS Verifier Camera Test：Android 兼容性测试套件中的相机测试，可验证静态元数据的完整性和一致性。
• CameraMetadataValidator：开源工具，可对比实际硬件能力与声明的元数据是否匹配。
• 自定义 dump 脚本：通过 camera_metadata_t 的 dump 接口输出所有Tag，与基线配置进行 diff 对比。

// 使用 CameraMetadata 的 dump 方法输出所有Tag
void dumpCameraMetadata(const camera_metadata_t *metadata) {
    size_t entryCount = get_camera_metadata_entry_count(metadata);
    for (size_t i = 0; i < entryCount; i++) {
        camera_metadata_entry_t entry;
        if (get_camera_metadata_entry(metadata, i, &entry) == 0) {
            // 打印Tag ID和值
            ALOGI("Tag 0x%x: type=%d, count=%zu",
                  entry.tag, entry.type, entry.count);
        }
    }
}