| <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="#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> |
| <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> |
| </compatibility-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="compatibility-matrix-schema">Compatibility 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 compatibility 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.instance</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> |