Skip to contentSkip to conversation

ref-manual: Added devicetree to the Classes section

RFC PATCH New Nathan Rossi 1 participant 2 messages Aug 2, 2018

lore
Share & tools
lore
#0 lore raw

RFC PATCH 1/2 ref-manual: Added devicetree to the Classes section

Add the devicetree class to the classes section of the ref-manual. This section covers the details around how the devicetree class works and how to use.

---
This change includes documentation about the devicetree class which is not yet in oe-core. As such this documentation is just an RFC in order to get feedback for when the changes are included in oe-core.

The oe-core patch for the devicetree class can be found here:
https://patchwork.openembedded.org/patch/153268/

---
 documentation/ref-manual/ref-classes.xml | 49 ++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
documentation/ref-manual/ref-classes.xml +49 -0
index 77f21ede79..ea3704b7fb 100644
@@ -631,6 +631,55 @@
     </para>
 </section>
 
+<section id='ref-classes-devicetree'>
+    <title><filename>devicetree.bbclass</filename></title>
+
+    <para>
+        The <filename>devicetree</filename> class handles the compilation,
+        preprocessing, installation and deployment of device trees and device
+        tree overlays.
+        Recipes inheriting this class should provide the device tree sources
+        in the <link linkend='var-S'><filename>S</filename></link> directory
+        or otherwise modify the variable <filename>DT_FILES_PATH</filename>
+        to specify the location of device tree files.
+    </para>
+
+    <para>
+        By default inheriting this class will cause the recipe to be
+        incompatible with any machine.
+        When using this class ensure to setup correct
+        <link linkend='var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></link>
+        values that correspond to the machine/BSP supported by the device tree
+        sources of the recipe.
+    </para>
+
+    <para>
+        This class will depends on the kernel sources to allow for inclusion
+        within device tree sources.
+        These source can be included in device tree sources using the
+        "<filename>/include/</filename>" or "<filename>#include</filename>"
+        directives.
+        The default include paths from the kernel are:
+        <itemizedlist>
+            <listitem><filename>${STAGING_KERNEL_DIR}/arch/${ARCH}/boot/dts</filename></listitem>
+            <listitem><filename>${STAGING_KERNEL_DIR}/arch/${ARCH}/boot/dts/*</filename></listitem>
+            <listitem><filename>${STAGING_KERNEL_DIR}/scripts/dtc/include-prefixes</filename></listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        These directories are set in the <filename>KERNEL_INCLUDE</filename>
+        variable (globbing in paths is expanded at compile time).
+        When this variable is set the recipe will depend on the kernel, to
+        disable this dependency empty the <filename>KERNEL_INCLUDE</filename>
+        variable.
+        <note>
+            Due to the inclusion of the kernel sources, this class defaults to
+            setting the license as <filename>GPLv2</filename>.
+        </note>
+    </para>
+</section>
+
 <section id='ref-classes-devshell'>
     <title><filename>devshell.bbclass</filename></title>
 
Signature · 1 line
2.18.0
#1 lore raw

RFC PATCH 2/2 bsp-guide: Add "BSP Device Tree Examples" section

Add the "BSP Device Tree Examples" section and sub-sections for documenting the two options for compiling device trees that are part of the meta layer. These sections cover examples for the beaglebone-yocto machine, as well as providing some information around reasons to use one method over the other or in conjunction with the other.

---
This change includes documentation about the devicetree class which is not yet in oe-core. As such this documentation is just an RFC in order to get feedback for when the changes are included in oe-core.

The oe-core patch for the devicetree class can be found here:
https://patchwork.openembedded.org/patch/153268/

---
 documentation/bsp-guide/bsp.xml | 168 ++++++++++++++++++++++++++++++++
 1 file changed, 168 insertions(+)
documentation/bsp-guide/bsp.xml +168 -0
index 0bb0b68ab2..2244cdee59 100644
@@ -2265,5 +2265,173 @@
             </itemizedlist>
         </para>
     </section>
+
+    <section id='bsp-device-tree-example'>
+        <title>BSP Device Tree Examples</title>
+
+        <para>
+            Certain BSPs (like the BeagleBone) require device tree
+            configuration.
+            There are two common configuration mechanisms to enable
+            compilation and deployment of device trees (and/or
+            overlays).
+            These following configurations for device tree compilation
+            are not mutually exclusive, depending on the BSP both can be
+            used to achieve one or more desired device tree configurations.
+        </para>
+
+        <section id='bsp-device-tree-kernel-example'>
+            <title>BSP Kernel Device Tree Example</title>
+
+            <para>
+                It is common for machines to have their device tree sources
+                maintained in the kernel sources.
+                In order to build these device trees during the kernel build
+                the make targets (e.g. <filename>am335x-bone.dtb</filename>)
+                for the desired device trees should be set in the variable
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_DEVICETREE'><filename>KERNEL_DEVICETREE</filename></ulink>,
+                multiple targets can be set with spaces seperating the target
+                names.
+                For details on how and where to specify this variable see the
+                previous section
+                "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-machine-configuration-example'>BSP Machine Configuration Example</ulink>".
+            </para>
+
+            <para>
+                The device trees located in the kernel sources are within the
+                <filename>arch/<replaceable>architecture</replaceable>/boot/dts</filename>
+                and or
+                <filename>arch/<replaceable>architecture</replaceable>/boot/dts/<replaceable>vendor</replaceable></filename>
+                directories.
+                Depending on the kernel recipe used the sources will vary and
+                as such the supported/available device trees will differ.
+                This is a limitation of using device trees located in the
+                kernel sources.
+                For custom BSPs this setup may be desired such that the device
+                tree for the custom board can be maintained as patches to the
+                kernel or as part of a forked kernel tree.
+            </para>
+
+            <para>
+                To add device trees for custom BSPs or where the device tree
+                sources are not already located in the kernel source, the
+                target kernel recipe needs to be appended or modified.
+                For more details on how to modify existing recipes and
+                patching the kernel sources see the
+                "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#modifying-an-existing-recipe'>Modifying an Existing Recipe</ulink>".
+            </para>
+        </section>
+
+        <section id='bsp-device-tree-recipe-example'>
+            <title>BSP Device Tree Recipe Example</title>
+
+            <para>
+                BSPs vary greatly is scope, relying on device tree sources
+                being in the kernel sources may be undesired.
+                The
+                <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-devicetree'><filename>devicetree</filename></ulink>
+                class allows for compiling of device tree sources from any
+                location that bitbake can fetch.
+            </para>
+
+            <para>
+                To setup the compilation of device tree sources create a BSP
+                specific recipe.
+                For more details on how to create recipes see the section
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-writing-a-new-recipe'>Writing a New Recipe</ulink>".
+                Inheriting the
+                <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-devicetree'><filename>devicetree</filename></ulink>
+                class provides all the setup for compilation, preprocessing as
+                well as providing kernel includes.
+                This compilation and preprocessing allows for the sources to be
+                processed like kernel device trees, where a device tree may use
+                C style preprocessor directives (e.g.
+                <filename>#include</filename>).
+                Define the source device tree location, in the following
+                example the source is provided as a file in the layer within
+                the "<filename>files/</filename>" subdirectory.
+            </para>
+
+            <literallayout class='monospaced'>
+     inherit devicetree
+
+     COMPATIBLE_MACHINE = "beaglebone-yocto"
+     SRC_URI = "file://beaglebone-uart4.dts"
+            </literallayout>
+
+            <para>
+                The following is the source device tree, located under
+                <filename>files/beaglebone-uart4.dts</filename>.
+            </para>
+
+            <literallayout class='monospaced'>
+     #include "am335x-bone.dts"
+
+     &amp;am33xx_pinmux {
+         bb_uart4_pins: pinmux_bb_uart4_pins {
+             pinctrl-single,pins =
+                 &lt;0x070 (PIN_INPUT | MUX_MODE6)&gt;, /* P9.11 uart4 rx */
+                 &lt;0x074 (PIN_OUTPUT | MUX_MODE6)&gt;; /* P9.13 uart4 tx */
+         };
+     };
+
+     &amp;uart4 {
+         status = "okay";
+         pinctrl-names = "default";
+         pinctrl-0 = &lt;&amp;bb_uart4_pins&gt;;
+     };
+            </literallayout>
+
+            <para>
+                The
+                <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-devicetree'><filename>devicetree</filename></ulink>
+                class can also handle the compilation of device tree overlays.
+                Overlay <filename>.dts</filename> files are determined to be
+                overlays based on the use of "<filename>/plugin/;</filename>".
+                The previous example of enabling UART 4 for the BeagleBone can
+                be configured as an overlay, the following example shows the
+                equivalent configuration for the BeagleBone to enable UART 4.
+            </para>
+
+            <para>
+                The following is the source device tree overlay, located
+                within the layer under
+                <filename>files/beaglebone-uart4.dts</filename>
+                within the recipes directory.
+            </para>
+
+            <literallayout class='monospaced'>
+     /dts-v1/;
+     /plugin/;
+     #include &lt;dt-bindings/pinctrl/am33xx.h&gt;
+     / {
+         compatible = "ti,beaglebone", "ti,beaglebone-black";
+         part-number = "BB-UART4";
+         version = "00A0";
+         exclusive-user = "P9.11", "P9.13", "uart4";
+
+         fragment@0 {
+             target = &lt;&amp;am33xx_pinmux&gt;;
+             __overlay__ {
+                 bb_uart4_pins: pinmux_bb_uart4_pins {
+                     pinctrl-single,pins =
+                         &lt;0x070 (PIN_INPUT | MUX_MODE6)&gt;, /* P9.11 uart4 rx */
+                         &lt;0x074 (PIN_OUTPUT | MUX_MODE6)&gt;; /* P9.13 uart4 tx */
+                 };
+             };
+         };
+
+         fragment@1 {
+             target = &lt;&amp;uart4&gt;;
+             __overlay__ {
+                 status = "okay";
+                 pinctrl-name = "default";
+                 pinctrl-0 = &lt;&amp;bb_uart4_pins&gt;;
+             };
+         };
+     };
+            </literallayout>
+        </section>
+    </section>
 </section>
 </chapter>
Signature · 1 line
2.18.0