[yocto] [yocto-docs][RFC PATCH 2/2] bsp-guide: Add "BSP Device Tree Examples" section
Nathan Rossi
nathan at nathanrossi.com
Thu Aug 2 02:34:35 PDT 2018
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 <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/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 at 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 at 1 {
+ target = <&uart4>;
+ __overlay__ {
+ status = "okay";
+ pinctrl-name = "default";
+ pinctrl-0 = <&bb_uart4_pins>;
+ };
+ };
+ };
+ </literallayout>
+ </section>
+ </section>
</section>
</chapter>
--
2.18.0
More information about the yocto
mailing list