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
|
<html devsite>
<head>
<title>Matching Rules</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>The two pairs of compatibility matrices and manifests are meant to be
reconciled at <a href="/devices/tech/ota/index.html">OTA</a> time to verify the
framework and vendor implementation can work with each other. This verification
is successful upon a match between the framework compatibility matrix and the
device manifest, as well as between the framework manifest and the device
compatibility matrix. The following sections detail matching rules used by
various components.</p>
<h2 id="hals">HAL matches</h2>
<p>The HAL-match rule identifies the versions of <code>hal</code> elements in a
manifest file that are considered supported by the owner of the corresponding
compatibility matrix.</p>
<ul>
<li>Multiple <code>version</code> elements are concatenated with
<strong>OR</strong> (see camera example below).</li>
<li>Multiple <code><hal></code> elements with the same name are
concatenated with <strong>AND</strong>.</li>
</ul>
<h4><strong>Example</strong>: Successful HAL match for Camera module</h4>
<p>For a HAL at version 2.5, the match rule is as follows:</p>
<table>
<tr>
<th>Matrix</th>
<th>Matching Manifest</th>
</tr>
<tr>
<td><code>2.5</code></td>
<td>2.5-2.∞. Shorthand for 2.5-5.</td>
</tr>
<tr>
<td><code>2.5-7</code></td>
<td>2.5-2.∞. Indicates the following:
<br>
<ul>
<li>2.5 is the minimum required version, meaning a manifest providing HAL
2.0-2.4 is not compatible.</li>
<li>2.7 is the maximum version that could be requested, meaning the owner of
the compatibility matrix (framework or device) will not request versions
beyond 2.7. The owner of the matching manifest can still serve version 2.10
(as an example) when 2.7 is requested. The compatibility-matrix owner knows
only that the requested service is compatible with API version 2.7.</li>
<li>-7 is informational only and does not affect the OTA update process.</li>
</ul>
Thus, a device with a HAL at version 2.10 in its manifest file remains
compatible with a framework that states <code>camera:</code>
<code>2.5-7</code> in its compatibility matrix.</td>
</tr>
</table>
<h4><strong>Example:</strong> Successful HAL match for DRM module</h4>
<p>The framework compatibility matrix states the following version information
for DRM HAL:</p>
<pre class="prettyprint"><hal>
<name>android.hardware.drm
<version>1.0</version>
<version>3.1-2</version>
<interface>
<name>IDrmFactory</name>
<instance>default</instance>
<instance>specific</instance>
</interface>
</hal>
<hal>
<name>android.hardware.drm
<version>2.0</version>
<interface>
<name>ICryptoFactory</name>
<instance>default</instance>
</interface>
</hal>
</pre>
<p>A vendor must implement ONE of the following HALs:</p>
<pre>
android.hardware.drm@1.x::IDrmFactory/default //where x >= 0
android.hardware.drm@1.x::IDrmFactory/specific //where x >= 0
</pre>
OR
<pre>
android.hardware.drm@3.y::IDrmFactory/default //where y >= 1
android.hardware.drm@3.y::IDrmFactory/specific //where y >= 1
</pre>
<p>... AND must also implement this HAL:</p>
<pre>
android.hardware.drm@2.z::ICryptoFactory/default //where z >= 0
</pre>
<h2 id="kernel">Kernel matches</h2>
<p>The <code><kernel></code> section of the framework compatibility matrix
describes the framework's requirements of the Linux kernel on the device. This
information is meant to be matched at OTA time against the
<a href="/devices/architecture/vintf/objects.html#runtime-collectible-information">information</a>
about the kernel that gets reported by the device's VINTF object.</p>
<p>A matrix can include multiple <code><kernel></code> sections, each with
a different <code>version</code> attribute using the format:</p>
<pre class="prettyprint">${ver}.${major_rev}.${kernel_minor_rev}</pre>
<p>The OTA considers only the <code><kernel></code> section with the same
<code>${ver}</code> and <code>${major_rev}</code> as the device kernel (i.e.,
<code>version="${ver}.${major_rev}.${matrix_minor_rev}")</code>; other sections
are ignored. In addition, the minor revision from the kernel must be a value
from the compatibility matrix (<code>${kernel_minor_rev} >=
${matrix_minor_rev}</code>;). If no <code><kernel></code> section meets
these requirements, it is a non-match.</p>
<p>If the <code><kernel></code> section does match, the process continues
by attempting to match <code>config</code> elements against
<code>/proc/config.gz</code>. For each config element in the compatibility
matrix, it looks up <code>/proc/config.gz</code> to see if the config is
present. When a config item is set to <code>n</code> in the compatibility
matrix for the matching <code><kernel></code> section, it must be absent
from <code>/proc/config.gz</code>. Finally, a config item not in the
compatibility matrix may or may not be present in <code>/proc/config.gz</code>.
</p>
<p>Examples of matches:</p>
<ul>
<li><code><value type="string">bar</value></code> matches
<code>"bar"</code>. Quotes are omitted in the compatibility matrix but present
in <code>/proc/config.gz</code>.</li>
<li><code><value type="int">4096</value></code> matches
<code>4096</code> or <code>0x1000</code> or <code>0X1000</code>.</li>
<li><code><value type="int">0x1000</value></code> matches
<code>4096</code> or <code>0x1000</code> or <code>0X1000</code>.</li>
<li><code><value type="int">0X1000</value></code> matches
<code>4096</code> or <code>0x1000</code> or <code>0X1000</code>.</li>
<li><code><value type="tristate">y</value></code> matches
<code>y</code>.</li>
<li><code><value type="tristate">m</value></code> matches
<code>m</code>.</li>
<li><code><value type="tristate">n</value></code> means the config
item must NOT exist in <code>/proc/config.gz</code>.</li>
<li><code><value type="range">1-0x3</value></code> matches
<code>1</code>, <code>2</code>, or <code>3</code>, or hexadecimal equivalent.
</li>
</ul>
<h4><strong>Example:</strong> Successful kernel match</h4>
<p>A framework compatibility matrix has the following kernel information:</p>
<pre class="prettyprint">
<kernel version="3.18.51">
<config>
<key>CONFIG_TRI</key>
<value type="tristate">y</value>
</config>
<config>
<key>CONFIG_NOEXIST</key>
<value type="tristate">n</value>
</config>
<config>
<key>CONFIG_DEC</key>
<value type="int">4096</value>
</config>
<config>
<key>CONFIG_HEX</key>
<value type="int">0XDEAD</value>
</config>
<config>
<key>CONFIG_STR</key>
<value type="string">str</value>
</config>
<config>
<key>CONFIG_EMPTY</key>
<value type="string"></value>
</config>
</kernel>
</pre>
<p>The kernel version is matched first. If a device in <code>uname()</code>
reports:</p>
<ul>
<li>3.10.73 (no match to matrix unless there is a separate kernel section
with <code><kernel version="3.10.x"></code> where <code>x <= 73</code>)
</li>
<li>3.18.50 (no match to matrix, smaller than <code>version</code>)</li>
<li>3.18.51 (match to matrix)</li>
<li>3.18.52 (match to matrix)</li>
<li>4.1.22 (no match to matrix unless there is a separate kernel section
with <code><kernel version="4.1.x"></code> where <code>x <= 22</code>)
</li>
</ul>
<p>After the appropriate <code><kernel></code> section is selected, for
each <code><config></code> item with value other than <code>n</code>, we
expect the corresponding entry to be present in <code>/proc/config.gz</code>;
for each <code><config></code> item with value <code>n</code>, we expect
the corresponding entry to not be present in <code>/proc/config.gz</code>. We
expect the content of <code><value></code> to exactly match the text after
the equal sign (including quotes), up to the newline character or
<code>#</code>, with leading and trailing whitespace truncated.</p>
<p>The following kernel configuration is an example of a successful match:</p>
<pre class="prettyprint">
# comments don't matter
CONFIG_TRI=y
# CONFIG_NOEXIST should not exist
CONFIG_DEC = 4096 # trailing comments and whitespaces are fine
CONFIG_HEX=57005 # 0XDEAD == 57005
CONFIG_STR="str"
CONFIG_EMPTY="" # empty string must have quotes
CONFIG_EXTRA="extra config items are fine too"
</pre>
<p>The following kernel configuration is an example of an unsuccessful match:</p>
<pre class="prettyprint">
CONFIG_TRI="y" # mismatch: quotes
CONFIG_NOEXIST=y # mismatch: CONFIG_NOEXIST exists
CONFIG_HEX=0x0 # mismatch; value doesn't match
CONFIG_DEC="" # mismatch; type mismatch (expect int)
CONFIG_EMPTY=1 # mismatch; expects ""
# mismatch: CONFIG_STR is missing
</pre>
<h2 id="se-policy">SE policy matches</h2>
<p>SE policy requires the following matches:</p>
<ul>
<li><code><sepolicy-version></code> defines a closed range of minor
versions for every major version. The sepolicy version reported by the device
must fall within one of these ranges to be compatible with the framework. Match
rules are similar to HAL versions; it is a match if the sepolicy version is
higher or equal to the minimum version for the range. The maximum version is
purely informational.</li>
<li><code><kernel-sepolicy-version></code> i.e. policydb version. Must
exactly match the <code>security_policyvers()</code> reported by the device.
</li>
</ul>
<h4><strong>Example:</strong> Successful SE policy match</h4>
<p>The framework compatibility matrix states the following sepolicy information:
</p>
<pre class="prettyprint">
<sepolicy>
<kernel-sepolicy-version>30</kernel-sepolicy-version>
<sepolicy-version>25.0</sepolicy-version>
<sepolicy-version>26.0-3</sepolicy-version>
</sepolicy>
</pre>
<p>On the device:</p>
<ul>
<li>The value returned by <code>security_policyvers()</code> must exactly equal
30. Otherwise it is not a match.</li>
<li>SE Policy version must be one of 25.0-∞ or 26.0-∞. Otherwise it is not a
match. (The "<code>-3</code>" after "<code>26.0</code>" is purely
informational.)</li>
</ul>
<h2 id="avb-version">AVB version matches</h2>
<p>The AVB version contains a MAJOR version and MINOR version, with the format
as MAJOR.MINOR (e.g., 1.0, 2.1). For details, refer to
<a href="https://android.googlesource.com/platform/external/avb/#Versioning-and-compatibility" class="external">Versioning
and Compatibility</a>. AVB version has the following system properties:</p>
<ul>
<li><code>ro.boot.vbmeta.avb_version</code> is the <code>libavb</code> version
in bootloader</li>
<li><code>ro.boot.avb_version</code> is the <code>libavb</code> version in
Android OS (<code>init/fs_mgr</code>)</li>
</ul>
<p>The system property appears only when the corresponding libavb has been used
to verify AVB metadata (and returns OK). It is absent if a verification failure
occurred (or no verification occurred at all).</p>
<p>A compatibility match compares the following:</p>
<ul>
<li>sysprop <code>ro.boot.vbmeta.avb_version</code> with
<code>avb.vbmeta-version</code> from framework compatibility matrix;
<ul>
<li><code>ro.boot.vbmeta.avb_version.MAJOR == avb.vbmeta-version.MAJOR</code></li>
<li><code>ro.boot.vbmeta.avb_version.MINOR >= avb.vbmeta-version.MINOR</code></li>
</ul>
</li>
<li>sysprop <code>ro.boot.avb_version</code> with
<code>avb.vbmeta-version</code> from framework compatibility matrix.
<ul>
<li><code>ro.boot.avb_version.MAJOR == avb.vbmeta-version.MAJOR</code></li>
<li><code>ro.boot.avb_version.MINOR >= avb.vbmeta-version.MINOR</code></li>
</ul>
</li>
</ul>
<p>The bootloader or Android OS might contain two copies of <code>libavb</code>
libraries, each with a different MAJOR version for upgrade devices and launch
devices. In this case, the same <em>unsigned</em> system image can be shared but
the final <em>signed</em> system images are different (with different
<code>avb.vbmeta-version</code>):</p>
<img src="../images/treble_vintf_avb_o_p.png">
<figcaption><strong>Figure 1. </strong>AVB version matches (<code>/system</code>
is P, all other partitions are O).</figcaption>
<br>
<br>
<img src="../images/treble_vintf_avb_p.png">
<figcaption><strong>Figure 2.</strong> AVB version matches (all partitions are
P).</figcaption>
<h4><strong>Example:</strong> Successful AVB version match</h4>
<p>The framework compatibility matrix states the following AVB information:</p>
<pre class="prettyprint">
<avb>
<vbmeta-version>2.1</vbmeta-version>
</avb>
</pre>
<p>On the device:</p>
<pre class="prettyprint">
ro.boot.avb_version == 1.0 &&
ro.boot.vbmeta.avb_version == 2.1 <font style="font-family: Roboto, Arial, Helvetica, sans-serif; background-color: red; color: white"> mismatch </font>
</pre>
<pre class="prettyprint">
ro.boot.avb_version == 2.1 &&
ro.boot.vbmeta.avb_version == 3.0 <font style="font-family: Roboto, Arial, Helvetica, sans-serif; background-color: red; color: white"> mismatch </font>
</pre>
<pre class="prettyprint">
ro.boot.avb_version == 2.1 &&
ro.boot.vbmeta.avb_version == 2.3 <font style="font-family: Roboto, Arial, Helvetica, sans-serif; background-color: green; color: white"> match </font>
</pre>
<pre class="prettyprint">
ro.boot.avb_version == 2.3 &&
ro.boot.vbmeta.avb_version == 2.1 <font style="font-family: Roboto, Arial, Helvetica, sans-serif; background-color: green; color: white"> match </font>
</pre>
</body>
</html>
|
