DT-Overlay

Introduction

A device tree overlay is a file that can be used at runtime (by the bootloader in our case) to dynamically modify the device tree, adding nodes to the tree and making changes to properties in the existing tree.

Build DT-Overlay from sources

Getting DT-Overlay sources

You can easily download DT Overlay source code from Linux4Microchip GitHub DT Overlays repository:

  • clone the Linux4Microchip GitHub DT Overlay repository
       $ git clone https://github.com/linux4microchip/dt-overlay-mchp.git
        Cloning into 'dt-overlay-mchp'...
        remote: Enumerating objects: 1585, done.
        remote: Counting objects: 100% (465/465), done.
        remote: Compressing objects: 100% (180/180), done.
        remote: Total 1585 (delta 282), reused 441 (delta 274), pack-reused 1120
        Receiving objects: 100% (1585/1585), 539.04 KiB | 4.08 MiB/s, done. 
        Resolving deltas: 100% (879/879), done.
       $ cd dt-overlay-mchp/
       

  • The source code has been taken from the master branch which is pointing to the latest branch we use.

Build DT-Overlay

To build the overlays for a board make sure the following steps are done:

  • the environment variables ARCH and CROSS_COMPILE are set correctly
  • (optional) the environment variable KERNEL_DIR points to Linux kernel and the kernel was already built for the board. This is needed because the DT Overlay repository uses the Device Tree Compiler (dtc) from the kernel source tree. By default, KERNEL_DIR is set to a linux directory that would be under the parent directory in the directory tree: ../linux
  • (optional) the environment variable KERNEL_BUILD_DIR that points to where the Linux kernel binary and Device Tree blob, resulting of your compilation of the kernel, are located. By default, KERNEL_BUILD_DIR is set to the same directory as KERNEL_DIR. It shouldn't be changed if you have the habit of compiling your kernel within the Linux source tree

The following example shows how to build the overlays for sama5d27_wlsom1_ek:

   $ make sama5d27_wlsom1_ek_dtbos
   

Build FIT image

To build the FIT image with overlays for a board make sure the following steps are done:

  • the environment variables ARCH and CROSS_COMPILE are set correctly
  • (optional) the environment variable KERNEL_DIR points to Linux kernel and the kernel was already built for the board. This is needed because the DT Overlay repository uses the Device Tree Compiler (dtc) from the kernel source tree. By default, KERNEL_DIR is set to a linux directory that would be under the parent directory in the directory tree: ../linux
  • (optional) the environment variable KERNEL_BUILD_DIR that points to where the Linux kernel binary and Device Tree blob, resulting of your compilation of the kernel, are located. By default, KERNEL_BUILD_DIR is set to the same directory as KERNEL_DIR. It shouldn't be changed if you have the habit of compiling your kernel within the Linux source tree.
  • mkimage is installed on the development machine
  • the Device Tree Compiler from Linux kernel is in the PATH environment variable

The following example shows how to build the FIT image for sama5d27_wlsom1_ek:

   $ make sama5d27_wlsom1_ek.itb
    ....
FIT description: Microchip SAMA5D27 WLSOM1 EK FIT Image
Created:         Fri Dec 15 16:40:28 2023
 Image 0 (kernel)
  Description:  Linux4SAM Linux kernel
  Created:      Fri Dec 15 16:40:28 2023
  Type:         Kernel Image
  Compression:  uncompressed
  Data Size:    4745096 Bytes = 4633.88 KiB = 4.53 MiB
  Architecture: ARM
  OS:           Linux
  Load Address: 0x22000000
  Entry Point:  0x22000000
  Hash algo:    crc32
  Hash value:   5de22fa3
  Hash algo:    sha1
  Hash value:   7724fc70f30773492bddcb42bb3fd7d18ceeffd2
 Image 1 (base_fdt)
  Description:  Flattened Device Tree blob
  Created:      Fri Dec 15 16:40:28 2023
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    26001 Bytes = 25.39 KiB = 0.02 MiB
  Architecture: ARM
  Load Address: 0x23000000
  Hash algo:    crc32
  Hash value:   90ea5cfb
  Hash algo:    sha1
  Hash value:   686782c189ecddb0f0d0c9e8e77e709c21c22b04
 Image 2 (fdt_isc)
  Description:  Device Tree blob ISC overlay
  Created:      Fri Dec 15 16:40:28 2023
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    830 Bytes = 0.81 KiB = 0.00 MiB
  Architecture: ARM
  Load Address: 0x23100000
  Hash algo:    crc32
  Hash value:   92c0d959
  Hash algo:    sha1
  Hash value:   2f3337a60b120686492f9ac0c2bae53a3095b612
 Image 3 (fdt_ov7670)
  Description:  Device Tree blob Ov7670 overlay
  Created:      Fri Dec 15 16:40:28 2023
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    2072 Bytes = 2.02 KiB = 0.00 MiB
  Architecture: ARM
  Load Address: 0x23110000
  Hash algo:    crc32
  Hash value:   b4a353ce
  Hash algo:    sha1
  Hash value:   7d0513f9b559d22cd00809e8781291444ff5b847
 Image 4 (fdt_ov7740)
  Description:  Device Tree blob OV7740 overlay
  Created:      Fri Dec 15 16:40:28 2023
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    2072 Bytes = 2.02 KiB = 0.00 MiB
  Architecture: ARM
  Load Address: 0x23120000
  Hash algo:    crc32
  Hash value:   b0626ba5
  Hash algo:    sha1
  Hash value:   ec984fad2e0510a9e327b04657929f470b330015
 Image 5 (fdt_pda4)
  Description:  Device Tree blob pda4300 overlay
  Created:      Fri Dec 15 16:40:28 2023
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    4213 Bytes = 4.11 KiB = 0.00 MiB
  Architecture: ARM
  Load Address: 0x23130000
  Hash algo:    crc32
  Hash value:   53644ef9
  Hash algo:    sha1
  Hash value:   e0722917a1783bebc86cb453ace294614bac2104
 Image 6 (fdt_pda5)
  Description:  Device Tree blob pda5000 overlay
  Created:      Fri Dec 15 16:40:28 2023
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    4217 Bytes = 4.12 KiB = 0.00 MiB
  Architecture: ARM
  Load Address: 0x23140000
  Hash algo:    crc32
  Hash value:   669d7bb1
  Hash algo:    sha1
  Hash value:   01fcaf139fe07f433eb8ce0648d05a1df374cfd6
 Image 7 (fdt_pda7)
  Description:  Device Tree blob pda7000 overlay
  Created:      Fri Dec 15 16:40:28 2023
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    4225 Bytes = 4.13 KiB = 0.00 MiB
  Architecture: ARM
  Load Address: 0x23150000
  Hash algo:    crc32
  Hash value:   bb84f7c1
  Hash algo:    sha1
  Hash value:   1d72d37cb6d9e16b90cfb0ec5e5df800090ae842
 Image 8 (fdt_pda7b)
  Description:  Device Tree blob pda7000b overlay
  Created:      Fri Dec 15 16:40:28 2023
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    4266 Bytes = 4.17 KiB = 0.00 MiB
  Architecture: ARM
  Load Address: 0x23160000
  Hash algo:    crc32
  Hash value:   73438626
  Hash algo:    sha1
  Hash value:   472a1175100916a96837aee70a535de869a7f6eb
 Image 9 (fdt_ov5640)
  Description:  Device Tree blob OV5640 overlay
  Created:      Fri Dec 15 16:40:28 2023
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    2157 Bytes = 2.11 KiB = 0.00 MiB
  Architecture: ARM
  Load Address: 0x23190000
  Hash algo:    crc32
  Hash value:   3bd2cf77
  Hash algo:    sha1
  Hash value:   3d2fb4a603eab7734829611019a8d91e180b59d2
 Image 10 (fdt_ptc)
  Description:  Device Tree blob PTC overlay
  Created:      Fri Dec 15 16:40:28 2023
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    187 Bytes = 0.18 KiB = 0.00 MiB
  Architecture: ARM
  Load Address: 0x23170000
  Hash algo:    crc32
  Hash value:   6ec7b17d
  Hash algo:    sha1
  Hash value:   27d81e67c9add557e8cf3bf70ed149684f12cfd5
 Image 11 (fdt_mt9v022)
  Description:  Device Tree blob MT9V022 overlay
  Created:      Fri Dec 15 16:40:28 2023
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    2539 Bytes = 2.48 KiB = 0.00 MiB
  Architecture: ARM
  Load Address: 0x23200000
  Hash algo:    crc32
  Hash value:   a8db090e
  Hash algo:    sha1
  Hash value:   0cd13acbc046e8959904159791e7c85943e2cf8f
 Image 12 (fdt_spi_click1)
  Description:  Device Tree blob at25ff321a spi flash clickboard overlay
  Created:      Fri Dec 15 16:40:28 2023
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    1156 Bytes = 1.13 KiB = 0.00 MiB
  Architecture: ARM
  Load Address: 0x23210000
  Hash algo:    crc32
  Hash value:   b10b382d
  Hash algo:    sha1
  Hash value:   c931565bea5ffb956676b7d4445403defad3bbd7
 Default Configuration: 'kernel_dtb'
 Configuration 0 (kernel_dtb)
  Description:  Linux kernel and base FDT blob for SAMA5D27_WLSOM1_EK board
  Kernel:       kernel
  FDT:          base_fdt
 Configuration 1 (base_dtb)
  Description:  FDT blob for base SAMA5D27_WLSOM1_EK board
  Kernel:       unavailable
  FDT:          base_fdt
 Configuration 2 (isc)
  Description:  FDT overlay blob for isc
  Kernel:       unavailable
  FDT:          fdt_isc
 Configuration 3 (ov7670)
  Description:  FDT overlay blob for ov7670 sensor
  Kernel:       unavailable
  FDT:          fdt_ov7670
 Configuration 4 (ov7740)
  Description:  FDT overlay blob for ov7740 sensor
  Kernel:       unavailable
  FDT:          fdt_ov7740
 Configuration 5 (ov5640)
  Description:  FDT overlay blob for ov5640 sensor
  Kernel:       unavailable
  FDT:          fdt_ov5640
 Configuration 6 (mt9v022)
  Description:  FDT overlay blob for mt9v022 sensor
  Kernel:       unavailable
  FDT:          fdt_mt9v022
 Configuration 7 (pda4)
  Description:  FDT overlay blob for PDA TM4300 screen
  Kernel:       unavailable
  FDT:          fdt_pda4
 Configuration 8 (pda5)
  Description:  FDT overlay blob for PDA TM5000 screen
  Kernel:       unavailable
  FDT:          fdt_pda5
 Configuration 9 (pda7)
  Description:  FDT overlay blob for PDA TM7000 screen
  Kernel:       unavailable
  FDT:          fdt_pda7
 Configuration 10 (pda7b)
  Description:  FDT overlay blob for PDA TM7000B screen
  Kernel:       unavailable
  FDT:          fdt_pda7b
 Configuration 11 (ptc)
  Description:  FDT overlay blob for PTC
  Kernel:       unavailable
  FDT:          fdt_ptc
 Configuration 12 (spi_click1)
  Description:  FDT overlay blob for at25ff321a spi flash clickboard (1)
  Kernel:       unavailable
  FDT:          fdt_spi_click1


   

The following example shows how to build a FIT image for SAM9X60 Curiosity board using the KERNEL_DIR and KERNEL_BUILD_DIR environment variables that are handled by the dt-overlay-mchp Makefile. This allows you to precisely specify where the kernel source tree is and where the resulting of your compilation of this kernel is located. It allows the Makefile to find the Device Tree Compiler (dtc), the kernel image (zImage) and the device tree for the board (.dtb). This brings a lot of flexibility to the process of creating a FIT image.
Note that environment variables ARCH and CROSS_COMPILE are set to their adapted values on this example system. CROSS_COMPILE variable in particular must be adapted to your own development host.

   $ KERNEL_DIR=/<path_to_kernel_sources> KERNEL_BUILD_DIR=/<path_to_kernel_build_dir> make ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- sam9x60_curiosity.itb
    ....
mkimage -D "-i../linux/arch/arm/boot/ -i../linux/arch/arm/boot/dts -i../linux/arch/arm/boot/dts/microchip -p 1000 -@ -Wno-unit_address_vs_reg -Wno-graph_child_address -Wno-pwms_property" -f sam9x60_curiosity.its sam9x60_curiosity.itb
FIT description: Microchip SAM9X60-Curiosity FIT Image
Created:         Fri Dec 15 16:56:09 2023
 Image 0 (kernel)
  Description:  Linux4SAM Linux kernel
  Created:      Fri Dec 15 16:56:09 2023
  Type:         Kernel Image
  Compression:  uncompressed
  Data Size:    5085776 Bytes = 4966.58 KiB = 4.85 MiB
  Architecture: ARM
  OS:           Linux
  Load Address: 0x22000000
  Entry Point:  0x22000000
  Hash algo:    crc32
  Hash value:   b4605b21
  Hash algo:    sha1
  Hash value:   3fb3bc54556929d38ef1b5905acdc6029989969c
 Image 1 (base_fdt)
  Description:  SAM9X60-Curiosity Flattened Device Tree blob
  Created:      Fri Dec 15 16:56:09 2023
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    37085 Bytes = 36.22 KiB = 0.04 MiB
  Architecture: ARM
  Load Address: 0x23000000
  Hash algo:    crc32
  Hash value:   3d4ee4bc
  Hash algo:    sha1
  Hash value:   d0788bdb30f321cbfc78c8ab58510225a1e2501b
 Image 2 (fdt_pda5)
  Description:  Device Tree blob pda5000 overlay
  Created:      Fri Dec 15 16:56:09 2023
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    4772 Bytes = 4.66 KiB = 0.00 MiB
  Architecture: ARM
  Load Address: 0x23100000
  Hash algo:    crc32
  Hash value:   9b565bfe
  Hash algo:    sha1
  Hash value:   c425668b2bc897fa83e867a0dea13547bb393a96
 Image 3 (fdt_wilc3000)
  Description:  Device Tree blob WILC3000 overlay
  Created:      Fri Dec 15 16:56:09 2023
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    1534 Bytes = 1.50 KiB = 0.00 MiB
  Architecture: ARM
  Load Address: 0x23110000
  Hash algo:    crc32
  Hash value:   8294b75c
  Hash algo:    sha1
  Hash value:   86494722c92f978610dbbc96cc5a07a3804cf6bf
 Default Configuration: 'kernel_dtb'
 Configuration 0 (kernel_dtb)
  Description:  Linux kernel and base FDT blob for SAM9X60-Curiosity board
  Kernel:       kernel
  FDT:          base_fdt
 Configuration 1 (base_dtb)
  Description:  Base FDT blob for SAM9X60-Curiosity board
  Kernel:       unavailable
  FDT:          base_fdt
 Configuration 2 (pda5)
  Description:  FDT overlay blob for PDA TM5000 screen
  Kernel:       unavailable
  FDT:          fdt_pda5
 Configuration 3 (wilc)
  Description:  FDT overlay blob for WILC3000
  Kernel:       unavailable
  FDT:          fdt_wilc3000


Loading FIT image in u-boot

The FIT image is a placeholder that has the zImage and the base Device Tree, plus additional overlays that can be selected at boot time.

The following steps are required to boot the FIT Image from U-boot:

  • Load the FIT image like you would normally load the uImage or zImage.
  • There is no need to load additional Device Tree Blob, the FIT image includes it
  • When booting the FIT image, specify the FIT configuration to use. Several configurations can be appended to the basic configuration, which we name 'kernel_dtb'

Warning, important U-boot 2021.04 and newer cannot load FIT images created before linux4sam_2021.04. This is due to an incompatible change in the FIT image configuration check in U-boot.

Example:

bootm 0x24000000#kernel_dtb

This will load the FIT image from address 0x24000000 in memory and then run the configuration named 'kernel_dtb'. This configuration includes the kernel plus the base Device Tree Blob built with the kernel.

To load additional FIT configurations, just append another configuration to the command.

Example to load the image sensor controller Device Tree overlay + sensor omnivision 0v7740:

bootm 0x24000000#kernel_dtb#isc#ov7740

Changes in dt-overlay-mchp

  • Support for all major PDAs: PDA 5000, PDA 4300, PDA 7000, PDA 7000B
  • Camera sensors support for SAM5D2: OV7740, OV7670

Tags

linux4microchip-2023.10

  • Include all features in linux4microchip-2023.10

linux4microchip-2023.04

  • Include all features in linux4microchip-2023.04

linux4microchip-2022.10

  • Include all features in linux4microchip-2022.10

linux4sam-2022.04

  • Include all features in linux4sam-2022.04

linux4sam-2021.04

  • Include all features in linux4sam-2021.04

linux4sam-2020.10

  • Include all features in linux4sam-2020.10

linux4sam-2020.04

  • Include all features in linux4sam-2020.04

linux4sam_6.2 tag

  • Include all features in linux4sam_6.2

linux4sam_6.1 tag

  • Include all features in linux4sam_6.1

linux4sam_6.0 tag

  • Include all features in linux4sam_6.0

Recent FAQ

r9 - 15 Dec 2023 - 15:08:02 - AndreiSimion
 
Linux & Open Source for AT91 Microchip Microprocessors

Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.

Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.

Microchip® and others, are registered trademarks or trademarks of Microchip Technology Inc. and its subsidiaries. This site is powered by the TWiki collaboration platform

Arm® and others are registered trademarks or trademarks of Arm Limited (or its affiliates). Other terms and product names may be trademarks of others.

Ideas, requests, contributions ? Connect to LinksToCommunities page.

Syndicate this siteRSS ATOM