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

[Gedare Bloom]

Please make two small changes noted below, and this can be pushed (if
the PDF build looks right).

On Fri, Aug 2, 2019 at 4:44 AM Vijay Kumar Banerjee
<vijaykumar9597 at gmail.com> wrote:
>
> ---
>  user/bsps/arm/beagle.rst | 21 +--------
>  user/exe/device-tree.rst | 92 ++++++++++++++++++++++++++++++++++++++++
>  user/exe/index.rst       |  1 +
>  3 files changed, 95 insertions(+), 19 deletions(-)
>  create mode 100644 user/exe/device-tree.rst
>
> 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..4f580bf
> --- /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 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 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 DTS file can be built using the `dtc` tool in libfdt using the
This is confusing, I think you want to say the DTB is built, while the
DTS is input for building it. You can just replace DTS by DTB.

We usually say a binary file is built from a source file. We don't say
a source file is built (unless it is generated by a tool, but even
then it is unusual to say you built it, rather you generated it).

> +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
ditto, s/DTS/DTB

> +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
> --
> 2.20.1
>