Additional Resources

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

Queryable code location

The code for the queryable vendor interface object goes to system/libvintf (see the queryable API).

Handwriting manifest files and compatibility matrices 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. A dummy <sepolicy>0.0</sepolicy> element exists at the end of the manifest. It is suggested that the element is deleted and 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 matrices 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 \
    -i system/libhidl/manifest.xml \
    -o device/manufacturer/device_name/compatibility_matrix.xml

Note the following:

  • Even though <vndk> entries are in the output compatibility matrix, they should be deleted and injected at build time.
  • All HALs are set to optional="true".

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

BOARD_SEPOLICY_VERS=10000.0 assemble_vintf -m \
    -i device/foo/bar/manifest.xml
    -o path/to/place/output/compatibility_matrix.xml

Note the following:

  • Even though <sepolicy> and <avb> are in the output compatibility matrix, they should be deleted and injected at build time.
  • All HALs are set to optional="true".

Example: Generate XML files from variables

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

DEVICE_MANIFEST_FILE := \
    device/manufacturer/device_name/manifest.xml
DEVICE_MATRIX_FILE := \
    device/manufacturer/device_name/compatibility_matrix.xml

Then the following commands (modified to omit implementation details) are executed to generate all XML files:

# device manifest; only when DEVICE_MANIFEST_FILE is set
BOARD_SEPOLICY_VERS=10000.0 assemble_vintf \
    -i device/manufacturer/device_name/manifest.xml \
    -o $(TARGET_OUT_VENDOR)/manifest.xml

# device compatibility matrix; only when DEVICE_MATRIX_FILE is set
assemble_vintf \
    -i device/manufacturer/device_name/compatibility_matrix.xml \
    -o $(TARGET_OUT_VENDOR)/compatibility_matrix.xml

# framework manifest
assemble_vintf
    -i system/libhidl/manifest.xml \
    -o $(TARGET_OUT)/manifest.xml \
    -c $(TARGET_OUT_VENDOR)/compatibility_matrix.xml

# framework compatibility matrix
BOARD_SEPOLICY_VERS=$(BOARD_SEPOLICY_VERS) \
POLICYVERS=$(POLICYVERS) \
BOARD_AVB_VBMETA_VERSION=$(BOARD_AVB_VBMETA_VERSION)
assemble_vintf \
    -i hardware/interfaces/compatibility_matrix.xml \
    -o $(TARGET_OUT)/compatibility_matrix.xml \
    -c $(TARGET_OUT_VENDOR)/manifest.xml \

Example: Generate device manifest from fragments

Multiple device 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 Ir HAL to device 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 device 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).

Caveats

It is also possible to determine the HALs at runtime by querying hwservicemanager (as lshal does). However:

  • hwservicemanager does not list passthrough services.
  • If a service has just crashed and is restarting, it may be missing from the query result.
  • It doesn't work for hot pluggable services.
  • hwservicemanager is not available in recovery mode (see below).

In recovery mode, the API to retrieve the vendor interface object must still be available to allow the device to check the vendor interface against the compatibility matrix again.