[PATCH] user/exe : Add Device Tree section

[Nils Hölscher]

On Mon, 22 Jul 2019 at 12:41, Vijay Kumar Banerjee <vijaykumar9597 at gmail.com>
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..3cd52cd
> --- /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
> +     # $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)
>

Does this really work?
Cause I had to change all includes in the dts files from relative to
absolute paths.

> +
> +Using Device Tree Overlay
> +-------------------------
> +
> +Device tree overlay is used either add properties or devices to the
> existing
>
 Little typo: Device tree overlay is used either [*to]* add properties or
devices to the existing

The rest looks fine to me.

Best,
Nils

> +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
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20190722/06db21c3/attachment-0002.html>