[PATCH] user/exe : Add Device Tree section

[Vijay Kumar Banerjee]

On Mon, Jul 22, 2019 at 5:07 PM Nils Hölscher <nilhoel1 at gmail.com> wrote:

>
>
> 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.
>
The reason to use the make_dtb.sh script is that it uses the -i option with
dtc which
sets the include directory.
Inside the script there are a few includes like these :
```
-i "$S/dts/${MACHINE}" -i "$S/gnu/dts/${MACHINE}"
```
here $S is the build tree argument. So if you use this script with the
right path to build
tree, i.e., the path to gnu/ directory, then the included files will be
discoverable and
there won't be a need to edit the includes.
I agree that it's not intuitive that the build tree must be the path to gnu
directory and a
user would not like to look into every script involved to figure out what
it does. How would
you suggest to include this information in the doc so that it's
understandable?

+
>> +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
>
> Thanks for the note. Will fix this in v2.

> The rest looks fine to me.
>
> Thanks for reviewing the patch!

> 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/1394668d/attachment.html>