Changes between Version 12 and Version 13 of linux/devicetree


Ignore:
Timestamp:
12/17/2021 10:02:04 PM (3 years ago)
Author:
Tim Harvey
Comment:

added dt overlay info

Legend:

Unmodified
Added
Removed
Modified

  • linux/devicetree

    v12 v13  
    11[[PageOutline]]
    22
    3 = Linux Device Tree support =
    4 The modern linux kernel uses a system called 'devicetree' to describe hardware in a consistent fashion to avoid needing custom 'board support' files for boards.
    5 
    6 Typically the bootloader will pass a 'flattened device tree' (a compiled binary representation of a device-tree) to the kernel so that the kernel can configure all the components on the board.
    7 
     3= Device Tree =
     4The modern linux kernel as well as the modern U-Boot bootloader use a system called 'devicetree' to describe hardware in a consistent fashion to avoid needing custom 'board support' files (compiled code) for boards.
     5
     6For a device-tree controlled U-Boot (newport/venice) the Secondary Program Loader (SPL) is in charge of choosing a dtb (flattened device tree binary) to pass to U-Boot.
     7
     8For a device-tree controlled Linux kernel the bootloader will load a dtb, modify it where necessary, and pass it to Linux.
     9
     10Because board specific details such as memory size, MAC addresses and serial numbers are relied to the kernel via device-tree the bootloader will modify the device-tree with these details before passing it to the kernel.
    811
    912== Device Tree Terminology ==
     13The following terminology is commonly used:
     14 * dt - device tree
     15 * fdt - Flattened device tree (binary image)
     16 * dtc - device tree compiler (the tool used to compile and de-compile device-tree)
     17
     18The following file extensions are typically used:
    1019 * dts - Board level definitions
    1120 * dtsi - SoC level definitions
    1221 * dtb - Binary blob of device tree loaded by bootloader
     22 * dtbo - Binary blob of device tree overlay (aka fragment) loaded and applied by bootloader
    1323
    1424
    1525== Example Device Tree File ==
    16 You can find the device tree files in arch/arm/boot/dts
    17 
    18 For the Gateworks Venice platform, the device tree files are at arch/arm64/boot/dts/freescale/
    19  - Note device tree source code (eg GW7200) is located in kernel source code at path: linux-venice/arch/arm64/boot/dts/freescale/imx8mm-venice-gw72xx.dtsi
    20  - Link for the Venice kernel source code [https://github.com/Gateworks/linux-venice here]
    21 
    22 For an example, see [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/arm/boot/dts/imx6qdl-gw54xx.dtsi imx6qdl-gw54xx.dtsi]
     26Device tree files exist in:
     27 * Linux kernel tree:
     28  - arch/arm/boot/dts for 32bit ARM
     29  - arch/arm64/boot/dts for 64bit ARM
     30 * U-Boot bootloader:
     31  - arch/arm/dts for ARM
     32
     33For Gateworks Kernels:
     34 - Venice: [https://github.com/Gateworks/linux-venice/tree/v5.10.76-venice/arch/arm64/boot/dts/freescale arch/arm64/boot/dts/freescale] imx8*-venice-*.dts*
     35 - Newport: [https://github.com/Gateworks/dts-newport dts-newport] gw*.dts* (Note Newport dt source is not in the Mainline Linux kernel)
     36 - Ventana: [https://github.com/Gateworks/linux-imx6/tree/gateworks_5.4.45/arch/arm/boot/dts/ arch/arm/boot/dts] imx6*-gw-*.dts*
    2337
    2438
    2539== Accessing devicetree from the Bootloader ==
    26 The Ventana u-boot has fdt support enabled and uses this through default bootscripts to load an fdt (based on the board model) from the filesystem of the boot media.  The bootloader then modifies the devicetree to disable components that are possible on the board, but perhaps not loaded on the bill-of-materials (for example, a Gateworks Special build).
    27 
    28 If desired you can use the ftd u-boot command to access/modify the devicetree before the kernel is booted.
     40The U-Boot bootloader is responsible for Loading a device-tree, making any adjustments necessary, and passing it to the kernel.
     41
     42If desired you can use the {{{ftd}}} U-boot command to access/modify the devicetree before the kernel is booted.
    2943
    3044Examples:
    31  * display the fdt of a Ventana board (loaded from NAND flash ubifs):
     45 * Ventana: display the fdt on a NAND flash board:
    3246{{{#!bash
    3347setenv fsload 'ubifsload'
    … …  
    3650fdt print
    3751}}}
    38  * disable PCI via device-tree:
     52 * Ventana: disable PCI via {{{fixfdt}}} script:
    3953{{{#!bash
    4054setenv fsload 'ubifsload'
    … …  
    4559}}}
    4660
    47 Note the Ventana bootloader has a '''fixfdt''' script that can make integrating fixups like this into the boot process easy. See [http://trac.gateworks.com/wiki/ventana/bootloader#Specifyinganalternatedevice-treeblobDTB here] for details.
     61Note some bootloader environments such as Ventana and Venice call a {{{fixfdt}}} script that can make integrating fixups like this into the boot process easy. See [http://trac.gateworks.com/wiki/ventana/bootloader#Specifyinganalternatedevice-treeblobDTB here] for details.
     62
     63Note also that some bootloader environments such as Venice offer dt overlay support where the bootloader can apply overlays to a dt to alter it before passing it to the kernel. In the case of venice you can set the {{{fdt_overlay}}} env variable to a list of files to load and apply as an overlay to modify the base fdt which is typically used for adding features from an add-on board like a display or camera.
    4864
    4965
    5066== Accessing devicetree from Linux ==
    51 If the kernel is configured with CONFIG_PROC_DEVICETREE (which the Ventana OpenWrt BSP does configure) and procfs is enabled, you can access the devicetree via /proc/device-tree.  This can be useful to obtain information about the board that the bootloader configured, such as board model and serial number.
     67If the kernel is configured with CONFIG_PROC_DEVICETREE and procfs is enabled (both are enabled on Gateworks default kernels), you can access the devicetree via {{{/proc/device-tree}}}. This can be useful to obtain information about the board that the bootloader configured, such as board model and serial number.
     68
     69Additionally the {{{/sys/firmware/devicetree/base}}} sysfs file represents the binary devicetree which you can use with the [wiki:#dtc device tree compiler].
    5270
    5371Examples:
    … …  
    6987}}}
    7088
    71 
    72 == Specifying the Device-tree that is used ==
    73 The [wiki:/linux/bootloader bootloader] is responsible for loading the device-tree blob (DTB) and executing the kernel
    74 The Gateworks ventana bootloader in a way that it knows where the DTB is loaded.
    75 
    76 Therefore, its the bootloader that decides which DTB to load and from where.
    77 
    78 See [wiki:/ventana/bootloader] for details on how the DTB filename is chosen and loaded.
    79 
    80 == Adding New Devices to the Device Tree
    81 For customers interested in adding a new device to an existing controller, see the [wiki:/SPI SPI] wiki page for an example of the process.
     89== Device Tree Overlays (aka Fragments) ==
     90The device-tree compiler and the U-Boot bootloader support the concept of applying changes to a base device-tree to make it easy to implement add-on boards such as a touchscreen display or camera that require dt bindings.
     91
     92Some specific requirements:
     93 - requires '/plugin/' specified
     94 - requires '&{/} { compatible };' node that specifies the board this fragment is compatible with
     95 - requires using handles of nodes that are defined in the base devicetree
     96 - requires compiling with the-@ flag
     97
     98To provide a simple example consider adding a simple SPI NOR flash device on an off-board SPI connector. Such a device has a Linux kernel driver and requires using device-tree bindings:
     99{{{
     100/dts-v1/;
     101/plugin/;
     102
     103&{/} {
     104        compatible = "gw,imx8mm-gw73xx-0x", "fsl,imx8mm";
     105};
     106
     107/* off-board header */
     108&ecspi2 {
     109       flash@0 {
     110               compatible = "spansion,m25p128", "jedec,spi-nor";
     111               spi-max-frequency = <30000000>;
     112               reg = <0>;
     113               #address-cells = <1>;
     114               #size-cells = <1>;
     115               m25p,fast-read;
     116
     117               partition@0 {
     118                       label = "data";
     119                       reg = <0x0 0x1000000>;
     120               };
     121       };
     122};
     123}}}
     124 - Note the compatible string specifies the board this is compatible with
     125 - Note the board in question's base dt specifies the ecspi2 handle which we modify here
     126
     127To compile this fragment:
     128{{{#!bash
     129dtc -@ -I dts -O dtb -o imx8mm-gw73xx-0x-spinor.dtbo imx8mm-gw73xx-0x-spinor.dts
     130}}}
     131
     132And to use it on a Venice imx8mm-gw73xx-0x make sure the dtbo exits alongside the kernel in the directory the bootscript resides (ie /boot)
     133{{{#!bash
     134setenv fdt_overlays "imx8mm-gw73xx-0x-spinor.dtbo"
     135saveenv
     136}}}
     137
     138Notes:
     139 * Support for compiling dtbo files appeared in the Linux kernel somewhere between 5.10 and 5.15
     140 * Gateworks uses dtbo's to provide support for adding a RaspberryPi v2.0 camera module and a RaspberryPi DFROBOT touchscreen display to a gw72xx/gw73xx baseboard for example.
     141
     142
     143== Gateworks Product family notes
     144
     145[=#venice]
     146=== Venice
     147For Venice:
     148 * U-Boot is controlled by device-tree, the DTB used is decided upon by the SPL based on EEPROM contents describing the board model, exists in a FIT image along with the ARM Trusted Firmware (ATF) and U-Boot proper and is specified by a 'DTB' banner before the SPL boots U-Boot proper.
     149 * The Linux device-tree comes from the kernel source tree (arch/arm64/boot/dts/freescale) and is loaded and modified by the bootloader. The {{{loadfdt}}} script is used to load the device-tree blob (dtb) and will attempt to load several board dtb files starting with the most specific names possible including board PCB revisions and ending with a generic file represending the baseboard.
     150 * A list of optional files specified by {{{fdt_overlays}}} will be loaded and applied as overlays and if defined {{{fixfdt}}} will be run as well.
     151
     152
     153[=#newport]
     154=== Newport
     155For Newport:
     156 * U-Boot is controlled by device-tree, the dtb used is loaded by BDK from the embedded FATFS based on the model from the board EEPROM.
     157 * DTS source files are in the [https://github.com/Gateworks/dts-newport dts-newport] repo and built by the BSP Makefile and populated in the FATFS
     158 * The bootscript uses the U-Boot 'live' device-tree used by U-Boot for Linux as well (by passing the bootm command '$fdtcontroladdr'). This is not required and if needed you could load your own dtb and pass the address instead however note that the DTS files for CN80xx do not exist in the kernel tree.
     159
     160
     161[=#ventana]
     162=== Ventana
     163For Ventana:
     164 * The latest Gateworks gateworks_v2017.05 U-Boot is not controlled by device tree and instead board support in U-Boot is handled by code based off the board model from the EEPROM
     165 * DTS source files are in the Linux kernel in the arch/arm/boot/dts directory and placed with the kernel uImage in the same directory as the bootscript in the root filesystem (ie /boot)
     166 * The bootloader {{{loadfdt}}} script is used to load the device-tree blob (dtb) in all standard boot cases for the Gateworks bootloader. This script attempts to load a dtb three times, each time with a more generic filename (from the {{{fdt_file}}}, {{{fdt_file1}}}, and {{{fdt_file2}}}) env variable which if not set (overridden) will get set per the board model defined in the Gateworks EEPROM. For example a GW5400-C would have the following:
     167{{{#!bash
     168Ventana >  print fdt_file
     169fdt_file=imx6q-gw5400-c.dtb
     170Ventana >  print fdt_file1
     171fdt_file1=imx6q-gw5400.dtb
     172Ventana >  print fdt_file2
     173fdt_file2=imx6q-gw54xx.dtb
     174}}}
     175
     176
     177=== Laguna
     178The Laguna bootloader and Linux kernel do not use device-tree for board configuration.
     179
     180
     181== Adding New Devices to the Device Tree
     182For customers interested in adding a new device to a board's device-tree (for example something connected to an off-board header) see the following examples:
     183 * [wiki:/SPI SPI]
     184
     185
     186[=#dtc]
     187== Device Tree Compiler
    82188
    83189=== Compiling the Device Tree