From f16c42333aa6b2de30a344dd68246d4a33d93e7d Mon Sep 17 00:00:00 2001 From: Android Partner Docs Date: Tue, 22 Aug 2017 10:41:24 -0700 Subject: Docs: Changes to source.android.com - 166080694 Devsite localized content from translation request a3d5a7... by Android Partner Docs - 166079245 Remove duplicate TOC entry to oob-users.html. by mheco - 166002955 Update builds for Oreo by Android Partner Docs - 165977566 Fixing bad conversion by hvm - 165977199 Edit links to point to public source files in AOSP. by cqn - 165962883 Add codename to CTS downloads page. by gdimino - 165955117 Integration of O branch into mainline. by gdimino - 165638251 Update July public Android security bulletin to remove QC... by Android Partner Docs - 165638198 Update June public Android security bulletin to remove QC... by Android Partner Docs - 165638174 Update May public Android security bulletin to remove QC ... by Android Partner Docs - 165638096 Update April public Android security bulletin to remove Q... by Android Partner Docs - 165528993 Update to Keymaster 2 and remove requirements language by daroberts - 165511119 Add Bluetooth verification / debug information by cqn - 165491345 Fixed link broken by file rename. by cqn - 165381648 Fixed broken image paths and renamed HCI Requirements file. by cqn - 165365185 Created high-level Bluetooth directory and added HTML ver... by cqn - 165335694 Devsite localized content from translation request 66a39c... by Android Partner Docs - 165246927 Update August 2017 bulletin with CVE-2017-0687 by daroberts PiperOrigin-RevId: 166080694 Change-Id: I2d3a8d77fa6a66c2099f13ba2e864545328fd17a --- en/devices/architecture/vintf/comp-matrices.html | 263 ++++++++++++++++ en/devices/architecture/vintf/index.html | 113 +++++++ en/devices/architecture/vintf/match-rules.html | 366 +++++++++++++++++++++++ en/devices/architecture/vintf/objects.html | 262 ++++++++++++++++ en/devices/architecture/vintf/resources.html | 184 ++++++++++++ 5 files changed, 1188 insertions(+) create mode 100644 en/devices/architecture/vintf/comp-matrices.html create mode 100644 en/devices/architecture/vintf/index.html create mode 100644 en/devices/architecture/vintf/match-rules.html create mode 100644 en/devices/architecture/vintf/objects.html create mode 100644 en/devices/architecture/vintf/resources.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 new file mode 100644 index 00000000..d3512e70 --- /dev/null +++ b/en/devices/architecture/vintf/comp-matrices.html @@ -0,0 +1,263 @@ + + + Compatibility Matrices + + + + + + +

This section describes the framework and device compatibility matrices and +the compatibility matrix schema. For +match rules, see Matching +Rules.

+ +

Framework compatibility matrix

+

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).

+ +

Example framework compatibility matrix file:

+ +
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Comments, Legal notices, etc. here -->
+<compatibility-matrix version="1.0" type="framework">
+    <hal>
+        <name>android.hardware.camera</name>
+        <version>1.0</version>
+        <version>3.1-4</version>
+        <interface>
+            <name>ICameraProvider</name>
+            <instance>default</instance>
+        </interface>
+    </hal>
+    <hal>
+        <name>android.hardware.nfc</name>
+        <version>1.0</version>
+        <interface>
+            <name>INfc</name>
+            <instance>default</instance>
+        </interface>
+    </hal>
+    <hal optional="true">
+        <name>android.hardware.graphics.composer</name>
+        <version>2.1</version>
+    </hal>
+    <hal format="native">
+        <name>GL</name>
+        <version>1.1</version>
+        <version>3.0</version>
+    </hal>
+    <hal format="native">
+        <name>EGL</name>
+        <version>1.1</version>
+    </hal>
+    <kernel version="3.18.51">
+        <config>
+            <key>CONFIG_A</key>
+            <value type="string"></value>
+        </config>
+        <config>
+            <key>CONFIG_B</key>
+            <value type="tristate">y</value>
+        </config>
+    </kernel>
+    <kernel version="4.1.22">
+        <config>
+            <key>CONFIG_A</key>
+            <value type="string">foo</value>
+        </config>
+        <config>
+            <key>CONFIG_B2</key>
+            <value type="int">1024</value>
+        </config>
+    </kernel>
+    <sepolicy>
+        <kernel-sepolicy-version>30</kernel-sepolicy-version>
+        <sepolicy-version>25.0</sepolicy-version>
+        <sepolicy-version>26.0-3</sepolicy-version>
+    </sepolicy>
+    <avb>
+        <vbmeta-version>2.1</vbmeta-version>
+    </avb>
+    <xmlfile format="dtd">
+        <name>media_profile</name>
+        <version>1.0</version>
+        <path>/system/etc/media_profile_V1_0.dtd</path>
+    </xmlfile>
+</compatiblity-matrix>
+
+ +

Device compatibility matrix

+

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:

+ +
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Comments, Legal notices, etc. here -->
+<compatibility-matrix version="1.0" type="device">
+    <hal>
+        <name>android.hidl.manager</name>
+        <version>1.0</version>
+        <interface>
+            <name>IServiceManager</name>
+            <instance>default</instance>
+        </interface>
+    </hal>
+    <hal>
+        <name>android.hidl.memory</name>
+        <version>1.0</version>
+        <interface>
+            <name>IMemory</name>
+            <instance>ashmem</instance>
+        </interface>
+    </hal>
+    <hal>
+        <name>android.hidl.allocator</name>
+        <version>1.0</version>
+        <interface>
+            <name>IAllocator</name>
+            <instance>ashmem</instance>
+        </interface>
+    </hal>
+    <hal>
+        <name>android.framework.sensor</name>
+        <version>1.0</version>
+        <interface>
+            <name>ISensorManager</name>
+            <instance>default</instance>
+        </interface>
+    </hal>
+    <xmlfile format="dtd" optional="false">
+        <name>sample_xml</name>
+        <version>1.0</version>
+    </xmlfile>
+</compatibility-matrix>
+
+ +

Compatiblity matrix schema

+
+
?xml
+
Optional. It only provides information to the XML parser.
+
compatibility-matrix.version
+
Required. Version of this compatiblity matrix. Describes the elements +expected in the manifest. Unrelated to XML version.
+
compatibility-matrix.type
+
Required. Type of this compatibility matrix: +
    +
  • "device": Device compatibility matrix.
    • +
  • "framework": Framework compatibility matrix.
    • +
+
+
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 +present. HAL entries are distinguished by a <name> element; +there can be several HAL entries with the same name (implies "and" condition). +
+
compatibility-matrix.hal.format
+
Optional. Value can be one of: +
    +
  • "hidl": HIDL HALs. This is the default.
    • +
  • "native": native HALs.
    • +
+
+
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 +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: +
    +
  • android.hardware.camera (HIDL HAL)
    • +
  • GLES (native HAL, requires name only)
    • +
+
+
compatibility-matrix.hal.version
+
Required, can repeat without duplicates. A list of version ranges (see +HAL matches) +that defines what versions the owner of the compatibility matrix (framework or +device) expects.
+
compatibility-matrix.hal.interface
+
Optional, can repeat. A list of required interfaces of this HAL.
+
compatibility-matrix.hal.interface.name
+
Required. Name of the interface.
+
compatibility-matrix.hal.interface
+
Optional, can repeat. A list of required instances of this interface.
+
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.
+
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 +pair; config items are distinguished by key.
+
compatibility-matrix.kernel.config.key
+
Required. Key name of the CONFIG item. Starts with +CONFIG_.
+
compatibility-matrix.kernel.config.value
+
Required. Value of the CONFIG item. Format depends on type: +
    +
  • string. Quotes are omitted.
    • +
  • int. Decimal and hexadecimal (must start with 0x + or 0X)values are accepted. Interpreted as an 64-bit integer; + overflows result in truncation. (Parser accepts values from -264 + 1 + to 264 - 1, 65th bit is truncated; for details refer to the + strtoull + man page.)
    • +
  • range. Format is [int]-[int], e.g. + 10-20. Hexadecimal values are accepted and must start with + 0x or 0X. Two boundaries must be an unsigned 64-bit + integer.
    • +
  • tristate. Valid values are y, m and + n.
    • +
+
+
compatibility-matrix.kernel.config.value.type
+
Required. Type of the value of the CONFIG item, one of: +
    +
  • string
    • +
  • int
    • +
  • range
    • +
  • tristate
    • +
+
+
compatibility-matrix.sepolicy
+
Required. Contains all sepolicy-related entries. Used only by the +framework compatibility matrix.
+
compatibility-matrix.sepolicy.sepolicy-version
+
Required, can repeat. Describes the requirement on sepolicy version. +Corresponds to manifest.sepolicy.version. Each instance of an +element defines a range of sepolicy versions.
+
compatibility-matrix.sepolicy.kernel-sepolicy-version
+
Required. Declares the policydb version the framework works +with.
+
compatibility-matrix.avb.vbmeta-version
+
Optional; used only by the framework compatibility matrix. Declares the +AVB +version used to sign system.img.
+
+ + + diff --git a/en/devices/architecture/vintf/index.html b/en/devices/architecture/vintf/index.html new file mode 100644 index 00000000..b0517a32 --- /dev/null +++ b/en/devices/architecture/vintf/index.html @@ -0,0 +1,113 @@ + + + Vendor Interface Object + + + + + + +

This document describes the design of the vendor interface object +(VINTF object), which aggregates relevant information about a device and makes +that information available through a queryable API.

+ + +

VINTF object design

+

A VINTF object gathers some of the information it needs directly from the +device. Other aspects, such as the manifests, are described statically in +XML.

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

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

+ + + + + + + + + + +
For the DeviceFor the Framework
+
    +
  • Defines a schema for the static component (the +device +manifest file).
    • +
  • Adds build time support for defining the device manifest file for a given +device.
    • +
  • Defines the +queryable +API at runtime that retrieves the device manifest file (along with the other +runtime-collectible information) and packages them into the query result.
    • +
+		 +
    +
  • Defines a schema for the static component (the +framework +manifest file).
    • +
  • Defines the +queryable +API at runtime that retrieves the framework manifest file and packages it +into the query result.
    • +
+
+ +

The VINTF object must be reliable and provide the same complete information +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 +DeviceInfo). Some information is retrieved at runtime and some of +it is statically-defined.

+ +
    +
  • The device manifest describes the static component of what +the device can provide to the the framework.
    • +
  • The framework compatibility matrix describes what the +Android framework expects from a given device. The matrix is a static entity +whose composition is determined manually during development of the next release +of the Android framework.
    • +
  • The framework manifest describes high-level services the +framework can provide to the device.
    • +
  • The device compatibility matrix describes the services the +vendor image requires of the framework. Its composition is determined manually +during the development of the device.
    • +
+ +

These two pairs of manifests and matrices must be reconciled at OTA time to +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.

+ + + diff --git a/en/devices/architecture/vintf/match-rules.html b/en/devices/architecture/vintf/match-rules.html new file mode 100644 index 00000000..61a5f1a7 --- /dev/null +++ b/en/devices/architecture/vintf/match-rules.html @@ -0,0 +1,366 @@ + + + Matching Rules + + + + + + +

The two pairs of compatibility matrices and manifests are meant to be +reconciled at OTA time to verify the +framework and vendor implementation can work with each other. This verification +is successful upon a match between the framework compatibility matrix and the +device manifest, as well as between the framework manifest and the device +compatibility matrix. The following sections detail matching rules used by +various components.

+ +

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.
    • +
+ +

Example: Successful HAL match for Camera module

+

For a HAL at version 2.5, the match rule is as follows:

+ + + + + + + + + + + + + + +
MatrixMatching Manifest
2.52.5-2.∞. Shorthand for 2.5-5.
2.5-72.5-2.∞. Indicates the following: +
+
    +
  • 2.5 is the minimum required version, meaning a manifest providing HAL + 2.0-2.4 is not compatible.
    • +
  • 2.7 is the maximum version that could be requested, meaning the owner of + the compatibility matrix (framework or device) will not request versions + beyond 2.7. The owner of the matching manifest can still serve version 2.10 + (as an example) when 2.7 is requested. The compatibility-matrix owner knows + only that the requested service is compatible with API version 2.7.
    • +
  • -7 is informational only and does not affect the OTA update process.
    • +
+ Thus, a device with a HAL at version 2.10 in its manifest file remains + compatible with a framework that states camera: + 2.5-7 in its compatibility matrix.
+ +

Example: Successful HAL match for DRM module

+

The framework compatibility matrix states the following version information +for DRM HAL:

+ +
<hal>
+    <name>android.hardware.drm
+    <version>1.0</version>
+    <version>3.1-2</version>
+    <interface>
+        <name>IDrmFactory</name>
+        <instance>default</instance>
+        <instance>specific</instance>
+    </interface>
+</hal>
+<hal>
+    <name>android.hardware.drm
+    <version>2.0</version>
+    <interface>
+        <name>ICryptoFactory</name>
+        <instance>default</instance>
+    </interface>
+</hal>
+
+ +

A vendor must implement ONE of the following HALs:

+ +
+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
+
+ +

... AND must also implement this HAL:

+ +
+android.hardware.drm@2.z::ICryptoFactory/default       //where z >= 0
+
+ +

Kernel matches

+

The <kernel> section of the framework compatibility matrix +describes the framework's requirements of the Linux kernel on the device. This +information is meant to be matched at OTA time against the +information +about the kernel that gets reported by the device's VINTF object.

+ +

A matrix can include multiple <kernel> sections, each with +a different version attribute using the format:

+ +
${ver}.${major_rev}.${kernel_minor_rev}
+ +

The OTA considers only the <kernel> section with the same +${ver} and ${major_rev} as the device kernel (i.e., +version="${ver}.${major_rev}.${matrix_minor_rev}"); other sections +are ignored. In addition, the minor revision from the kernel must be a value +from the compatibility matrix (${kernel_minor_rev} >= +${matrix_minor_rev};). If no <kernel> section meets +these requirements, it is a non-match.

+ +

If the <kernel> section does match, the process continues +by attempting to match config elements against +/proc/config.gz. For each config element in the compatibility +matrix, it looks up /proc/config.gz to see if the config is +present. When a config item is set to n in the compatibility +matrix for the matching <kernel> section, it must be absent +from /proc/config.gz. Finally, a config item not in the +compatibility matrix may or may not be present in /proc/config.gz. +

+ +

Examples of matches:

+
    +
  • <value type="string">bar</value> matches +"bar". Quotes are omitted in the compatibility matrix but present +in /proc/config.gz.
    • +
  • <value type="int">4096</value> matches +4096 or 0x1000 or 0X1000.
    • +
  • <value type="int">0x1000</value> matches +4096 or 0x1000 or 0X1000.
    • +
  • <value type="int">0X1000</value> matches +4096 or 0x1000 or 0X1000.
    • +
  • <value type="tristate">y</value> matches +y.
    • +
  • <value type="tristate">m</value> matches +m.
    • +
  • <value type="tristate">n</value> means the config +item must NOT exist in /proc/config.gz.
    • +
  • <value type="range">1-0x3</value> matches +1, 2, or 3, or hexadecimal equivalent. +
    • +
+ +

Example: Successful kernel match

+

A framework compatibility matrix has the following kernel information:

+ +
+<kernel version="3.18.51">
+   <config>
+      <key>CONFIG_TRI</key>
+      <value type="tristate">y</value>
+   </config>
+   <config>
+      <key>CONFIG_NOEXIST</key>
+      <value type="tristate">n</value>
+   </config>
+   <config>
+      <key>CONFIG_DEC</key>
+      <value type="int">4096</value>
+   </config>
+   <config>
+      <key>CONFIG_HEX</key>
+      <value type="int">0XDEAD</value>
+   </config>
+   <config>
+      <key>CONFIG_STR</key>
+      <value type="string">str</value>
+   </config>
+   <config>
+      <key>CONFIG_EMPTY</key>
+      <value type="string"></value>
+   </config>
+</kernel>
+
+ +

The kernel version is matched first. If a device in uname() +reports:

+
    +
  • 3.10.73 (no match to matrix unless there is a separate kernel section +with <kernel version="3.10.x"> where x <= 73) +
    • +
  • 3.18.50 (no match to matrix, smaller than version)
    • +
  • 3.18.51 (match to matrix)
    • +
  • 3.18.52 (match to matrix)
    • +
  • 4.1.22 (no match to matrix unless there is a separate kernel section +with <kernel version="4.1.x"> where x <= 22) +
    • +
+ +

After the appropriate <kernel> section is selected, for +each <config> item with value other than n, we +expect the corresponding entry to be present in /proc/config.gz; +for each <config> item with value n, we expect +the corresponding entry to not be present in /proc/config.gz. We +expect the content of <value> to exactly match the text after +the equal sign (including quotes), up to the newline character or +#, with leading and trailing whitespace truncated.

+ +

The following kernel configuration is an example of a successful match:

+ +
+# comments don't matter
+CONFIG_TRI=y
+# CONFIG_NOEXIST should not exist
+CONFIG_DEC = 4096 # trailing comments and whitespaces are fine
+CONFIG_HEX=57005  # 0XDEAD == 57005
+CONFIG_STR="str"
+CONFIG_EMPTY=""   # empty string must have quotes
+CONFIG_EXTRA="extra config items are fine too"
+
+ +

The following kernel configuration is an example of an unsuccessful match:

+ +
+CONFIG_TRI="y"   # mismatch: quotes
+CONFIG_NOEXIST=y # mismatch: CONFIG_NOEXIST exists
+CONFIG_HEX=0x0   # mismatch; value doesn't match
+CONFIG_DEC=""    # mismatch; type mismatch (expect int)
+CONFIG_EMPTY=1   # mismatch; expects ""
+# mismatch: CONFIG_STR is missing
+
+ +

SE policy matches

+

SE policy requires the following matches:

+
    +
  • <sepolicy-version> defines a closed range of minor +versions for every major version. The sepolicy version reported by the device +must fall within one of these ranges to be compatible with the framework. Match +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. +
    • +
+ +

Example: Successful SE policy match

+

The framework compatibility matrix states the following sepolicy information: +

+ +
+    <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.
    • +
  • 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.)
    • +
+ +

AVB version matches

+

The AVB version contains a MAJOR version and MINOR version, with the format +as MAJOR.MINOR (e.g., 1.0, 2.1). For details, refer to +Versioning +and Compatibility. AVB version has the following system properties:

+
    +
  • ro.boot.vbmeta.avb_version is the libavb version +in bootloader
    • +
  • ro.boot.avb_version is the libavb version in +Android OS (init/fs_mgr)
    • +
+ +

The system property appears only when the corresponding libavb has been used +to verify AVB metadata (and returns OK). It is absent if a verification failure +occurred (or no verification occurred at all).

+ +

A compatibility match compares the following:

+
    +
  • sysprop ro.boot.vbmeta.avb_version with +avb.vbmeta-version from framework compatibility matrix; +
      +
    • ro.boot.vbmeta.avb_version.MAJOR == avb.vbmeta-version.MAJOR
      • +
    • ro.boot.vbmeta.avb_version.MINOR >= avb.vbmeta-version.MINOR
      • +
    +
    • +
  • sysprop ro.boot.avb_version with +avb.vbmeta-version from framework compatibility matrix. +
      +
    • ro.boot.avb_version.MAJOR == avb.vbmeta-version.MAJOR
      • +
    • ro.boot.avb_version.MINOR >= avb.vbmeta-version.MINOR
      • +
    +
    • +
+ +

The bootloader or Android OS might contain two copies of libavb +libraries, each with a different MAJOR version for upgrade devices and launch +devices. In this case, the same unsigned system image can be shared but +the final signed system images are different (with different +avb.vbmeta-version):

+ + +
Figure 1. AVB version matches (/system +is P, all other partitions are O).
+
+
+ +
Figure 2. AVB version matches (all partitions are +P).
+ +

Example: Successful AVB version match

+

The framework compatibility matrix states the following AVB information:

+ +
+<avb>
+    <vbmeta-version>2.1</vbmeta-version>
+</avb>
+
+ +

On the device:

+ +
+ro.boot.avb_version              == 1.0 &&
+ro.boot.vbmeta.avb_version       == 2.1  mismatch 
+
+ +
+ro.boot.avb_version              == 2.1 &&
+ro.boot.vbmeta.avb_version       == 3.0  mismatch 
+
+ +
+ro.boot.avb_version              == 2.1 &&
+ro.boot.vbmeta.avb_version       == 2.3  match 
+
+ +
+ro.boot.avb_version              == 2.3 &&
+ro.boot.vbmeta.avb_version       == 2.1  match 
+
+ + + diff --git a/en/devices/architecture/vintf/objects.html b/en/devices/architecture/vintf/objects.html new file mode 100644 index 00000000..87abeedf --- /dev/null +++ b/en/devices/architecture/vintf/objects.html @@ -0,0 +1,262 @@ + + + VINTF Object Data + + + + + + +

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 +/vendor/manifest.xml. +

+ +

Example Device manifest:

+ +
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Comments, Legal notices, etc. here -->
+<manifest version="1.0" type="device">
+    <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>
+        <version>2.0</version>
+        <interface>
+            <name>INfc</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>
+
+ +

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 Framework manifest (provided by Google):

+ +
+<?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.framework.sensorservice</name>
+        <transport>hwbinder</transport>
+        <version>1.0</version>
+        <interface>
+            <name>ISensorManager</name>
+            <instance>default</instance>
+        </interface>
+    </hal>
+</manifest>
+
+ +

Manifest file schema

+
+
?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.
+
manifest.type
+
Required. Type of this manifest. It has value device for +device manifest file and framework for framework manifest +file.
+
manifest.hal
+
Optional, can repeat. A single HAL (HIDL or native, such as GL), +depending on the format attribute.
+
manifest.hal.format
+
Optional. Value can be one of: +
    +
  • hidl: HIDL HALs. This is the default. +
  • native: native HALs.
    • +
+
+
manifest.hal.name
+
Required. Fully-qualified package name of HAL. Multiple HAL entries can use +the same name. Examples: +
    +
  • android.hardware.camera (HIDL HAL)
    • +
  • GLES (native HAL, requires name only)
    • +
+
+
manifest.hal.transport
+
Required when manifest.hal.format == "hidl". Must NOT be +present otherwise. States what transport will be used when an interface from +this package is queried from service manager. Value can be one of: +
    +
  • hwbinder: binderized mode
    • +
  • passthrough: passthrough mode
    • +
+
+
manifest.hal.transport.arch
+
Required for passthrough and must not be present for +hwbinder. Describes the bitness of the passthrough service being +provided. Value can be one of: +
    +
  • 32: 32-bit mode
    • +
  • 64: 64-bit mode
    • +
  • 32+64: both
    • +
+
+
manifest.hal.version
+
Required, can repeat. A version for the hal tags in a +manifest. Format is MAJOR.MINOR. For +examples, refer to hardware/interfaces, +vendor/${VENDOR}/interfaces, +framework/hardware/interfaces, or +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.
+
manifest.hal.interface
+
Required, can repeat without duplicates. State an interface in the +package that has an instance name. There can be multiple +<interface> elements in a <hal>; names +must be distinct.
+
manifest.hal.interface.name
+
Required. Name of the interface.
+
manifest.hal.interface.instance
+
Required, can repeat. Instance name of the interface. Can have multiple +instances for an interface but no duplicated <instance> +elements.
+
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.
+
+ +

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 new file mode 100644 index 00000000..65828508 --- /dev/null +++ b/en/devices/architecture/vintf/resources.html @@ -0,0 +1,184 @@ + + + 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. +
  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. +
  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.
    4. +
+ +

ASSEMBLE_VINTF

+

assemble_vintf is a host-side tool that:

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

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 \
+
+ +

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.

+ + + -- cgit v1.2.3