1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
|
<html devsite>
<head>
<title>Matching Rules</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>The two pairs of compatibility matrices and manifests are meant to be
reconciled at <a href="/devices/tech/ota/index.html">OTA</a> time to verify the
framework and vendor implementation can work with each other. This verification
is successful upon a match between the framework compatibility matrix and the
device manifest, as well as between the framework manifest and the device
compatibility matrix. The following sections detail matching rules used by
various components.</p>
<h2 id="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><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>
<p>For a HAL at version 2.5, the match rule is as follows:</p>
<table>
<tr>
<th>Matrix</th>
<th>Matching Manifest</th>
</tr>
<tr>
<td><code>2.5</code></td>
<td>2.5-2.∞. Shorthand for 2.5-5.</td>
</tr>
<tr>
<td><code>2.5-7</code></td>
<td>2.5-2.∞. Indicates the following:
<br>
<ul>
<li>2.5 is the minimum required version, meaning a manifest providing HAL
2.0-2.4 is not compatible.</li>
<li>2.7 is the maximum version that could be requested, meaning the owner of
the compatibility matrix (framework or device) will not request versions
beyond 2.7. The owner of the matching manifest can still serve version 2.10
(as an example) when 2.7 is requested. The compatibility-matrix owner knows
only that the requested service is compatible with API version 2.7.</li>
<li>-7 is informational only and does not affect the OTA update process.</li>
</ul>
Thus, a device with a HAL at version 2.10 in its manifest file remains
compatible with a framework that states <code>camera:</code>
<code>2.5-7</code> in its compatibility matrix.</td>
</tr>
</table>
<h4><strong>Example:</strong> Successful HAL match for DRM module</h4>
<p>The framework compatibility matrix states the following version information
for DRM HAL:</p>
<pre class="prettyprint"><hal>
<name>android.hardware.drm
<version>1.0</version>
<version>3.1-2</version>
<interface>
<name>IDrmFactory</name>
<instance>default</instance>
<instance>specific</instance>
</interface>
</hal>
<hal>
<name>android.hardware.drm
<version>2.0</version>
<interface>
<name>ICryptoFactory</name>
<instance>default</instance>
<regex-instance>[a-z]+/[0-9]+</regex-instance>
</interface>
</hal>
</pre>
<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
</pre>
OR
<pre>
android.hardware.drm@3.y::IDrmFactory/default // where y >= 1
android.hardware.drm@3.y::IDrmFactory/specific // where y >= 1
</pre>
<p>... AND must also implement all of these instances:</p>
<pre>
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>
<p>The <code><kernel></code> section of the framework compatibility matrix
describes the framework's requirements of the Linux kernel on the device. This
information is meant to be matched at OTA time against the
<a href="/devices/architecture/vintf/objects.html#runtime-collectible-information">information</a>
about the kernel that gets reported by the device's VINTF object.</p>
<p>A matrix can include multiple <code><kernel></code> sections, each with
a different <code>version</code> attribute using the format:</p>
<pre class="prettyprint">${ver}.${major_rev}.${kernel_minor_rev}</pre>
<p>The OTA considers only the <code><kernel></code> section with the same
<code>${ver}</code> and <code>${major_rev}</code> as the device kernel (i.e.,
<code>version="${ver}.${major_rev}.${matrix_minor_rev}")</code>; other sections
are ignored. In addition, the minor revision from the kernel must be a value
from the compatibility matrix (<code>${kernel_minor_rev} >=
${matrix_minor_rev}</code>;). If no <code><kernel></code> section meets
these requirements, it is a non-match.</p>
<p>If the <code><kernel></code> section does match, the process continues
by attempting to match <code>config</code> elements against
<code>/proc/config.gz</code>. For each config element in the compatibility
matrix, it looks up <code>/proc/config.gz</code> to see if the config is
present. When a config item is set to <code>n</code> in the compatibility
matrix for the matching <code><kernel></code> section, it must be absent
from <code>/proc/config.gz</code>. Finally, a config item not in the
compatibility matrix may or may not be present in <code>/proc/config.gz</code>.
</p>
<p>Examples of matches:</p>
<ul>
<li><code><value type="string">bar</value></code> matches
<code>"bar"</code>. Quotes are omitted in the compatibility matrix but present
in <code>/proc/config.gz</code>.</li>
<li><code><value type="int">4096</value></code> matches
<code>4096</code> or <code>0x1000</code> or <code>0X1000</code>.</li>
<li><code><value type="int">0x1000</value></code> matches
<code>4096</code> or <code>0x1000</code> or <code>0X1000</code>.</li>
<li><code><value type="int">0X1000</value></code> matches
<code>4096</code> or <code>0x1000</code> or <code>0X1000</code>.</li>
<li><code><value type="tristate">y</value></code> matches
<code>y</code>.</li>
<li><code><value type="tristate">m</value></code> matches
<code>m</code>.</li>
<li><code><value type="tristate">n</value></code> means the config
item must NOT exist in <code>/proc/config.gz</code>.</li>
<li><code><value type="range">1-0x3</value></code> matches
<code>1</code>, <code>2</code>, or <code>3</code>, or hexadecimal equivalent.
</li>
</ul>
<h4><strong>Example:</strong> Successful kernel match</h4>
<p>A framework compatibility matrix has the following kernel information:</p>
<pre class="prettyprint">
<kernel version="3.18.51">
<config>
<key>CONFIG_TRI</key>
<value type="tristate">y</value>
</config>
<config>
<key>CONFIG_NOEXIST</key>
<value type="tristate">n</value>
</config>
<config>
<key>CONFIG_DEC</key>
<value type="int">4096</value>
</config>
<config>
<key>CONFIG_HEX</key>
<value type="int">0XDEAD</value>
</config>
<config>
<key>CONFIG_STR</key>
<value type="string">str</value>
</config>
<config>
<key>CONFIG_EMPTY</key>
<value type="string"></value>
</config>
</kernel>
</pre>
<p>The kernel version is matched first. If a device in <code>uname()</code>
reports:</p>
<ul>
<li>3.10.73 (no match to matrix unless there is a separate kernel section
with <code><kernel version="3.10.x"></code> where <code>x <= 73</code>)
</li>
<li>3.18.50 (no match to matrix, smaller than <code>version</code>)</li>
<li>3.18.51 (match to matrix)</li>
<li>3.18.52 (match to matrix)</li>
<li>4.1.22 (no match to matrix unless there is a separate kernel section
with <code><kernel version="4.1.x"></code> where <code>x <= 22</code>)
</li>
</ul>
<p>After the appropriate <code><kernel></code> section is selected, for
each <code><config></code> item with value other than <code>n</code>, we
expect the corresponding entry to be present in <code>/proc/config.gz</code>;
for each <code><config></code> item with value <code>n</code>, we expect
the corresponding entry to not be present in <code>/proc/config.gz</code>. We
expect the content of <code><value></code> to exactly match the text after
the equal sign (including quotes), up to the newline character or
<code>#</code>, with leading and trailing whitespace truncated.</p>
<p>The following kernel configuration is an example of a successful match:</p>
<pre class="prettyprint">
# comments don't matter
CONFIG_TRI=y
# CONFIG_NOEXIST should not exist
CONFIG_DEC = 4096 # trailing comments and whitespaces are fine
CONFIG_HEX=57005 # 0XDEAD == 57005
CONFIG_STR="str"
CONFIG_EMPTY="" # empty string must have quotes
CONFIG_EXTRA="extra config items are fine too"
</pre>
<p>The following kernel configuration is an example of an unsuccessful match:</p>
<pre class="prettyprint">
CONFIG_TRI="y" # mismatch: quotes
CONFIG_NOEXIST=y # mismatch: CONFIG_NOEXIST exists
CONFIG_HEX=0x0 # mismatch; value doesn't match
CONFIG_DEC="" # mismatch; type mismatch (expect int)
CONFIG_EMPTY=1 # mismatch; expects ""
# mismatch: CONFIG_STR is missing
</pre>
<h2 id="se-policy">SE policy matches</h2>
<p>SE policy requires the following matches:</p>
<ul>
<li><code><sepolicy-version></code> defines a closed range of minor
versions for every major version. The sepolicy version reported by the device
must fall within one of these ranges to be compatible with the framework. Match
rules are similar to HAL versions; it is a match if the sepolicy version is
higher or equal to the minimum version for the range. The maximum version is
purely informational.</li>
<li><code><kernel-sepolicy-version></code> i.e. policydb version. Must
be less than the <code>security_policyvers()</code> reported by the device.
</li>
</ul>
<h4><strong>Example:</strong> Successful SE policy match</h4>
<p>The framework compatibility matrix states the following sepolicy information:
</p>
<pre class="prettyprint">
<sepolicy>
<kernel-sepolicy-version>30</kernel-sepolicy-version>
<sepolicy-version>25.0</sepolicy-version>
<sepolicy-version>26.0-3</sepolicy-version>
</sepolicy>
</pre>
<p>On the device:</p>
<ul>
<li>The value returned by <code>security_policyvers()</code> must 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>
</ul>
<h2 id="avb-version">AVB version matches</h2>
<p>The AVB version contains a MAJOR version and MINOR version, with the format
as MAJOR.MINOR (e.g., 1.0, 2.1). For details, refer to
<a href="https://android.googlesource.com/platform/external/avb/#Versioning-and-compatibility" class="external">Versioning
and Compatibility</a>. AVB version has the following system properties:</p>
<ul>
<li><code>ro.boot.vbmeta.avb_version</code> is the <code>libavb</code> version
in bootloader</li>
<li><code>ro.boot.avb_version</code> is the <code>libavb</code> version in
Android OS (<code>init/fs_mgr</code>)</li>
</ul>
<p>The system property appears only when the corresponding libavb has been used
to verify AVB metadata (and returns OK). It is absent if a verification failure
occurred (or no verification occurred at all).</p>
<p>A compatibility match compares the following:</p>
<ul>
<li>sysprop <code>ro.boot.vbmeta.avb_version</code> with
<code>avb.vbmeta-version</code> from framework compatibility matrix;
<ul>
<li><code>ro.boot.vbmeta.avb_version.MAJOR == avb.vbmeta-version.MAJOR</code></li>
<li><code>ro.boot.vbmeta.avb_version.MINOR >= avb.vbmeta-version.MINOR</code></li>
</ul>
</li>
<li>sysprop <code>ro.boot.avb_version</code> with
<code>avb.vbmeta-version</code> from framework compatibility matrix.
<ul>
<li><code>ro.boot.avb_version.MAJOR == avb.vbmeta-version.MAJOR</code></li>
<li><code>ro.boot.avb_version.MINOR >= avb.vbmeta-version.MINOR</code></li>
</ul>
</li>
</ul>
<p>The bootloader or Android OS might contain two copies of <code>libavb</code>
libraries, each with a different MAJOR version for upgrade devices and launch
devices. In this case, the same <em>unsigned</em> system image can be shared but
the final <em>signed</em> system images are different (with different
<code>avb.vbmeta-version</code>):</p>
<img src="../images/treble_vintf_avb_o_p.png">
<figcaption><strong>Figure 1. </strong>AVB version matches (<code>/system</code>
is P, all other partitions are O).</figcaption>
<br>
<br>
<img src="../images/treble_vintf_avb_p.png">
<figcaption><strong>Figure 2.</strong> AVB version matches (all partitions are
P).</figcaption>
<h4><strong>Example:</strong> Successful AVB version match</h4>
<p>The framework compatibility matrix states the following AVB information:</p>
<pre class="prettyprint">
<avb>
<vbmeta-version>2.1</vbmeta-version>
</avb>
</pre>
<p>On the device:</p>
<pre class="prettyprint">
ro.boot.avb_version == 1.0 &&
ro.boot.vbmeta.avb_version == 2.1 <font style="font-family: Roboto, Arial, Helvetica, sans-serif; background-color: red; color: white"> mismatch </font>
</pre>
<pre class="prettyprint">
ro.boot.avb_version == 2.1 &&
ro.boot.vbmeta.avb_version == 3.0 <font style="font-family: Roboto, Arial, Helvetica, sans-serif; background-color: red; color: white"> mismatch </font>
</pre>
<pre class="prettyprint">
ro.boot.avb_version == 2.1 &&
ro.boot.vbmeta.avb_version == 2.3 <font style="font-family: Roboto, Arial, Helvetica, sans-serif; background-color: green; color: white"> match </font>
</pre>
<pre class="prettyprint">
ro.boot.avb_version == 2.3 &&
ro.boot.vbmeta.avb_version == 2.1 <font style="font-family: Roboto, Arial, Helvetica, sans-serif; background-color: green; color: white"> match </font>
</pre>
<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>
|
