Additional Resources

Stay organized with collections Save and categorize content based on your preferences.

The following resources provide details on code locations, tools, testing, and licensing.

Queryable code location

The code for the queryable vendor interface object goes to system/libvintf.

Handwriting manifest files and compatibility matrixes can be tough. Use the following tools to generate a boilerplate manifest/compatibility matrix to start from.

LSHAL

LSHAL is a device-side tool that lists all registered HALs to hwservicemanager and all available passthrough implementations (e.g. android.hardware.foo@1.0-impl.so) on the device. It can also generate a device manifest file based on the list:

adb shell su 0 /system/bin/lshal --init-vintf

Note the following:

  1. If a package is both registered to hwservicemanager and found as a passthrough HAL, <transport> is set to hwbinder.
  2. No SELinux version is written into the manifest. It is suggested that the element is injected via assemble_vintf as explained below.
  3. The generated HAL manifest file may be inaccurate. Human attention is required to fix inconsistencies between the device manifest and what vendor.img actually provides.

ASSEMBLE_VINTF

assemble_vintf is a host-side tool that:

  1. Verifies a compatibility matrix or manifest file is valid.
  2. Injects variables to manifests/compatibility matrixes available at build time and generates a new file that should be installed to the device.
  3. Checks compatibility between the generated file and its dual.
  4. If a manifest file is given, optionally generates a boilerplate compatibility matrix that is compatible with the manifest file.

Example: Generate device compatibility matrix from a framework manifest file

assemble_vintf -m --hals-only \
    -i system/libhidl/manifest.xml \
    -o device/manufacturer/device_name/compatibility_matrix.xml

Note that all HALs are set to optional="true".

Example: Generate a skeleton framework compatibility matrix from a device manifest file

assemble_vintf -m --hals-only \
    -i device/foo/bar/manifest.xml \
    -o path/to/place/output/compatibility_matrix.xml

Note that all HALs are set to optional="true".

Example: Generate device manifest XML files from variables

At build time, if the following variables are defined in device/manufacturer/device_name/BoardConfig.mk:

# Vendor manifest is named DEVICE_MANIFEST_FILE for legacy reasons.
DEVICE_MANIFEST_FILE := \
    device/manufacturer/device_name/vendor_manifest.xml
ODM_MANIFEST_FILES := \
    device/manufacturer/device_name/odm_manifest.xml
ODM_MANIFEST_SKUS := sku1 sku2
ODM_MANIFEST_SKU1_FILES := \
    device/manufacturer/device_name/odm_manifest_sku1.xml
ODM_MANIFEST_SKU2_FILES := \
    device/manufacturer/device_name/odm_manifest_sku2.xml

Then the following commands are executed (in the build system, modified to omit implementation details) to generate device manifest XML files:

# vendor manifest; only when DEVICE_MANIFEST_FILE is set
BOARD_SEPOLICY_VERS=$(BOARD_SEPOLICY_VERS) assemble_vintf \
    $(addprefix,-i ,$(DEVICE_MANIFEST_FILE)) \
    -o $(TARGET_OUT_VENDOR)/etc/vintf/manifest.xml

# ODM manifests
assemble_vintf \
    $(addprefix,-i ,$(ODM_MANIFEST_FILES)) \
    -o $(TARGET_OUT_ODM)/etc/vintf/manifest.xml

# ODM manifests for each sku
assemble_vintf \
    $(addprefix,-i ,$(ODM_MANIFEST_SKU1_FILES)) \
    -o $(TARGET_OUT_ODM)/etc/vintf/manifest_sku1.xml
assemble_vintf \
    $(addprefix,-i ,$(ODM_MANIFEST_SKU2_FILES)) \
    -o $(TARGET_OUT_ODM)/etc/vintf/manifest_sku2.xml

At runtime, the VINTF object combines vendor manifests and ODM manifests as the device manifest. See Device manifest for details.

Example: Generate device compatibility matrix XML files from variables

At build time, if the following variables are defined in device/manufacturer/device_name/BoardConfig.mk:

# vendor compatibility matrix is named DEVICE_MATRIX_FILE for legacy reasons.
DEVICE_MATRIX_FILE := \
    device/manufacturer/device_name/vendor_compatibility_matrix.xml \
    device/manufacturer/device_name/vendor_compatibility_matrix_additional.xml

Then the following commands are executed (in the build system, modified to omit implementation details) to generate device compatibility matrix XML files:

# vendor compatibility matrix; only when DEVICE_MATRIX_FILE is set
assemble_vintf \
    $(addprefix,-i ,$(DEVICE_MATRIX_FILE)) \
    -o $(TARGET_OUT_VENDOR)/etc/vintf/compatibility_matrix.xml

At runtime, the VINTF object uses the vendor compatibility matrix as the device compatibility matrix. See Device compatibility matrix for details.

Example: Generate framework manifest XML files from variables

The following variables may be defined in device/manufacturer/device_name/BoardConfig.mk:

# Device-specific system manifest is named DEVICE_FRAMEWORK_MANIFEST_FILE for legacy reasons
DEVICE_FRAMEWORK_MANIFEST_FILE := \
    device/manufacturer/device_name/device_system_manifest.xml

# Product manifest
PRODUCT_MANIFEST_FILES := \
    device/manufacturer/device_name/product_manifest.xml

The following commands are executed (in the build system, modified to omit implementation details) to generate framework manifest XML files:

# system manifest
assemble_vintf \
    -i system/libhidl/vintfdata/manifest.xml \
    $(addprefix,-i ,$(DEVICE_FRAMEWORK_MANIFEST_FILE)) \
    -o $(TARGET_OUT)/etc/vintf/manifest.xml

# product manifest
assemble_vintf \
    $(addprefix,-i ,$(PRODUCT_MANIFEST_FILES)) \
    -o $(TARGET_OUT_PRODUCT)/etc/vintf/manifest.xml

At runtime, the VINTF object combines the system manifest, system manifest fragments, product manifest, and product manifest fragments as the framework manifest. See Framework manifest for details.

Example: Generate framework compatibility matrix XML files from variables

The following variables may be defined in device/manufacturer/device_name/BoardConfig.mk to define the product FCM and device-specific system FCM:

DEVICE_PRODUCT_COMPATIBILITY_MATRIX_FILE := \
    device/manufacturer/device_name/product_compatibility_matrix.xml
# Device-specific system compatibility matrix is named
# DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE for legacy reasons.
DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE := \
    device/manufacturer/device_name/device_system_compatibility_matrix.xml

The system_ext FCM must be installed with Soong modules. The product FCM may also be installed with Soong modules; do not define DEVICE_PRODUCT_COMPATIBILITY_MATRIX_FILE if this method is used. In addition, multiple product FCM versions and system_ext FCM versions may be installed with Soong modules. Define the following:

  • Define a module in device/manufacturer/device_name/Android.bp. For example (replace system_ext with product for product FCM): 
    vintf_compatibility_matrix {
    name: "system_ext_compatibility_matrix.xml",
    stem: "compatibility_matrix.xml",
    system_ext_specific: true,
    // product_specific: true, // for product FCM
    srcs: [
        "system_ext_compatibility_matrix.xml",
    ],
}
  • Install the module to device/manufacturer/device_name/device.mk. For example: 
    PRODUCT_PACKAGES += system_ext_compatibility_matrix.xml

The following commands are executed (in the build system, modified to omit implementation details) to generate framework compatibility matrix XML files:

# common system compatibility matrix for each FCM version
BOARD_SEPOLICY_VERS=$(BOARD_SEPOLICY_VERS) \
POLICYVERS=$(POLICYVERS) \
BOARD_AVB_VBMETA_VERSION=$(BOARD_AVB_VBMETA_VERSION)
assemble_vintf \
    -i hardware/interfaces/compatibility_matrices/compatibility_matrix.empty.xml
    $(addprefix,-i ,$(DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE)) \
    -o $(TARGET_OUT)/etc/vintf/compatibility_matrix.device.xml

# framework compatibility matrixes at each FCM version
assemble_vintf
    -i hardware/interfaces/compatibility_matrices/compatibility_matrix.{level}.xml \
    -o $(TARGET_OUT)/etc/vintf/compatibility_matrix.{level}.xml \
    --kernel=...

# product framework compatibility matrix; only when
# DEVICE_PRODUCT_COMPATIBILITY_MATRIX_FILE is set or when the Soong module for
# product FCM is defined
assemble_vintf
    -i $(DEVICE_PRODUCT_COMPATIBILITY_MATRIX_FILE)
    -o $(TARGET_OUT_PRODUCT)/etc/vintf/compatibility_matrix.xml

# system_ext framework compatibility matrix; only when the Soong module for
# system_ext FCM is defined
assemble_vintf
    -i <srcs for the soong module>
    -o $(TARGET_OUT_SYSTEM_EXT)/etc/vintf/compatibility_matrix.xml

At runtime, the VINTF object combines a subset of system compatibility matrixes and product compatibility matrixes as the framework compatibility matrix. See Framework compatibility matrix for details.

Example: Generate the vendor manifest from fragments

Multiple vendor manifest fragments can be bundled at build time. For example:

<!-- device/manufacturer/device_name/manifest_common.xml -->
<manifest version="1.0" type="device">
    <!-- common HALs here -->
</manifest>

<!-- device/manufacturer/device_name/ir.xml -->
<manifest version="1.0" type="device">
    <hal>
        <name>android.hardware.ir</name>
        <version>1.0</version>
        <!-- other fields -->
    </hal>
</manifest>

# device/manufacturer/device_name/BoardConfig.mk
DEVICE_MANIFEST_FILE := device/manufacturer/device_name/manifest_common.xml
ifdef BOARD_ENABLE_IR
    DEVICE_MANIFEST_FILE += device/manufacturer/device_name/ir.xml
endif

Then, assemble_vintf adds the IR HAL to the vendor manifest if BOARD_ENABLE_IR is defined, and omits it if BOARD_ENABLE_IR is not defined. The following commands (modified to omit implementation details) are executed to generate the vendor manifest:

# if BOARD_ENABLE_IR is defined
BOARD_SEPOLICY_VERS=10000.0 assemble_vintf \
    -i device/manufacturer/device_name/manifest_common.xml:device/manufacturer/device_name/ir.xml \
    -o $(TARGET_OUT_VENDOR)/manifest.xml

# if BOARD_ENABLE_IR is not defined
BOARD_SEPOLICY_VERS=10000.0 assemble_vintf \
    -i device/manufacturer/device_name/manifest_common.xml \
    -o $(TARGET_OUT_VENDOR)/manifest.xml

For details, see:

assemble_vintf --help

Testing

The platform/system/libvintf project uses GTest for the serialization, deserialization, and compatibility checking.

Licensing

  • tinyxml2 (external/tinyxml2) for serializing/deserializing the object to/from XML. BSD-like license.
  • libselinux (external/selinux/libselinux) for getting policydb version. Public domain license.
  • libz (external/zlib) for decompressing /proc/config.gz. BSD-like license.
  • libvintf project uses Apache 2.0 license (with appropriate MODULE_LICENSE_APACHE2 and NOTICE files).