diff options
| author | Android Partner Docs <noreply@android.com> | 2017-08-22 10:41:24 -0700 |
|---|---|---|
| committer | Clay Murphy <claym@google.com> | 2017-08-22 15:01:44 -0700 |
| commit | f16c42333aa6b2de30a344dd68246d4a33d93e7d (patch) | |
| tree | 311af599312cacb21c888aeae828cae59b0d64a1 /en/devices/architecture/vintf | |
| parent | 04426e67ca3ee557a0083f9b3c6ba789021bd7a0 (diff) | |
| download | source.android.com-f16c42333aa6b2de30a344dd68246d4a33d93e7d.tar.gz | |
Docs: Changes to source.android.com
- 166080694 Devsite localized content from translation request a3d5a7... by Android Partner Docs <noreply@android.com>
- 166079245 Remove duplicate TOC entry to oob-users.html. by mheco <mheco@google.com>
- 166002955 Update builds for Oreo by Android Partner Docs <noreply@android.com>
- 165977566 Fixing bad conversion by hvm <hvm@google.com>
- 165977199 Edit links to point to public source files in AOSP. by cqn <cqn@google.com>
- 165962883 Add codename to CTS downloads page. by gdimino <gdimino@google.com>
- 165955117 Integration of O branch into mainline. by gdimino <gdimino@google.com>
- 165638251 Update July public Android security bulletin to remove QC... by Android Partner Docs <noreply@android.com>
- 165638198 Update June public Android security bulletin to remove QC... by Android Partner Docs <noreply@android.com>
- 165638174 Update May public Android security bulletin to remove QC ... by Android Partner Docs <noreply@android.com>
- 165638096 Update April public Android security bulletin to remove Q... by Android Partner Docs <noreply@android.com>
- 165528993 Update to Keymaster 2 and remove requirements language by daroberts <daroberts@google.com>
- 165511119 Add Bluetooth verification / debug information by cqn <cqn@google.com>
- 165491345 Fixed link broken by file rename. by cqn <cqn@google.com>
- 165381648 Fixed broken image paths and renamed HCI Requirements file. by cqn <cqn@google.com>
- 165365185 Created high-level Bluetooth directory and added HTML ver... by cqn <cqn@google.com>
- 165335694 Devsite localized content from translation request 66a39c... by Android Partner Docs <noreply@android.com>
- 165246927 Update August 2017 bulletin with CVE-2017-0687 by daroberts <daroberts@google.com>
PiperOrigin-RevId: 166080694
Change-Id: I2d3a8d77fa6a66c2099f13ba2e864545328fd17a
Diffstat (limited to 'en/devices/architecture/vintf')
| -rw-r--r-- | en/devices/architecture/vintf/comp-matrices.html | 263 | ||||
| -rw-r--r-- | en/devices/architecture/vintf/index.html | 113 | ||||
| -rw-r--r-- | en/devices/architecture/vintf/match-rules.html | 366 | ||||
| -rw-r--r-- | en/devices/architecture/vintf/objects.html | 262 | ||||
| -rw-r--r-- | en/devices/architecture/vintf/resources.html | 184 |
5 files changed, 1188 insertions, 0 deletions
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 @@ +<html devsite> + <head> + <title>Compatibility Matrices</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + <body> + <!-- + Copyright 2017 The Android Open Source Project + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> + +<p>This section describes the framework and device compatibility matrices and +the <a href="#compatiblity-matrix-schema">compatibility matrix schema</a>. For +match rules, see <a href="/devices/architecture/vintf/match-rules.html">Matching +Rules</a>.</p> + +<h2 id="framework-compatibility-matrix">Framework compatibility matrix</h2> +<p>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 <code>system.img</code>). 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).</p> + +<p>Example framework compatibility matrix file:</p> + +<pre class="prettyprint"> +<?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> +</pre> + +<h2 id="device-compatibility-matrix">Device compatibility matrix</h2> +<p>The device compatibility matrix describes a set of requirements the device +expects from the framework (requirements enforced at launch and OTA time). +</p> +<p>Example device compatibility matrix file:</p> + +<pre class="prettyprint"> +<?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> +</pre> + +<h2 id="compatiblity-matrix-schema">Compatiblity matrix schema</h2> +<dl> +<dt><code>?xml</code></dt> +<dd>Optional. It only provides information to the XML parser.</dd> +<dt><code>compatibility-matrix.version</code></dt> +<dd>Required. Version of this compatiblity matrix. Describes the elements +expected in the manifest. Unrelated to XML version.</dd> +<dt><code>compatibility-matrix.type</code></dt> +<dd>Required. Type of this compatibility matrix: + <ul> + <li><code>"device"</code>: Device compatibility matrix.</li> + <li><code>"framework"</code>: Framework compatibility matrix.</li> + </ul> +</dd> +<dt><code>compatibility-matrix.hal</code></dt> +<dd>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 <code><name></code> element; +there can be several HAL entries with the same name (implies "and" condition). +</dd> +<dt><code>compatibility-matrix.hal.format</code></dt> +<dd>Optional. Value can be one of: + <ul> + <li><code>"hidl"</code>: HIDL HALs. This is the default.</li> + <li><code>"native"</code>: native HALs.</li> + </ul> +</dd> +<dt><code>compatibility-matrix.hal.optional</code></dt> +<dd>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 +<code><p;hal></code> entry is marked as optional, it means the owner can +work with this HAL, if present, but does not require it to be present.</dd> +<dt><code>compatibility-matrix.hal.name</code></dt> +<dd>Required. Full package name of this HAL. Examples: + <ul> + <li><code>android.hardware.camera</code> (HIDL HAL)</li> + <li><code>GLES</code> (native HAL, requires name only)</li> + </ul> +</dd> +<dt><code>compatibility-matrix.hal.version</code></dt> +<dd>Required, can repeat without duplicates. A list of version ranges (see +<a href="/devices/architecture/vintf/match-rules.html#hals">HAL matches</a>) +that defines what versions the owner of the compatibility matrix (framework or +device) expects.</dd> +<dt><code>compatibility-matrix.hal.interface</code></dt> +<dd>Optional, can repeat. A list of required interfaces of this HAL.</dd> +<dt><code>compatibility-matrix.hal.interface.name</code></dt> +<dd>Required. Name of the interface.</dd> +<dt><code>compatibility-matrix.hal.interface</code></dt> +<dd>Optional, can repeat. A list of required instances of this interface.</dd> +<dt><code>compatibility-matrix.kernel.version</code></dt> +<dd>Required. Kernel version. Format is +<code>{version}.{major-revision}.{minor-revision}</code>. Version and major +revision must match exactly, minor-revision defines the minimum LTS version of +the kernel the framework expects.</dd> +<dt><code>compatibility-matrix.kernel.config</code></dt> +<dd>Optional, can repeat. Lists <code>CONFIG</code> items that must be +matched for this kernel version. Each <code>CONFIG</code> item is a key-value +pair; config items are distinguished by key.</dd> +<dt><code>compatibility-matrix.kernel.config.key</code></dt> +<dd>Required. Key name of the <code>CONFIG</code> item. Starts with +<code>CONFIG_</code>.</dd> +<dt><code>compatibility-matrix.kernel.config.value</code></dt> +<dd>Required. Value of the <code>CONFIG</code> item. Format depends on type: + <ul> + <li><code>string</code>. Quotes are omitted.</li> + <li><code>int</code>. Decimal and hexadecimal (must start with <code>0x</code> + or <code>0X)</code>values are accepted. Interpreted as an 64-bit integer; + overflows result in truncation. (Parser accepts values from -2<sup>64</sup> + 1 + to 2<sup>64</sup> - 1, 65th bit is truncated; for details refer to the + <a href="http://man7.org/linux/man-pages/man3/strtoul.3.html" class="external">strtoull + man page</a>.)</li> + <li><code>range</code>. Format is <code>[int]-[int]</code>, e.g. + <code>10-20</code>. Hexadecimal values are accepted and must start with + <code>0x</code> or <code>0X</code>. Two boundaries must be an unsigned 64-bit + integer.</li> + <li><code>tristate</code>. Valid values are <code>y</code>, <code>m</code> and + <code>n</code>.</li> + </ul> +</dd> +<dt><code>compatibility-matrix.kernel.config.value.type</code></dt> +<dd>Required. Type of the value of the <code>CONFIG</code> item, one of: + <ul> + <li><code>string</code></li> + <li><code>int</code></li> + <li><code>range</code></li> + <li><code>tristate</code></li> + </ul> +</dd> +<dt><code>compatibility-matrix.sepolicy</code></dt> +<dd>Required. Contains all sepolicy-related entries. Used only by the +framework compatibility matrix.</dd> +<dt><code>compatibility-matrix.sepolicy.sepolicy-version</code></dt> +<dd>Required, can repeat. Describes the requirement on sepolicy version. +Corresponds to <code>manifest.sepolicy.version</code>. Each instance of an +element defines a range of sepolicy versions.</dd> +<dt><code>compatibility-matrix.sepolicy.kernel-sepolicy-version</code></dt> +<dd>Required. Declares the <code>policydb</code> version the framework works +with.</dd> +<dt><code>compatibility-matrix.avb.vbmeta-version</code></dt> +<dd>Optional; used only by the framework compatibility matrix. Declares the +<a href="/devices/architecture/vintf/match-rules.html#avb-version">AVB +version</a> used to sign <code>system.img</code>.</dd> +</dl> + + </body> +</html> 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 @@ +<html devsite> + <head> + <title>Vendor Interface Object</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + <body> + <!-- + Copyright 2017 The Android Open Source Project + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> + +<p>This document describes the design of the <em>vendor interface object</em> +(VINTF object), which aggregates relevant information about a device and makes +that information available through a <em>queryable API</em>.</p> + + +<h2 id=about-objects>VINTF object design</h2> +<p>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.</p> + +<img src="../images/treble_vintf_mm.png"> +<figcaption><strong>Figure 1.</strong> Manifests, compatibility matrices, and +runtime-collectible information.</figcaption> + +<p>VINTF object design provides the following for device and framework +components:</p> + +<table> +<tr> +<th style="width:50%">For the Device</th> +<th>For the Framework</th> +</tr> +<tr> +<td> +<ul> +<li>Defines a schema for the static component (the +<a href="/devices/architecture/vintf/objects.html#device-manifest-file">device +manifest file</a>).</li> +<li>Adds build time support for defining the device manifest file for a given +device.</li> +<li>Defines the +<a href="/devices/architecture/vintf/objects.html#queryable-api">queryable +API</a> at runtime that retrieves the device manifest file (along with the other +runtime-collectible information) and packages them into the query result.</li> +</ul> +</td> +<td> +<ul> +<li>Defines a schema for the static component (the +<a href="/devices/architecture/vintf/objects.html#framework-manifest-file">framework +manifest file</a>).</li> +<li>Defines the +<a href="/devices/architecture/vintf/objects.html#queryable-api">queryable +API</a> at runtime that retrieves the framework manifest file and packages it +into the query result.</li> +</ul> +</td> +</tr> +</table> + +<p>The VINTF object must be reliable and provide the same complete information +regardless of when the object is requested (see +<a href="/devices/architecture/vintf/resources.html#caveats">Caveats</a>).</p> + +<h2 id=manifests-matrices>Manifests & matrices</h2> +<p>Android O requires an API at runtime to query what is on the device and send +that information to the <a href="/devices/tech/ota/index.html">Over-the-Air +(OTA)</a> update server and other interested parties (such as CTS +<code>DeviceInfo</code>). Some information is retrieved at runtime and some of +it is statically-defined.</p> + +<ul> +<li>The <strong>device manifest</strong> describes the static component of what +the device can provide to the the framework.</li> +<li>The <strong>framework compatibility matrix</strong> 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.</li> +<li>The <strong>framework manifest</strong> describes high-level services the +framework can provide to the device.</li> +<li>The <strong>device compatibility matrix</strong> describes the services the +vendor image requires of the framework. Its composition is determined manually +during the development of the device.</li> +</ul> + +<p>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 <em>manifest</em> describes what is provided and a +<em>compatibility matrix</em> describes what is required.</p> + +<p><a href="/devices/architecture/vintf/objects.html">VINTF Object Data</a> +defines the schema for the manifest, +<a href="/devices/architecture/vintf/comp-matrices.html">Compatibility +Matrices</a> defines the schema for the compatibility matrix, and +<a href="/devices/architecture/vintf/match-rules.html">Matching Rules</a> +defines the rules for a successful match between a compatibility matrix +and a manifest.</p> + + </body> +</html> 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 @@ +<html devsite> + <head> + <title>Matching Rules</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + <body> + <!-- + Copyright 2017 The Android Open Source Project + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> + +<p>The two pairs of compatibility matrices and manifests are meant to be +reconciled at <a href="/devices/tech/ota/index.html">OTA</a> 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.</p> + +<h2 id="hals">HAL matches</h2> +<p>The HAL-match rule identifies the versions of <code>hal</code> elements in a +manifest file that are considered supported by the owner of the corresponding +compatibility matrix.</p> +<ul> +<li>Multiple <code>version</code> elements are concatenated with +<strong>OR</strong> (see camera example below).</li> +<li>Multiple <code><hal></code> elements with the same name are +concatenated with <strong>AND</strong>.</li> +</ul> + +<h4><strong>Example</strong>: Successful HAL match for Camera module</h4> +<p>For a HAL at version 2.5, the match rule is as follows:</p> + +<table> + <tr> + <th>Matrix</th> + <th>Matching Manifest</th> + </tr> + <tr> + <td><code>2.5</code></td> + <td>2.5-2.∞. Shorthand for 2.5-5.</td> + </tr> + <tr> + <td><code>2.5-7</code></td> + <td>2.5-2.∞. Indicates the following: + <br> + <ul> + <li>2.5 is the minimum required version, meaning a manifest providing HAL + 2.0-2.4 is not compatible.</li> + <li>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.</li> + <li>-7 is informational only and does not affect the OTA update process.</li> + </ul> + Thus, a device with a HAL at version 2.10 in its manifest file remains + compatible with a framework that states <code>camera:</code> + <code>2.5-7</code> in its compatibility matrix.</td> + </tr> +</table> + +<h4><strong>Example:</strong> Successful HAL match for DRM module</h4> +<p>The framework compatibility matrix states the following version information +for DRM HAL:</p> + +<pre class="prettyprint"><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> +</pre> + +<p>A vendor must implement ONE of the following HALs:</p> + +<pre> +android.hardware.drm@1.x::IDrmFactory/default //where x >= 0 +android.hardware.drm@1.x::IDrmFactory/specific //where x >= 0 +</pre> + +OR + +<pre> +android.hardware.drm@3.y::IDrmFactory/default //where y >= 1 +android.hardware.drm@3.y::IDrmFactory/specific //where y >= 1 +</pre> + +<p>... AND must also implement this HAL:</p> + +<pre> +android.hardware.drm@2.z::ICryptoFactory/default //where z >= 0 +</pre> + +<h2 id="kernel">Kernel matches</h2> +<p>The <code><kernel></code> 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 +<a href="/devices/architecture/vintf/objects.html#runtime-collectible-information">information</a> +about the kernel that gets reported by the device's VINTF object.</p> + +<p>A matrix can include multiple <code><kernel></code> sections, each with +a different <code>version</code> attribute using the format:</p> + +<pre class="prettyprint">${ver}.${major_rev}.${kernel_minor_rev}</pre> + +<p>The OTA considers only the <code><kernel></code> section with the same +<code>${ver}</code> and <code>${major_rev}</code> as the device kernel (i.e., +<code>version="${ver}.${major_rev}.${matrix_minor_rev}")</code>; other sections +are ignored. In addition, the minor revision from the kernel must be a value +from the compatibility matrix (<code>${kernel_minor_rev} >= +${matrix_minor_rev}</code>;). If no <code><kernel></code> section meets +these requirements, it is a non-match.</p> + +<p>If the <code><kernel></code> section does match, the process continues +by attempting to match <code>config</code> elements against +<code>/proc/config.gz</code>. For each config element in the compatibility +matrix, it looks up <code>/proc/config.gz</code> to see if the config is +present. When a config item is set to <code>n</code> in the compatibility +matrix for the matching <code><kernel></code> section, it must be absent +from <code>/proc/config.gz</code>. Finally, a config item not in the +compatibility matrix may or may not be present in <code>/proc/config.gz</code>. +</p> + +<p>Examples of matches:</p> +<ul> +<li><code><value type="string">bar</value></code> matches +<code>"bar"</code>. Quotes are omitted in the compatibility matrix but present +in <code>/proc/config.gz</code>.</li> +<li><code><value type="int">4096</value></code> matches +<code>4096</code> or <code>0x1000</code> or <code>0X1000</code>.</li> +<li><code><value type="int">0x1000</value></code> matches +<code>4096</code> or <code>0x1000</code> or <code>0X1000</code>.</li> +<li><code><value type="int">0X1000</value></code> matches +<code>4096</code> or <code>0x1000</code> or <code>0X1000</code>.</li> +<li><code><value type="tristate">y</value></code> matches +<code>y</code>.</li> +<li><code><value type="tristate">m</value></code> matches +<code>m</code>.</li> +<li><code><value type="tristate">n</value></code> means the config +item must NOT exist in <code>/proc/config.gz</code>.</li> +<li><code><value type="range">1-0x3</value></code> matches +<code>1</code>, <code>2</code>, or <code>3</code>, or hexadecimal equivalent. +</li> +</ul> + +<h4><strong>Example:</strong> Successful kernel match</h4> +<p>A framework compatibility matrix has the following kernel information:</p> + +<pre class="prettyprint"> +<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> +</pre> + +<p>The kernel version is matched first. If a device in <code>uname()</code> +reports:</p> +<ul> +<li>3.10.73 (no match to matrix unless there is a separate kernel section +with <code><kernel version="3.10.x"></code> where <code>x <= 73</code>) +</li> +<li>3.18.50 (no match to matrix, smaller than <code>version</code>)</li> +<li>3.18.51 (match to matrix)</li> +<li>3.18.52 (match to matrix)</li> +<li>4.1.22 (no match to matrix unless there is a separate kernel section +with <code><kernel version="4.1.x"></code> where <code>x <= 22</code>) +</li> +</ul> + +<p>After the appropriate <code><kernel></code> section is selected, for +each <code><config></code> item with value other than <code>n</code>, we +expect the corresponding entry to be present in <code>/proc/config.gz</code>; +for each <code><config></code> item with value <code>n</code>, we expect +the corresponding entry to not be present in <code>/proc/config.gz</code>. We +expect the content of <code><value></code> to exactly match the text after +the equal sign (including quotes), up to the newline character or +<code>#</code>, with leading and trailing whitespace truncated.</p> + +<p>The following kernel configuration is an example of a successful match:</p> + +<pre class="prettyprint"> +# 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" +</pre> + +<p>The following kernel configuration is an example of an unsuccessful match:</p> + +<pre class="prettyprint"> +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 +</pre> + +<h2 id="se-policy">SE policy matches</h2> +<p>SE policy requires the following matches:</p> +<ul> +<li><code><sepolicy-version></code> 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.</li> +<li><code><kernel-sepolicy-version></code> i.e. policydb version. Must +exactly match the <code>security_policyvers()</code> reported by the device. +</li> +</ul> + +<h4><strong>Example:</strong> Successful SE policy match</h4> +<p>The framework compatibility matrix states the following sepolicy information: +</p> + +<pre class="prettyprint"> + <sepolicy> + <kernel-sepolicy-version>30</kernel-sepolicy-version> + <sepolicy-version>25.0</sepolicy-version> + <sepolicy-version>26.0-3</sepolicy-version> + </sepolicy> +</pre> + +<p>On the device:</p> +<ul> +<li>The value returned by <code>security_policyvers()</code> must exactly equal +30. Otherwise it is not a match.</li> +<li>SE Policy version must be one of 25.0-∞ or 26.0-∞. Otherwise it is not a +match. (The "<code>-3</code>" after "<code>26.0</code>" is purely +informational.)</li> +</ul> + +<h2 id="avb-version">AVB version matches</h2> +<p>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 +<a href="https://android.googlesource.com/platform/external/avb/#Versioning-and-compatibility" class="external">Versioning +and Compatibility</a>. AVB version has the following system properties:</p> +<ul> +<li><code>ro.boot.vbmeta.avb_version</code> is the <code>libavb</code> version +in bootloader</li> +<li><code>ro.boot.avb_version</code> is the <code>libavb</code> version in +Android OS (<code>init/fs_mgr</code>)</li> +</ul> + +<p>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).</p> + +<p>A compatibility match compares the following:</p> +<ul> +<li>sysprop <code>ro.boot.vbmeta.avb_version</code> with +<code>avb.vbmeta-version</code> from framework compatibility matrix; + <ul> + <li><code>ro.boot.vbmeta.avb_version.MAJOR == avb.vbmeta-version.MAJOR</code></li> + <li><code>ro.boot.vbmeta.avb_version.MINOR >= avb.vbmeta-version.MINOR</code></li> + </ul> +</li> +<li>sysprop <code>ro.boot.avb_version</code> with +<code>avb.vbmeta-version</code> from framework compatibility matrix. + <ul> + <li><code>ro.boot.avb_version.MAJOR == avb.vbmeta-version.MAJOR</code></li> + <li><code>ro.boot.avb_version.MINOR >= avb.vbmeta-version.MINOR</code></li> + </ul> +</li> +</ul> + +<p>The bootloader or Android OS might contain two copies of <code>libavb</code> +libraries, each with a different MAJOR version for upgrade devices and launch +devices. In this case, the same <em>unsigned</em> system image can be shared but +the final <em>signed</em> system images are different (with different +<code>avb.vbmeta-version</code>):</p> + +<img src="../images/treble_vintf_avb_o_p.png"> +<figcaption><strong>Figure 1. </strong>AVB version matches (<code>/system</code> +is P, all other partitions are O).</figcaption> +<br> +<br> +<img src="../images/treble_vintf_avb_p.png"> +<figcaption><strong>Figure 2.</strong> AVB version matches (all partitions are +P).</figcaption> + +<h4><strong>Example:</strong> Successful AVB version match</h4> +<p>The framework compatibility matrix states the following AVB information:</p> + +<pre class="prettyprint"> +<avb> + <vbmeta-version>2.1</vbmeta-version> +</avb> +</pre> + +<p>On the device:</p> + +<pre class="prettyprint"> +ro.boot.avb_version == 1.0 && +ro.boot.vbmeta.avb_version == 2.1 <font style="font-family: Roboto, Arial, Helvetica, sans-serif; background-color: red; color: white"> mismatch </font> +</pre> + +<pre class="prettyprint"> +ro.boot.avb_version == 2.1 && +ro.boot.vbmeta.avb_version == 3.0 <font style="font-family: Roboto, Arial, Helvetica, sans-serif; background-color: red; color: white"> mismatch </font> +</pre> + +<pre class="prettyprint"> +ro.boot.avb_version == 2.1 && +ro.boot.vbmeta.avb_version == 2.3 <font style="font-family: Roboto, Arial, Helvetica, sans-serif; background-color: green; color: white"> match </font> +</pre> + +<pre class="prettyprint"> +ro.boot.avb_version == 2.3 && +ro.boot.vbmeta.avb_version == 2.1 <font style="font-family: Roboto, Arial, Helvetica, sans-serif; background-color: green; color: white"> match </font> +</pre> + + </body> +</html> 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 @@ +<html devsite> + <head> + <title>VINTF Object Data</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + <body> + <!-- + Copyright 2017 The Android Open Source Project + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> + +<p>A VINTF object aggregates data from +<a href="#device-manifest-file">device manifest</a> and +<a href="#framework-manifest-file">framework manifest</a> files (XML) and from +the device itself at <a href="#runtime-data">runtime</a>. Both manifests share a +format, although not all elements apply to both (for details on the schema, see +<a href="#manifest-file-schema">Manifest file schema</a>).</p> + +<h2 id="device-manifest-file">Device manifest file</h2> +<p>The Device manifest file is provided by the device. It lives in the Android +source tree at <code>device/${VENDOR}/${DEVICE}/manifest.xml</code> and on the +device at +<code><a href="https://android.googlesource.com/platform/system/libhidl/+/master/manifest.xml" class="external">/vendor/manifest.xml</a></code>. +</p> + +<p>Example Device manifest:</p> + +<pre class="prettyprint"> +<?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> +</pre> + +<h2 id="framework-manifest-file">Framework manifest file</h2> +<p>The Framework manifest file is provided by Google and is manually generated. +It lives in the Android source tree at <code>system/libhidl/manifest.xml</code> +and on the device under <code>/system/manifest.xml</code>.</p> + +<p>Example Framework manifest (provided by Google):</p> + +<pre class="prettyprint"> +<?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> +</pre> + +<h2 id="manifest-file-schema">Manifest file schema</h2> +<dl> +<dt><code>?xml</code></dt> +<dd>Optional. Only provides information to the XML parser.</dd> +<dt><code>manifest.version</code></dt> +<dd>Required. Version of <strong>this</strong> manifest. Describes the elements +expected in the manifest. Unrelated to XML version.</dd> +<dt><code>manifest.type</code></dt> +<dd>Required. Type of this manifest. It has value <code>device</code> for +device manifest file and <code>framework</code> for framework manifest +file.</dd> +<dt><code>manifest.hal</code></dt> +<dd>Optional, can repeat. A single HAL (HIDL or native, such as GL), +depending on the <code>format</code> attribute.</dd> +<dt><code>manifest.hal.format</code></dt> +<dd>Optional. Value can be one of: + <ul> + <li><code>hidl</code>: HIDL HALs. This is the default. + <li><code>native</code>: native HALs.</li> + </ul> +</dd> +<dt><code>manifest.hal.name</code></dt> +<dd>Required. Fully-qualified package name of HAL. Multiple HAL entries can use +the same name. Examples: + <ul> + <li><code>android.hardware.camera</code> (HIDL HAL)</li> + <li><code>GLES</code> (native HAL, requires name only)</li> + </ul> + </dd> +<dt><code>manifest.hal.transport</code></dt> +<dd>Required when <code>manifest.hal.format == "hidl"</code>. 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: + <ul> + <li><code>hwbinder</code>: binderized mode</li> + <li><code>passthrough</code>: passthrough mode</li> + </ul> +</dd> +<dt><code>manifest.hal.transport.arch</code></dt> +<dd>Required for <code>passthrough</code> and must not be present for +<code>hwbinder</code>. Describes the bitness of the passthrough service being +provided. Value can be one of: + <ul> + <li><code>32</code>: 32-bit mode</li> + <li><code>64</code>: 64-bit mode</li> + <li><code>32+64</code>: both</li> + </ul> +</dd> +<dt><code>manifest.hal.version</code></dt> +<dd>Required, can repeat. A version for the <code>hal</code> tags in a +manifest. Format is <code><var>MAJOR</var>.<var>MINOR</var></code>. For +examples, refer to <code>hardware/interfaces</code>, +<code>vendor/${VENDOR}/interfaces</code>, +<code>framework/hardware/interfaces</code>, or<code> +system/hardware/interfaces</code>. +<br><br> +HIDL and native HALs may use multiple version fields as long as they represent +<strong>distinct major versions</strong>, 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 <code>hal</code> elements with the same name.</dd> +<dt><code>manifest.hal.interface</code></dt> +<dd>Required, can repeat without duplicates. State an interface in the +package that has an instance name. There can be multiple +<code><interface></code> elements in a <code><hal></code>; names +must be distinct.</dd> +<dt><code>manifest.hal.interface.name</code></dt> +<dd>Required. Name of the interface.</dd> +<dt><code>manifest.hal.interface.instance</code></dt> +<dd>Required, can repeat. Instance name of the interface. Can have multiple +instances for an interface but no duplicated <code><instance></code> +elements.</dd> +<dt><code>manifest.sepolicy</code></dt> +<dd>Required. Contains all sepolicy-related entries.</dd> +<dt><code>manifest.sepolicy.version</code></dt> +<dd>Required for device manifest. Declares sepolicy version. It has the +format <var>SDK_INT</var>.<var>PLAT_INT</var>.</dd> +</dl> + +<h2 id=runtime-data>Runtime data</h2> +<p>Some information required for the device manifest can be collected only at +runtime. Information is available via +<code>::android::vintf::VintfObject::GetRuntimeInfo()</code> and includes the +following:</p> + +<ul> +<li>Kernel information, including: + <ul> + <li><code>/proc/config.gz</code>. Zipped full kernel configuration that needs + to be read at runtime and converted to a queryable object.</li> + <li><code>/proc/version</code>. Information available through + <code>uname()</code> system call.</li> + <li><code>/proc/cpuinfo</code>. Format may be different for 32-bit and 64-bit + machine.</li> + <li>policydb version + <ul> + <li><code>/sys/fs/selinux/policyvers</code> (assuming <code>selinuxfs</code> + is mounted at <code>/sys/fs/selinux</code>).</li> + <li><code>security_policyvers()</code> API from <code>libselinux</code> gives + you the same.</li> + </ul> + </li> + </ul> +<li>static libavb version, including: + <ul> + <li>bootloader system property: <code>ro.boot.vbmeta.avb_version</code></li> + <li>init/fs_mgr system property: <code>ro.boot.avb_version</code></li> + </ul> +</li> +</ul> + +<h2 id="queryable-api">Queryable API</h2> +<p>The VINTF object is a system API as the +<code>hwservicemanager</code>, OTA update service, CTS <code>DeviceInfo</code>, +and others need information from this API.</p> + +<ul> +<li>C++ queryable API is in +<a href="https://android.googlesource.com/platform/system/libvintf/+/master/include/vintf/VintfObject.h" class="external"><code>android::vintf::VintfObject</code></a></li> +<li>Java queryable API is in +<a href="https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/os/VintfObject.java" class="external"><code>android.os.VintfObject</code></a> +</ul> + + </body> +</html> 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 @@ +<html devsite> + <head> + <title>Additional Resources</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + <body> + <!-- + Copyright 2017 The Android Open Source Project + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + --> + +<p>The following resources provide details on code locations, tools, testing, +licensing, and caveats.</p> + +<h2 id=query-api-code>Queryable code location</h2> +<p>The code for the queryable vendor interface object goes to +<code><a href="https://android.googlesource.com/platform/system/libvintf/+/master#" class="external">system/libvintf</a></code> +(see the +<a href="/devices/architecture/vintf/objects.html#queryable-api">queryable +API</a>).</p> + +<h2 id="related-tools">Tools</h2> +<p>Handwriting manifest files and compatibility matrices can be tough. Use the +following tools to generate a boilerplate manifest/compatibility matrix to start +from.</p> + +<h3 id="lshal">LSHAL</h3> +<p>LSHAL is a device-side tool that lists all registered HALs to +<code>hwservicemanager</code> and all available passthrough implementations +(e.g. <code>android.hardware.foo@1.0-impl.so</code>) on the device. It can also +generate a <strong>device manifest</strong> file based on the list:</p> + +<pre class="devsite-terminal"> +adb shell su 0 /system/bin/lshal --init-vintf +</pre> + +<p>Note the following:</p> +<ol> +<li>If a package is both registered to <code>hwservicemanager</code> and found +as a passthrough HAL, <code><transport></code> is set to +<code>hwbinder</code>.</li> +<li>A dummy <code><sepolicy><version>0.0</version></sepolicy></code> +element exists at the end of the manifest. It is suggested that the element is +deleted and injected via <code>assemble_vintf</code> as explained below.</li> +<li>The generated HAL manifest file may be inaccurate. Human attention is +required to fix inconsistencies between the device manifest and what +<code>vendor.img</code> actually provides.</li> +</ol> + +<h3 id="assemble_vintf">ASSEMBLE_VINTF</h3> +<p><code>assemble_vintf</code> is a host-side tool that:</p> +<ol> +<li>Verifies a compatibility matrix or manifest file is valid.</li> +<li>Injects variables to manifests/compatibility matrices available at build +time and generates a new file that should be installed to the device.</li> +<li>Checks compatibility between the generated file and its dual.</li> +<li>If a manifest file is given, optionally generates a boilerplate +compatibility matrix that is compatible with the manifest file.</li> +</ol> + +<h4><strong>Example:</strong> Generate <strong>device compatibility +matrix</strong> from a framework manifest file</h4> + +<pre class="devsite-terminal"> +assemble_vintf -m \ + -i system/libhidl/manifest.xml \ + -o device/manufacturer/device_name/compatibility_matrix.xml +</pre> +<p>Note the following:</p> +<ul> +<li>Even though <code><vndk></code> entries are in the output +compatibility matrix, they should be deleted and injected at build time.</li> +<li>All HALs are set to <code>optional="true"</code>.</li> +</ul> + +<h4><strong>Example:</strong> Generate a skeleton framework compatibility +matrix from a device manifest file</h4> + +<pre class="devsite-terminal"> +BOARD_SEPOLICY_VERS=10000.0 assemble_vintf -m \ + -i device/foo/bar/manifest.xml + -o path/to/place/output/compatibility_matrix.xml +</pre> +<p>Note the following:</p> +<ul> +<li>Even though <code><sepolicy></code> and <code><avb></code> are +in the output compatibility matrix, they should be deleted and injected at +build time.</li> +<li>All HALs are set to <code>optional="true"</code>.</li> +</ul> + +<h4><strong>Example:</strong> Generate XML files from variables</h4> + +<p>At build time, if the following variables are +defined in <code>device/manufacturer/device_name/BoardConfig.mk</code>:</p> + +<pre class="prettyprint"> +DEVICE_MANIFEST_FILE := \ + device/manufacturer/device_name/manifest.xml +DEVICE_MATRIX_FILE := \ + device/manufacturer/device_name/compatibility_matrix.xml +</pre> + +<p>Then the following commands (modified to omit implementation details) are +executed to generate all XML files:</p> + +<pre class="prettyprint"> +# 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 \ +</pre> + +<p>For details, see:</p> + +<pre class="devsite-terminal">assemble_vintf --help</pre> + +<h2 id="testing">Testing</h2> +<p>The <code>platform/system/libvintf</code> project uses +<a href="https://github.com/google/googletest" class="external">GTest</a> for +the serialization, deserialization, and compatibility checking.</p> + +<h2 id="licensing">Licensing</h2> +<ul> +<li><code>tinyxml2</code> (external/tinyxml2) for serializing/deserializing the +object to/from XML. BSD-like license.</li> +<li><code>libselinux</code> (external/selinux/libselinux) for getting policydb +version. Public domain license.</li> +<li><code>libz</code> (external/zlib) for decompressing +<code>/proc/config.gz</code>. BSD-like license.</li> +<li><code>libvintf</code> project uses Apache 2.0 license (with appropriate +MODULE_LICENSE_APACHE2 and NOTICE files).</li> +</ul> + +<h2 id="caveats">Caveats</h2> +<p>It is also possible to determine the HALs at runtime by querying +<code>hwservicemanager</code> (as <code>lshal</code> does). However:</p> +<ul> +<li><code>hwservicemanager</code> does not list passthrough services.</li> +<li>If a service has just crashed and is restarting, it may be missing from the +query result.</li> +<li>It doesn't work for hot pluggable services.</li> +<li><code>hwservicemanager</code> is not available in recovery mode (see +below).</li> +</ul> + +<p>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.</p> + + </body> +</html> |