diff options
Diffstat (limited to 'en/devices/architecture/vintf/match-rules.html')
-rw-r--r-- | en/devices/architecture/vintf/match-rules.html | 187 |
1 files changed, 168 insertions, 19 deletions
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> |