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

[Vijay Kumar Banerjee]

On Sat, Jul 27, 2019 at 5:49 PM Christian Mauderer <list at c-mauderer.de>
wrote:

> 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?
>
> Hi, I have posted the v3 of the patch with the corrections you noted,
please
have a look:
https://lists.rtems.org/pipermail/devel/2019-July/026943.html

> 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
> >
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20190730/8496646f/attachment-0002.html>