配置manifest.xml和compatibility_matrix.xml

核心原则

1. 需求驱动供给：永远是先有需求 (compatibility_matrix.xml)，再根据需求去实现和声明供给 (manifest.xml)
2. 匹配原则：供给必须完全满足需求。这包括：
   ○ HAL：名称、版本（供给版本 >= 需求要求的最低版本）、接口名称、实例名称必须匹配
   ○ 内核：供给的内核版本必须 >= 需求要求的最低内核版本；所有要求的内核配置 (config) 必须存在且值正确
   ○ SePolicy：供给的版本必须 >= 需求的版本
3. 分区归属：
   ○ 框架的需求 (framework compatibility matrix) 位于 system 分区
   ○ 供应商的供给 (vendor manifest) 和 供应商的额外需求 (device compatibility matrix) 位于 vendor 或 odm 分区

配置步骤详解

第 一 步：确定框架的需求 (The Foundation)

首先，你必须清楚 Android 框架对你的设备有什么要求。这是你的“起点”

1. 找到模板和参考：
   ○ 源码路径：/hardware/interfaces/compatibility_matrices/
   ○ 查看 android.hardware 各种 HAL 的官方兼容性矩阵。例如，framework_compatibility_matrix.current.xml 包含了通用要求
   ○ 参考 AOSP 为类似设备（如 Pixel）提供的设备树 device/ 下的 manifest.xml 和 compatibility_matrix.xml 文件
2. 理解需求内容：
   ○ 打开 framework_compatibility_matrix.current.xml，你会看到类似下面的内容，这定义了框架对所有设备的基本要求：

   <compatibility-matrix version="2.0" type="framework"><hal format="hidl" optional="false"><name>android.hardware.vibrator</name><version>2.1</version><version>2.2</version></hal><hal format="hidl" optional="true"><name>android.hardware.nfc</name><version>1.2</version></hal><kernel version="5.4" /><sepolicy><kernel-sepolicy-version>30</kernel-sepolicy-version></sepolicy>
   </compatibility-matrix>

   ○ 这表示：所有设备必须 (optional="false") 提供至少 2.1 版本的 Vibrator HAL，并且如果提供了 NFC 功能 (optional="true")，则其 HAL 版本必须是 1.2。同时，内核版本不能低于 5.4，SePolicy 版本不能低于 30

第 二 步：编写供应商供给清单 (Vendor Manifest.xml)

根据第一步中框架的需求，你来编写 vendor/manifest.xml，声明你的设备具体提供了什么

1. 文件位置：通常位于 device/<manufacturer>/<device>/vendor/manifest.xml 或 vendor/<manufacturer>/<device>/manifest.xml
2. 为每个需求添加 HAL：

   对于框架要求的每个 optional="false" 的 HAL，你都必须提供一个对应的 <hal> 条目

   示例：声明 Vibrator HAL

   <manifest version="2.0" type="device"><!-- 声明一个 HIDL 格式的 Vibrator HAL，版本为 2.2 --><hal format="hidl"><name>android.hardware.vibrator</name><transport>hwbinder</transport> <!-- HIDL 使用 hwbinder --><version>2.2</version> <!-- 你实现的版本是 2.2，满足框架 2.1+ 的需求 --><interface><name>IVibrator</name> <!-- 接口名 --><instance>default</instance> <!-- 实例名 --></interface></hal><!-- 如果你的设备有 NFC，并且你实现了它，就声明它 --><hal format="hidl"><name>android.hardware.nfc</name><transport>hwbinder</transport><version>1.2</version><interface><name>INfc</name><instance>default</instance></interface></hal>
   </manifest>

3. 声明内核信息：

   内核信息通常由构建系统自动生成并注入到最终的 manifest.xml 中。你需要在 AndroidBoard.mk 或内核配置中确保内核版本和配置正确。

   手动声明示例（不常见）：

   <manifest version="2.0" type="device">...<kernel version="5.10.43"> <!-- 你设备实际运行的内核版本 --><config><key>CONFIG_ARM</key> <!-- 框架要求的内核配置 --><value>y</value>      <!-- 你必须确保此配置在你的内核中为 y --></config><config><key>CONFIG_CPU_FREQ_GOV_ONDEMAND</key><value>m</value>      <!-- 模块配置则为 m --></config></kernel><sepolicy><version>30.0</version> <!-- 你设备的 sepolicy 版本 --></sepolicy>
   </manifest>

第 三 步：处理设备特定需求 (Device Compatibility Matrix)

如果你的供应商实现有一些特殊的、框架没有要求的依赖，你需要创建一个 device compatibility matrix

1. 文件位置：通常与 vendor manifest.xml 在同一目录，名为 compatibility_matrix.xml
2. 常见场景：
   ○ 你的供应商 HAL 依赖一个特定的系统属性
   ○ 你的设备需要一个框架未要求的特定内核模块 (kmod)
   
   示例：供应商要求一个内核模块

   <!-- device/<manufacturer>/<device>/compatibility_matrix.xml -->
   <compatibility-matrix version="2.0" type="device"><kernel><version>5.10.43</version> <!-- 供应商实现需要的最低内核版本 --><condition>config:XXX</condition> <!-- 可选条件 --><kmod>my_custom_driver</kmod> <!-- 要求加载名为 my_custom_driver 的内核模块 --></kernel>
   </compatibility-matrix>

   这个文件的意思是：“我的供应商实现，需要内核版本为 5.10.43，并且需要系统确保 my_custom_driver.ko 这个内核模块被加载”

第 四 步：构建时检查与合成

在构建过程中，构建系统会执行关键步骤：

1. 检查：使用 hidl-gen 等工具验证 manifest.xml 的语法和有效性
2. 合成：使用 assemble_vintf 工具将：
   ○ 系统的 framework compatibility matrix
   ○ 供应商的 device compatibility matrix (如果有)
   ○ 供应商的 vendor manifest.xml
   ○ 其他分区的 manifest (如 odm)
   合并成一个最终的、设备级的兼容性描述文件。这个过程会进行一致性检查。如果发现不满足需求（例如，框架要求 Vibrator 2.1，但供应商只提供了 2.0），构建会失败

第 五 步：运行时验证

设备启动时，vintfd 守护进程会收集所有分区的 manifest 和 matrix 文件，在内存中执行同样的合成与检查。你可以使用以下命令验证：

# 查看完整的运行时 VINTF 信息
adb shell dumpsys vintf# 专门查看 HAL 列表
adb shell lshal# 检查设备是否符合 Treble 要求 (非常重要!)
adb shell getprop ro.treble.enabled # 结果为 true 则表示基本通过
adb shell cat /proc/version # 查看实际运行的内核版本

最佳实践与常见陷阱

• 从高版本开始：实现 HAL 时，尽量实现当前框架所要求的最高版本，以提高未来的兼容性
• 善用 optional="true"：对于框架中 optional="true" 的 HAL，只有你的设备有相应硬件时才需要实现和声明。没有则忽略
• 精确匹配：<name>, <interface>, <instance> 必须与 HAL 实现中的完全一致，大小写敏感
• 内核版本是关键：确保你声明的内核版本与实际运行的完全一致，否则 OTA 更新会失败
• 使用工具：充分利用 lshal 和 dumpsys vintf 来调试和验证你的配置
• OTA 测试：务必进行一次完整的 OTA 更新模拟测试，确保旧的供应商实现与新的系统框架兼容性矩阵匹配