From ea448b829ef3c5eefcadcd50fdf74c873eeadd86 Mon Sep 17 00:00:00 2001 From: Android Partner Docs Date: Wed, 8 Aug 2018 13:50:33 -0700 Subject: Docs: Changes to source.android.com - 207940242 One more fix: add header for Television Requirements. by Gina Dimino - 207936055 Update health README link. by Android Partner Docs - 207929938 Errata run for Android 9 CDD. by Gina Dimino - 207897850 Fix typos in Develop and Configure index pages by Kenneth Lau - 207813977 Devsite localized content from translation request 958913. by Android Partner Docs - 207813949 Devsite localized content from translation request 953118. by Android Partner Docs - 207813941 Devsite localized content from translation request 961934. by Android Partner Docs - 207813934 Devsite localized content from translation request 552632. by Android Partner Docs - 207813463 Update line numbers in links by Kenneth Lau - 207796341 Fixing the URL for the CDD link in versions file. by Gina Dimino - 207779392 Fix incorrect link by Kenneth Lau - 207777680 Update build numbers for 2018/08 releases by Android Partner Docs - 207775888 Update links to AOSP by Kenneth Lau - 207769948 Update links to AOSP by Kenneth Lau - 207763826 Clarify system for HIDL passthrough loading. by Android Partner Docs - 207733156 Fixing malformed links in html for kernel patches, adding... by Heidi von Markham - 207650104 Remove link by Heidi von Markham - 207640627 Tags for Android P. by Android Partner Docs - 207626815 Making link absolute by Clay Murphy - 207611166 Add Background Restrictions into Release Notes. by Christina Nguyen - 207606267 Fixing unclosed tag, reformatting for clarity by Heidi von Markham - 207604244 Fix malformed link by Clay Murphy - 207598416 adding subscript by Heidi von Markham - 207595049 Fix link in section 3.5.1. by Gina Dimino - 207590813 Fix broken link due to file path change by Christina Nguyen - 207588930 Update Power nav to include changes to mgmt page (broken ... by Christina Nguyen - 207588102 Separate out the Power Management article into "Applicati... by Christina Nguyen - 207583000 Fix broken links in HAL interface section by Kenneth Lau - 207582699 Put index files in place as redirects are not taking hold by Clay Murphy - 207575443 P release notes: fix bad links, remove "P release" by Mark Hecomovich - 207574657 Fix link typo from release notes to Carrier ID page by Christina Nguyen - 207559561 Integrate SAC next branch into mainline for Android P/9 p... by Mark Hecomovich - 207559252 Publish links to July localized versions within Japanese ... by Clay Murphy - 207122872 Devsite localized content from translation request 958912. by Android Partner Docs - 207122854 Devsite localized content from translation request 961384. by Android Partner Docs - 207007888 Add blurb about the SystemUpdateSampler app on SAC so use... by Christina Nguyen - 206862073 Update Camera HAL testing page by Kenneth Lau - 206805870 Devsite localized content from translation request 960240. by Android Partner Docs - 206805861 Devsite localized content from translation request 954945. by Android Partner Docs PiperOrigin-RevId: 207940242 Change-Id: I3dee204c744e2e6062ac56810b88aefabf84636a --- en/devices/architecture/vintf/comp-matrices.html | 95 ++++- en/devices/architecture/vintf/dm.html | 160 ++++++++ en/devices/architecture/vintf/fcm.html | 446 +++++++++++++++++++++++ en/devices/architecture/vintf/index.html | 32 +- en/devices/architecture/vintf/match-rules.html | 187 +++++++++- en/devices/architecture/vintf/objects.html | 212 +++++++---- en/devices/architecture/vintf/resources.html | 86 ++--- 7 files changed, 1052 insertions(+), 166 deletions(-) create mode 100644 en/devices/architecture/vintf/dm.html create mode 100644 en/devices/architecture/vintf/fcm.html (limited to 'en/devices/architecture/vintf') diff --git a/en/devices/architecture/vintf/comp-matrices.html b/en/devices/architecture/vintf/comp-matrices.html index 74589eef..01ac349c 100644 --- a/en/devices/architecture/vintf/comp-matrices.html +++ b/en/devices/architecture/vintf/comp-matrices.html @@ -26,19 +26,20 @@ the compatibility matrix schema. For match rules, see Matching Rules.

-

Framework compatibility matrix

+

Framework compatibility matrix +(FCM)

The framework compatibility matrix describes the requirements of the framework on the device it runs on. The matrix file is associated with the Android framework image (on system.img). It is expected the -requirements of the framework's compatibility matrix will be satisfied by the -device manifest (requirements enforced at launch and OTA time).

+requirements of the FCM will be satisfied by the device manifest (requirements +enforced at launch and OTA time).

-

Example framework compatibility matrix file:

+

Example FCM file:

 <?xml version="1.0" encoding="UTF-8"?>
 <!-- Comments, Legal notices, etc. here -->
-<compatibility-matrix version="1.0" type="framework">
+<compatibility-matrix version="1.0" type="framework" level="3">
     <hal>
         <name>android.hardware.camera</name>
         <version>1.0</version>
@@ -46,6 +47,7 @@ device manifest (requirements enforced at launch and OTA time).

         <interface>
             <name>ICameraProvider</name>
             <instance>default</instance>
+            <regex-instance>[a-z_]+/[0-9]+</regex-instance>
         </interface>
     </hal>
     <hal>
@@ -70,6 +72,16 @@ device manifest (requirements enforced at launch and OTA time).

         <version>1.1</version>
     </hal>
     <kernel version="3.18.51">
+        <!-- common configs -->
+    </kernel>
+    <kernel version="3.18.51">
+        <!-- arm specific configs -->
+        <condition>
+            <config>
+                <key>CONFIG_ARM</key>
+                <value type="tristate">y</value>
+            </config>
+        <condition>
         <config>
             <key>CONFIG_A</key>
             <value type="string"></value>
@@ -80,6 +92,7 @@ device manifest (requirements enforced at launch and OTA time).

         </config>
     </kernel>
     <kernel version="4.1.22">
+        <!-- common configs -->
         <config>
             <key>CONFIG_A</key>
             <value type="string">foo</value>
@@ -105,11 +118,14 @@ device manifest (requirements enforced at launch and OTA time).

 </compatibility-matrix>
-

Device compatibility matrix

+

For more details, see FCM +Lifecycle.

+ +

Device compatibility matrix (DCM)

The device compatibility matrix describes a set of requirements the device expects from the framework (requirements enforced at launch and OTA time).

-

Example device compatibility matrix file:

+

Example DCM file:

 <?xml version="1.0" encoding="UTF-8"?>
@@ -147,20 +163,28 @@ expects from the framework (requirements enforced at launch and OTA time).
             <instance>default</instance>
         </interface>
     </hal>
-    <xmlfile format="dtd" optional="false">
-        <name>sample_xml</name>
-        <version>1.0</version>
-    </xmlfile>
+    <vendor-ndk>
+        <version>27</version>
+    </vendor-ndk>
+    <system-sdk>
+        <version>27</version>
+    </system-sdk>
 </compatibility-matrix>

Compatibility matrix schema

+

This section describes the meaning of these XML tags. Some "required" tags +can be missing from the source file in Android source tree and written by +assemble_vintf +at build time. "Required" tags must be present in the corresponding files on the +device.

+
?xml
Optional. It only provides information to the XML parser.
compatibility-matrix.version
-
Required. Version of this compatibility matrix. Describes the elements -expected in the manifest. Unrelated to XML version.
+
Required. Meta-version of this compatibility matrix. Describes the elements +expected in the compatibility matrix. Unrelated to XML version.
compatibility-matrix.type
Required. Type of this compatibility matrix:
    @@ -168,6 +192,11 @@ expected in the manifest. Unrelated to XML version.
  • "framework": Framework compatibility matrix.
    • +
    manifest.level
    +
    Required for framework compatibility matrix. Specifies the Framework +Compatibility Matrix Version (FCM Version) of this file. Should not be +declared in device-specific framework compatibility matrix (i.e. +DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE).
    compatibility-matrix.hal
    Optional and can repeat. Lists a single HAL (HIDL or native) that is required by owner of the compatibility matrix (framework or device) to be @@ -184,7 +213,7 @@ there can be several HAL entries with the same name (implies "and" condition).
    compatibility-matrix.hal.optional
    Attribute is optional and defaults to false. States whether this HAL is optional to the owner of the compatibility matrix (framework or device). If a -<p;hal> entry is marked as optional, it means the owner can +<hal> entry is marked as optional, it means the owner can work with this HAL, if present, but does not require it to be present.
    compatibility-matrix.hal.name
    Required. Full package name of this HAL. Examples: @@ -204,11 +233,28 @@ device) expects.
    Required. Name of the interface.
    compatibility-matrix.hal.interface.instance
    Optional, can repeat. A list of required instances of this interface.
    +
    compatibility-matrix.hal.interface.regex-instance
    +
    Optional, can repeat. A list of required instance name patterns on this +interface. Use +Extended +Regular Expression format.
    +
    compatibility-matrix.kernel
    +
    Optional, can repeat. Specify a list of kernel configs that the framework +requires on each kernel version.
    +Multiple <kernel> with the same <version> can +exist to imply "and" relationship. Each <kernel> is a "fragment" +of the requirements that are enabled only when <conditions> are +met.
    compatibility-matrix.kernel.version
    Required. Kernel version. Format is -{version}.{major-revision}.{minor-revision}. Version and major -revision must match exactly, minor-revision defines the minimum LTS version of -the kernel the framework expects.
    +VERSION.MAJOR_REVISION.MINOR_REVISION. +Version and major revision must match exactly. Minor revision defines the +minimum LTS version of the kernel the framework expects. +
    compatibility-matrix.kernel.condition
    +
    Optional. Must not exist for the first <kernel> of each +version. Specifies a list of conditions. Only when the conditions are met are +the requirements stated in this <kernel> fragment is enabled. +
    compatibility-matrix.kernel.config
    Optional, can repeat. Lists CONFIG items that must be matched for this kernel version. Each CONFIG item is a key-value @@ -257,7 +303,22 @@ with.
    Optional; used only by the framework compatibility matrix. Declares the AVB version used to sign system.img.
    +
    compatibility-matrix.vendor-ndk
    +
    Optional; used only by the device compatibility matrix. Declares the +requirement of the VNDK vendor snapshot. If missing, no VNDK requirement is made +on the system image.
    +
    compatibility-matrix.vendor-ndk.version
    +
    Required. A positive integer that declares a VNDK version required by the +vendor image.
    +
    compatibility-matrix.vendor-ndk.library
    +
    Optional, can repeat. Declares a set of VNDK libraries required by the +vendor image. Same semantics as manifest.vendor-ndk.library.
    +
    compatibility-matrix.system-sdk.version
    +
    Optional, can repeat; used only by the device compatibility matrix. Declares +the requirement by vendor apps on System SDK versions. If missing, no System SDK +requirement is made on the system image.
    + diff --git a/en/devices/architecture/vintf/dm.html b/en/devices/architecture/vintf/dm.html new file mode 100644 index 00000000..091094dc --- /dev/null +++ b/en/devices/architecture/vintf/dm.html @@ -0,0 +1,160 @@ + + + Device Manifest Development + + + + {% include "_versions.html" %} + + + +

    When developing and releasing new devices, vendors can define and declare the +Target FCM Version in the device manifest (DM). When upgrading the vendor image +for old devices, vendors can choose to implement new HAL versions and increment +the Target FCM Version.

    + + + +

    Developing new devices

    +

    When defining the device Target FCM Version for new devices:

    + +
      +
    1. Leave DEVICE_MANIFEST_FILE and +PRODUCT_ENFORCE_VINTF_MANIFEST undefined.
      2. +
    2. Implement HALs for the Target FCM Version.
      3. +
    3. Write the correct device manifest file.
      4. +
    4. Write the Target FCM Version to device manifest file.
      5. +
    5. Set DEVICE_MANIFEST_FILE.
      6. +
    6. Set PRODUCT_ENFORCE_VINTF_MANIFEST to true.
      7. +
    + +

    Releasing new devices

    +

    When a new device is released, its initial Target FCM Version needs to be +determined and declared in the device manifest as the +"target-level" attribute in the top-level +<manifest> element.

    + +

    For example, devices launching with Android {{ androidPVersionNumber }} must +have Target FCM Version equal to 3 (the higher version available at this time). +To declare this in the device manifest:

    + +
    +<manifest version="1.0" type="device" target-level="3">
+    <!-- ... -->
+</manifest>
+
    + +

    Upgrading vendor image

    +

    When upgrading the vendor image for an old device, vendors can choose to +implement new HAL versions and increment the Target FCM Version.

    + +

    Upgrading HALs

    +

    During a vendor image upgrade, vendors can implement new HAL versions +provided that HAL name, interface name, and instance name are the same. For +example:

    + +
      +
    • Google Pixel 2 and Pixel 2 XL devices released with Target FCM Version +2, which implemented the required audio 2.0 HAL +android.hardware.audio@2.0::IDeviceFactory/default.
      • +
    • For the audio 4.0 HAL that released with Android +{{ androidPVersionNumber }}, Google Pixel 2 and Pixel 2 XL devices can use a +full OTA to upgrade to the 4.0 HAL, which implements +android.hardware.audio@4.0::IDeviceFactory/default.
      • +
    • Even though the compatibility_matrix.2.xml specifies audio 2.0 +only, the requirement on a vendor image with Target FCM Version 2 has been +loosened because the Android {{ androidPVersionNumber }} framework (FCM Version +3) considers audio 4.0 a replacement of audio 2.0 HAL in terms of functionality. +
      • +
    + +

    To summarize, given that compatibility_matrix.2.xml requires +audio 2.0 and compatibility_matrix.3.xml requires audio 4.0, the +requirements are as follows:

    + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FCM Version (System)Target FCM Version (Vendor)Requirements
    2 (8.1)2 (8.1)Audio 2.0
    3 ({{ androidPVersionNumber }})2 (8.1)Audio 2.0 or 4.0
    3 ({{ androidPVersionNumber }})3 ({{ androidPVersionNumber }})Audio 4.0
    + +

    Upgrading Target FCM Version

    + +

    During a vendor image upgrade, vendors can also increment the Target FCM +Version to specify the targeted FCM Version the upgraded vendor image can work +with. To bump the Target FCM Version of a device, vendors need to:

    + +
      +
    1. Implement all new required HAL Versions for the Target FCM Version.
      2. +
    2. Modify HAL Versions in the device manifest file.
      3. +
    3. Modify the Target FCM Version in the device manifest file.
      4. +
    4. Remove deprecated HAL versions.
      5. +
    5. For devices launched with {{ androidPVersionNumber }} or older, cherry-pick +these CLs before generating OTA update packages: + +
      6. +
    + +

    For example, Google Pixel and Pixel XL devices launched with Android 7.0 +so their Target FCM Version must be at least legacy. However, the device +manifest declares the Target FCM Version 2 because the vendor image has +been updated to conform with compatibility_matrix.2.xml:

    + +
    +<manifest version="1.0" type="device" target-level="2">
+
    + +

    If vendors do not implement all required new HAL versions or do not remove +deprecated HAL versions, the Target FCM Version cannot be upgraded.

    + +

    For example, Google Pixel 2 and Pixel 2 XL devices have Target FCM Version 2. +While they do implement some HALs required by +compatibility_matrix.3.xml (such as audio 4.0, health 2.0, etc.), +they do not remove android.hardware.radio.deprecated@1.0, which is +deprecated at FCM Version 3 (Android {{ androidPVersionNumber }}). Hence, these +devices cannot upgrade the Target FCM Version to 3.

    + + + diff --git a/en/devices/architecture/vintf/fcm.html b/en/devices/architecture/vintf/fcm.html new file mode 100644 index 00000000..7087915b --- /dev/null +++ b/en/devices/architecture/vintf/fcm.html @@ -0,0 +1,446 @@ + + + FCM Lifecycle + + + + {% include "_versions.html" %} + + + +

    An Android framework release has multiple Framework Compatibility Matrices +(FCMs)—one for each upgradable Target FCM Version—that define what +the framework may use and Target FCM version requirements. As part of the FCM +lifecycle, Android deprecates and removes HIDL HALs, then modifies FCM files to +reflect the status of the HAL Version. + +

    To enable framework-only OTAs in their own ecosystems, partners who extend +vendor interfaces should also deprecate and remove HIDL HALs using the same +methods.

    + + + +

    Terminology

    + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Framework Compatibility Matrix (FCM)An XML file that specifies framework requirements on conforming vendor +implementations. The compatibility matrix is versioned, and a new version +is frozen for each framework release. Each framework release contains +multiple FCMs.
    Platform FCM Versions (SF)The set of all FCM versions in a framework release. The framework can work +with any vendor implementation that satisfies one of these FCMs.
    FCM Version (F)The highest version among all FCMs in a framework release.
    Target FCM Version (V)The targeted FCM version (from SF), declared explicitly in the + device manifest, that a vendor implementation satisfies. A vendor + implementation must be generated against a published FCM, although it may +declare newer HAL versions in its Device Manifest.
    HAL VersionA HAL Version has the format foo@x.y, where foo +is the HAL name and x.y is the specific version; e.g. +nfc@1.0, keymaster@3.0 (the root prefix, e.g. +android.hardware, is omitted throughout this document.)
    Device ManifestAn XML file that specifies what HAL versions the vendor image provides. The +contents of a device manifest are constrained by the Target FCM version of +the device but can list HALs that are strictly newer relative to the FCM +corresponding to V.
    + + +

    Developing in a new FCM Version

    +

    Android increments the FCM Version for each framework release (such as +Android 8, 8.1, etc). During development, the new +compatibility_matrix.current.xml is created (F) and +the existing compatibility_matrix.f.xml (where f < +F) is no longer changed.

    + +

    To start developing in a new FCM Version F:

    + +
      +
    1. Copy the latest compatibility_matrix.<F-1>.xml to +compatibility_matrix.current.xml.
      2. +
    2. Update the level attribute in the file to F.
      3. +
    3. Add corresponding build rules to install this compatibility matrix to the +device.
      4. +
    + +

    Introducing a new HAL

    +

    During development, when introducing a new HAL (Wi-Fi, NFC, etc.) to Android +on the current FCM Version F, add the HAL to +compatibility_matrix.current.xml with the following +optional settings:

    + +
      +
    • optional="false" if devices that ship with V = F +must launch with this HAL,
      +
      +OR +
      +
      • +
    • optional="true" if devices that ship with V = F +can launch without this HAL.
      • +
    + +

    For example, Android 8.1 introduced cas@1.0 as an optional HAL. +Devices launching with Android 8.1 are not required to implement this HAL, so +the following entry was added to compatibility_matrix.current.xml +(renamed to compatibility_matrix.2.xml +after Android 8.1 released):

    + +
    +<hal format="hidl" optional="true">
+    <name>android.hardware.cas</name>
+    <version>1.0</version>
+    <interface>
+        <name>IMediaCasService</name>
+        <instance>default</instance>
+    </interface>
+</hal>
+
    + +

    Upgrading a HAL (minor)

    +

    During development, when a HAL has a minor-version upgrade from +x.z to x.(z+1) at current FCM Version F, +if that version is:

    + +
      +
    • Required on devices launching with V = F, the +compatibility_matrix.current.xml must state x.(z+1)and +optional="false".
      • +
    • Not required on devices launching with V = F, the +compatibility_matrix.current.xml must copy x.y-z and +optionality from compatibility_matrix.<F-1>.xml and change +the version to x.w-(z+1) (where w >= y).
      • +
    + +

    For example, Android 8.1 introduced broadcastradio@1.1 as a +minor version upgrade of 1.0 HAL. The older version, +broadcastradio@1.0, is optional for devices launching with Android +8.0 while the newer version, broadcastradio@1.1, is optional for +devices launching with Android 8.1. In compatibility_matrix.1.xml:

    + +
    +<hal format="hidl" optional="true">
+    <name>android.hardware.broadcastradio</name>
+    <version>1.0</version>
+    <interface>
+        <name>IBroadcastRadioFactory</name>
+        <instance>default</instance>
+    </interface>
+</hal>
+
    + +

    This entry was copied to compatibility_matrix.current.xml +(renamed to compatibility_matrix.2.xml +after Android 8.1 released) and modified as follows:

    + +
    +<hal format="hidl" optional="true">
+    <name>android.hardware.broadcastradio</name>
+    <version>1.0-1</version>
+    <interface>
+        <name>IBroadcastRadioFactory</name>
+        <instance>default</instance>
+    </interface>
+</hal>
+
    + +

    Upgrading a HAL (major)

    +

    During development, when a HAL has a major-version upgrade at current FCM +Version F, the new major version x.0 is added to +compatibility_matrix.current.xml with the following +optional settings:

    + +
      +
    • optional="false" with only version x.0, if devices +that ship with V = F must launch with x.0.
      • +
    • optional="false" but along with older major versions in the +same <hal> tag, if devices that ship with V = F +must launch with this HAL, but can launch with an older major version.
      • +
    • optional="true" if devices that ship with V = F do +not have to launch the HAL.
      • +
    + +

    For example, Android {{ androidPVersionNumber }} introduces +health@2.0 as a major-version upgrade of the 1.0 HAL and deprecates +the 1.0 HAL. The older version, health@1.0, is optional for devices +launching with Android 8.0 and Android 8.1. Devices launching with Android +{{ androidPVersionNumber }} must not provide the deprecated 1.0 HAL and must +instead provide the new 2.0 version. In compatibility_matrix.legacy.xml, +compatibility_matrix.1.xml, +and compatibility_matrix.2.xml:

    + +
    +<hal format="hidl" optional="true">
+    <name>android.hardware.health</name>
+    <version>1.0</version>
+    <interface>
+        <name>IHealth</name>
+        <instance>default</instance>
+    </interface>
+</hal>
+
    + +

    This entry is copied to compatibility_matrix.current.xml +(renamed to compatibility_matrix.3.xml with the Android +{{ androidPVersionNumber }} release) and modified as follows:

    + +
    +<hal format="hidl" optional="false">
+    <name>android.hardware.health</name>
+    <version>2.0</version>
+    <interface>
+        <name>IHealth</name>
+        <instance>default</instance>
+    </interface>
+</hal>
+
    + +

    Restrictions:

    +
      +
    • Because the 2.0 HAL is in compatibility_matrix.3.xml with +optional="false", devices that launch with Android +{{ androidPVersionNumber }} must ship with 2.0 HAL.
      • +
    • Because the 1.0 HAL is not in compatibility_matrix.3.xml, +devices that launch with Android {{ androidPVersionNumber }} must not provide +the 1.0 HAL (as this HAL is considered deprecated).
      • +
    • Because the 1.0 HAL is present in legacy/1/2.xml (older FCM Versions that +Android {{ androidPVersionNumber }} can work with) as an optional HAL, the +Android {{ androidPVersionNumber }} framework can still work with the 1.0 HAL +(which is not considered a removed HAL Version).
      • +
    + +

    New FCM Versions

    +

    The process of releasing an FCM Version is done solely by Google as part of +an AOSP release and includes the following steps:

    + +
      +
    1. Rename compatibility_matrix.current.xml to +compatibility_matrix.F.xml.
      2. +
    2. Ensure the file has the attribute level="F".
      3. +
    3. Edit corresponding build +rules to reflect the file name change.
      4. +
    4. Ensure all devices build and boot.
      5. +
    5. Update +VTS tests to ensure devices launching with the latest framework (based +on Shipping API level) have Target FCM Version V >= F.
      6. +
    6. Publish file to AOSP.
      7. +
    + +

    This file cannot be changed once renamed and published. For +example, during Android {{ androidPVersionNumber }} development the following +files are built +for hardware/interfaces/compatibility_matrices/:

    + +
      +
    • compatibility_matrix.legacy.xml
      • +
    • compatibility_matrix.1.xml
      • +
    • compatibility_matrix.2.xml
      • +
    • compatibility_matrix.current.xml
      • +
    + +

    When Android {{ androidPVersionNumber }} is released, +compatibility_matrix.current.xml is renamed to +compatibility_matrix.3.xml and the following files are +built for hardware/interfaces/compatibility_matrices/:

    + +
      +
    • compatibility_matrix.legacy.xml
      • +
    • compatibility_matrix.1.xml
      • +
    • compatibility_matrix.2.xml
      • +
    • compatibility_matrix.3.xml
      • +
    + +

    +VTS +tests ensure that devices launching with Android {{ androidPVersionNumber }} +have Target FCM Version >= 3.

    + +

    HAL Version deprecation

    + +

    Deprecating a HAL Version is a developer decision (i.e. for AOSP HALs, Google +makes the decision). It could happen when a higher HAL version (whether minor or +major) is released. When a given HAL foo@x.y is deprecated at FCM +Version F, it means that any device launching with Target FCM +Version V = F or later must not implement foo at +version x.y or any version older than x.y. A +deprecated HAL version is still supported by the framework for upgrading +devices.

    + +

    When FCM Version F is released, a HAL Version +foo@x.y is considered deprecated if the specific HAL Version is not +explicitly stated in the latest FCM for Target FCM Version V = F. +For devices launching with V, one of the following conditions is +true:

    + +
      +
    • The framework requires a higher version (major or minor);
      • +
    • The framework doesn't require the HAL anymore.
      • +
    + +

    For example, in Android {{ androidPVersionNumber }}, health@2.0 +is introduced as a major version upgrade of 1.0 HAL. health@1.0 is +removed from compatibility_matrix.3.xml but is present in compatibility_matrix.legacy.xml, +compatibility_matrix.1.xml, +and compatibility_matrix.2.xml. +Hence, health@1.0 is considered deprecated.

    + +

    Removal of support for Target FCM Versions

    +

    When active devices of a certain Target FCM Version V drop below +a certain threshold, the Target FCM Version is removed from the set +SF of the next framework release. This is done by removing +compatibility_matrix.V.xml from the build rules (so that it is no +longer installed on the system image), and by deleting any code that implemented +or depended on the removed functionality. Devices with a target FCM Version +outside of SF for a given framework release cannot upgrade to that +release.

    + +

    HAL Version status

    +

    The following sections describe (in chronological order) the possible states +of a HAL Version.

    + +

    Unreleased

    +

    If a HAL Version is not in any of the public and frozen compatibility +matrices, it is considered unreleased and possibly in development. This includes +HAL Versions that are only in compatibility_matrix.current.xml. +Examples:

    + +
      +
    • During the development of Android {{ androidPVersionNumber }} (before +compatibiility_matrix.current.xml is renamed to +compatibility_matrix.3.xml), the health@2.0 HAL was +considered an unreleased HAL.
      • +
    • The teleportation@1.0 HAL is not in any released compatibility +matrices, and is also considered an unreleased HAL.
      • +
    + +

    Released and Current

    +

    If a HAL Version is in any public and frozen compatibility matrix, it is +released. For example, after FCM Version 3 is frozen (when +compatibiility_matrix.current.xml is renamed to +compatibility_matrix.3.xml) and published to AOSP, the +health@2.0 HAL is considered a released and current HAL Version. +

    + +

    If a HAL Version is in a public and frozen compatibility matrix that has +the highest FCM Version (excluding +compatibility_matrix.current.xml), the HAL version is current (i.e. +not deprecated). For example, existing HAL Versions (such as +nfc@1.0 introduced in compatibility_matrix.legacy.xml) +that continue to exist in compatibility_matrix.3.xml are also +considered as released and current HAL Versions.

    + +

    Released but Deprecated

    +

    A HAL Version is deprecated if and only if:

    + +
      +
    • It is released;
      • +
    • It is not in the public and frozen compatibility matrix that has the highest +FCM Version;
      • +
    • It is in a public and frozen compatibility matrix that the framework still +supports.
      • +
    + +

    Examples:

    + + + +

    Hence power@1.0 is current, but NOT deprecated, +in Android {{ androidPVersionNumber }}.

    + +

    Removed

    +

    A HAL Version is removed if and only if:

    + +
      +
    • It was previously released;
      • +
    • It is not in any public and frozen compatibility matrix that the framework +supports.
      • +
    + +

    Compatibility matrices that are public, frozen, but not supported by the +framework are kept in the code base to define the removed HAL Versions set so +that VTS tests can be written to ensure removed HALs are not on new devices. +

    + +

    Legacy FCMs

    +

    Target FCM Version legacy is a special value for all non-Treble devices. The +legacy FCM, compatibility_matrix.legacy.xml, lists the requirements +of the framework on legacy devices (i.e. devices launched prior to Android 8.0). +

    + +

    If this file exists for an FCM with version F, any non-Treble +device can be upgraded to F provided its device manifest is +compatible with this file. Its removal follows the same procedure as FCMs for +other Target FCM Versions (removed after the number of active pre-8.0 devices +drops below a certain threshold).

    + + + diff --git a/en/devices/architecture/vintf/index.html b/en/devices/architecture/vintf/index.html index fe1fc07d..31c00565 100644 --- a/en/devices/architecture/vintf/index.html +++ b/en/devices/architecture/vintf/index.html @@ -33,7 +33,7 @@ XML.

    Figure 1. Manifests, compatibility matrices, and -runtime-collectible information.
    +runtime-collectible information

    VINTF object design provides the following for device and framework components:

    @@ -76,9 +76,9 @@ regardless of when the object is requested (see Caveats).

    Manifests & matrices

    -

    Android O requires an API at runtime to query what is on the device and send -that information to the Over-the-Air -(OTA) update server and other interested parties (such as CTS +

    As of Android 8.0, a runtime API queries what is on the device and sends that +information to the Over-the-Air (OTA) +update server and other interested parties (such as CTS DeviceInfo). Some information is retrieved at runtime and some of it is statically-defined.

    @@ -101,13 +101,23 @@ ensure a device can get framework updates that are compatible with the device's capabilities. In general, a manifest describes what is provided and a compatibility matrix describes what is required.

    -

    VINTF Object Data -defines the schema for the manifest, -Compatibility -Matrices defines the schema for the compatibility matrix, and -Matching Rules -defines the rules for a successful match between a compatibility matrix -and a manifest.

    +

    This section includes the following details on manifests and matrices:

    +
      +
    • Manifests defines + the device manifest, framework manifest, and manifest file schema.
      • +
    • Compatibility + Matrices defines the schema for the compatibility matrix.
      • +
    • FCM Lifecycle details + how HIDL HALs are deprecated and removed and how FCM files are modifed to + reflect the status of the HAL Version.
      • +
    • DM Development describes + how vendors can define and declare the Target FCM Version in the device + manifest for new devices or implement new HAL versions and increment the + Target FCM Version when upgrading the vendor image for old devices.
      • +
    • Matching Rules + defines the rules for a successful match between a compatibility matrix and a + manifest.
      • +
    diff --git a/en/devices/architecture/vintf/match-rules.html b/en/devices/architecture/vintf/match-rules.html index 61a5f1a7..dd79254b 100644 --- a/en/devices/architecture/vintf/match-rules.html +++ b/en/devices/architecture/vintf/match-rules.html @@ -29,15 +29,34 @@ device manifest, as well as between the framework manifest and the device compatibility matrix. The following sections detail matching rules used by various components.

    +

    Framework compatibility matrix version matches

    +

    To match a device manifest with a framework compatibility matrix, +the Shipping FCM version specified by manifest.target-level +must exactly equal to the FCM version specified by +compatibility-matrix.level. Otherwise there is no match.

    + +

    If the framework compatibility matrix is requested with +libvintf, this match is always successful because +libvintf opens the device manifest, retrieves the Shipping FCM +Version, and returns the framework compatibility matrix at that Shipping FCM +Version (plus some optional HALs from compatibility matrices at higher FCM +Versions).

    +

    HAL matches

    The HAL-match rule identifies the versions of hal elements in a manifest file that are considered supported by the owner of the corresponding compatibility matrix.

      -
    • Multiple version elements are concatenated with -OR (see camera example below).
      • -
    • Multiple <hal> elements with the same name are -concatenated with AND.
      • +
    • Multiple <hal> elements have AND +relationship.
      • +
    • Multiple <version> elements within the same +<hal> have +OR relationship. If two or more are specified, only +one of the version needs to be implemented (see DRM example below).
      • +
    • Multiple <instance> and +<regex-instance> elements within the same +<hal> have +AND relationship (see DRM example below).

    Example: Successful HAL match for Camera module

    @@ -92,28 +111,32 @@ for DRM HAL:

    <interface> <name>ICryptoFactory</name> <instance>default</instance> + <regex-instance>[a-z]+/[0-9]+</regex-instance> </interface> </hal> -

    A vendor must implement ONE of the following HALs:

    +

    A vendor must implement ONE of the following instances:

    -android.hardware.drm@1.x::IDrmFactory/default          //where x >= 0
-android.hardware.drm@1.x::IDrmFactory/specific         //where x >= 0
+android.hardware.drm@1.x::IDrmFactory/default          // where x >= 0
+android.hardware.drm@1.x::IDrmFactory/specific         // where x >= 0
    OR 
    -android.hardware.drm@3.y::IDrmFactory/default          //where y >= 1
-android.hardware.drm@3.y::IDrmFactory/specific         //where y >= 1
+android.hardware.drm@3.y::IDrmFactory/default          // where y >= 1
+android.hardware.drm@3.y::IDrmFactory/specific         // where y >= 1
    -

    ... AND must also implement this HAL:

    +

    ... AND must also implement all of these instances:

    -android.hardware.drm@2.z::ICryptoFactory/default       //where z >= 0
+android.hardware.drm@2.z::ICryptoFactory/default       // where z >= 0
+android.hardware.drm@2.z::ICryptoFactory/${INSTANCE}
+            // where z >= 0 and ${INSTANCE} matches [a-z]+/[0-9]+
+            // e.g. legacy/0

    Kernel matches

    @@ -257,7 +280,7 @@ rules are similar to HAL versions; it is a match if the sepolicy version is higher or equal to the minimum version for the range. The maximum version is purely informational.
  • <kernel-sepolicy-version> i.e. policydb version. Must -exactly match the security_policyvers() reported by the device. +be less than the security_policyvers() reported by the device.
    • @@ -266,17 +289,22 @@ exactly match the security_policyvers() reported by the device. 

    -    <sepolicy>
-        <kernel-sepolicy-version>30</kernel-sepolicy-version>
-        <sepolicy-version>25.0</sepolicy-version>
-        <sepolicy-version>26.0-3</sepolicy-version>
-    </sepolicy>
+<sepolicy>
+    <kernel-sepolicy-version>30</kernel-sepolicy-version>
+    <sepolicy-version>25.0</sepolicy-version>
+    <sepolicy-version>26.0-3</sepolicy-version>
+</sepolicy>

    On the device:

      -
    • The value returned by security_policyvers() must exactly equal -30. Otherwise it is not a match.
      • +
    • The value returned by security_policyvers() must be greater +than or equal to 30. Otherwise it is not a match. For example: +
        +
      • If a device returns 29, it is not a match.
        • +
      • If a device returns 31, it is a match.
        • +
      +
    • SE Policy version must be one of 25.0-∞ or 26.0-∞. Otherwise it is not a match. (The "-3" after "26.0" is purely informational.)
      • @@ -362,5 +390,126 @@ ro.boot.avb_version == 2.3 && ro.boot.vbmeta.avb_version == 2.1  match  +

      VNDK version matches

      +

      The device compatibility matrix declares the required VNDK version in +compatibility-matrix.vendor-ndk.version. If the device +compatibility matrix does not have a <vendor-ndk> tag, no +requirements are imposed, and hence it is always considered a match.

      +

      If the device compatibility matrix does have a <vendor-ndk> +tag, an <vendor-ndk> entry with a matching +<version> is looked up from the set of VNDK vendor snapshots +provided by the framework in the framework manifest. If such an entry does not +exist, there is no match.

      +

      If such entry does exist, the set of libraries enumerated in the device +compatibility matrix must be a subset of the set of libraries stated in the +framework manifest; otherwise, the entry is not considered a match.

      +
        +
      • As a special case, if no libraries are enumerated in the device + compatibility matrix, the entry is always considered a match, because empty + set is a subset of any set.
        • +
      + +

      Example: Successful VNDK version match

      +

      If the device compatibility matrix states the following requirement on VNDK: +

      + +
      +<!-- Example Device Compatibility Matrix -->
+<vendor-ndk>
+    <version>27</version>
+    <library>libjpeg.so</library>
+    <library>libbase.so</library>
+</vendor-ndk>
+
      + +

      In the framework manifest, only the entry with version 27 is considered.

      + +
      +<!-- Framework Manifest Example A -->
+<vendor-ndk>
+    <version>27</version>
+    <library>libjpeg.so</library>
+    <library>libbase.so</library>
+    <library>libfoo.so</library>
+</vendor-ndk>
+
      + +

      Example A is a match, because VNDK version 27 is in the framework manifest, +and {libjpeg.so, libbase.so, libfoo.so} ⊇ {libjpeg.so, libbase.so}. +

      + +
      +<!-- Framework Manifest Example B -->
+<vendor-ndk>
+    <version>26</version>
+    <library>libjpeg.so</library>
+    <library>libbase.so</library>
+</vendor-ndk>
+<vendor-ndk>
+    <version>27</version>
+    <library>libbase.so</library>
+</vendor-ndk>
+
      + +

      Example B is not a match. Even though VNDK version 27 is in the framework +manifest, libjpeg.so is not supported by the framework in that +snapshot. VNDK version 26 is ignored.

      + +

      System SDK version matches

      +

      The device compatibility matrix declares a set of required System SDK +version in compatibility-matrix.system-sdk.version. There is a +match only if the set is a subset of provided System SDK versions as declared +in manifest.system-sdk.version in the framework manifest.

      +
        +
      • As a special case, if no System SDK versions are enumerated in the device + compatibility matrix, it is always considered a match, because empty + set is a subset of any set.
        • +
      + +

      Example: Successful System SDK version match

      +

      If the device compatibility matrix states the following requirement on System +SDK: +

      + +
      +<!-- Example Device Compatibility Matrix -->
+<system-sdk>
+    <version>26</version>
+    <version>27</version>
+</system-sdk>
+
      + +

      Then, the framework must provide System SDK version 26 and 27 to match.

      + +
      +<!-- Framework Manifest Example A -->
+<system-sdk>
+    <version>26</version>
+    <version>27</version>
+</system-sdk>
+
      + +

      Example A is a match.

      + +
      +<!-- Framework Manifest Example B -->
+<system-sdk>
+    <version>26</version>
+    <version>27</version>
+    <version>28</version>
+</system-sdk>
+
      + +

      Example B is a match.

      + +
      +<!-- Framework Manifest Example C -->
+<system-sdk>
+    <version>26</version>
+</system-sdk>
+
      + +

      Example C is not a match, because System SDK version 27 is not provided.

      + diff --git a/en/devices/architecture/vintf/objects.html b/en/devices/architecture/vintf/objects.html index c7ab09fd..a5e34a2c 100644 --- a/en/devices/architecture/vintf/objects.html +++ b/en/devices/architecture/vintf/objects.html @@ -1,6 +1,6 @@ - VINTF Object Data + Manifests @@ -21,26 +21,39 @@ limitations under the License. --> -

      A VINTF object aggregates data from -device manifest and -framework manifest files (XML) and from -the device itself at runtime. Both manifests share a -format, although not all elements apply to both (for details on the schema, see -Manifest file schema).

      - -

      Device manifest file

      -

      The Device manifest file is provided by the device. It lives in the Android -source tree at device/${VENDOR}/${DEVICE}/manifest.xml and on the -device at -/vintfdata/manifest.xml. +

      A VINTF object aggregates data from device +manifest and framework manifest files +(XML) and from the device itself at runtime. Both +manifests share a format, although not all elements apply to both (for details +on the schema, see Manifest file schema).

      -

      Example Device manifest:

      +

      Device manifest

      +

      The Device manifest (provided by the device) consists of the vendor manifest +and the ODM manifest:

      + +
        +
      • The vendor manifest specifies HALs, VNDK versions, etc. common to an SoC. It +is recommended to be placed in the Android source tree at +device/${VENDOR}/${DEVICE}/manifest.xml, but multiple fragment +files can be used. For details, see +Generate +DM from fragments. +
        • +
      • The ODM manifest overrides the vendor manifest and lists HALs specific to +the product.
        • +
      + +

      This setup enables multiple products with the same board to share the same +vendor image (which provides common HALs) yet have different ODM images (which +specify product-specific HALs).

      + +

      Example vendor manifest:

       <?xml version="1.0" encoding="UTF-8"?>
 <!-- Comments, Legal notices, etc. here -->
-<manifest version="1.0" type="device">
+<manifest version="1.0" type="device" target-level="1">
     <hal>
         <name>android.hardware.camera</name>
         <transport>hwbinder</transport>
@@ -70,6 +83,21 @@ device at
             <instance>default</instance>
         </interface>
     </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="native">
         <name>EGL</name>
         <version>1.1</version>
@@ -86,12 +114,47 @@ device at
 </manifest>
      -

      Framework manifest file

      -

      The Framework manifest file is provided by Google and is manually generated. -It lives in the Android source tree at system/libhidl/manifest.xml -and on the device under /system/manifest.xml.

      +

      Example ODM manifest:

      -

      Example Framework manifest (provided by Google):

      +
      +<?xml version="1.0" encoding="UTF-8"?>
+<!-- Comments, Legal notices, etc. here -->
+<manifest version="1.0" type="device">
+    <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>
+    <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>
+
      + +For more details, see DM +Development. + +

      Framework manifest

      +

      The Framework manifest file (provided by Google) is manually generated and +lives in the Android source tree at +/system/libhidl/manifest.xml. +

      + +

      Example Framework manifest:

       <?xml version="1.0" encoding="UTF-8"?>
@@ -133,20 +196,36 @@ and on the device under /system/manifest.xml.
      
             <instance>default</instance>
         </interface>
     </hal>
+    <vendor-ndk>
+        <version>27</version>
+    </vendor-ndk>
+    <system-sdk>
+        <version>27</version>
+    </system-sdk>
 </manifest>

      Manifest file schema

      +

      This section describes the meaning of these XML tags. Some "required" tags +can be missing from the source file in Android source tree and written by +assemble_vintf +at build time. "Required" tags must be present in the corresponding files on the +device.

      +
      ?xml
      Optional. Only provides information to the XML parser.
      manifest.version
      -
      Required. Version of this manifest. Describes the elements -expected in the manifest. Unrelated to XML version.
      +
      Required. Meta-version of this manifest. Describes the +elements expected in the manifest. Unrelated to XML version.
      manifest.type
      Required. Type of this manifest. It has value device for device manifest file and framework for framework manifest file.
      +
      manifest.target-level
      +
      Required for device manifest. Specifies the Framework Compatibility Matrix +Version (FCM Version) that this device manifest is targeted to be compatible +with. This is also called the Shipping FCM Version of the device.
      manifest.hal
      Optional, can repeat. A single HAL (HIDL or native, such as GL), depending on the format attribute.
      @@ -157,6 +236,17 @@ depending on the format attribute.
    • native: native HALs.
    +
    manifest.hal.override
    +
    Optional. Value can be one of: +
      +
    • true: override other <hal> elements with + the same <name> and major version. If no + <version> or <fqname> are in this + <hal> element, then this HAL is disabled.
      • +
    • false: do not override other <hal> elements + with the same <name> and major version.
      • +
    +
    manifest.hal.name
    Required. Fully-qualified package name of HAL. Multiple HAL entries can use the same name. Examples: @@ -185,7 +275,7 @@ provided. Value can be one of:
    manifest.hal.version
    -
    Required, can repeat. A version for the hal tags in a +
    Optional, can repeat. A version for the hal tags in a manifest. Format is MAJOR.MINOR. For examples, refer to hardware/interfaces, vendor/${VENDOR}/interfaces, @@ -195,7 +285,8 @@ system/hardware/interfaces. HIDL and native HALs may use multiple version fields as long as they represent distinct major versions, with only one minor version per major version provided. For example, 3.1 and 3.2 cannot coexist, but 1.0 and 3.4 can. -This applies for all hal elements with the same name.
    +This applies for all hal elements with the same name, unless +override="true".
    manifest.hal.interface
    Required, can repeat without duplicates. State an interface in the package that has an instance name. There can be multiple @@ -207,56 +298,37 @@ must be distinct.
    Required, can repeat. Instance name of the interface. Can have multiple instances for an interface but no duplicated <instance> elements.
    +
    manifest.hal.fqname
    +
    Optional, can repeat. An alternative way to specify an instance for the HAL +with name manifest.hal.name. Format is +@MAJOR.MINOR::INTERFACE/INSTANCE. +For devices upgrading from Android 8.0, this cannot be used to declare +instances required by the compatibility matrix.
    manifest.sepolicy
    Required. Contains all sepolicy-related entries.
    manifest.sepolicy.version
    -
    Required for device manifest. Declares sepolicy version. It has the -format SDK_INT.PLAT_INT.
    +
    Required for device manifest. Declares SELinux version. It has the +format SDK_INT.PLAT_INT.
    +
    manifest.vendor-ndk
    +
    Required, can repeat; required for framework manifest. Must not be present +in the device manifest. Multiple <vendor-ndk> entries must have +different <version>’s. Describes a set of VNDK snapshots +provided by the framework.
    +
    manifest.vendor-ndk.version
    +
    Required. It is a positive integer representing the version of the VNDK +snapshot.
    +
    manifest.vendor-ndk.library
    +
    Optional, can repeat, without duplicates. Describes a set of VNDK libraries +provided by the framework for this VNDK vendor snapshot. The value is the +filename of a library, e.g. libjpeg.so, including the prefix +lib and the suffix .so. No path components are +allowed.
    +
    manifest.system-sdk.version
    +
    Optional, can repeat, without duplicates; used only by the framework +manifest. Describes a set of System SDK versions provided by the framework to +vendor apps.
    -

    Runtime data

    -

    Some information required for the device manifest can be collected only at -runtime. Information is available via -::android::vintf::VintfObject::GetRuntimeInfo() and includes the -following:

    - -
      -
    • Kernel information, including: -
        -
      • /proc/config.gz. Zipped full kernel configuration that needs - to be read at runtime and converted to a queryable object.
        • -
      • /proc/version. Information available through - uname() system call.
        • -
      • /proc/cpuinfo. Format may be different for 32-bit and 64-bit - machine.
        • -
      • policydb version -
          -
        • /sys/fs/selinux/policyvers (assuming selinuxfs - is mounted at /sys/fs/selinux).
          • -
        • security_policyvers() API from libselinux gives - you the same.
          • -
        -
        • -
      -
    • static libavb version, including: -
        -
      • bootloader system property: ro.boot.vbmeta.avb_version
        • -
      • init/fs_mgr system property: ro.boot.avb_version
        • -
      -
      • -
    - -

    Queryable API

    -

    The VINTF object is a system API as the -hwservicemanager, OTA update service, CTS DeviceInfo, -and others need information from this API.

    - - - + diff --git a/en/devices/architecture/vintf/resources.html b/en/devices/architecture/vintf/resources.html index 0f408a89..7f70ffff 100644 --- a/en/devices/architecture/vintf/resources.html +++ b/en/devices/architecture/vintf/resources.html @@ -22,7 +22,7 @@ -->

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

    +and licensing.

    Queryable code location

    The code for the queryable vendor interface object goes to @@ -51,9 +51,8 @@ adb shell su 0 /system/bin/lshal --init-vintf

  • If a package is both registered to hwservicemanager and found as a passthrough HAL, <transport> is set to hwbinder.
    • -
  • 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.
    • +
  • No SELinux version is written into the manifest. It is suggested that the +element is injected via assemble_vintf as explained below.
  • 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.
    • @@ -74,32 +73,21 @@ compatibility matrix that is compatible with the manifest file. matrix from a framework manifest file 
    -assemble_vintf -m \
+assemble_vintf -m --hals-only \
     -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".
      • -
    +

    Note that 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
+assemble_vintf -m --hals-only \
+    -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".
      • -
    +

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

    Example: Generate XML files from variables

    @@ -113,37 +101,53 @@ 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:

    +

    Then the following commands are executed (in the build system, modified to omit implementation +details) 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
+    $(addprefix,-i ,$(DEVICE_MANIFEST_FILE)) \
+    -o $(TARGET_OUT_VENDOR)/etc/vintf/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
+    -i $(DEVICE_MATRIX_FILE) \
+    -o $(TARGET_OUT_VENDOR)/etc/vintf/compatibility_matrix.xml
 
 # framework manifest
 assemble_vintf
-    -i system/libhidl/manifest.xml \
+    $(addprefix,-i ,system/libhidl/manifest.xml $(DEVICE_FRAMEWORK_MANIFEST_FILE)) \
     -o $(TARGET_OUT)/manifest.xml \
-    -c $(TARGET_OUT_VENDOR)/compatibility_matrix.xml
+    -c $(TARGET_OUT_VENDOR)/etc/vintf/compatibility_matrix.xml
 
-# framework compatibility matrix
+# common framework 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_matrix.xml \
-    -o $(TARGET_OUT)/compatibility_matrix.xml \
-    -c $(TARGET_OUT_VENDOR)/manifest.xml \
+    $(addprefix,-i ,\
+        hardware/interfaces/compatibility_matrices/compatibility_matrix.empty.xml \
+        $(DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE)) \
+    -o $(TARGET_OUT)/etc/vintf/compatibility_matrix.empty.xml
+
+# framework compatibility matrices 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=...
+
+# Final framework compatibility matrix to check with device manifest.
+# Each input matrix should have a unique "level" attribute.
+PRODUCT_ENFORCE_VINTF_MANIFEST=$(PRODUCT_ENFORCE_VINTF_MANIFEST) \
+assemble_vintf
+    -i $(TARGET_OUT)/etc/vintf/compatibility_matrix.*.xml
+    -o /tmp/compatibility_matrix.xml
+    -c $(TARGET_OUT_VENDOR)/manifest.xml
    -

    Example: Generate device manifest from fragments

    +

    Example: +Generate device manifest from fragments

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

    @@ -210,21 +214,5 @@ version. Public domain license. 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.

    - -- cgit v1.2.3