diff options
Diffstat (limited to 'en/devices/architecture/dto')
| -rw-r--r-- | en/devices/architecture/dto/compile.html | 430 | ||||
| -rw-r--r-- | en/devices/architecture/dto/implement.html | 187 | ||||
| -rw-r--r-- | en/devices/architecture/dto/index.html | 150 | ||||
| -rw-r--r-- | en/devices/architecture/dto/multiple.html | 81 | ||||
| -rw-r--r-- | en/devices/architecture/dto/optimize.html | 380 | ||||
| -rw-r--r-- | en/devices/architecture/dto/partitions.html | 309 | ||||
| -rw-r--r-- | en/devices/architecture/dto/syntax.html | 328 |
7 files changed, 0 insertions, 1865 deletions
diff --git a/en/devices/architecture/dto/compile.html b/en/devices/architecture/dto/compile.html deleted file mode 100644 index aea2f3bc..00000000 --- a/en/devices/architecture/dto/compile.html +++ /dev/null @@ -1,430 +0,0 @@ -<html devsite=""> -<head> - <title>Compiling & Verifying</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>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> - - <aside 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</a></code> in AOSP, which is synced with the latest DTC - (with DTO patches merged as needed).</aside> - - - <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> - - - <aside class="note"><strong>Note:</strong> <code>/include/</code> does NOT - support the use of <code>__overlay__</code> in overlay DT sources.</aside> - - - <p><img src="../images/treble_dto_simulate.png"> - </p> - - - <figcaption><strong>Figure 1.</strong> Use syntax <code>/include/</code> to simulate - DTO on the host</figcaption> - - - <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> - - - <h2 id="verifying-DTO-in-p">Verifying DTO in Android {{ androidPVersionNumber }}</h2> - - - <p>Android {{ androidPVersionNumber}} requires a Device Tree Blob Overlay - (DTBO) partition. To add nodes or make changes to the properties in the SoC - DT, the bootloader must dynamically overlay a device specific DT over - the SoC DT.</p> - - - <h3 id="indicating-applied-overlays">Indicating applied overlays</h3> - - - <p>To enable the <a href="/compatibility/vts/"> - Vendor Test Suite (VTS)</a> to assess the correctness of overlay - application, vendors must add a new kernel command line parameter - <code>androidboot.dtbo_idx</code> that indicates the overlays selected from - the DTBO partition. For example, the parameter <code>androidboot. - dtbo_idx=x,y,z</code> reports <code>x</code>, <code>y</code> and - <code>z</code> as the zero-based indices of the Device Tree Overlays (DTOs) - from the DTBO partition applied (in that order) by the bootloader to the base - Device Tree (DT).</p> - - - <p>Overlays can apply to nodes from the main device tree or add new nodes, - but <strong>cannot</strong> refer to a node added in a previous overlay. This - restriction is necessary because the overlay application does not merge the - overlay symbol table with the main DT symbol table (not merging avoids - conflicts in symbol names and complication of dependencies between - overlays).</p> - - - <h4 id="example-invalid-overlays">Example: Invalid overlays</h4> - - - <p>In this example, <code>overlay_2.dts</code> refers to node - <strong><code>e</code></strong> , which was added by - <code>overlay_1.dts</code>. After <code>overlay_1</code> is applied to the - main DT, if an attempt is made to apply <code>overlay_2</code> to the - resultant DT, the overlay application will fail with an error that the symbol - <strong><code>e</code></strong> is not present in the symbol table for the - base DT.</p> - - - <table> - <tr> - <th width="33%">main.dts</th> - - <th>overlay_1.dts</th> - - <th>overlay_2.dts</th> - - </tr> - <tr> - <td> - <pre> -<strong>[main.dts]</strong> - -/dts-v1/; - -/ { - a: a {}; - b: b {}; - c: c {}; -}; -</pre> - </td> - - <td> - <pre> -<strong>[overlay_1.dts]</strong> - -/dts-v1/; -/plugin/; - -&b { ref1 = <&a>; - e: e { - prop = <0x0a>; - phandle = <0x04>; - }; -}; -</pre> -</td> - - <td> -<pre> -<strong>[overlay_2.dts]</strong> - -/dts-v1/; -/plugin/; - -/* invalid! */ -<font color="red">&e</font> { - prop = <0x0b>; -}; -</pre> - </td> - </tr> - </table> - - - <h4 id="example-valid-overlays">Example: Valid overlays</h4> - - - <p>In this example, <code>overlay_2.dts</code> refers only to node - <strong><code>b</code></strong> from the main DTS. When - <code>overlay_1</code> is applied to the base DT, then followed by the - application of <code>overlay_2</code>, the value of property - <strong><code>prop</code></strong> in node <strong><code>e</code></strong> - (set by <code>overlay_1.dts</code>) is overwritten by the value set by - <code>overlay_2.dts</code>.</p> - - - <table> - <tr> - <th width="33%">main.dts</th> - - <th>overlay_1.dts</th> - - <th>overlay_2.dts</th> - - </tr> - - - <tr> - <td> - <pre> -<strong>[final.dts]</strong> - -/dts-v1/; - -/ { - a: a {}; - b: b {}; - c: c {}; -}; -</pre> - </td> - - <td> - <pre> -<strong>[overlay_1.dts]</strong> - -/dts-v1/; -/plugin/; - - -&b { ref1 = <&a>; - e { - prop = <0x0c>; - }; -}; -</pre> - </td> - - <td> - <pre> -<strong>[overlay_2.dts]</strong> - -/dts-v1/; -/plugin/; - -/* valid */ -<font color="blue">&b</font> { ref1 = <&c>; - e { - prop = <0x0d>; - }; -}; -</pre> - </td> - </tr> - </table> - - - <h3 id="implementing-the-dtbo-partition">Implementing the DTBO partition</h3> - - - <p>To implement the required DTBO partition, ensure the bootloader can do the - following:</p> - - - <ol> - <li>Identify the board it is running on and select the corresponding - overlay(s) to be applied.</li> - - - <li>Append the <code>androidboot.dtbo_idx</code> parameter to the kernel - command line. - - <ul> - <li>The parameter must indicate, the zero-based indices of the DTOs - from the DTBO partition image it applied to the base DT (in the same - order).</li> - - - <li>The indices must refer to the position of the overlay in the DTBO - partition.</li> - </ul> - </li> - </ol> - - - <p>For details on the structure of the DTBO partition, refer to <a href= - "https://source.android.com/devices/architecture/dto/">Device Tree - Overlays</a> on source.android.com.</p> - - - <h3 id="validating-the-dtbo-partition">Validating the DTBO partition</h3> - - - <p>You can use VTS to verify the following:</p> - - - <ul> - <li>Existence of the kernel command line parameter - <code>androidboot.dtbo_idx</code> (by checking that <code>Init</code> has - automatically set up the corresponding <code>ro.boot.dtbo_idx</code> system - property).</li> - - - <li>Validity of the <code>ro.boot.dtbo_idx</code> system property (by - checking that the property specifies at least one valid DTBO image - index).</li> - - - <li>Validity of the DTBO partition (also verifies the overlays in the DTBO - partition that are applied to the base DT).</li> - - - <li>Additional nodes or property changes in the resulting DT are presented - to the Linux kernel.</li> - </ul> - - - <p>For example, in the following overlays and final DT, adding - <code>androidboot.dtbo_idx=5,3</code> to the kernel command line passes - validation but adding <code>androidboot.dtbo_idx=3,5</code> to the kernel - command line does not pass validation.</p> - - - <table> - <tr> - <th width="50%">Overlay DT at index 3</th> - - - <th>Overlay DT at index 5</th> - -<tr> -<td> -<pre> -<strong>[overlay_1.dts]</strong> - -/dts-v1/; -/plugin/; - -&c <strong>{ prop = <0xfe>; }</strong>; -</pre> - </td> - - <td> - <pre> -<strong>[overlay_2.dts]</strong> - -/dts-v1/; -/plugin/; - -&c { prop = <0xff>; }; -</pre> - </td> - </tr> - -<table> - <tr> - <th>Final DT</th> - - <tr> - <td> - <pre> -/dts-v1/; -/ { - - a { - phandle = <0x1>; - }; - - b { - phandle = <0x2>; - }; - - c { - phandle = <0x3>; - <strong>prop = <0xfe></strong>; - }; - - __symbols__ { - a = "/a"; - b = "/b"; - c = "/c"; - }; -}; - - </table> -</body> -</html> diff --git a/en/devices/architecture/dto/implement.html b/en/devices/architecture/dto/implement.html deleted file mode 100644 index 52906fc8..00000000 --- a/en/devices/architecture/dto/implement.html +++ /dev/null @@ -1,187 +0,0 @@ -<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="/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 deleted file mode 100644 index 8470b2ad..00000000 --- a/en/devices/architecture/dto/index.html +++ /dev/null @@ -1,150 +0,0 @@ -<html devsite> - <head> - <title>Device Tree Overlays</title> - <meta name="project_path" value="/_project.yaml" /> - <meta name="book_path" value="/_book.yaml" /> - </head> - <body> - {% include "_versions.html" %} - <!-- - Copyright 2018 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> - -<p>A <a href="https://lkml.org/lkml/2012/11/5/615" class="external">device tree -overlay</a> (DTO) enables a central device tree blob (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 required -<a href="/devices/architecture/dto/partitions.html">DTO/DTBO partition -formatting</a>.</p> - -<h2 id="p-update">Updates in Android {{ androidPVersionNumber }} Release</h2> -<p>In Android {{ androidPVersionNumber }}, the bootloader must not modify the -properties defined in the device tree overlays before passing the unified -device tree blob to the kernel.</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 deleted file mode 100644 index f431a9d7..00000000 --- a/en/devices/architecture/dto/multiple.html +++ /dev/null @@ -1,81 +0,0 @@ -<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 corresponding main device tree, and</li> -<li>Read the board ID and select the set of overlay device trees accordingly. -</li> -</ul> - -<p>Only one main DT should be selected for use at runtime. Multiple overlay DTs -may be selected but they must be compatible with the chosen main DT. Using -multiple overlays can help avoid storing one overlay per board within the DTBO -partition and enable the bootloader to determine the subset of required overlays -based on the board ID (or possibly by probing the peripherals). For -example, Board A may need the devices added by the overlays 1, 3, and 5 while -Board B may need the devices added by the overlays 1, 4, and 5.</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 deleted file mode 100644 index 7624cc14..00000000 --- a/en/devices/architecture/dto/optimize.html +++ /dev/null @@ -1,380 +0,0 @@ -<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> diff --git a/en/devices/architecture/dto/partitions.html b/en/devices/architecture/dto/partitions.html deleted file mode 100644 index 195f1192..00000000 --- a/en/devices/architecture/dto/partitions.html +++ /dev/null @@ -1,309 +0,0 @@ -<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 2018 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 version; // DTBO image version, the current version is 0. - // The version will be incremented when the - // dt_table_header struct is updated. -}; - -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="devsite-click-to-copy"> -<code class="devsite-terminal">mkdtimg create <image_filename> (<global-option>...) \</code> - <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="devsite-click-to-copy"> -[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"; -}; - - -<code class="devsite-terminal">mkdtimg create dtbo.img --id=/:board_id --custom0=0xabc \</code> - 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="devsite-click-to-copy"> -[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 - - -<code class="devsite-terminal">mkdtimg cfg_create dtbo.img dtboimg.cfg</code> -</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="devsite-click-to-copy"> -<code class="devsite-terminal">mkdtimg dump dtbo.img</code> -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 - version = 0 -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 deleted file mode 100644 index 64981420..00000000 --- a/en/devices/architecture/dto/syntax.html +++ /dev/null @@ -1,328 +0,0 @@ -<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> |