Skip to contentSkip to conversation

ref-manual: classes.rst: document devicetree.bbclass

PATCH In review [email protected] 3 participants 4 messages Apr 12, 2023 – Jun 22, 2023

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 ref-manual: classes.rst: document devicetree.bbclass

From: Michael Opdenacker <[email protected]>

This addresses [YOCTO #15092]

---
 documentation/ref-manual/classes.rst | 43 ++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)
documentation/ref-manual/classes.rst +43 -0
index f8172e6b29..79a2bdb69b 100644
@@ -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``
Signature · 1 line
2.34.1
Reviewed-by on v1 1/1
#1 lore raw

Hi Mike,

Quoted 6 lines · On Wed, 12 Apr 2023 21:11:22 +0200 [email protected] wrote:

From: Michael Opdenacker <[email protected]>

This addresses [YOCTO #15092]

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:

Signature · 3 lines
Luca Ceresoli, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
#2 lore raw
In reply to [email protected]

Hi Michael, Luca,

Quoted 32 lines · Michael Opdenacker via lists.yoctoproject.org

From: Michael Opdenacker <[email protected]>

This addresses [YOCTO #15092]

---
  documentation/ref-manual/classes.rst | 43 ++++++++++++++++++++++++++++
  1 file changed, 43 insertions(+)
documentation/ref-manual/classes.rst +14 -0
index f8172e6b29..79a2bdb69b 100644
@@ -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:

documentation/ref-manual/classes.rst add the task at the appropriate place, which is usually after · line 606

Quoted 10 lines
documentation/ref-manual/classes.rst +10 -0
+
+- 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

#3 lore raw

Hi Quentin,

Quoted 48 lines · On Thu, 22 Jun 2023 14:54:13 +0200 Quentin Schulz…

Hi Michael, Luca,

Quoted 32 lines · Michael Opdenacker via lists.yoctoproject.org

From: Michael Opdenacker <[email protected]>

This addresses [YOCTO #15092]

---
  documentation/ref-manual/classes.rst | 43 ++++++++++++++++++++++++++++
  1 file changed, 43 insertions(+)
documentation/ref-manual/classes.rst +14 -0
index f8172e6b29..79a2bdb69b 100644
@@ -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:

documentation/ref-manual/classes.rst add the task at the appropriate place, which is usually after · line 606

Quoted 10 lines
documentation/ref-manual/classes.rst +10 -0
+
+- 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.

Quoted 5 lines

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! :-)

Quoted 2 lines

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

Signature · 3 lines
Luca Ceresoli, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com