[PATCH v2] user/exe : Add Device Tree section

[Vijay Kumar Banerjee]

---
 user/exe/device-tree.rst | 100 +++++++++++++++++++++++++++++++++++++++
 user/exe/index.rst       |   1 +
 2 files changed, 101 insertions(+)
 create mode 100644 user/exe/device-tree.rst

diff --git a/user/exe/device-tree.rst b/user/exe/device-tree.rst
new file mode 100644
index 0000000..fcbcfd7
--- /dev/null
+++ b/user/exe/device-tree.rst
@@ -0,0 +1,100 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2018 Vijay Kumar Banerjee <vijaykumar9597 at gmail.com>
+
+Device Tree
+===========
+.. index:: Device Tree
+
+A Device Tree is a data structure that is used to describe properties of
+non-discoverable hardware instead of hardcoding them on the Kernel. The device
+tree data is generally stored in a `.dts` or a Device Tree Source (DTS) file.
+This file is then compiled into a binary format called Device Tree Blob (DTB)
+with `.dtb` extension. RTEMS preferably uses DTB built from the FreeBSD source
+tree matching the libbsd HEAD commit hash.
+
+Building the DTB
+----------------
+
+A single device tree source (DTS) file can be built using the `dtc` tool in
+libfdt using the following command :
+
+.. code-block:: none
+
+    dtc -I dts -O dtb -o my-devicetree.dtb my-devicetree.dts
+
+For building the DTS from the FreeBSD source, the `make_dtb.sh` script
+from `freebsd/sys/tools/fdt` must be used as most of the DTS files in FreeBSD
+have included `.dtsi` files from their source tree. An example is given below as
+a reference of how to build the device tree from the FreeBSD source.
+
+`NOTE : The following example uses FreeBSD master branch from github mirror as
+an example. It is advised to always use the source from the commit matching the
+libBSD HEAD.`
+
+.. code-block:: shell
+   :linenos:
+
+     #We're using the script from freebsd/sys/tools/make_dtb.sh
+     #Target device: Beaglebone Black.
+     #Architecture: Arm.
+     #DTS source name: am335x-boneblack.dts
+
+     #The make_dtb.sh script uses environment variable MACHINE
+     export MACHINE='arm'
+
+     SCRIPT_DIR=$HOME/freebsd/sys/tools/fdt
+
+     #The arguments to the script are
+     # $1 -> Build Tree (This is the path to freebsd/sys/ directory)
+     # $2 -> DTS source file
+     # $3 -> output path of the DTB file
+
+     ${SCRIPT_DIR}/make_dtb.sh ${SCRIPT_DIR}/../../ \
+     ${SCRIPT_DIR}/../../gnu/dts/arm/am335x-boneblack.dts \
+     $(pwd)
+
+Using Device Tree Overlay
+-------------------------
+
+Device tree overlay is used either to add properties or devices to the existing
+device tree. Adding any property to DTS using an overlay will override the
+current values in the DTB. The Overlays enable us to modify the device tree
+using a small maintainable plugin without having to edit the whole Base Tree.
+
+There are two ways of applying an overlay on top of the built dtb.
+
+#. Use fdtoverlay from libfdt
+
+#. Add the overlay in the root partition of the SDcard and apply it using u-boot
+   from the uEnv.txt file.
+
+The fdtoverlay command can be used as follows:
+
+.. code-block:: none
+
+    fdtoverlay -i my-base-tree.dtb -o output-tree.dtb my-overlay.dtbo
+
+To apply it from u-boot during system initialization we have to add the device
+tree overlay file in the root directory of the SDcard and use uEnv.txt to load
+and apply the overlay.
+
+Below is a sample script that can be used as a reference to write the uEnv.txt
+properly so that it applies all the overlays (.dtbo):
+
+.. code-block:: shell
+    :linenos:
+
+    overlays="fdt addr 0x88000000"
+    app=rtems-app.img
+    DTB_INSTALL_NAME=my-basetree.dtb
+
+    for f in "$(pwd)"/*.dtbo
+    do
+        name=`basename "${f}"`
+        overlays="${overlays}; fatload mmc 0 0x88100000 ${name}; fdt resize 0x1000; fdt apply 0x88100000"
+    done
+    echo "setenv bootdelay 5
+    uenvcmd=run boot
+    boot=fatload mmc 0 0x80800000 $app ; fatload mmc 0 0x88000000 ${DTB_INSTALL_NAME} ; ${overlays} ; bootm 0x80800000 - 0x88000000" >uEnv.txt
+
diff --git a/user/exe/index.rst b/user/exe/index.rst
index 3e9b571..e22420a 100644
--- a/user/exe/index.rst
+++ b/user/exe/index.rst
@@ -21,3 +21,4 @@ execiutable, and creating and dynamically loading code.
    initialization
    debugging
    loader
+   device-tree
-- 
2.20.1