[PATCH] ref-manual: classes.rst: document devicetree.bbclass

[PATCH] ref-manual: classes.rst: document devicetree.bbclass

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

This addresses [YOCTO #15092]

Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/ref-manual/classes.rst | 43 ++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index f8172e6b29..79a2bdb69b 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -580,6 +580,49 @@ add the task at the appropriate place, which is usually after
 :ref:`ref-tasks-install`. The class then takes care of
 staging the files from :term:`DEPLOYDIR` to :term:`DEPLOY_DIR_IMAGE`.
 
+.. _ref-classes-devicetree:
+
+``devicetree``
+==============
+
+The :ref:`ref-classes-devicetree` class allows to build a recipe that compiles
+device tree source files that are not in the kernel tree.
+
+The compilation of out-of-tree device tree sources is the same as the kernel
+in-tree device tree compilation process. This includes the ability to include
+sources from the kernel such as SoC ``dtsi`` files as well as C header files,
+such as ``gpio.h``.
+
+The :ref:`ref-tasks-compile` task will compile two kinds of files:
+
+- Regular device tree sources with a ``.dts`` extension.
+
+- Device tree overlays, detected from the presence of the ``/plugin/;``
+  string in the file contents.
+
+This class behaves in a similar way as the :ref:`ref-classes-kernel-devicetree`
+class, also deploying output files into ``/boot/devicetree``. However, this
+class stores the deployed device tree binaries into the ``devicetree``
+subdirectory. This avoids clashes with the :ref:`ref-classes-kernel-devicetree`
+output. Additionally, the device trees are populated into the sysroot for
+access via the sysroot from within other recipes.
+
+An extra padding is appended to non-overlay device trees binaries. This
+can typically be used as extra space for adding extra properties at boot time.
+The padding size can be modified by setting ``DT_PADDING_SIZE`` to the desired
+size, in bytes.
+
+See :oe_git:`devicetree.bbclass sources
+</openembedded-core/tree/meta/classes-recipe/devicetree.bbclass>` 
+for further variables controlling this class.
+
+Here is an excerpt of an example ``recipes-kernel/linux/devicetree-acme.bb``
+recipe inheriting this class::
+
+   inherit devicetree
+   COMPATIBLE_MACHINE = "^mymachine$"
+   SRC_URI:mymachine = "file://mymachine.dts"
+
 .. _ref-classes-devshell:
 
 ``devshell``
-- 
2.34.1

Re: [PATCH] ref-manual: classes.rst: document devicetree.bbclass

[Luca Ceresoli]

Hi Mike,

On Wed, 12 Apr 2023 21:11:22 +0200
michael.opdenacker@bootlin.com wrote:

> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
> 
> This addresses [YOCTO #15092]
> 
> Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>

Thank you!

Since you already added my SoB line (which seems appropriate) I'm not
sure it makes sense to also add a Reviewed-by line, but in case it does
you can add:

Reviewed-by: Luca Ceresoli <luca.ceresoli@bootlin.com>

-- 
Luca Ceresoli, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH] ref-manual: classes.rst: document devicetree.bbclass

[Quentin Schulz]

Hi Michael, Luca,

On 4/12/23 21:11, Michael Opdenacker via lists.yoctoproject.org wrote:
> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
> 
> This addresses [YOCTO #15092]
> 
> Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> ---
>   documentation/ref-manual/classes.rst | 43 ++++++++++++++++++++++++++++
>   1 file changed, 43 insertions(+)
> 
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index f8172e6b29..79a2bdb69b 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -580,6 +580,49 @@ add the task at the appropriate place, which is usually after
>   :ref:`ref-tasks-install`. The class then takes care of
>   staging the files from :term:`DEPLOYDIR` to :term:`DEPLOY_DIR_IMAGE`.
>   
> +.. _ref-classes-devicetree:
> +
> +``devicetree``
> +==============
> +
> +The :ref:`ref-classes-devicetree` class allows to build a recipe that compiles
> +device tree source files that are not in the kernel tree.
> +
> +The compilation of out-of-tree device tree sources is the same as the kernel
> +in-tree device tree compilation process. This includes the ability to include
> +sources from the kernel such as SoC ``dtsi`` files as well as C header files,
> +such as ``gpio.h``.
> +
> +The :ref:`ref-tasks-compile` task will compile two kinds of files:
> +
> +- Regular device tree sources with a ``.dts`` extension.
> +
> +- Device tree overlays, detected from the presence of the ``/plugin/;``
> +  string in the file contents.
> +
> +This class behaves in a similar way as the :ref:`ref-classes-kernel-devicetree`
> +class, also deploying output files into ``/boot/devicetree``. However, this
> +class stores the deployed device tree binaries into the ``devicetree``
> +subdirectory.

If I'm not mistaken, you're saying the same thing twice.

I believe :ref:`ref-classes-kernel-devicetree` class puts the dtb in 
/boot directory by default (KERNEL_DTBDEST which defaults to 
KERNEL_IMAGEDEST which defaults to boot) while 
:ref:`ref-classes-devicetree` class puts it into /boot/devicetree/ 
directory?

I think you may have used the comment from the devicetree.bbclass header 
which is also a bit confusing.

Cheers,
Quentin

Re: [docs] [PATCH] ref-manual: classes.rst: document devicetree.bbclass

[Luca Ceresoli]

Hi Quentin,

On Thu, 22 Jun 2023 14:54:13 +0200
Quentin Schulz <quentin.schulz@theobroma-systems.com> wrote:

> Hi Michael, Luca,
> 
> On 4/12/23 21:11, Michael Opdenacker via lists.yoctoproject.org wrote:
> > From: Michael Opdenacker <michael.opdenacker@bootlin.com>
> > 
> > This addresses [YOCTO #15092]
> > 
> > Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
> > Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> > ---
> >   documentation/ref-manual/classes.rst | 43 ++++++++++++++++++++++++++++
> >   1 file changed, 43 insertions(+)
> > 
> > diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> > index f8172e6b29..79a2bdb69b 100644
> > --- a/documentation/ref-manual/classes.rst
> > +++ b/documentation/ref-manual/classes.rst
> > @@ -580,6 +580,49 @@ add the task at the appropriate place, which is usually after
> >   :ref:`ref-tasks-install`. The class then takes care of
> >   staging the files from :term:`DEPLOYDIR` to :term:`DEPLOY_DIR_IMAGE`.
> >   
> > +.. _ref-classes-devicetree:
> > +
> > +``devicetree``
> > +==============
> > +
> > +The :ref:`ref-classes-devicetree` class allows to build a recipe that compiles
> > +device tree source files that are not in the kernel tree.
> > +
> > +The compilation of out-of-tree device tree sources is the same as the kernel
> > +in-tree device tree compilation process. This includes the ability to include
> > +sources from the kernel such as SoC ``dtsi`` files as well as C header files,
> > +such as ``gpio.h``.
> > +
> > +The :ref:`ref-tasks-compile` task will compile two kinds of files:
> > +
> > +- Regular device tree sources with a ``.dts`` extension.
> > +
> > +- Device tree overlays, detected from the presence of the ``/plugin/;``
> > +  string in the file contents.
> > +
> > +This class behaves in a similar way as the :ref:`ref-classes-kernel-devicetree`
> > +class, also deploying output files into ``/boot/devicetree``. However, this
> > +class stores the deployed device tree binaries into the ``devicetree``
> > +subdirectory.  
> 
> If I'm not mistaken, you're saying the same thing twice.
> 
> I believe :ref:`ref-classes-kernel-devicetree` class puts the dtb in 
> /boot directory by default (KERNEL_DTBDEST which defaults to 
> KERNEL_IMAGEDEST which defaults to boot) while 
> :ref:`ref-classes-devicetree` class puts it into /boot/devicetree/ 
> directory?

Haha, you are perfectly right, I wrote nonsense! :-)

> I think you may have used the comment from the devicetree.bbclass header 
> which is also a bit confusing.

Indeed that was my starting point.

I'm sending an amendment tomorrow.

Thanks for reviewing,
Luca

-- 
Luca Ceresoli, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com