ref-manual: Added devicetree to the Classes section
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
@@ -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
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
@@ -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" + + &am33xx_pinmux { + bb_uart4_pins: pinmux_bb_uart4_pins { + pinctrl-single,pins = + <0x070 (PIN_INPUT | MUX_MODE6)>, /* P9.11 uart4 rx */ + <0x074 (PIN_OUTPUT | MUX_MODE6)>; /* P9.13 uart4 tx */ + }; + }; + + &uart4 { + status = "okay"; + pinctrl-names = "default"; + pinctrl-0 = <&bb_uart4_pins>; + }; + </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 <dt-bindings/pinctrl/am33xx.h> + / { + compatible = "ti,beaglebone", "ti,beaglebone-black"; + part-number = "BB-UART4"; + version = "00A0"; + exclusive-user = "P9.11", "P9.13", "uart4"; + + fragment@0 { + target = <&am33xx_pinmux>; + __overlay__ { + bb_uart4_pins: pinmux_bb_uart4_pins { + pinctrl-single,pins = + <0x070 (PIN_INPUT | MUX_MODE6)>, /* P9.11 uart4 rx */ + <0x074 (PIN_OUTPUT | MUX_MODE6)>; /* P9.13 uart4 tx */ + }; + }; + }; + + fragment@1 { + target = <&uart4>; + __overlay__ { + status = "okay"; + pinctrl-name = "default"; + pinctrl-0 = <&bb_uart4_pins>; + }; + }; + }; + </literallayout> + </section> + </section> </section> </chapter>
Signature · 1 line
2.18.0