diff options
| author | Android Partner Docs <noreply@android.com> | 2017-08-22 10:41:24 -0700 |
|---|---|---|
| committer | Clay Murphy <claym@google.com> | 2017-08-22 15:01:44 -0700 |
| commit | f16c42333aa6b2de30a344dd68246d4a33d93e7d (patch) | |
| tree | 311af599312cacb21c888aeae828cae59b0d64a1 /en/devices/architecture/dto | |
| parent | 04426e67ca3ee557a0083f9b3c6ba789021bd7a0 (diff) | |
| download | source.android.com-f16c42333aa6b2de30a344dd68246d4a33d93e7d.tar.gz | |
Docs: Changes to source.android.com
- 166080694 Devsite localized content from translation request a3d5a7... by Android Partner Docs <noreply@android.com>
- 166079245 Remove duplicate TOC entry to oob-users.html. by mheco <mheco@google.com>
- 166002955 Update builds for Oreo by Android Partner Docs <noreply@android.com>
- 165977566 Fixing bad conversion by hvm <hvm@google.com>
- 165977199 Edit links to point to public source files in AOSP. by cqn <cqn@google.com>
- 165962883 Add codename to CTS downloads page. by gdimino <gdimino@google.com>
- 165955117 Integration of O branch into mainline. by gdimino <gdimino@google.com>
- 165638251 Update July public Android security bulletin to remove QC... by Android Partner Docs <noreply@android.com>
- 165638198 Update June public Android security bulletin to remove QC... by Android Partner Docs <noreply@android.com>
- 165638174 Update May public Android security bulletin to remove QC ... by Android Partner Docs <noreply@android.com>
- 165638096 Update April public Android security bulletin to remove Q... by Android Partner Docs <noreply@android.com>
- 165528993 Update to Keymaster 2 and remove requirements language by daroberts <daroberts@google.com>
- 165511119 Add Bluetooth verification / debug information by cqn <cqn@google.com>
- 165491345 Fixed link broken by file rename. by cqn <cqn@google.com>
- 165381648 Fixed broken image paths and renamed HCI Requirements file. by cqn <cqn@google.com>
- 165365185 Created high-level Bluetooth directory and added HTML ver... by cqn <cqn@google.com>
- 165335694 Devsite localized content from translation request 66a39c... by Android Partner Docs <noreply@android.com>
- 165246927 Update August 2017 bulletin with CVE-2017-0687 by daroberts <daroberts@google.com>
PiperOrigin-RevId: 166080694
Change-Id: I2d3a8d77fa6a66c2099f13ba2e864545328fd17a
Diffstat (limited to 'en/devices/architecture/dto')
| -rw-r--r-- | en/devices/architecture/dto/compile.html | 103 | ||||
| -rw-r--r-- | en/devices/architecture/dto/implement.html | 187 | ||||
| -rw-r--r-- | en/devices/architecture/dto/index.html | 144 | ||||
| -rw-r--r-- | en/devices/architecture/dto/multiple.html | 75 | ||||
| -rw-r--r-- | en/devices/architecture/dto/optimize.html | 299 | ||||
| -rw-r--r-- | en/devices/architecture/dto/partitions.html | 307 | ||||
| -rw-r--r-- | en/devices/architecture/dto/syntax.html | 328 |
7 files changed, 1443 insertions, 0 deletions
diff --git a/en/devices/architecture/dto/compile.html b/en/devices/architecture/dto/compile.html new file mode 100644 index 00000000..65e3cbc2 --- /dev/null +++ b/en/devices/architecture/dto/compile.html @@ -0,0 +1,103 @@ +<html devsite> + <head> + <title>Compiling & Verifying</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>You can use Device Tree Compiler (DTC) to compile the Device Tree Source +files. However, before applying the overlay DT on the target main DT, you should +also verify the result by simulating the behavior of DTO.</p> + +<h2 id=compile>Compiling with DTC</h2> +<p>When using <code>dtc</code> to compile <code>.dts</code>, you must add option +<code>-@</code> to add a <code>__symbols__</code> node in the resulting +<code>.dtbo</code>. The <code>__symbols__</code> node contains a list of all +nodes that are marked with a label, which the DTO library can use for +references.</p> + +<p>Sample command to build main DT <code>.dts</code>:</p> + +<pre class="devsite-terminal"> +dtc -@ -O dtb -o my_main_dt.dtb my_main_dt.dts +</pre> + +<p>Sample command to build the overlay DT <code>.dts</code>:</p> + +<pre class="devsite-terminal"> +dtc -@ -O dtb -o my_overlay_dt.dtbo my_overlay_dt.dts +</pre> + +<p class="note"><strong>Note:</strong> If you encounter the DTC build error: +<code>invalid option --'@'</code>, you might need to update your DTC version. +Upstream of AOSP, the official DTC supports DTO as of +<a href="https://github.com/dgibson/dtc/tree/v1.4.4" class="external">version +1.4.4</a> and most patches are merged after December 2016. For DTO support, we +recommend using the +<code><a href="https://android.googlesource.com/platform/external/dtc/" class="external">external/dtc</code></a> +in AOSP, which is synced with the latest DTC (with DTO patches merged as +needed).</p> + +<h2 id=verify>Verify DTO results on the host</h2> +<p>Verification can help you identify errors that might occur when placing the +overlay DT on the main DT. Before updating the target, you can verify the +result of overlaying DT on the host by simulating the behavior of DTO using +<code>/include/</code> in <code>.dts</code>.</p> + +<p class="note"><strong>Note:</strong> <code>/include/</code> does NOT support +the use of <code>__overlay__</code> in overlay DT sources.</p> + +<p><img src="../images/treble_dto_simulate.png"></p> +<p><strong>Figure 1.</strong> Use syntax <code>/include/</code> to simulate DTO +on the host.</p> + +<ol> +<li>Create a copy of the overlay <code>.dts</code>. In the copy, remove the +first line header. Example: +<pre> +/dts-v1/; +/plugin/; +</pre> +Save the file as <code>my_overlay_dt_wo_header.dts</code> (or any filename you +want).</li> + +<li>Create a copy of the main <code>.dts</code>. In the copy, after the last +line, append the include syntax for the file you created in step 1. For example: +<pre> +/include/ "my_overlay_dt_wo_header.dts" +</pre> +Save the file as <code>my_main_dt_with_include.dts</code> (or any filename you +want).</li> + +<li>Use <code>dtc</code> to compile <code>my_main_dt_with_include.dts</code> to +get the merged DT, which should be the same result as DTO. For example: +<pre class="devsite-terminal"> +dtc -@ -O dtb -o my_merged_dt.dtb my_main_dt_with_include.dts +</pre> +</li> + +<li>Use <code>dtc</code> to dump <code>my_merged_dt.dto</code>. +<pre class="devsite-terminal"> +dtc -O dts -o my_merged_dt.dts my_merged_dt.dtb +</pre> +</li> +</ol> + + </body> +</html> diff --git a/en/devices/architecture/dto/implement.html b/en/devices/architecture/dto/implement.html new file mode 100644 index 00000000..5d10a92c --- /dev/null +++ b/en/devices/architecture/dto/implement.html @@ -0,0 +1,187 @@ +<html devsite> + <head> + <title>Implementing DTOs</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>Implementing DTO involves dividing the device tree, building, partitioning, +and running. After you have a working implementation, you must also maintain +compatibility between the two DTs and determine a strategy for ensuring the +security of each DT partition.</p> + +<h2 id=divide>Dividing the DT</h2> +<p>Start by dividing the device tree into two (2) parts:</p> +<ul> +<li><strong>Main DT</strong>. The SoC-only part and the default configurations, +provided by SoC vendor.</li> +<li><strong>Overlay DT</strong>. The device-specific configurations, provided by +ODM/OEM.</li> +</ul> +<p>After dividing the device trees, you must ensure compatibility between main +DT and overlay DT so that merging main DT and overlay DT results in a complete +DT for the device. For details on DTO format and rules, see +<a href="/devices/architecture/dto/syntax.html">DTO Syntax</a>. For details on +multiple device trees, see +<a href="/devices/architecture/dto/multiple.html">Multiple DTs</a>.</p> + +<h2 id=build>Building main & overlay DTs</h2> +<p>To build the main DT:</p> +<ol> +<li>Compile main DT <code>.dts</code> into <code>.dtb</code> file.</li> +<li>Flash <code>.dtb</code> file into a bootloader runtime-accessible partition +(detailed below).</li> +</ol> + +<p>To build the overlay DT:</p> +<ol> +<li>Compile overlay DT <code>.dts</code> into <code>.dtbo</code> file. While +this file format is the same as the <code>.dtb</code> file formatted as a +flattened device tree, the different file extension distinguishes it from the +main DT. +</li> +<li>Flash <code>.dtbo</code> file into a bootloader runtime-accessible partition +(as detailed below).</li> +</ol> + +<p>For details on compiling with DTC and verifying DTO results on the host, see +<a href="/devices/architecture/dto/compile.html">Compiling & Verifying</a>. +</p> + +<h2 id=partition>Partitioning DTs</h2> +<p>Determine a bootloader runtime-accessible and trusted location in flash +memory to put <code>.dtb</code> and <code>.dtbo</code>.</p> + +<p>Example locations for the main DT:</p> +<ul> +<li>Part of boot partition, appended to the kernel (<code>image.gz</code>).</li> +<li>Separate DT blobs (<code>.dtb</code>) in dedicated partition +(<code>dtb</code>).</li> +</ul> + +<p>Example locations for the overlay DT:</p> + +<div style="width:75%"> +<div class="attempt-left"> +<table><tr><th style="text-align: center;">Unique Partition</th></tr></table> +<figure id="treble_dto_dtbo_partition_1"> +<img src="../images/treble_dto_dtbo_partition_1.png" style="display:block; margin:0 auto"> +<figcaption> +<strong>Figure 1.</strong> Put <code>.dtbo</code> into a unique partition, e.g. +<code>dtbo</code> partition. +</figcaption> +</figure> +</div> +<div class="attempt-right"> +<figure id="treble_dto_dtbo_partition_2"> +<table><tr><th style="text-align: center;">ODM Partition</th></tr></table> +<img src="../images/treble_dto_dtbo_partition_2.png" style="display:block; margin:0 auto"> +<figcaption> +<strong>Figure 2.</strong> Put <code>.dtbo</code> into <code>odm</code> +partition (do this only if your bootloader has capability to load data from the +filesystem of <code>odm</code> partition). +</figcaption> +</figure> +</div> +</div> + +<p class="note" style="clear:both"><strong>Note:</strong> The size of the +overlay DT partition depends on the device and the amount of changes needed on +top of the main DT blob. Typically, 8 MB is more than enough and allows room to +grow in the future if required.</p> + +<p>For devices that support +<a href="https://source.android.com/devices/tech/ota/ab_updates.html">seamless +(A/B) updates</a>, A/B the main DT and overlay DT partitions:</p> + +<div style="width:75%"> +<div class="attempt-left"> +<table><tr><th style="text-align: center;">Example 1</th></tr></table> +<figure id="treble_dto_dtbo_ab_1"> +<img src="../images/treble_dto_dtbo_ab_1.png" style="display:block; margin:0 auto"> +<figcaption> +<strong>Figure 3.</strong> DTBO partition A/B, example 1. +</figcaption> +</figure> +</div> +<div class="attempt-right"> +<table><tr><th style="text-align: center;">Example 2</th></tr></table> +<figure id="treble_dto_dtbo_ab_2"> +<img src="../images/treble_dto_dtbo_ab_2.png" style="display:block; margin:0 auto"> +<figcaption> +<strong>Figure 4.</strong> DTBO partition A/B, example 2. +</figcaption> +</figure> +</div> +</div> + +<h2 id=run style="clear:both">Running in bootloader</h2> +<p>To run:</p> + +<figure id=treble_dto_dtbo> +<img src="../images/treble_dto_dtbo.png"> +<figcaption><strong>Figure 5.</strong> Typical runtime implementation for device +tree overlay in bootloader.</figcaption> +</figure> + +<ol> +<li>Load <code>.dtb</code> from storage into memory.</li> +<li>Load <code>.dtbo</code> from storage into memory.</li> +<li>Overlay <code>.dtb</code> with <code>.dtbo</code> to be a merged DT.</li> +<li>Start kernel given the memory address of the merged DT.</li> +</ol> + +<h2 id=maintain>Maintaining compatibility</h2> +<p>The main DTB (from SoC vendor) is treated as an API surface for DTBOs. After +separating the device tree into a SoC-common part and a device-specific part, +you must keep the two parts mutually compatible in the future, including:</p> + +<ul> +<li><strong>DT definition in main DT</strong> <em>(e.g. nodes, properties, +labels)</em>. Any definition change in main DT could trigger changes in overlay +DT. For example, to correct a node name in main DT, define an "alias" label that +maps to the original node name (to avoid the change of overlay DT).</li> +<li><strong>Overlay DT store location</strong> <em>(e.g. partition name, store +format)</em>.</li> +</ul> + +<h2 id=security>Ensuring security</h2> +<p>Bootloader must ensure the DTB/DTBO is secure, unmodified, and uncorrupted. +You could use any solution to secure DTB/DTBO, for example, +<a href="/security/verifiedboot/verified-boot#signature_format">Boot image +signature</a> in VBoot 1.0 or +<a href="https://android.googlesource.com/platform/external/avb/+/master/README.md#The-VBMeta-struct" class="external">AVB HASH footer</a> (VBoot 2.0). +</p> + +<ul> +<li>If DTB/DTBO is in a unique partition, you can add that partition to the +trust chain of AVB. The trust chain starts from a hardware-protected root of +trust and goes to the bootloader, which verifies the integrity and authenticity +of DTB/DTBO partition.</li> +<li>If DTB/DTBO is in an existing partition (such as the <code>odm</code> +partition), that partition should be in the trust chain of AVB. (DTBO partition +could share a public key with <code>odm</code> partition).</li> +</ul> + +<p>For details, refer to <a href="/security/verifiedboot/index.html">Verified +Boot</a>.</p> + + </body> +</html> diff --git a/en/devices/architecture/dto/index.html b/en/devices/architecture/dto/index.html new file mode 100644 index 00000000..3fdf3c28 --- /dev/null +++ b/en/devices/architecture/dto/index.html @@ -0,0 +1,144 @@ +<html devsite> + <head> + <title>Device Tree Overlays</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>A device tree (DT) is a data structure of named nodes and properties that +describe non-discoverable hardware. Operating systems, such as the Linux kernel +used in Android, use DTs to support a wide range of hardware configurations used +by Android-powered devices. Hardware vendors supply their own DT source files, +which Linux then compiles into the Device Tree Blob (DTB) file used by the +bootloader.</p> + +A <a href="https://lkml.org/lkml/2012/11/5/615" class="external">device tree +overlay</a> (DTO) enables a central DTB to be overlaid on the device tree. A +bootloader using DTO can maintain the system-on-chip (SoC) DT and dynamically +overlay a device-specific DT, adding nodes to the tree and making changes to +properties in the existing tree.</p> + +<p>This page details a typical bootloader workflow for loading a DT and provides +a list of common DT terms. Other pages in this section describe how to +<a href="/devices/architecture/dto/implement.html">implement bootloader support +for DTO</a>, how to +<a href="/devices/architecture/dto/compile.html">compile</a>, verify, and +<a href="/devices/architecture/dto/optimize.html">optimize your DTO +implementation</a>, and how to +<a href="/devices/architecture/dto/multiple.html">use multiple DTs</a>. You can +also get details on <a href="/devices/architecture/dto/syntax.html">DTO +syntax</a> and recommended +<a href="/devices/architecture/dto/partition.html">DTO/DTBO partition +formatting</a>.</p> + +<h2 id=load-dt>Loading a device tree</h2> +<p>Loading a device tree in bootloader involves building, partitioning, and +running.</p> + +<figure id="treble_dto_bootloader"> +<img src="../images/treble_dto_bootloader.png"> +<figcaption><strong>Figure 1.</strong> Typical implementation for loading device +tree in bootloader.</figcaption> +</figure> + +<ol> +<li>To build: +<ul> +<li>Use the device tree compiler (<code>dtc</code>) to compile device tree +source (<code>.dts</code>) into a device tree blob (<code>.dtb</code>), +formatted as a flattened device tree.</li> +<li>Flash the <code>.dtb</code> file into a bootloader runtime-accessible +location (detailed below).</li> +</ul> +</li> +<li>To partition, determine a bootloader runtime-accessible and trusted location +in flash memory to put <code>.dtb</code>. Example locations: + +<div style="width:75%"> +<div class="attempt-left"> +<table><tr><th style="text-align: center;">Boot Partition</th></tr></table> +<figure id="treble_dto_partition_1"> +<img src="../images/treble_dto_partition_1.png" style="display:block; margin:0 auto"> +<figcaption> +<strong>Figure 2.</strong> Put <code>.dtb</code> in boot partition by appending +to <code>image.gz</code> and passing as "<code>kernel</code>" to +<code>mkbootimg</code>. +</figcaption> +</figure> +</div> +<div class="attempt-right"> +<table><tr><th style="text-align: center;">Unique Partition</th></tr></table> +<figure id="treble_dto_partition_2"> +<img src="../images/treble_dto_partition_2.png" style="display:block; margin:0 auto"> +<figcaption> +<strong>Figure 3.</strong> Put <code>.dtb</code> in an unique partition (e.g. +<code>dtb</code> partition). +</figcaption> +</figure> +</div> +</div> +</li> + +<li style="clear:both">To run: +<ul> +<li>Load <code>.dtb</code> from storage into memory.</li> +<li>Start kernel given the memory address of the loaded DT.</li> +</ul> +</li> +</ol> + +<h2 id=terms>Terminology</h2> +<p>This section uses the following device tree terms:</p> +<table> +<tbody> +<tr> +<th>DT</th> +<td>Device Tree</td> +</tr> +<tr> +<th>DTB</th> +<td>Device Tree Blob</td> +</tr> +<tr> +<th>DTBO</th> +<td>Device Tree Blob for Overlay</td> +</tr> +<tr> +<th>DTC</th> +<td>Device Tree Compiler</td> +</tr> +<tr> +<th>DTO</th> +<td>Device Tree Overlay</td> +</tr> +<tr> +<th>DTS</th> +<td>Device Tree Source</td> +</tr> +<tr> +<th>FDT</th> +<td>Flattened Device Tree, a binary format contained in a <code>.dtb</code> blob +file</td> +</tr> +</tbody> +</table> + + </body> +</html> diff --git a/en/devices/architecture/dto/multiple.html b/en/devices/architecture/dto/multiple.html new file mode 100644 index 00000000..52f47a46 --- /dev/null +++ b/en/devices/architecture/dto/multiple.html @@ -0,0 +1,75 @@ +<html devsite> + <head> + <title>Using Multiple DTs</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>Many SoC vendors and ODMs support the use of multiple DTs on a device, +enabling one image to power multiple SKUs/configurations. In such cases, the +bootloader identifies the hardware and loads the corresponding DT at runtime: +</p> + +<p><img src="../images/treble_dto_multiple_dt.png"></p> +<figcaption><strong>Figure 1.</strong> Multiple device trees overlay in +bootloader.</figcaption> + +<p class="note"><strong>Note:</strong> Using multiple DTs is not mandatory.</p> + +<h2 id=setting>Setting up</h2> +<p>To add support for multiple DTs to the DTO model, set up a list of main DTs +and another list of overlay DTs.</p> + +<p><img src="../images/treble_dto_multiple_dt_runtime.png"></p> +<figcaption><strong>Figure 2.</strong> Runtime DTO implementation for multiple +DTs.</figcaption> + +<p>The bootloader should be able to:</p> + +<ul> +<li>read the SoC ID and select the main DT correspondingly, and</li> +<li>read the board ID and select the overlay DT accordingly.</li> +</ul> + +<p>Only one main DT and one overlay DT are selected for use at runtime, and the +selected pair must be compatible.</p> + +<h2 id=partition>Partitioning</h2> +<p>To partition, determine a bootloader runtime-accessible and trusted location +in flash memory to store the DTBs and DTBOs (bootloader must be able to locate +these files in the matching process). Keep in mind that DTBs and DTBOs can not +exist in the same partition. If your DTBs/DTBOs are in the +<code>dtb</code>/<code>dtbo</code> partition, use the table structure and header +format detailed in <a href="/devices/architecture/dto/partitions.html">DTB/DTBO +Partition Format</a>.</p> + +<h2 id=runtime>Running in bootloader</h2> +<p>To run:</p> +<ol> +<li><strong>Identify the SoC</strong> and load the corresponding .dtb from +storage into memory.</li> +<li><strong>Identify the board</strong> and load the corresponding +<code>.dtbo</code> from storage into memory.</li> +<li>Overlay the <code>.dtb</code> with the <code>.dtbo</code> to be a merged +DT.</li> +<li>Start kernel given the memory address of the merged DT.</li> +</ol> + + </body> +</html> diff --git a/en/devices/architecture/dto/optimize.html b/en/devices/architecture/dto/optimize.html new file mode 100644 index 00000000..7502d7ad --- /dev/null +++ b/en/devices/architecture/dto/optimize.html @@ -0,0 +1,299 @@ +<html devsite> + <head> + <title>Optimizing DTOs</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 page details optimizations you can make to your DTO implementation, +describes restrictions against overlaying the root node, and 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. +We recommend putting 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, we recommend using <code>libufdt</code> to implement DTO (source +at +<code><a href="https://android.googlesource.com/platform/system/libufdt/+/refs/heads/master" class="external">platform/system/libufdt</code></a> +in AOSP). <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 (124ms runtime), <code>libufdt</code> +DTO runtime is 10ms.</p> + +<p>In performance testing for Pixel devices, we 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 6~8x time difference</li> +<li>1000 overlay (append or override) operations have 8~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 <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, we +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 a <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 a +<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=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>To get the size of <code>merged_fdt</code>, use <code>dtc_totalsize()</code>: +<pre class="prettyprint"> +merged_fdt_size = dtc_totalsize(merged_fdt); +</pre> +</li> + +<li>Pass merged DT to start kernel. When you start the kernel, pass merged DT to +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> diff --git a/en/devices/architecture/dto/partitions.html b/en/devices/architecture/dto/partitions.html new file mode 100644 index 00000000..bcbea204 --- /dev/null +++ b/en/devices/architecture/dto/partitions.html @@ -0,0 +1,307 @@ +<html devsite> + <head> + <title>DTB/DTBO Partitions</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>If your DTB/DTBO is in a unique partition, e.g. <code>dtb</code> and +<code>dtbo</code> partition, use the following table structure and header +format:</p> + +<p><img src="../images/treble_dto_partition_layout.png"></p> +<figcaption><strong>Figure 1.</strong> Example +<code>dtb</code>/<code>dtbo</code> partition layout (for AVB signature, see +<a href="/devices/architecture/dto/implement.html#security">Security</a>). +</figcaption> + +<h2 id=structures>Data structures</h2> +<p>The <code>dt_table_header</code> is <strong>only</strong> for the +<code>dtb</code>/<code>dtbo</code> partition; you CANNOT append this format +after the end of <code>image.gz</code>. If you have a single DTB/DTBO, you must +still use this format (and the <code>dt_entry_size</code> in +<code>dt_table_header</code> is 1).</p> + +<pre class="prettyprint"> +#define DT_TABLE_MAGIC 0xd7b7ab1e + +struct dt_table_header { + uint32_t magic; // DT_TABLE_MAGIC + uint32_t total_size; // includes dt_table_header + all dt_table_entry + // and all dtb/dtbo + uint32_t header_size; // sizeof(dt_table_header) + + uint32_t dt_entry_size; // sizeof(dt_table_entry) + uint32_t dt_entry_count; // number of dt_table_entry + uint32_t dt_entries_offset; // offset to the first dt_table_entry + // from head of dt_table_header + + uint32_t page_size; // flash page size we assume + uint32_t reserved[1]; // must be zero +}; + +struct dt_table_entry { + 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 custom[4]; // optional, must be zero if unused +}; +</pre> + +<p>To read all <code>dt_table_entry</code>, use the <code>dt_entry_size</code>, +<code>dt_entry_count</code>, and <code>dt_entries_offset</code>. Example:</p> +<pre class="prettyprint"> +my_read(entries_buf, + header_addr + header->dt_entries_offset, + header->dt_entry_size * header->dt_entry_count); +</pre> + +<p>The <code>id</code>, <code>rev</code>, <code>custom</code> in +<code>dt_table_entry</code> are optional hardware identifications of the device +tree the bootloader can use to efficiently identify the DTB/DTBO to load. If the +bootloader requires additional information, put it in the DTB/DTBO where +bootloader can read it by parsing DTB/DTBO (see the sample code below).</p> + +<h2 id=sample-code>Sample code</h2> +<p>The following sample code checks the hardware identification in bootloader. +</p> + +<ul> +<li>The <code>check_dtbo()</code> function checks the hardware identification. +It first checks the data in struct <code>dt_table_entry</code> (<code>id</code>, +<code>rev</code>, etc.). If this data is not enough, it loads <code>dtb</code> +data into memory and checks the value in <code>dtb</code>.</li> +<li>The values of <code>my_hw_information</code> and <code>soc_id</code> +properties are parsed in the root node (example in <code>my_dtbo_1.dts</code>). + +<pre class="prettyprint"> +[my_dtbo_1.dts] +/dts-v1/; +/plugin/; + +/ { + /* As DTS design, these properties only for loader, won't overlay */ + compatible = "board_manufacturer,board_model"; + + /* These properties are examples */ + board_id = <0x00010000>; + board_rev = <0x00010001>; + another_hw_information = "some_data"; + soc_id = <0x68000000>; + ... +}; + +&device@0 { + value = <0x1>; + status = "okay"; +}; + + +[my_bootloader.c] +int check_dtbo(const dt_table_entry *entry, uint32_t header_addr) { + ... + if (entry->id != ... || entry->rev != ...) { + ... + } + ... + void * fdt_buf = my_load_dtb(header_addr + entry->dt_offset, entry->dt_size); + int root_node_off = fdt_path_offset(fdt_buf, "/"); + ... + const char *my_hw_information = + (const char *)fdt_getprop(fdt_buf, root_node_off, "my_hw_information", NULL); + if (my_hw_information != NULL && strcmp(my_hw_information, ...) != 0) { + ... + } + const fdt32_t *soc_id = fdt_getprop(fdt_buf, root_node_off, "soc_id", NULL); + if (soc_id != NULL && *soc_id != ...) { + ... + } + ... +} +</pre></li></ul> + +<h2 id=mkdtimg>mkdtimg</h2> +<p><code>mkdtimg</code> is a tool for creating +<code>dtb</code>/<code>dtbo</code> images +(<a href="https://android-review.googlesource.com/#/q/topic:mkdtimg+(status:open+OR+status:merged+OR+status:pending)" class="external">source +code</a> at <code>system/libufdt</code> in AOSP). <code>mkdtimg</code> supports +several commands, including <code>create</code>, <code>cfg_create</code>, and +<code>dump</code>.</p> + +<h3 id=create>create</h3> +<p>Use the <code>create</code> command to create a +<code>dtb</code>/<code>dtbo</code> image:</p> +<pre class="prettyprint"> +$mkdtimg create <image_filename> (<global-option>...) \ + <ftb1_filename> (<entry1_option>...) \ + <ftb2_filename> (<entry2_option>...) \ + ... +</pre> + +<p><code>ftbX_filename</code> generates a <code>dt_table_entry</code> in the +image. <code>entryX_option</code>s are the values to assign to +<code>dt_table_entry</code>. These values can be any of the following:</p> +<pre class="prettyprint"> +--id=<number|path> +--rev=<number|path> +--custom0=<number|path> +--custom1=<number|path> +--custom2=<number|path> +--custom3=<number|path> +</pre> + +<p>Number values can be a 32-bit digit (such as 68000) or a hex number (such as +0x6800). Alternatively, you can specify a path using the format:</p> +<pre class="prettyprint"> +<full_node_path>:<property_name> +</pre> + +<p>For example, <code>/board/:id</code>. <code>mkdtimg</code> reads the value +from the path in the DTB/DTBO file and assigns the value (32-bit) to a relative +property in <code>dt_table_entry</code>. Alternatively, you can give a +<code>global_option</code> as a default option for all entries. The default +value of <code>page_size</code> in <code>dt_table_header</code> is 2048; use +<code>global_option --page_size=<number></code> to assign a different +value.</p> + +<p>Example:</p> +<pre class="prettyprint"> +[board1.dts] +/dts-v1/; +/plugin/; + +/ { + compatible = "board_manufacturer,board_model"; + board_id = <0x00010000>; + board_rev = <0x00010001>; + another_hw_information = "some_data"; + ... +}; + +&device@0 { + value = <0x1>; + status = "okay"; +}; + + +$mkdtimg create dtbo.img --id=/:board_id --custom0=0xabc \ + board1.dtbo \ + board2.dtbo --id=0x6800 \ + board3.dtbo --id=0x6801 --custom0=0x123 +</pre> + +<ul> +<li>First <code>dt_table_entry</code> (<code>board1.dtbo</code>) <code>id</code> +is <code>0x00010000</code> and <code>custom[0]</code> is +<code>0x00000abc</code>.</li> +<li>Second <code>id</code> is <code>0x00006800</code> and +<code>custom[0]</code> is <code>0x00000abc</code>.</li> +<li>Third <code>id</code> is <code>0x00006801</code> and <code>custom[0]</code> +is <code>0x00000123</code>.</li> +<li>All others use the default value (<code>0</code>).</li> +</ul> + +<h3 id=cfg-create>cfg_create</h3> +<p>The <code>cfg_create</code> command creates an image with a config file in +the following format:</p> +<pre class="prettyprint"> +# global options + <global_option> + ... +# entries +<ftb1_filename> # comment + <entry1_option> # comment + ... +<ftb2_filename> + <entry2_option> + ... +... +</pre> + +<p>Options <code>global_option</code> and <code>entryX_option</code> must start +with one or more space characters (these options are the same as +<code>create</code> options, without the <code>--</code> prefix). Empty lines or +lines beginning with <code>#</code> are ignored.</p> + +<p>Example:</p> +<pre class="prettyprint"> +[dtboimg.cfg] +# global options + id=/:board_id + rev=/:board_rev + custom0=0xabc + +board1.dtbo + +board2.dtbo + id=0x6800 # override the value of id in global options + +board2.dtbo + id=0x6801 # override the value of id in global options + custom0=0x123 # override the value of custom0 in global options + + +$mkdtimg cfg_create dtbo.img dtboimg.cfg +</pre> + +<p><code>mkdtimg</code> does not handle alignment for +<code>.dtb</code>/<code>.dtbo</code> files but rather appends them to the image. +When you use <code>dtc</code> to compile <code>.dts</code> to +<code>.dtb</code>/<code>.dtbo</code>, you must add option <code>-a</code>. For +example, adding the option <code>-a 4</code> adds padding so the size of +<code>.dtb</code>/<code>.dtbo</code> aligns to 4 bytes.</p> + +<p>Several DT table entries can share a <code>.dtb</code>/<code>.dtbo</code>. If +you use the same filename for different entries, it stores only one content in +the image with same <code>dt_offset</code> and <code>dt_size</code>. This is +useful when using different hardware with identical DTs.</p> + +<h3 id=dump>dump</h3> +<p>For <code>dtb</code>/<code>dtbo</code> images, use the <code>dump</code> +command to print the information in the image. Example:</p> +<pre class="prettyprint"> +$mkdtimg dump dtbo.img +dt_table_header: + magic = d7b7ab1e + total_size = 1300 + header_size = 32 + dt_entry_size = 32 + dt_entry_count = 3 + dt_entries_offset = 32 + page_size = 2048 + reserved[0] = 00000000 +dt_table_entry[0]: + dt_size = 380 + dt_offset = 128 + id = 00010000 + rev = 00010001 + custom[0] = 00000abc + custom[1] = 00000000 + custom[2] = 00000000 + custom[3] = 00000000 + (FDT)size = 380 + (FDT)compatible = board_manufacturer,board_model +... +</pre> + + </body> +</html> diff --git a/en/devices/architecture/dto/syntax.html b/en/devices/architecture/dto/syntax.html new file mode 100644 index 00000000..64981420 --- /dev/null +++ b/en/devices/architecture/dto/syntax.html @@ -0,0 +1,328 @@ +<html devsite> + <head> + <title>DTO Syntax</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>Device Tree Source (DTS) format is a textual representation of a device tree. +The Device Tree Compiler (DTC) processes this format into a binary device tree, +which is the form expected by the Linux kernel.</p> + +<h2 id=reference>Using references</h2> + +<p>The <a href="https://github.com/pantoniou/dtc" class="external">DTC</a> +(Device Tree compiler + overlay patches) project describes the DTS format in +<a href="https://android.googlesource.com/platform/external/dtc/+/refs/heads/master/Documentation/dts-format.txt" class="external">dtc-format.txt</a> +and +<a href="https://android.googlesource.com/platform/external/dtc/+/refs/heads/master/Documentation/manual.txt" class="external">manual.txt</a>. +DTO format and rules are described in +<a href="https://android.googlesource.com/platform/external/dtc/+/refs/heads/master/Documentation/dt-object-internal.txt" class="external">dt-object-internal.txt</a>. +These documents describe how to update the main DT using node +<code>fragment@x</code> and syntax <code>__overlay__</code> in overlay DT. For +example:</p> +<pre class="prettyprint"> +/ { + fragment@0 { + target = <&some_node>; + __overlay__ { + some_prop = "okay"; + ... + }; + }; +}; +</pre> + +<p>However, Google strongly recommends you do <strong>not</strong> use +<code>fragment@x</code> and syntax <code>__overlay__</code>, and instead use the +reference syntax. For example:</p> +<pre class="prettyprint"> +&some_node { + some_prop = "okay"; + ... +}; +</pre> + +<p>Reference syntax is compiled by <code>dtc</code> into the same object as the +above using syntax <code>__overlay__</code>. This syntax does not force you to +number the fragments, enabling you to read and write overlay DTS easily. If your +<code>dtc</code> doesn't support this syntactic sugar, use the +<a href="https://android.googlesource.com/platform/external/dtc" class="external">dtc +in AOSP</a>.</p> + +<h2 id=labels>Using labels</h2> +<p>To allow undefined references to nodes not present at compilation time, the +overlay DT <code>.dts</code> file must have a tag <code>/plugin/</code> in its +header. For example:</p> + +<pre class="prettyprint"> +/dts-v1/; +/plugin/; +</pre> + +<p>From here you can target the nodes to be overlaid using a reference, which is +an absolute node path prefixed with an ampersand (&). For example, for +<code>node@0</code> in the main DT:</p> + +<table> +<tr> +<th width="50%">Define labels in the main DT ...</th> +<th>... then use the labels.</th> +</tr> + +<tr> +<td> +<pre class="prettyprint"> +[my_main_dt.dts] + +/dts-v1/; + +/ { + my_node: node@0 { + status = "disabled"; + + my_child: child@0 { + value = <0xffffffff>; + }; + }; +}; +</pre> +</td> + +<td class="alt"> +<pre class="prettyprint"> +[my_overlay_dt.dts] + +/dts-v1/; +/plugin/; + +&my_node { + status = "okay"; +}; + +&my_child { + value = <0x1>; +}; +</pre> +</td> +</tr> +</table> + +<h2 id=override>Overriding</h2> +<p>If the reference target property exists in the main DT, it is overridden +after DTO; otherwise, it is appended. For example:</p> + +<table> +<tr> +<th width="33%">main.dts</th> +<th width="33%">overlay.dts</th> +<th>Merged Result</th> +</tr> + +<tr> +<td> +<pre class="prettyprint"> +[my_main_dt.dts] + +/dts-v1/; + +/ { + compatible = "corp,foo"; + + my_node: node@0 { + status = "disabled"; + }; +}; +</pre> +</td> + +<td class="alt"> +<pre class="prettyprint"> +[my_overlay_dt.dts] + +/dts-v1/; +/plugin/; + +&my_node { + status = "okay"; +}; +</pre> +</td> + +<td> +<pre class="prettyprint"> +/dts-v1/; + +/ { + compatible = "corp,foo"; + + ... + + node@0 { + linux,phandle = <0x1>; + phandle = <0x1>; + status = "okay"; + }; +}; +</pre> +</td> +</tr> +</table> + +<h2 id=append>Appending</h2> +<p>If the reference target property does not exist in the main DT, it is +appended after DTO. For example:</p> + +<table> +<tr> +<th width="33%">main.dts</th> +<th width="33%">overlay.dts</th> +<th>Merged Result</th> +</tr> + +<tr> +<td> +<pre class="prettyprint"> +[my_main_dt.dts] + +/dts-v1/; + +/ { + compatible = "corp,foo"; + + my_node: node@0 { + status = "okay"; + }; +}; +</pre> +</td> + +<td class="alt"> +<pre class="prettyprint"> +[my_overlay_dt.dts] + +/dts-v1/; +/plugin/; + +&my_node { + new_prop = "bar"; +}; +</pre> +</td> + +<td> +<pre class="prettyprint"> +/dts-v1/; + +/ { + compatible = "corp,foo"; + + ... + + node@0 { + linux,phandle = <0x1>; + phandle = <0x1>; + status = "okay"; + new_prop = "bar"; + }; +}; +</pre> +</td> +</tr> +</table> + +<h2 id="child">Child nodes</h2> +<p>Examples of child node syntax:</p> + +<table> +<tr> +<th width="33%">main.dts</th> +<th width="33%">overlay.dts</th> +<th>Merged Result</th> +</tr> + +<tr> +<td> +<pre class="prettyprint"> +[my_main_dt.dts] + +/dts-v1/; + +/ { + compatible = "corp,foo"; + + my_nodes: nodes { + compatible = "corp,bar"; + + node@0 { + status = "disabled"; + }; + }; +}; +</pre> +</td> + +<td class="alt"> +<pre class="prettyprint"> +[my_overlay_dt.dts] + +/dts-v1/; +/plugin/; + +&my_nodes { + new_prop1 = "abc"; + + node@0 { + status = "okay"; + new_prop2 = "xyz"; + }; +}; +</pre> +</td> + +<td> +<pre class="prettyprint"> +/dts-v1/; + +/ { + compatible = "corp,foo"; + + ... + + nodes { + linux,phandle = <0x1>; + phandle = <0x1>; + compatible = "corp,bar"; + new_prop1 = "abc"; + + node@0 { + linux,phandle = <0x2>; + phandle = <0x2>; + status = "okay"; + new_prop2 = "xyz"; + }; + }; +}; +</pre> +</td> +</tr> +</table> + + </body> +</html> |