[yocto] [yocto-docs][RFC PATCH 1/2] ref-manual: Added devicetree to the Classes section

[Nathan Rossi]

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.

Signed-off-by: Nathan Rossi <nathan at nathanrossi.com>
---
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(+)

diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index 77f21ede79..ea3704b7fb 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -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>
 
-- 
2.18.0