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.
Signed-off-by: Nathan Rossi <nat...@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/bsp-guide/bsp.xml | 168 ++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml index 0bb0b68ab2..2244cdee59 100644 --- a/documentation/bsp-guide/bsp.xml +++ b/documentation/bsp-guide/bsp.xml @@ -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> -- 2.18.0 -- _______________________________________________ yocto mailing list yocto@yoctoproject.org https://lists.yoctoproject.org/listinfo/yocto
