[PATCH] user/exe : Add Device Tree section

Mon Jul 22 12:52:49 UTC 2019

On Mon, 22 Jul 2019 at 14:12, Vijay Kumar Banerjee <vijaykumar9597 at gmail.com>
wrote:

>
>
>
> 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?
>
Yes this is truly confusing.
But I don't know if this need to be mentioned.
I just didn't know it and used a more complicated way to build my device
trees.
The whole external device tree stuff isn't optimal, I also remember a
discussion on devel about this.

>
> +
>>> +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/93118c02/attachment-0002.html>