清单

VINTF 对象会汇总设备清单框架清单文件 (XML) 中的数据。这两个清单采用同一种格式,不过并非所有元素都适用于两者(有关架构方面的详细信息,请参阅清单文件架构)。

设备清单

设备清单(由设备提供)包含供应商清单和 ODM 清单。

  • 供应商清单会指定 SoC 通用的 HAL、SELinux 政策版本等。建议将其放置在 Android 源代码树的 device/VENDOR/DEVICE/manifest.xml 中,但可以使用多个 fragment 文件。有关详情,请参阅清单 fragment从 fragment 生成设备清单
  • ODM 清单列出了 ODM 分区中的产品专用 HAL。VINTF 对象会按以下顺序加载 ODM 清单:
    1. /odm/etc/vintf/manifest_SKU.xml(如果定义了 SKU,其中 SKU 是属性 ro.boot.product.hardware.sku 的值)
    2. /odm/etc/vintf/manifest.xml
    3. /odm/etc/manifest_SKU.xml(如果定义了 SKU
    4. /odm/etc/manifest.xml
  • 供应商清单列出了 vendor 分区中的产品专用 HAL。VINTF 对象会按以下顺序加载供应商清单:
    1. /vendor/etc/vintf/manifest_SKU.xml(如果定义了 SKU,其中 SKU 是属性 ro.boot.product.vendor.sku 的值)
    2. /vendor/etc/vintf/manifest.xml
  • VINTF 对象会按以下顺序加载设备清单:
    1. 如果该供应商清单存在,请合并以下内容:
      1. 供应商清单
      2. 可选的供应商清单 Fragment
      3. 可选的 ODM 清单
      4. 可选的 ODM 清单 Fragment
    2. 否则,如果存在 ODM 清单,将 ODM 清单与可选的 ODM 清单片段合并在一起。
    3. /vendor/manifest.xml(旧版,无片段)
    4. 最后,组合来自任何供应商 APEX 的清单 fragment。

    请注意:

    • 在旧版设备上,使用旧版供应商清单和 ODM 清单。ODM 清单可能会完全覆盖旧版供应商清单。
    • 在搭载 Android 9 的设备上,ODM 清单会与供应商清单合并。
    • 合并清单列表时,列表中后出现的清单可能会覆盖列表中先出现的清单中的标记,但前提是后出现的清单中的标记具有 override="true" 属性。例如,ODM 清单可能会覆盖供应商清单中的某些 <hal> 标记。请参阅以下属性 override 的文档。

此设置可让采用相同开发板的多个产品共用同一个供应商映像(用于提供通用 HAL),但具有不同的 ODM 映像(用于指定产品专用的 HAL)。

下面是一个示例供应商清单。

<?xml version="1.0" encoding="UTF-8"?>
<!-- Comments, Legal notices, etc. here -->
<manifest version="2.0" type="device" target-level="1">
    <hal>
        <name>android.hardware.camera</name>
        <transport>hwbinder</transport>
        <version>3.4</version>
        <interface>
            <name>ICameraProvider</name>
            <instance>legacy/0</instance>
            <instance>proprietary/0</instance>
        </interface>
    </hal>
    <hal>
        <name>android.hardware.nfc</name>
        <transport>hwbinder</transport>
        <version>1.0</version>
        <version>2.0</version>
        <interface>
            <name>INfc</name>
            <instance>nfc_nci</instance>
        </interface>
    </hal>
    <hal>
        <name>android.hardware.nfc</name>
        <transport>hwbinder</transport>
        <fqname>@2.0::INfc/default</fqname>
    </hal>
    <hal>
        <name>android.hardware.drm</name>
        <transport>hwbinder</transport>
        <version>1.0</version>
        <interface>
            <name>ICryptoFactory</name>
            <instance>default</instance>
        </interface>
        <interface>
            <name>IDrmFactory</name>
            <instance>default</instance>
        </interface>
        <fqname>@1.1::ICryptoFactory/clearkey</fqname>
        <fqname>@1.1::IDrmFactory/clearkey</fqname>
    </hal>
    <hal format="aidl">
        <name>android.hardware.light</name>
        <version>1</version>
        <fqname>ILights/default</fqname>
    </hal>
    <hal format="aidl">
        <name>android.hardware.power</name>
        <version>2</version>
        <interface>
            <name>IPower</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal format="native">
        <name>EGL</name>
        <version>1.1</version>
    </hal>
    <hal format="native">
        <name>GLES</name>
        <version>1.1</version>
        <version>2.0</version>
        <version>3.0</version>
    </hal>
    <sepolicy>
        <version>25.0</version>
    </sepolicy>
</manifest>

下面是一个示例 ODM 清单。

<?xml version="1.0" encoding="UTF-8"?>
<!-- Comments, Legal notices, etc. here -->
<manifest version="1.0" type="device">
    <!-- camera 3.4 in vendor manifest is ignored -->
    <hal override="true">
        <name>android.hardware.camera</name>
        <transport>hwbinder</transport>
        <version>3.5</version>
        <interface>
            <name>ICameraProvider</name>
            <instance>legacy/0</instance>
        </interface>
    </hal>
    <!-- NFC is declared to be disabled -->
    <hal override="true">
        <name>android.hardware.nfc</name>
        <transport>hwbinder</transport>
    </hal>
    <hal>
        <name>android.hardware.power</name>
        <transport>hwbinder</transport>
        <version>1.1</version>
        <interface>
            <name>IPower</name>
            <instance>default</instance>
        </interface>
    </hal>
</manifest>

下面是 OTA 软件包中的一个示例设备清单。

<?xml version="1.0" encoding="UTF-8"?>
<!-- Comments, Legal notices, etc. here -->
<manifest version="1.0" type="device" target-level="1">
    <!-- hals ommited -->
    <kernel version="4.4.176">
        <config>
            <key>CONFIG_ANDROID</key>
            <value>y</value>
        </config>
        <config>
            <key>CONFIG_ARM64</key>
            <value>y</value>
        </config>
    <!-- other configs ommited -->
    </kernel>
</manifest>

如需了解详情,请参阅设备清单开发

框架清单

框架清单文件由系统清单、产品清单和 system_ext 清单组成。

  • 系统清单(由 Google 提供)是手动生成的,位于 Android 源代码树的 /system/libhidl/manifest.xml 中。
  • 产品清单(由设备提供)列出了由 product 分区上安装的模块提供服务的 HAL。
  • system_ext 清单(由设备提供)列出了以下内容:
    • 由安装在 system_ext 分区中的模块提供服务的 HAL;
    • VNDK 版本;
    • 系统 SDK 版本。

与设备清单类似,可以使用多个 Fragment 文件。如需了解详情,请参阅清单 Fragment

下面是一个示例框架清单。

<?xml version="1.0" encoding="UTF-8"?>
<!-- Comments, Legal notices, etc. here -->
<manifest version="1.0" type="framework">
    <hal>
        <name>android.hidl.allocator</name>
        <transport>hwbinder</transport>
        <version>1.0</version>
        <interface>
            <name>IAllocator</name>
            <instance>ashmem</instance>
        </interface>
    </hal>
    <hal>
        <name>android.hidl.memory</name>
        <transport arch="32+64">passthrough</transport>
        <version>1.0</version>
        <interface>
            <name>IMapper</name>
            <instance>ashmem</instance>
        </interface>
    </hal>
    <hal>
        <name>android.hidl.manager</name>
        <transport>hwbinder</transport>
        <version>1.0</version>
        <interface>
            <name>IServiceManager</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal>
        <name>android.frameworks.sensorservice</name>
        <transport>hwbinder</transport>
        <version>1.0</version>
        <interface>
            <name>ISensorManager</name>
            <instance>default</instance>
        </interface>
    </hal>
    <hal max-level="5">
        <name>android.frameworks.schedulerservice</name>
        <transport>hwbinder</transport>
        <version>1.0</version>
        <interface>
            <name>ISchedulingPolicyService</name>
            <instance>default</instance>
        </interface>
    </hal>
    <vendor-ndk>
        <version>27</version>
    </vendor-ndk>
    <system-sdk>
        <version>27</version>
    </system-sdk>
</manifest>

清单 Fragment

在 Android 10 及更高版本中,您可以在构建系统中将清单条目与 HAL 模块相关联。这有助于在构建系统中有条件地包含 HAL 模块。

示例

在您的 Android.bpAndroid.mk 文件中,将 vintf_fragments 添加到任意模块。例如,您可以修改实现了 HAL 的模块 (my.package.foo@1.0-service-bar)。

... {
    ...
    vintf_fragments: ["manifest_foo.xml"],
    ...
}
LOCAL_MODULE := ...
LOCAL_VINTF_FRAGMENTS := manifest_foo.xml

在名为 manifest_foo.xml 的文件中,为此模块创建清单。在构建时,此清单会添加到设备中。在此处添加条目与在设备的主清单中添加条目相同。这样,客户端就可以使用该接口,并允许 VTS 识别设备上的 HAL 实现。此清单会执行常规清单执行的任何操作。

下面的示例实现了安装到 vendorodm 分区的 android.hardware.foo@1.0::IFoo/default。如果安装到 systemproductsystem_ext 分区,则改为使用 framework 类型,而不是 device 类型。

<manifest version="1.0" type="device">
    <hal format="hidl">
        <name>android.hardware.foo</name>
        <transport>hwbinder</transport>
        <fqname>@1.0::IFoo/default</fqname>
    </hal>
</manifest>

如果 HAL 模块已打包到供应商 APEX 中,请使用 prebuilt_etc 将其关联的 VINTF fragment 打包到同一 APEX 中,如 VINTF fragment 中所述。

清单文件架构

这一部分介绍了下列 XML 标记的含义。某些“必需”的标记可以在构建时由 assemble_vintf 写入,因此不一定要包含在 Android 源代码树中的源文件中。设备上的相应文件中必须有“必需”标记。

?xml
可选。只向 XML 解析器提供信息。
manifest.version
必需。清单的元版本。描述该清单中应该存在的元素。与 XML 版本无关。
manifest.type
必需。该清单的类型。对于设备清单文件,其值为 device;对于框架清单文件,其值为 framework
manifest.target-level
对于设备清单而言是必需的。用于指定相应设备清单要兼容的框架兼容性矩阵 (FCM) 版本,也称为设备的 Shipping FCM 版本。
manifest.hal
可选且可重复。单个 HAL(HIDL 或原生,如 GL),具体取决于 format 属性。
manifest.hal.format
可选。值可以是:
  • hidl:HIDL HAL。这是默认值。
  • aidlAIDL HAL。 仅适用于清单元版本 2.0 及更高版本。
  • native:本机 HAL。
manifest.hal.max-level
可选。仅对框架清单有效。如果设置了此标记,最高级别低于框架清单中的目标 FCM 版本的 HAL 会被停用。
manifest.hal.override
可选。值可以是:
  • true:覆盖其他具有相同 <name> 和主要版本的 <hal> 元素。如果此 <hal> 元素中没有 <version><fqname>,则 <hal> 元素会声明此 HAL 将被停用。
  • false:不覆盖其他具有相同 <name> 和主要版本的 <hal> 元素。
manifest.hal.name
必需。HAL 的完全限定软件包名称。多个 HAL 条目可以使用相同的名称。示例:
  • android.hardware.camera(HIDL 或 AIDL HAL)
  • GLES(本机 HAL,只需提供名称)
manifest.hal.transport
manifest.hal.format == "hidl" 时是必需的,在其他情况下则不得存在。指明从服务管理器查询来自该软件包的接口时使用什么传输模式。值可以是:
  • hwbinder:绑定模式
  • passthrough:透传模式
manifest.hal.format == "aidl" 时为可选,在其他情况下则不得存在。说明远程提供接口时使用什么传输模式。该值必须为:
  • inet:Inet 套接字
manifest.hal.transport.ipmanifest.hal.transport.port 必须用于进一步指定 Inet 连接信息。
manifest.hal.transport.arch
对于 passthrough 是必需的,对于 hwbinder 不得存在。描述正在提供的透传服务的位数。值可以是:
  • 32:32 位模式
  • 64:64 位模式
  • 32+64:两者
manifest.hal.transport.ip
对于 inet 是必需的,在其他情况下则不得存在。说明提供远程接口的 IP 地址。
manifest.hal.transport.port
对于 inet 是必需的,在其他情况下则不得存在。说明提供远程接口的端口。
manifest.hal.version
可选且可重复。清单中 hal 标记的版本。

对于 HIDL 和原生 HAL,格式为 MAJOR.MINOR。如需查看示例,请参阅 hardware/interfacesvendor/${VENDOR}/interfacesframeworks/hardware/interfacessystem/hardware/interfaces

HIDL 和原生 HAL 可以使用多个版本字段,前提是它们代表不同的主要版本,并且提供的每个主要版本只有一个次要版本。例如,3.1 和 3.2 不能共存,但 1.0 和 3.4 可以共存。这适用于所有同名的 hal 元素,除非 override="true"<version> 的值与 <fqname> 不相关联,因为 <fqname> 带有版本信息。

对于 AIDL HAL,不得在搭载 Android 11 及以下版本的设备上存在 <version><version> 必须是搭载 Android 12 及更高版本的设备上的一个整数。每个 (package, interface, instance) 元组最多只能有一个 <version>。如果不存在,则默认设置为 1<version> 的值与同一 <hal> 中的所有 <fqname> 相关联,因为 <fqname> 不带版本信息。
manifest.hal.interface
必需,可以在不重名的情况下重复。指明软件包中具有实例名称的接口。一个 <hal> 中可以有多个 <interface> 元素,但名称必须不同。
manifest.hal.interface.name
必需。接口的名称。
manifest.hal.interface.instance
必需且可重复。接口的实例名称。一个接口可以有多个实例,但不能有重复的 <instance> 元素。
manifest.hal.fqname
可选且可重复。为名称是 manifest.hal.name 的 HAL 指定实例的另一种方法。
  • 对于 HIDL HAL,格式为 @MAJOR.MINOR::INTERFACE/INSTANCE
  • 对于 AIDL HAL,格式为 INTERFACE/INSTANCE
manifest.sepolicy
必需。包含所有与 sepolicy 相关的条目。
manifest.sepolicy.version
对于设备清单而言是必需的。声明 SELinux 版本。格式为 SDK_INT.PLAT_INT
manifest.vendor-ndk
必需且可重复;对于框架清单而言是必需的。不得出现在设备清单中。多个 <vendor-ndk> 条目必须具有不同的 <version>。用于描述框架提供的一组 VNDK 快照。
manifest.vendor-ndk.version
必需。一个正整数,表示 VNDK 快照的版本。
manifest.vendor-ndk.library
可选,可以在不重名的情况下重复。用于描述框架为此 VNDK 供应商快照提供的一组 VNDK 库。值是库的文件名,例如 libjpeg.so,包含前缀 lib 和后缀 .so。不允许添加路径组件。
manifest.system-sdk.version
可选,可以在不重名的情况下重复;仅供框架清单使用。用于描述框架为供应商应用提供的一组系统 SDK 版本。
manifest.kernel
可选。描述有关内核的静态信息。
manifest.kernel.target-level
可选。描述内核分支。如果其值不存在,则默认其值为 manifest.target-level。必须大于等于 manifest.target-level。如需了解详情,请参阅内核匹配规则