summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorVijay Kumar Banerjee <vijaykumar9597@gmail.com>2019-08-04 02:00:57 +0530
committerChristian Mauderer <oss@c-mauderer.de>2019-08-07 20:42:37 +0200
commit7c89bd6d5fe9e511a0bb684dbe34733d7f8e5a7f (patch)
tree4931d5da215f954ac6c9379d8dcaa3f6fe8f3284
parentuser: Move support sections to top level (diff)
downloadrtems-docs-7c89bd6d5fe9e511a0bb684dbe34733d7f8e5a7f.tar.bz2
user/exe: Add Device Tree section
-rw-r--r--user/bsps/arm/beagle.rst21
-rw-r--r--user/exe/device-tree.rst92
-rw-r--r--user/exe/index.rst1
3 files changed, 95 insertions, 19 deletions
diff --git a/user/bsps/arm/beagle.rst b/user/bsps/arm/beagle.rst
index eb4ecfb..fa7fa05 100644
--- a/user/bsps/arm/beagle.rst
+++ b/user/bsps/arm/beagle.rst
@@ -40,25 +40,8 @@ from the libbsd HEAD of freebsd-org. For example if the HEAD is at
Then the right Device Tree Source (DTS) file is:
https://github.com/freebsd/freebsd/blob/19a6ceb89dbacf74697d493e48c388767126d418/sys/gnu/dts/arm/am335x-boneblack.dts
-.. code-block:: shell
- :linenos:
-
- #building the dtb
- #We will use the script from https://github.com/freebsd/freebsd/blob/19a6ceb89dbacf74697d493e48c388767126d418/sys/tools/fdt/make_dtb.sh
-
- #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
- # $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)
+Please refer to the :ref:`device-tree` to know more about building and applying
+the Device Trees.
Writing the uEnv.txt file
-------------------------
diff --git a/user/exe/device-tree.rst b/user/exe/device-tree.rst
new file mode 100644
index 0000000..bd21552
--- /dev/null
+++ b/user/exe/device-tree.rst
@@ -0,0 +1,92 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2019 Vijay Kumar Banerjee <vijaykumar9597@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 in 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 a DTB built from the FreeBSD source
+tree matching the freebsd-org HEAD commit hash in libBSD.
+
+Building the DTB
+----------------
+
+A single DTB 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 DTB 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 for 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
+freebsd-org HEAD in libBSD.`
+
+.. 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 SD card and apply it using U-Boot
+
+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 SD card and use U-Boot commands
+to apply the overlay.
+
+Below is given the series of U-Boot commands that can be used to apply the
+overlay, given that the overlay blob (.dtbo) file is already in the card.
+
+.. code-block:: shell
+
+ fatload mmc 0:1 0x80800000 rtems-app.img
+ fatload mmc 0:1 0x88000000 my-base-tree.dtb
+ fdt addr 0x88000000
+ fatload mmc 0:1 0x88100000 my-overlay.dtbo
+ fdt resize 0x1000
+ fdt apply 0x88100000
+ bootm 0x80800000-0x88000000
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