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
|
<html devsite>
<head>
<title>Optimizing DTOs</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
{% include "_versions.html" %}
<!--
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 page discusses optimizations you can make to your DTO implementation,
describes restrictions against overlaying the root node, and details how to
configure compressed overlays in the DTBO image. It also provides sample
implementation instructions and code.
</p>
<h2 id=kernel>Kernel command line</h2>
<p>
The original kernel command line in device tree is located in the
<code>chosen/bootargs</code> node. The bootloader must concatenate this
location with other sources of kernel command line:
</p>
<pre class="prettyprint">
/dts-v1/;
/ {
chosen: chosen {
bootargs = "...";
};
};
</pre>
<p>
DTO <strong>cannot</strong> concatenate values from main DT and overlay DT, so
you must put the kernel command line of the main DT in
<code>chosen/bootargs</code> and the kernel command line of the overlay DT in
<code>chosen/bootargs_ext</code>. Bootloader can then concatenate these
locations and pass the result to the kernel.
</p>
<table>
<tr>
<th width="50%">main.dts</th>
<th>overlay.dts</th>
</tr>
<tr>
<td>
<pre class="prettyprint">
/dts-v1/;
/ {
chosen: chosen {
bootargs = "...";
};
};
</pre>
</td>
<td class="alt">
<pre class="prettyprint">
/dts-v1/;
/plugin/;
&chosen {
bootargs_ext = "...";
};
</pre>
</td>
</tr>
</table>
<h2 id=libufdt>libufdt</h2>
<p>
While the latest
<code><a href="https://github.com/dgibson/dtc/tree/master/libfdt" class="external">libfdt</code></a>
supports DTO, is it recommended to use <code>libufdt</code> to implement DTO
(AOSP source at
<code><a href="https://android.googlesource.com/platform/system/libufdt/+/refs/heads/master" class="external">platform/system/libufdt</code></a>).
<code>libufdt</code> builds a real tree structure (un-flattened device tree,
or <em>ufdt</em>) from the flattened device tree (FDT), so it can improve the
merging of two <code>.dtb</code> files from O(N2) to O(N), where N is the
number of nodes in the tree.
</p>
<h3 id=performance>Performance testing</h3>
<p>
In Google's internal testing, using <code>libufdt</code> on 2405
<code>.dtb</code> and 283 <code>.dtbo</code> DT nodes results in file sizes of
70,618 and 8,566 bytes after compilation. Compared with a
<a href="http://fxr.watson.org/fxr/source/boot/fdt/" class="external">DTO
implementation</a> ported from FreeBSD (124 ms runtime), <code>libufdt</code>
DTO runtime is 10 ms.
</p>
<p>
Performance testing for Pixel devices compared <code>libufdt</code> and
<code>libfdt</code>. The number of base nodes effect is similar, but includes
the following differences:
</p>
<ul>
<li>500 overlay (append or override) operations have 6x to 8x time
difference</li>
<li>1000 overlay (append or override) operations have 8x to 10x time
difference</li>
</ul>
<p>
Example with appending count set to X:
</p>
<p><img src="../images/treble_dto_appending.png"></p>
<figcaption><strong>Figure 1.</strong> Appending count is X</figcaption>
<p>
Example with overriding count set to X:
</p>
<p><img src="../images/treble_dto_overriding.png"></p>
<figcaption><strong>Figure 2.</strong> Overriding count is X</figcaption>
<p>
<code>libufdt</code> is developed with some <code>libfdt</code> APIs and data
structures. When using <code>libufdt</code>, you must include and link
<code>libfdt</code> (however, in your code you can use the <code>libfdt</code>
API to operate DTB or DTBO).
</p>
<h3 id=api>libufdt DTO API</h3>
<p>
The main API to DTO in <code>libufdt</code> is as follows:
</p>
<pre class="prettyprint">
struct fdt_header *ufdt_apply_overlay(
struct fdt_header *main_fdt_header,
size_t main_fdt_size,
void *overlay_fdt,
size_t overlay_size);
</pre>
<p>
The parameter <code>main_fdt_header</code> is the main DT and
<code>overlay_fdt</code> is the buffer containing the contents of a
<code>.dtbo</code> file. The return value is a new buffer containing the
merged DT (or <code>null</code> in case of error). The merged DT is formated
in FDT, which you can pass to the kernel when starting the kernel.
</p>
<p>
The new buffer from the return value is created by <code>dto_malloc()</code>,
which you should implement when porting <code>libufdt</code> into bootloader.
For reference implementations, refer to
<code>sysdeps/libufdt_sysdeps_*.c</code>.
</p>
<h2 id=root>Root node restrictions</h2>
<p>
You cannot overlay a new node or property into the root node of main DT
because overlay operations rely on labels. Because the main DT must define a
label and the overlay DT assigns the nodes to be overlaid with labels, you
cannot give a label for the root node (and therefore cannot overlay the root
node).
</p>
<p>
SoC vendors must define the overlaying ability of main DT; ODM/OEMs can only
append or override nodes with labels defined by the SoC vendor. As a
workaround, you can define an <strong><code>odm</code></strong> node under the
root node in base DT, enabling all ODM nodes in overlay DT to add new nodes.
Alternatively, you could put all SoC-related nodes in the base DT into an
<strong><code>soc</code></strong> node under root node as described below:
</p>
<table>
<tr>
<th width="50%">main.dts</th>
<th>overlay.dts</th>
</tr>
<tr>
<td>
<pre>
/dts-v1/;
/ {
compatible = "corp,bar";
...
chosen: chosen {
bootargs = "...";
};
/* nodes for all soc nodes */
soc {
...
soc_device@0: soc_device@0 {
compatible = "corp,bar";
...
};
...
};
odm: odm {
/* reserved for overlay by odm */
};
};
</pre>
</td>
<td class="alt">
<pre class="prettyprint">
/dts-v1/;
/plugin/;
/ {
};
&chosen {
bootargs_ex = "...";
};
&odm {
odm_device@0 {
...
};
...
};
</pre>
</td>
</tr>
</table>
<h2 id="compressed-overlays">Using compressed overlays</h2>
<p>
Android {{ androidPVersionNumber }} adds support for using compressed overlays
in the DTBO image when using version 1 of the device tree table header.
When using DTBO header v1, the four least significant bits of the flags field
in <em>dt_table_entry</em> indicate the compression format of the DT entry.
</p>
<pre class="prettyprint">struct dt_table_entry_v1 {
uint32_t dt_size;
uint32_t dt_offset; /* offset from head of dt_table_header */
uint32_t id; /* optional, must be zero if unused */
uint32_t rev; /* optional, must be zero if unused */
uint32_t flags; /* For version 1 of dt_table_header, the 4 least significant bits
of 'flags' will be used to indicate the compression
format of the DT entry as per the enum 'dt_compression_info' */
uint32_t custom[3]; /* optional, must be zero if unused */
};
</pre>
<p>
Currently, <code>zlib</code> and <code>gzip</code> compressions are supported.
</p>
<pre class="prettyprint">enum dt_compression_info {
NO_COMPRESSION,
ZLIB_COMPRESSION,
GZIP_COMPRESSION
};
</pre>
<p>
Android {{ androidPVersionNumber }} adds support for testing compressed
overlays to the <code>VtsFirmwareDtboVerification</code> test to help you
verify the correctness of overlay application.
</p>
<h2 id=sample>Sample DTO implementation</h2>
<p>
The following instructions walk you through a sample implementation of DTO
with <code>libufdt</code> (sample code below).
</p>
<h3 id=sample-instructions>Sample DTO instructions</h3>
<ol>
<li>Include libraries. To use <code>libufdt</code>, include
<code>libfdt</code> for data structures and APIs:
<pre class="prettyprint">
#include <libfdt.h>
#include <ufdt_overlay.h>
</pre>
</li>
<li>Load main DT and overlay DT. Load <code>.dtb</code> and <code>.dtbo</code>
from storage into memory (exact steps depend on your design). At this point,
you should have the buffer and size of <code>.dtb</code>/<code>.dtbo</code>:
<pre class="prettyprint">
main_size = my_load_main_dtb(main_buf, main_buf_size)
</pre>
<pre class="prettyprint">
overlay_size = my_load_overlay_dtb(overlay_buf, overlay_buf_size);
</pre>
</li>
<li>Overlay the DTs:
<ol>
<li>Use <code>ufdt_install_blob()</code> to get the FDT header for main DT:
<pre class="prettyprint">
main_fdt_header = ufdt_install_blob(main_buf, main_size);
main_fdt_size = main_size;
</pre>
</li>
<li>Call <code>ufdt_apply_overlay()</code> to DTO to get a merged DT in FDT
format:
<pre class="prettyprint">
merged_fdt = ufdt_apply_overlay(main_fdt_header, main_fdt_size,
overlay_buf, overlay_size);
</pre>
</li>
<li>Use <code>merged_fdt</code> to get the size of
<code>dtc_totalsize()</code>:
<pre class="prettyprint">
merged_fdt_size = dtc_totalsize(merged_fdt);
</pre>
</li>
<li>Pass the merged DT to start the kernel:
<pre class="prettyprint">
my_kernel_entry(0, machine_type, merged_fdt);
</pre>
</li>
</ol>
</li>
</ol>
<h3 id=sample-code>Sample DTO code</h3>
<pre class="prettyprint">
#include <libfdt.h>
#include <ufdt_overlay.h>
…
{
struct fdt_header *main_fdt_header;
struct fdt_header *merged_fdt;
/* load main dtb into memory and get the size */
main_size = my_load_main_dtb(main_buf, main_buf_size);
/* load overlay dtb into memory and get the size */
overlay_size = my_load_overlay_dtb(overlay_buf, overlay_buf_size);
/* overlay */
main_fdt_header = ufdt_install_blob(main_buf, main_size);
main_fdt_size = main_size;
merged_fdt = ufdt_apply_overlay(main_fdt_header, main_fdt_size,
overlay_buf, overlay_size);
merged_fdt_size = dtc_totalsize(merged_fdt);
/* pass to kernel */
my_kernel_entry(0, machine_type, merged_fdt);
}
</pre>
</body>
</html>
|
