<div dir="ltr"><div dir="ltr"><br><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, Jul 22, 2019 at 5:07 PM Nils Hölscher <<a href="mailto:nilhoel1@gmail.com">nilhoel1@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, 22 Jul 2019 at 12:41, Vijay Kumar Banerjee <<a href="mailto:vijaykumar9597@gmail.com" target="_blank">vijaykumar9597@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">---<br>
 user/exe/device-tree.rst | 100 +++++++++++++++++++++++++++++++++++++++<br>
 user/exe/index.rst       |   1 +<br>
 2 files changed, 101 insertions(+)<br>
 create mode 100644 user/exe/device-tree.rst<br>
<br>
diff --git a/user/exe/device-tree.rst b/user/exe/device-tree.rst<br>
new file mode 100644<br>
index 0000000..3cd52cd<br>
--- /dev/null<br>
+++ b/user/exe/device-tree.rst<br>
@@ -0,0 +1,100 @@<br>
+.. SPDX-License-Identifier: CC-BY-SA-4.0<br>
+<br>
+.. Copyright (C) 2018 Vijay Kumar Banerjee <<a href="mailto:vijaykumar9597@gmail.com" target="_blank">vijaykumar9597@gmail.com</a>><br>
+<br>
+Device Tree<br>
+===========<br>
+.. index:: Device Tree<br>
+<br>
+A Device Tree is a data structure that is used to describe properties of<br>
+non-discoverable hardware instead of hardcoding them on the Kernel. The device<br>
+tree data is generally stored in a `.dts` or a Device Tree Source (DTS) file.<br>
+This file is then compiled into a binary format called Device Tree Blob (DTB)<br>
+with `.dtb` extension. RTEMS preferably uses DTB built from the FreeBSD source<br>
+tree matching the libbsd HEAD commit hash.<br>
+<br>
+Building the DTB<br>
+----------------<br>
+<br>
+A single device tree source (DTS) file can be built using the `dtc` tool in<br>
+libfdt using the following command :<br>
+<br>
+.. code-block:: none<br>
+<br>
+    dtc -I dts -O dtb -o my-devicetree.dtb my-devicetree.dts<br>
+<br>
+For building the DTS from the FreeBSD source, the `make_dtb.sh` script<br>
+from `freebsd/sys/tools/fdt` must be used as most of the DTS files in FreeBSD<br>
+have included `.dtsi` files from their source tree. An example is given below as<br>
+a reference of how to build the device tree from the FreeBSD source.<br>
+<br>
+`NOTE : The following example uses FreeBSD master branch from github mirror as<br>
+an example. It is advised to always use the source from the commit matching the<br>
+libBSD HEAD.`<br>
+<br>
+.. code-block:: shell<br>
+   :linenos:<br>
+<br>
+     #We're using the script from freebsd/sys/tools/make_dtb.sh<br>
+     #Target device: Beaglebone Black.<br>
+     #Architecture: Arm.<br>
+     #DTS source name: am335x-boneblack.dts<br>
+<br>
+     #The make_dtb.sh script uses environment variable MACHINE<br>
+     export MACHINE='arm'<br>
+<br>
+     SCRIPT_DIR=$HOME/freebsd/sys/tools/fdt<br>
+<br>
+     #The arguments to the script are<br>
+     # $1 -> Build Tree<br>
+     # $2 -> DTS source file<br>
+     # $3 -> output path of the DTB file<br>
+<br>
+     ${SCRIPT_DIR}/make_dtb.sh ${SCRIPT_DIR}/../../ \<br>
+     ${SCRIPT_DIR}/../../gnu/dts/arm/am335x-boneblack.dts \<br>
+     $(pwd)<br></blockquote><div><br></div><div>Does this really work?</div><div>Cause I had to change all includes in the dts files from relative to absolute paths. </div></div></div></blockquote><div>The reason to use the make_dtb.sh script is that it uses the -i option with dtc which</div><div>sets the include directory.</div><div>Inside the script there are a few includes like these :<br>```<br>-i "$S/dts/${MACHINE}" -i "$S/gnu/dts/${MACHINE}"</div><div>```</div><div>here $S is the build tree argument. So if you use this script with the right path to build</div><div>tree, i.e., the path to gnu/ directory, then the included files will be discoverable and</div><div>there won't be a need to edit the includes.</div><div>I agree that it's not intuitive that the build tree must be the path to gnu directory and a</div><div>user would not like to look into every script involved to figure out what it does. How would</div><div>you suggest to include this information in the doc so that it's understandable? </div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
+<br>
+Using Device Tree Overlay<br>
+-------------------------<br>
+<br>
+Device tree overlay is used either add properties or devices to the existing<br></blockquote><div> Little typo: Device tree overlay is used either [<b>to]</b> add properties or devices to the existing</div><div><br></div></div></div></blockquote><div>Thanks for the note. Will fix this in v2. </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div class="gmail_quote"><div></div><div>The rest looks fine to me.</div><div><br></div></div></div></blockquote><div>Thanks for reviewing the patch! </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div class="gmail_quote"><div></div><div>Best,</div><div>Nils</div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
+device tree. Adding any property to DTS using an overlay will override the<br>
+current values in the DTB. The Overlays enable us to modify the device tree<br>
+using a small maintainable plugin without having to edit the whole Base Tree.<br>
+<br>
+There are two ways of applying an overlay on top of the built dtb.<br>
+<br>
+#. Use fdtoverlay from libfdt<br>
+<br>
+#. Add the overlay in the root partition of the SDcard and apply it using u-boot<br>
+   from the uEnv.txt file.<br>
+<br>
+The fdtoverlay command can be used as follows:<br>
+<br>
+.. code-block:: none<br>
+<br>
+    fdtoverlay -i my-base-tree.dtb -o output-tree.dtb my-overlay.dtbo<br>
+<br>
+To apply it from u-boot during system initialization we have to add the device<br>
+tree overlay file in the root directory of the SDcard and use uEnv.txt to load<br>
+and apply the overlay.<br>
+<br>
+Below is a sample script that can be used as a reference to write the uEnv.txt<br>
+properly so that it applies all the overlays (.dtbo):<br>
+<br>
+.. code-block:: shell<br>
+    :linenos:<br>
+<br>
+    overlays="fdt addr 0x88000000"<br>
+    app=rtems-app.img<br>
+    DTB_INSTALL_NAME=my-basetree.dtb<br>
+<br>
+    for f in "$(pwd)"/*.dtbo<br>
+    do<br>
+        name=`basename "${f}"`<br>
+        overlays="${overlays}; fatload mmc 0 0x88100000 ${name}; fdt resize 0x1000; fdt apply 0x88100000"<br>
+    done<br>
+    echo "setenv bootdelay 5<br>
+    uenvcmd=run boot<br>
+    boot=fatload mmc 0 0x80800000 $app ; fatload mmc 0 0x88000000 ${DTB_INSTALL_NAME} ; ${overlays} ; bootm 0x80800000 - 0x88000000" >uEnv.txt<br>
+<br>
diff --git a/user/exe/index.rst b/user/exe/index.rst<br>
index 3e9b571..e22420a 100644<br>
--- a/user/exe/index.rst<br>
+++ b/user/exe/index.rst<br>
@@ -21,3 +21,4 @@ execiutable, and creating and dynamically loading code.<br>
    initialization<br>
    debugging<br>
    loader<br>
+   device-tree<br>
-- <br>
2.20.1<br>
<br>
_______________________________________________<br>
devel mailing list<br>
<a href="mailto:devel@rtems.org" target="_blank">devel@rtems.org</a><br>
<a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a><br>
</blockquote></div></div>
</blockquote></div></div>