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 sam9x75_curiosity_dtbos:

   $ make sam9x75_curiosity_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 sam9x75_curiosity.itb
    ....
FIT description: Microchip SAM9X75-Curiosity FIT Image
Created:         Thu May 16 15:14:43 2024
 Image 0 (kernel)
  Description:  Linux4SAM Linux kernel
  Created:      Thu May 16 15:14:43 2024
  Type:         Kernel Image
  Compression:  uncompressed
  Data Size:    5221704 Bytes = 5099.32 KiB = 4.98 MiB
  Architecture: ARM
  OS:           Linux
  Load Address: 0x22000000
  Entry Point:  0x22000000
  Hash algo:    crc32
  Hash value:   9778d68b
  Hash algo:    sha1
  Hash value:   1c5dc50a13f1b6d18787ebdbbbcde67b069f10e3
 Image 1 (base_fdt)
  Description:  SAM9X75-Curiosity Flattened Device Tree blob
  Created:      Thu May 16 15:14:43 2024
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    28755 Bytes = 28.08 KiB = 0.03 MiB
  Architecture: ARM
  Load Address: 0x23000000
  Hash algo:    crc32
  Hash value:   d35678b4
  Hash algo:    sha1
  Hash value:   2598efa5e36ccc3defdae2c0de86f416c9c088f7
 Image 2 (fdt_isc_imx219)
  Description:  Device Tree blob ISC IMX219 overlay
  Created:      Thu May 16 15:14:43 2024
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    4126 Bytes = 4.03 KiB = 0.00 MiB
  Architecture: ARM
  Load Address: 0x23100000
  Hash algo:    crc32
  Hash value:   d8fd34cf
  Hash algo:    sha1
  Hash value:   75ff92b00dc8d9466fe07789822127ee5d225640
 Image 3 (fdt_lvds_panel)
  Description:  Device Tree blob for AC69T88A LVDS Display Panel
  Created:      Thu May 16 15:14:43 2024
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    3946 Bytes = 3.85 KiB = 0.00 MiB
  Architecture: ARM
  Load Address: 0x23110000
  Hash algo:    crc32
  Hash value:   f2aca13d
  Hash algo:    sha1
  Hash value:   cceb96efe1621f3ad6427d6cdf8f4e2702aacb00
 Image 4 (fdt_gmac_lan8840)
  Description:  Device Tree blob for LAN8840 RGMII PHY overlay
  Created:      Thu May 16 15:14:43 2024
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    2168 Bytes = 2.12 KiB = 0.00 MiB
  Architecture: ARM
  Load Address: 0x23120000
  Hash algo:    crc32
  Hash value:   44e2f96d
  Hash algo:    sha1
  Hash value:   8879cb8f80cc87d5ed53af5bae11a4cc9f1ddc41
 Image 5 (fdt_i2s_proto)
  Description:  Device Tree blob PROTO Audio board overlay
  Created:      Thu May 16 15:14:43 2024
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    1666 Bytes = 1.63 KiB = 0.00 MiB
  Architecture: ARM
  Load Address: 0x23130000
  Hash algo:    crc32
  Hash value:   df39dc8b
  Hash algo:    sha1
  Hash value:   1c7c335aad79d82d3482b3d9da7fbbcd4bf98ee4
 Default Configuration: 'kernel_dtb'
 Configuration 0 (kernel_dtb)
  Description:  Linux kernel and base FDT blob for SAM9X75-Curiosity board
  Kernel:       kernel
  FDT:          base_fdt
 Configuration 1 (base_dtb)
  Description:  Base FDT blob for SAM9X75-Curiosity board
  Kernel:       unavailable
  FDT:          base_fdt
 Configuration 2 (imx219)
  Description:  FDT overlay blob for ISC IMX219 sensor
  Kernel:       unavailable
  FDT:          fdt_isc_imx219
 Configuration 3 (lvds)
  Description:  FDT overlay blob for AC69T88A LVDS Display Panel
  Kernel:       unavailable
  FDT:          fdt_lvds_panel
 Configuration 4 (lan8840)
  Description:  FDT overlay blob for LAN8840 RGMII PHY Daughter Card
  Kernel:       unavailable
  FDT:          fdt_gmac_lan8840
 Configuration 5 (i2s_proto)
  Description:  FDT overlay blob for I2S PROTO audio board
  Kernel:       unavailable
  FDT:          fdt_i2s_proto

   

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:         Thu May 16 15:16:13 2024
 Image 0 (kernel)
  Description:  Linux4SAM Linux kernel
  Created:      Thu May 16 15:16:13 2024
  Type:         Kernel Image
  Compression:  uncompressed
  Data Size:    5221704 Bytes = 5099.32 KiB = 4.98 MiB
  Architecture: ARM
  OS:           Linux
  Load Address: 0x22000000
  Entry Point:  0x22000000
  Hash algo:    crc32
  Hash value:   9778d68b
  Hash algo:    sha1
  Hash value:   1c5dc50a13f1b6d18787ebdbbbcde67b069f10e3
 Image 1 (base_fdt)
  Description:  SAM9X60-Curiosity Flattened Device Tree blob
  Created:      Thu May 16 15:16:13 2024
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    36432 Bytes = 35.58 KiB = 0.03 MiB
  Architecture: ARM
  Load Address: 0x23000000
  Hash algo:    crc32
  Hash value:   a4558e6d
  Hash algo:    sha1
  Hash value:   b31d0eb8b22d9bc32c1751c8d9c01689d4ea0757
 Image 2 (fdt_pda5)
  Description:  Device Tree blob pda5000 overlay
  Created:      Thu May 16 15:16:13 2024
  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:      Thu May 16 15:16:13 2024
  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'

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
• MIPI camera sensor support for SAMA7G5 and SAM9x75: IMX219

Tags

linux4microchip-2024.04

• Include all features in linux4microchip-2024.04

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