diff options
| author | Android Partner Docs <noreply@android.com> | 2018-08-08 13:50:33 -0700 |
|---|---|---|
| committer | Clay Murphy <claym@google.com> | 2018-08-08 14:05:32 -0700 |
| commit | ea448b829ef3c5eefcadcd50fdf74c873eeadd86 (patch) | |
| tree | 34c2647a8d8c2dffdbcdac2c5ba11d41d1426da8 /en/devices/architecture/vintf | |
| parent | 19a77ba572d415186ce503e4bf8be87fe45d08eb (diff) | |
| download | source.android.com-ea448b829ef3c5eefcadcd50fdf74c873eeadd86.tar.gz | |
Docs: Changes to source.android.com
- 207940242 One more fix: add header for Television Requirements. by Gina Dimino <gdimino@google.com>
- 207936055 Update health README link. by Android Partner Docs <noreply@android.com>
- 207929938 Errata run for Android 9 CDD. by Gina Dimino <gdimino@google.com>
- 207897850 Fix typos in Develop and Configure index pages by Kenneth Lau <kennethlau@google.com>
- 207813977 Devsite localized content from translation request 958913. by Android Partner Docs <noreply@android.com>
- 207813949 Devsite localized content from translation request 953118. by Android Partner Docs <noreply@android.com>
- 207813941 Devsite localized content from translation request 961934. by Android Partner Docs <noreply@android.com>
- 207813934 Devsite localized content from translation request 552632. by Android Partner Docs <noreply@android.com>
- 207813463 Update line numbers in links by Kenneth Lau <kennethlau@google.com>
- 207796341 Fixing the URL for the CDD link in versions file. by Gina Dimino <gdimino@google.com>
- 207779392 Fix incorrect link by Kenneth Lau <kennethlau@google.com>
- 207777680 Update build numbers for 2018/08 releases by Android Partner Docs <noreply@android.com>
- 207775888 Update links to AOSP by Kenneth Lau <kennethlau@google.com>
- 207769948 Update links to AOSP by Kenneth Lau <kennethlau@google.com>
- 207763826 Clarify system for HIDL passthrough loading. by Android Partner Docs <noreply@android.com>
- 207733156 Fixing malformed links in html for kernel patches, adding... by Heidi von Markham <hvm@google.com>
- 207650104 Remove link by Heidi von Markham <hvm@google.com>
- 207640627 Tags for Android P. by Android Partner Docs <noreply@android.com>
- 207626815 Making link absolute by Clay Murphy <claym@google.com>
- 207611166 Add Background Restrictions into Release Notes. by Christina Nguyen <cqn@google.com>
- 207606267 Fixing unclosed tag, reformatting for clarity by Heidi von Markham <hvm@google.com>
- 207604244 Fix malformed link by Clay Murphy <claym@google.com>
- 207598416 adding subscript by Heidi von Markham <hvm@google.com>
- 207595049 Fix link in section 3.5.1. by Gina Dimino <gdimino@google.com>
- 207590813 Fix broken link due to file path change by Christina Nguyen <cqn@google.com>
- 207588930 Update Power nav to include changes to mgmt page (broken ... by Christina Nguyen <cqn@google.com>
- 207588102 Separate out the Power Management article into "Applicati... by Christina Nguyen <cqn@google.com>
- 207583000 Fix broken links in HAL interface section by Kenneth Lau <kennethlau@google.com>
- 207582699 Put index files in place as redirects are not taking hold by Clay Murphy <claym@google.com>
- 207575443 P release notes: fix bad links, remove "P release" by Mark Hecomovich <mheco@google.com>
- 207574657 Fix link typo from release notes to Carrier ID page by Christina Nguyen <cqn@google.com>
- 207559561 Integrate SAC next branch into mainline for Android P/9 p... by Mark Hecomovich <mheco@google.com>
- 207559252 Publish links to July localized versions within Japanese ... by Clay Murphy <claym@google.com>
- 207122872 Devsite localized content from translation request 958912. by Android Partner Docs <noreply@android.com>
- 207122854 Devsite localized content from translation request 961384. by Android Partner Docs <noreply@android.com>
- 207007888 Add blurb about the SystemUpdateSampler app on SAC so use... by Christina Nguyen <cqn@google.com>
- 206862073 Update Camera HAL testing page by Kenneth Lau <kennethlau@google.com>
- 206805870 Devsite localized content from translation request 960240. by Android Partner Docs <noreply@android.com>
- 206805861 Devsite localized content from translation request 954945. by Android Partner Docs <noreply@android.com>
PiperOrigin-RevId: 207940242
Change-Id: I3dee204c744e2e6062ac56810b88aefabf84636a
Diffstat (limited to 'en/devices/architecture/vintf')
| -rw-r--r-- | en/devices/architecture/vintf/comp-matrices.html | 95 | ||||
| -rw-r--r-- | en/devices/architecture/vintf/dm.html | 160 | ||||
| -rw-r--r-- | en/devices/architecture/vintf/fcm.html | 446 | ||||
| -rw-r--r-- | en/devices/architecture/vintf/index.html | 32 | ||||
| -rw-r--r-- | en/devices/architecture/vintf/match-rules.html | 187 | ||||
| -rw-r--r-- | en/devices/architecture/vintf/objects.html | 212 | ||||
| -rw-r--r-- | en/devices/architecture/vintf/resources.html | 86 |
7 files changed, 1052 insertions, 166 deletions
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 <a href="#compatibility-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> +<h2 id="framework-compatibility-matrix">Framework compatibility matrix +(FCM)</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> +requirements of the FCM will be satisfied by the device manifest (requirements +enforced at launch and OTA time).</p> -<p>Example framework compatibility matrix file:</p> +<p>Example FCM file:</p> <pre class="prettyprint"> <?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).</p> <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).</p> <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).</p> </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).</p> </compatibility-matrix> </pre> -<h2 id="device-compatibility-matrix">Device compatibility matrix</h2> +<p>For more details, see <a href="/devices/architecture/vintf/fcm">FCM +Lifecycle</a>.</p> + +<h2 id="device-compatibility-matrix">Device compatibility matrix (DCM)</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> +<p>Example DCM file:</p> <pre class="prettyprint"> <?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> </pre> <h2 id="compatibility-matrix-schema">Compatibility matrix schema</h2> +<p>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 +<code><a href="/devices/architecture/vintf/resources#assemble_vintf">assemble_vintf</a></code> +at build time. "Required" tags must be present in the corresponding files on the +device.</p> + <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 compatibility matrix. Describes the elements -expected in the manifest. Unrelated to XML version.</dd> +<dd>Required. Meta-version of this compatibility matrix. Describes the elements +expected in the compatibility matrix. Unrelated to XML version.</dd> <dt><code>compatibility-matrix.type</code></dt> <dd>Required. Type of this compatibility matrix: <ul> @@ -168,6 +192,11 @@ expected in the manifest. Unrelated to XML version.</dd> <li><code>"framework"</code>: Framework compatibility matrix.</li> </ul> </dd> +<dt><code>manifest.level</code></dt> +<dd>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. +<code>DEVICE_FRAMEWORK_COMPATIBILITY_MATRIX_FILE</code>).</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 @@ -184,7 +213,7 @@ there can be several HAL entries with the same name (implies "and" condition). <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 +<code><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: @@ -204,11 +233,28 @@ device) expects.</dd> <dd>Required. Name of the interface.</dd> <dt><code>compatibility-matrix.hal.interface.instance</code></dt> <dd>Optional, can repeat. A list of required instances of this interface.</dd> +<dt><code>compatibility-matrix.hal.interface.regex-instance</code></dt> +<dd>Optional, can repeat. A list of required instance name patterns on this +interface. Use +<a href="http://man7.org/linux/man-pages/man7/regex.7.html" class="external">Extended +Regular Expression</a> format.</dd> +<dt><code>compatibility-matrix.kernel</code></dt> +<dd>Optional, can repeat. Specify a list of kernel configs that the framework +requires on each kernel version.<br> +Multiple <code><kernel></code> with the same <code><version></code> can +exist to imply "and" relationship. Each <code><kernel></code> is a "fragment" +of the requirements that are enabled only when <code><conditions></code> are +met.</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> +<code><var>VERSION</var>.<var>MAJOR_REVISION</var>.<var>MINOR_REVISION</var></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.condition</code></dt> +<dd>Optional. Must not exist for the first <code><kernel></code> of each +version. Specifies a list of conditions. Only when the conditions are met are +the requirements stated in this <code><kernel></code> fragment is enabled. +</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 @@ -257,7 +303,22 @@ with.</dd> <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> +<dt><code>compatibility-matrix.vendor-ndk</code></dt> +<dd>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.</dd> +<dt><code>compatibility-matrix.vendor-ndk.version</code></dt> +<dd>Required. A positive integer that declares a VNDK version required by the +vendor image.</dd> +<dt><code>compatibility-matrix.vendor-ndk.library</code></dt> +<dd>Optional, can repeat. Declares a set of VNDK libraries required by the +vendor image. Same semantics as <code>manifest.vendor-ndk.library</code>.</dd> +<dt><code>compatibility-matrix.system-sdk.version</code></dt> +<dd>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.</dd> </dl> </body> </html> + 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 @@ +<html devsite> + <head> + <title>Device Manifest Development</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + {% include "_versions.html" %} + <body> + <!-- + Copyright 2018 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>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.</p> + +<aside class="note"><strong>Note:</strong> For details on terms used in this +page, see <a href="/devices/architecture/vintf/fcm#terminology">Terminology</a>. +</aside> + +<h2 id=develop-new-devices>Developing new devices</h2> +<p>When defining the device Target FCM Version for new devices:</p> + +<ol> +<li>Leave <code>DEVICE_MANIFEST_FILE</code> and +<code>PRODUCT_ENFORCE_VINTF_MANIFEST</code> undefined.</li> +<li>Implement HALs for the Target FCM Version.</li> +<li>Write the correct device manifest file.</li> +<li>Write the Target FCM Version to device manifest file.</li> +<li>Set <code>DEVICE_MANIFEST_FILE</code>.</li> +<li>Set <code>PRODUCT_ENFORCE_VINTF_MANIFEST</code> to <code>true</code>.</li> +</ol> + +<h2 id=release-new-devices>Releasing new devices</h2> +<p>When a new device is released, its initial Target FCM Version needs to be +determined and declared in the device manifest as the +"<code>target-level</code>" attribute in the top-level +<code><manifest></code> element.</p> + +<p>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:</p> + +<pre class="prettyprint"> +<manifest version="1.0" type="device" target-level="3"> + <!-- ... --> +</manifest> +</pre> + +<h2 id=upgrade-vendor-image>Upgrading vendor image</h2> +<p>When upgrading the vendor image for an old device, vendors can choose to +implement new HAL versions and increment the Target FCM Version.</p> + +<h3 id=upgrade-hals>Upgrading HALs</h3> +<p>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:</p> + +<ul> +<li>Google Pixel 2 and Pixel 2 XL devices released with Target FCM Version +2, which implemented the required audio 2.0 HAL +<code>android.hardware.audio@2.0::IDeviceFactory/default</code>.</li> +<li>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 +<code>android.hardware.audio@4.0::IDeviceFactory/default</code>.</li> +<li>Even though the <code>compatibility_matrix.2.xml</code> 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. +</li> +</ul> + +<p>To summarize, given that <code>compatibility_matrix.2.xml</code> requires +audio 2.0 and <code>compatibility_matrix.3.xml</code> requires audio 4.0, the +requirements are as follows:</p> + +<table> +<thead> +<tr> +<th>FCM Version (System)</th> +<th>Target FCM Version (Vendor)</th> +<th>Requirements</th> +</tr> +</thead> +<tbody> +<tr> +<td>2 (8.1)</td> +<td>2 (8.1)</td> +<td>Audio 2.0</td> +</tr> +<tr> +<td>3 ({{ androidPVersionNumber }})</td> +<td>2 (8.1)</td> +<td>Audio 2.0 or 4.0</td> +</tr> +<tr> +<td>3 ({{ androidPVersionNumber }})</td> +<td>3 ({{ androidPVersionNumber }})</td> +<td>Audio 4.0</td> +</tr> +</tbody> +</table> + +<h3 id=upgrade=target-fcm>Upgrading Target FCM Version</h3> + +<p>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:</p> + +<ol> +<li>Implement all new required HAL Versions for the Target FCM Version.</li> +<li>Modify HAL Versions in the device manifest file.</li> +<li>Modify the Target FCM Version in the device manifest file.</li> +<li>Remove deprecated HAL versions.</li> +<li>For devices launched with {{ androidPVersionNumber }} or older, cherry-pick +these CLs before generating OTA update packages: + <ul> + <li><a href="https://android-review.googlesource.com/722283">CL 722283</a></li> + <li><a href="https://android-review.googlesource.com/722284">CL 722284</a></li> + <li><a href="https://android-review.googlesource.com/722345">CL 722345</a></li> + </ul> +</li> +</ol> + +<p>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 <a +href="https://android.googlesource.com/device/google/marlin/+/0a276ad8b98fde395ed99a4b303434800c07049e/manifest.xml#1" class="external">device +manifest</a> declares the Target FCM Version 2 because the vendor image has +been updated to conform with <code>compatibility_matrix.2.xml</code>:</p> + +<pre class="prettyprint"> +<manifest version="1.0" type="device" target-level="2"> +</pre> + +<p>If vendors do not implement all required new HAL versions or do not remove +deprecated HAL versions, the Target FCM Version cannot be upgraded.</p> + +<p>For example, Google Pixel 2 and Pixel 2 XL devices have Target FCM Version 2. +While they do implement some HALs required by +<code>compatibility_matrix.3.xml</code> (such as audio 4.0, health 2.0, etc.), +they do not remove <code>android.hardware.radio.deprecated@1.0</code>, which is +deprecated at FCM Version 3 (Android {{ androidPVersionNumber }}). Hence, these +devices cannot upgrade the Target FCM Version to 3.</p> + +</body> +</html> 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 @@ +<html devsite> + <head> + <title>FCM Lifecycle</title> + <meta name="project_path" value="/_project.yaml" /> + <meta name="book_path" value="/_book.yaml" /> + </head> + {% include "_versions.html" %} + <body> + <!-- + Copyright 2018 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>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 <a href="#hal-version-status">HAL Version</a>. + +<p>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.</p> + +<aside class="note"><strong>Note:</strong> For more details on HIDL HALs, see +<a href="/devices/architecture/vintf/comp-matrices">Compatibility Matrices</a>, +<a href="/devices/architecture/vintf/match-rules">Matching Rules</a>, and +<a href="/devices/architecture/hidl/versioning">HIDL HAL Versioning</a>.</aside> + +<h2 id=terminology>Terminology</h2> + +<table> +<tr> +<th>Framework Compatibility Matrix (FCM)</th> +<td>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.</td> +</tr> +<tr> +<th>Platform FCM Versions (S<sub>F</sub>)</th> +<td>The set of all FCM versions in a framework release. The framework can work +with any vendor implementation that satisfies one of these FCMs.</td> +</tr> +<tr> +<th>FCM Version (F)</th> +<td>The highest version among all FCMs in a framework release.</td> +</tr> +<tr> +<th>Target FCM Version (V)</th> +<td>The targeted FCM version (from S<sub>F</sub>), 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.</td> +</tr> +<tr> +<th>HAL Version</th> +<td>A HAL Version has the format <code>foo@x.y</code>, where <code>foo</code> +is the HAL name and <code>x.y</code> is the specific version; e.g. +<code>nfc@1.0</code>, <code>keymaster@3.0</code> (the root prefix, e.g. +<code>android.hardware</code>, is omitted throughout this document.)</td> +</tr> +<tr> +<th>Device Manifest</th> +<td>An 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.</td> +</tr> +</table> + + +<h2 id=develop-new-fcm>Developing in a new FCM Version</h2> +<p>Android increments the FCM Version for each framework release (such as +Android 8, 8.1, etc). During development, the new +<code>compatibility_matrix.current.xml</code> is created (<code>F</code>) and +the existing <code>compatibility_matrix.f.xml</code> (where <code>f</code> < +<code>F</code>) is no longer changed.</p> + +<p>To start developing in a new FCM Version <code>F</code>:</p> + +<ol> +<li>Copy the latest <code>compatibility_matrix.<F-1>.xml</code> to +<code>compatibility_matrix.current.xml</code>.</li> +<li>Update the <code>level</code> attribute in the file to <code>F</code>.</li> +<li>Add corresponding build rules to install this compatibility matrix to the +device.</li> +</ol> + +<h2 id=introduce-new-hal>Introducing a new HAL</h2> +<p>During development, when introducing a new HAL (Wi-Fi, NFC, etc.) to Android +on the current FCM Version <code>F</code>, add the HAL to +<code>compatibility_matrix.current.xml</code> with the following +<code>optional</code> settings:</p> + +<ul> +<li><code>optional="false"</code> if devices that ship with <code>V = F</code> +must launch with this HAL,<br> +<br> +OR +<br> +</li> +<li><code>optional="true"</code> if devices that ship with <code>V = F</code> +can launch without this HAL.</li> +</ul> + +<p>For example, Android 8.1 introduced <code>cas@1.0</code> as an optional HAL. +Devices launching with Android 8.1 are not required to implement this HAL, so +the following entry was added to <code>compatibility_matrix.current.xml</code> +(renamed to <code><a +href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.2.xml#74" class="external">compatibility_matrix.2.xml</code></a> +after Android 8.1 released):</p> + +<pre class="prettyprint"> +<hal format="hidl" optional="true"> + <name>android.hardware.cas</name> + <version>1.0</version> + <interface> + <name>IMediaCasService</name> + <instance>default</instance> + </interface> +</hal> +</pre> + +<h2 id=upgrade-hal-minor>Upgrading a HAL (minor)</h2> +<p>During development, when a HAL has a minor-version upgrade from +<code>x.z</code> to <code>x.(z+1)</code> at current FCM Version <code>F</code>, +if that version is:</p> + +<ul> +<li>Required on devices launching with <code>V = F</code>, the +<code>compatibility_matrix.current.xml</code> must state <code>x.(z+1)</code>and +<code>optional="false"</code>.</li> +<li>Not required on devices launching with <code>V = F</code>, the +<code>compatibility_matrix.current.xml</code> must copy <code>x.y-z</code> and +optionality from <code>compatibility_matrix.<F-1>.xml</code> and change +the version to <code>x.w-(z+1)</code> (where <code>w >= y</code>).</li> +</ul> + +<p>For example, Android 8.1 introduced <code>broadcastradio@1.1</code> as a +minor version upgrade of 1.0 HAL. The older version, +<code>broadcastradio@1.0</code>, is optional for devices launching with Android +8.0 while the newer version, <code>broadcastradio@1.1</code>, is optional for +devices launching with Android 8.1. In <code><a +href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.1.xml#58" class="external">compatibility_matrix.1.xml</code></a>:</p> + +<pre class="prettyprint"> +<hal format="hidl" optional="true"> + <name>android.hardware.broadcastradio</name> + <version>1.0</version> + <interface> + <name>IBroadcastRadioFactory</name> + <instance>default</instance> + </interface> +</hal> +</pre> + +<p>This entry was copied to <code>compatibility_matrix.current.xml</code> +(renamed to <code><a +href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.2.xml#58">compatibility_matrix.2.xml</code></a> +after Android 8.1 released) and modified as follows:</p> + +<pre class="prettyprint"> +<hal format="hidl" optional="true"> + <name>android.hardware.broadcastradio</name> + <version>1.0-1</version> + <interface> + <name>IBroadcastRadioFactory</name> + <instance>default</instance> + </interface> +</hal> +</pre> + +<h2 id=upgrade-hal-major>Upgrading a HAL (major)</h2> +<p>During development, when a HAL has a major-version upgrade at current FCM +Version <code>F</code>, the new major version <code>x.0</code> is added to +<code>compatibility_matrix.current.xml</code> with the following +<code>optional</code> settings:</p> + +<ul> +<li><code>optional="false"</code> with only version <code>x.0</code>, if devices +that ship with <code>V = F</code> must launch with <code>x.0</code>.</li> +<li><code>optional="false"</code> but along with older major versions in the +same <code><hal></code> tag, if devices that ship with <code>V = F</code> +must launch with this HAL, but can launch with an older major version.</li> +<li><code>optional="true"</code> if devices that ship with <code>V = F</code> do +not have to launch the HAL.</li> +</ul> + +<p>For example, Android {{ androidPVersionNumber }} introduces +<code>health@2.0</code> as a major-version upgrade of the 1.0 HAL and deprecates +the 1.0 HAL. The older version, <code>health@1.0</code>, 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 <code><a +href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.legacy.xml#150" class="external">compatibility_matrix.legacy.xml</code></a>, +<code><a +href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.1.xml#150" class="external">compatibility_matrix.1.xml</code></a>, +and <code><a +href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.2.xml#158" class="external">compatibility_matrix.2.xml</code></a>:</p> + +<pre class="prettyprint"> +<hal format="hidl" optional="true"> + <name>android.hardware.health</name> + <version>1.0</version> + <interface> + <name>IHealth</name> + <instance>default</instance> + </interface> +</hal> +</pre> + +<p>This entry is copied to <code>compatibility_matrix.current.xml</code> +(renamed to <code>compatibility_matrix.3.xml</code> with the Android +{{ androidPVersionNumber }} release) and modified as follows:</p> + +<pre class="prettyprint"> +<hal format="hidl" optional="false"> + <name>android.hardware.health</name> + <version>2.0</version> + <interface> + <name>IHealth</name> + <instance>default</instance> + </interface> +</hal> +</pre> + +<p>Restrictions:</p> +<ul> +<li>Because the 2.0 HAL is in <code>compatibility_matrix.3.xml</code> with +<code>optional="false"</code>, devices that launch with Android +{{ androidPVersionNumber }} must ship with 2.0 HAL.</li> +<li>Because the 1.0 HAL is not in <code>compatibility_matrix.3.xml</code>, +devices that launch with Android {{ androidPVersionNumber }} must not provide +the 1.0 HAL (as this HAL is considered deprecated).</li> +<li>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).</li> +</ul> + +<h2 id=new-fcm-versions>New FCM Versions</h2> +<p>The process of releasing an FCM Version is done solely by Google as part of +an AOSP release and includes the following steps:</p> + +<ol> +<li>Rename <code>compatibility_matrix.current.xml</code> to +<code>compatibility_matrix.F.xml</code>.</li> +<li>Ensure the file has the attribute <code>level="F"</code>.</li> +<li>Edit corresponding <a +href="https://android.googlesource.com/platform/hardware/interfaces/+/2d8442c76270b2c32816d1dac56bbd536b0bf790/compatibility_matrices/Android.mk" class="external">build +rules</a> to reflect the file name change.</li> +<li>Ensure all devices build and boot.</li> +<li><a +href="https://android.googlesource.com/platform/test/vts-testcase/hal/+/95e09aca7711cace6184077debc556b05335a8b1/treble/vintf/vts_treble_vintf_test.cpp#87" class="external">Update +VTS tests</a> to ensure devices launching with the latest framework (based +on Shipping API level) have Target FCM Version <code>V >= F</code>.</li> +<li>Publish file to AOSP.</li> +</ol> + +<p>This file <strong>cannot</strong> be changed once renamed and published. For +example, during Android {{ androidPVersionNumber }} development the following +files are <a +href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/Android.mk" class="external">built</a> +for <code>hardware/interfaces/compatibility_matrices/</code>:</p> + +<ul> +<li><code>compatibility_matrix.legacy.xml</code></li> +<li><code>compatibility_matrix.1.xml</code></li> +<li><code>compatibility_matrix.2.xml</code></li> +<li><code>compatibility_matrix.current.xml</code></li> +</ul> + +<p>When Android {{ androidPVersionNumber }} is released, +<code>compatibility_matrix.current.xml</code> is renamed to +<code>compatibility_matrix.3.xml</code> and the following files are +built for <code>hardware/interfaces/compatibility_matrices/</code>:</p> + +<ul> +<li><code>compatibility_matrix.legacy.xml</code></li> +<li><code>compatibility_matrix.1.xml</code></li> +<li><code>compatibility_matrix.2.xml</code></li> +<li><code>compatibility_matrix.3.xml</code></li> +</ul> + +<p> +<a href="https://android.googlesource.com/platform/test/vts-testcase/hal/+/95e09aca7711cace6184077debc556b05335a8b1/treble/vintf/vts_treble_vintf_test.cpp#435" class="external">VTS +tests</a> ensure that devices launching with Android {{ androidPVersionNumber }} +have Target FCM Version >= 3.</p> + +<h2 id=hal-version-deprecation>HAL Version deprecation</h2> + +<p>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 <code>foo@x.y</code> is deprecated at FCM +Version <code>F</code>, it means that any device launching with Target FCM +Version <code>V = F</code> or later must not implement <code>foo</code> at +version <code>x.y</code> or any version older than <code>x.y</code>. A +deprecated HAL version is still supported by the framework for upgrading +devices.</p> + +<p>When FCM Version <code>F</code> is released, a HAL Version +<code>foo@x.y</code> is considered deprecated if the specific HAL Version is not +explicitly stated in the latest FCM for Target FCM Version <code>V = F</code>. +For devices launching with <code>V</code>, one of the following conditions is +true:</p> + +<ul> +<li>The framework requires a higher version (major or minor);</li> +<li>The framework doesn't require the HAL anymore.</li> +</ul> + +<p>For example, in Android {{ androidPVersionNumber }}, <code>health@2.0</code> +is introduced as a major version upgrade of 1.0 HAL. <code>health@1.0</code> is +removed from <code>compatibility_matrix.3.xml</code> but is present in <code><a +href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.legacy.xml#150" class="external">compatibility_matrix.legacy.xml</code></a>, +<code><a +href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.1.xml#150" class="external">compatibility_matrix.1.xml</code></a>, +and <code><a +href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.2.xml#158" class="external">compatibility_matrix.2.xml</code></a>. +Hence, <code>health@1.0</code> is considered deprecated.</p> + +<h2 id=removal-of-support>Removal of support for Target FCM Versions</h2> +<p>When active devices of a certain Target FCM Version <code>V</code> drop below +a certain threshold, the Target FCM Version is removed from the set +S<sub>F</sub> of the next framework release. This is done by removing +<code>compatibility_matrix.V.xml</code> 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 S<sub>F</sub> for a given framework release cannot upgrade to that +release.</p> + +<h2 id=hal-version-status>HAL Version status</h2> +<p>The following sections describe (in chronological order) the possible states +of a HAL Version.</p> + +<h3 id=hal-unreleased>Unreleased</h3> +<p>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 <code>compatibility_matrix.current.xml</code>. +Examples:</p> + +<ul> +<li>During the development of Android {{ androidPVersionNumber }} (before +<code>compatibiility_matrix.current.xml</code> is renamed to +<code>compatibility_matrix.3.xml</code>), the <code>health@2.0</code> HAL was +considered an unreleased HAL.</li> +<li>The <code>teleportation@1.0</code> HAL is not in any released compatibility +matrices, and is also considered an unreleased HAL.</li> +</ul> + +<h3 id=hal-released-and-current>Released and Current</h3> +<p>If a HAL Version is in any public and frozen compatibility matrix, it is +released. For example, after FCM Version 3 is frozen (when +<code>compatibiility_matrix.current.xml</code> is renamed to +<code>compatibility_matrix.3.xml</code>) and published to AOSP, the +<code>health@2.0</code> HAL is considered a released and current HAL Version. +</p> + +<p>If a HAL Version is in a public and frozen compatibility matrix that has +the highest FCM Version (excluding +<code>compatibility_matrix.current.xml</code>), the HAL version is current (i.e. +not deprecated). For example, existing HAL Versions (such as +<code>nfc@1.0</code> introduced in <code><a +href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.legacy.xml#198" class="external">compatibility_matrix.legacy.xml</code></a>) +that continue to exist in <code>compatibility_matrix.3.xml</code> are also +considered as released and current HAL Versions.</p> + +<h3 id=hal-released-but-deprecated>Released but Deprecated</h3> +<p>A HAL Version is deprecated if and only if:</p> + +<ul> +<li>It is released;</li> +<li>It is not in the public and frozen compatibility matrix that has the highest +FCM Version;</li> +<li>It is in a public and frozen compatibility matrix that the framework still +supports.</li> +</ul> + +<p>Examples:</p> + +<ul> +<li>The <code>health@1.0</code> HAL is in in <code><a +href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.legacy.xml#150" class="external">compatibility_matrix.legacy.xml</code></a>, +<code><a +href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.1.xml#150" class="external">compatibility_matrix.1.xml</code></a>, +and <code><a +href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.2.xml#158" class="external">compatibility_matrix.2.xml</code></a>, +but not in <code>compatibility_matrix.3.xml</code>. Hence it is considered +deprecated in Android {{ androidPVersionNumber }}.</li> +<li>The power HAL has a minor version upgrade in Android +{{ androidPVersionNumber }}, but <code>power@1.0</code> is still in +<code>compatibility_matrix.3.xml</code>. +<ul> +<li><code>power@1.0</code> is in <code><a +href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.legacy.xml#206" class="external">compatibility_matrix.legacy.xml</code></a>, +<code><a +href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.1.xml#206" class="external">compatibility_matrix.1.xml</code></a>, +and <code><a +href="https://android.googlesource.com/platform/hardware/interfaces/+/241e5aba9ebfe85a9599b333f89be51905148f81/compatibility_matrices/compatibility_matrix.2.xml#222" class="external">compatibility_matrix.2.xml</code></a>.</li> +<li><code>compatibility_matrix.3.xml</code> has <code>power@1.0-1</code>.</li> +</ul> +</li> +</ul> + +<p>Hence <code>power@1.0</code> is current, but <strong>NOT</strong> deprecated, +in Android {{ androidPVersionNumber }}.</p> + +<h3 id=hal-removed>Removed</h3> +<p>A HAL Version is removed if and only if:</p> + +<ul> +<li>It was previously released;</li> +<li>It is not in any public and frozen compatibility matrix that the framework +supports. </li> +</ul> + +<p>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. +</p> + +<h2>Legacy FCMs</h2> +<p>Target FCM Version legacy is a special value for all non-Treble devices. The +legacy FCM, <code>compatibility_matrix.legacy.xml</code>, lists the requirements +of the framework on legacy devices (i.e. devices launched prior to Android 8.0). +</p> + +<p>If this file exists for an FCM with version <code>F</code>, any non-Treble +device can be upgraded to <code>F</code> 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).</p> + +</body> +</html> 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.</p> <img src="../images/treble_vintf_mm.png"> <figcaption><strong>Figure 1.</strong> Manifests, compatibility matrices, and -runtime-collectible information.</figcaption> +runtime-collectible information</figcaption> <p>VINTF object design provides the following for device and framework components:</p> @@ -76,9 +76,9 @@ 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 +<p>As of Android 8.0, a runtime API queries what is on the device and sends 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> @@ -101,13 +101,23 @@ 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> +<p>This section includes the following details on manifests and matrices:</p> +<ul> + <li><a href="/devices/architecture/vintf/objects.html">Manifests</a> defines + the device manifest, framework manifest, and manifest file schema.</li> + <li><a href="/devices/architecture/vintf/comp-matrices.html">Compatibility + Matrices</a> defines the schema for the compatibility matrix.</li> + <li><a href="/devices/architecture/vintf/fcm.html">FCM Lifecycle</a> details + how HIDL HALs are deprecated and removed and how FCM files are modifed to + reflect the status of the HAL Version.</li> + <li><a href="/devices/architecture/vintf/dm.html">DM Development</a> 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.</li> + <li><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.</li> +</ul> </body> </html> 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.</p> +<h2 id="fcm-version">Framework compatibility matrix version matches</h2> +<p>To match a device manifest with a framework compatibility matrix, +the Shipping FCM version specified by <code>manifest.target-level</code> +must exactly equal to the FCM version specified by +<code>compatibility-matrix.level</code>. Otherwise there is no match.</p> + +<p>If the framework compatibility matrix is requested with +<code>libvintf</code>, this match is always successful because +<code>libvintf</code> 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).</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> +<li>Multiple <code><hal></code> elements have <strong>AND</strong> +relationship.</li> +<li>Multiple <code><version></code> elements within the same +<code><hal></code> have +<strong>OR</strong> relationship. If two or more are specified, only +one of the version needs to be implemented (see DRM example below).</li> +<li>Multiple <code><instance></code> and +<code><regex-instance></code> elements within the same +<code><hal></code> have +<strong>AND</strong> relationship (see DRM example below).</li> </ul> <h4><strong>Example</strong>: Successful HAL match for Camera module</h4> @@ -92,28 +111,32 @@ for DRM HAL:</p> <interface> <name>ICryptoFactory</name> <instance>default</instance> + <regex-instance>[a-z]+/[0-9]+</regex-instance> </interface> </hal> </pre> -<p>A vendor must implement ONE of the following HALs:</p> +<p>A vendor must implement ONE of the following instances:</p> <pre> -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 </pre> OR <pre> -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 </pre> -<p>... AND must also implement this HAL:</p> +<p>... AND must also implement all of these instances:</p> <pre> -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 </pre> <h2 id="kernel">Kernel matches</h2> @@ -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.</li> <li><code><kernel-sepolicy-version></code> i.e. policydb version. Must -exactly match the <code>security_policyvers()</code> reported by the device. +be less than the <code>security_policyvers()</code> reported by the device. </li> </ul> @@ -266,17 +289,22 @@ exactly match the <code>security_policyvers()</code> reported by the device. </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> +<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>The value returned by <code>security_policyvers()</code> must be greater +than or equal to 30. Otherwise it is not a match. For example: +<ul> +<li>If a device returns 29, it is not a match.</li> +<li>If a device returns 31, it is a match.</li> +</ul> +</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> @@ -362,5 +390,126 @@ 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> +<h2 id="vndk">VNDK version matches</h2> +<p>The device compatibility matrix declares the required VNDK version in +<code>compatibility-matrix.vendor-ndk.version</code>. If the device +compatibility matrix does not have a <code><vendor-ndk></code> tag, no +requirements are imposed, and hence it is always considered a match.</p> +<p>If the device compatibility matrix does have a <code><vendor-ndk></code> +tag, an <code><vendor-ndk></code> entry with a matching +<code><version></code> 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.</p> +<p>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.</p> +<ul> + <li>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.</li> +</ul> + +<h4><strong>Example:</strong> Successful VNDK version match</h4> +<p>If the device compatibility matrix states the following requirement on VNDK: +</p> + +<pre class="prettyprint"> +<!-- Example Device Compatibility Matrix --> +<vendor-ndk> + <version>27</version> + <library>libjpeg.so</library> + <library>libbase.so</library> +</vendor-ndk> +</pre> + +<p>In the framework manifest, only the entry with version 27 is considered.</p> + +<pre class="prettyprint"> +<!-- Framework Manifest Example A --> +<vendor-ndk> + <version>27</version> + <library>libjpeg.so</library> + <library>libbase.so</library> + <library>libfoo.so</library> +</vendor-ndk> +</pre> + +<p>Example A is a match, because VNDK version 27 is in the framework manifest, +and <code>{libjpeg.so, libbase.so, libfoo.so} ⊇ {libjpeg.so, libbase.so}</code>. +</p> + +<pre class="prettyprint"> +<!-- 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> +</pre> + +<p>Example B is not a match. Even though VNDK version 27 is in the framework +manifest, <code>libjpeg.so</code> is not supported by the framework in that +snapshot. VNDK version 26 is ignored.</p> + +<h2 id="vsdk">System SDK version matches</h2> +<p>The device compatibility matrix declares a set of required System SDK +version in <code>compatibility-matrix.system-sdk.version</code>. There is a +match only if the set is a subset of provided System SDK versions as declared +in <code>manifest.system-sdk.version</code> in the framework manifest.</p> +<ul> + <li>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.</li> +</ul> + +<h4><strong>Example:</strong> Successful System SDK version match</h4> +<p>If the device compatibility matrix states the following requirement on System +SDK: +</p> + +<pre class="prettyprint"> +<!-- Example Device Compatibility Matrix --> +<system-sdk> + <version>26</version> + <version>27</version> +</system-sdk> +</pre> + +<p>Then, the framework must provide System SDK version 26 and 27 to match.</p> + +<pre class="prettyprint"> +<!-- Framework Manifest Example A --> +<system-sdk> + <version>26</version> + <version>27</version> +</system-sdk> +</pre> + +<p>Example A is a match.</p> + +<pre class="prettyprint"> +<!-- Framework Manifest Example B --> +<system-sdk> + <version>26</version> + <version>27</version> + <version>28</version> +</system-sdk> +</pre> + +<p>Example B is a match.</p> + +<pre class="prettyprint"> +<!-- Framework Manifest Example C --> +<system-sdk> + <version>26</version> +</system-sdk> +</pre> + +<p>Example C is not a match, because System SDK version 27 is not provided.</p> + </body> </html> 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 @@ <html devsite> <head> - <title>VINTF Object Data</title> + <title>Manifests</title> <meta name="project_path" value="/_project.yaml" /> <meta name="book_path" value="/_book.yaml" /> </head> @@ -21,26 +21,39 @@ 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/vintfdata/manifest.xml" class="external">/vintfdata/manifest.xml</a></code>. +<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> -<p>Example Device manifest:</p> +<h2 id="device-manifest-file">Device manifest</h2> +<p>The Device manifest (provided by the device) consists of the vendor manifest +and the ODM manifest:</p> + +<ul> +<li>The vendor manifest specifies HALs, VNDK versions, etc. common to an SoC. It +is recommended to be placed in the Android source tree at +<code>device/${VENDOR}/${DEVICE}/manifest.xml</code>, but multiple fragment +files can be used. For details, see +<a href="/devices/architecture/vintf/resources.html#manifest-fragments">Generate +DM from fragments</a>. +</li> +<li>The ODM manifest overrides the vendor manifest and lists HALs specific to +the product.</li> +</ul> + +<p>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).</p> + +<p>Example vendor manifest:</p> <pre class="prettyprint"> <?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> </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 ODM manifest:</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="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> +</pre> + +For more details, see <a href="/devices/architecture/vintf/dm">DM +Development</a>. + +<h2 id="framework-manifest-file">Framework manifest</h2> +<p>The Framework manifest file (provided by Google) is manually generated and +lives in the Android source tree at +<code><a href="https://android.googlesource.com/platform/system/libhidl/+/master/manifest.xml" class="external">/system/libhidl/manifest.xml</a></code>. +</p> + +<p>Example Framework manifest:</p> <pre class="prettyprint"> <?xml version="1.0" encoding="UTF-8"?> @@ -133,20 +196,36 @@ and on the device under <code>/system/manifest.xml</code>.</p> <instance>default</instance> </interface> </hal> + <vendor-ndk> + <version>27</version> + </vendor-ndk> + <system-sdk> + <version>27</version> + </system-sdk> </manifest> </pre> <h2 id="manifest-file-schema">Manifest file schema</h2> +<p>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 +<code><a href="/devices/architecture/vintf/resources.html#assemble_vintf">assemble_vintf</a></code> +at build time. "Required" tags must be present in the corresponding files on the +device.</p> + <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> +<dd>Required. Meta-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.target-level</code></dt> +<dd>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.</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> @@ -157,6 +236,17 @@ depending on the <code>format</code> attribute.</dd> <li><code>native</code>: native HALs.</li> </ul> </dd> +<dt><code>manifest.hal.override</code></dt> +<dd>Optional. Value can be one of: + <ul> + <li><code>true</code>: override other <code><hal></code> elements with + the same <code><name></code> and major version. If no + <code><version></code> or <code><fqname></code> are in this + <code><hal></code> element, then this HAL is disabled.</li> + <li><code>false</code>: do not override other <code><hal></code> elements + with the same <code><name></code> and major version.</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: @@ -185,7 +275,7 @@ provided. Value can be one of: </ul> </dd> <dt><code>manifest.hal.version</code></dt> -<dd>Required, can repeat. A version for the <code>hal</code> tags in a +<dd>Optional, 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>, @@ -195,7 +285,8 @@ system/hardware/interfaces</code>. 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> +This applies for all <code>hal</code> elements with the same name, unless +<code>override="true"</code>.</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 @@ -207,56 +298,37 @@ must be distinct.</dd> <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.hal.fqname</code></dt> +<dd>Optional, can repeat. An alternative way to specify an instance for the HAL +with name <code>manifest.hal.name</code>. Format is +<code>@<var>MAJOR</var>.<var>MINOR</var>::<var>INTERFACE</var>/<var>INSTANCE</var></code>. +For devices upgrading from Android 8.0, this cannot be used to declare +instances required by the compatibility matrix.</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> +<dd>Required for device manifest. Declares SELinux version. It has the +format <code><var>SDK_INT</var>.<var>PLAT_INT</var></code>.</dd> +<dt><code>manifest.vendor-ndk</code></dt> +<dd>Required, can repeat; required for framework manifest. Must not be present +in the device manifest. Multiple <code><vendor-ndk></code> entries must have +different <code><version></code>’s. Describes a set of VNDK snapshots +provided by the framework.</dd> +<dt><code>manifest.vendor-ndk.version</code></dt> +<dd>Required. It is a positive integer representing the version of the VNDK +snapshot.</dd> +<dt><code>manifest.vendor-ndk.library</code></dt> +<dd>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. <code>libjpeg.so</code>, including the prefix +<code>lib</code> and the suffix <code>.so</code>. No path components are +allowed.</dd> +<dt><code>manifest.system-sdk.version</code></dt> +<dd>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.</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 index 0f408a89..7f70ffff 100644 --- a/en/devices/architecture/vintf/resources.html +++ b/en/devices/architecture/vintf/resources.html @@ -22,7 +22,7 @@ --> <p>The following resources provide details on code locations, tools, testing, -licensing, and caveats.</p> +and licensing.</p> <h2 id=query-api-code>Queryable code location</h2> <p>The code for the queryable vendor interface object goes to @@ -51,9 +51,8 @@ adb shell su 0 /system/bin/lshal --init-vintf <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>No SELinux version is written into the manifest. It is suggested that the +element is 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> @@ -74,32 +73,21 @@ compatibility matrix that is compatible with the manifest file.</li> matrix</strong> from a framework manifest file</h4> <pre class="devsite-terminal"> -assemble_vintf -m \ +assemble_vintf -m --hals-only \ -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> +<p>Note that all HALs are set to <code>optional="true"</code>.</p> <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 +assemble_vintf -m --hals-only \ + -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> +<p>Note that all HALs are set to <code>optional="true"</code>.</p> <h4><strong>Example:</strong> Generate XML files from variables</h4> @@ -113,37 +101,53 @@ 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> +<p>Then the following commands are executed (in the build system, modified to omit implementation +details) 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 + $(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 </pre> -<h4><strong>Example:</strong> Generate device manifest from fragments</h4> +<h4 id=manifest-fragments><strong>Example:</strong> +Generate device manifest from fragments</h4> <p>Multiple device manifest fragments can be bundled at build time. For example:</p> @@ -210,21 +214,5 @@ version. Public domain license.</li> 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> |