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

[Christian Mauderer]

Hello Vijay,

sorry for the long delay between posting and review. It was a busy week.

Would that replace part of the documentation you did in the beagle BSP?
In that case it might could be good to remove it from there and put up a
reference.

@all: Could one of our native English speakers please proof-read that too?

On 23/07/2019 06:41, Vijay Kumar Banerjee wrote:
> ---
>  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>

Wrong year. Except you started with that last year.

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

If RTEMS is used together with libbsd the DTB should be build from the
FreeBSD source tree matching the commit that is used for `freebsd-org`
in libbsd.

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

Maybe already mention the -@ option here if someone wants to use overlays.

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

I think there shouldn't be a space between NOTE and the colon, should there?

> +an example. It is advised to always use the source from the commit matching the
> +libBSD HEAD.`

... matching `freebsd_org` 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 SDcard and apply it using u-boot

"U-Boot" - they use big letters on their home page:
http://www.denx.de/wiki/U-Boot. Please also fix that in the rest of the
text below.

> +   from the uEnv.txt file.

uEnv.txt isn't a must. I think it's a Beagle convention (and maybe for
some other boards too). Just stop after "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 SDcard and use uEnv.txt to load
> +and apply the overlay.

Again: SD card (by the way: There should be a space between SD and card
as far as I know) and uEnv.txt is for Beagle.

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

I would suggest to only show the U-Boot commands (in multiple lines)
that are used to apply an overlay and not the script to generate a
uEnv.txt. Would most likely be more useful if someone tries to adapt it
to another board.

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