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 Linux4SAM GitHub DT Overlays repository:

  • clone the Linux4sam GitHub DT Overlay repository
       $ git clone git://github.com/linux4sam/dt-overlay-at91.git
       Cloning into 'dt-overlay-at91'...
       remote: Enumerating objects: 760, done.
       remote: Counting objects: 100% (760/760), done.
       remote: Compressing objects: 100% (428/428), done.
       remote: Total 760 (delta 340), reused 735 (delta 315), pack-reused 0
       Receiving objects: 100% (760/760), 369.55 KiB | 1.23 MiB/s, done.
       Resolving deltas: 100% (340/340), done.
       $ cd dt-overlay-at91/
       

  • 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 sama5d2_xplained:

   $ make sama5d2_xplained_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 sama5d2_xplained:

   $ make sama5d2_xplained.itb
    ....
FIT description: Microchip SAMA5D2 Xplained FIT Image
Created:         Tue Nov  6 14:35:36 2018
 Image 0 (kernel@1)
  Description:  Linux4SAM Linux kernel
  Created:      Tue Nov  6 14:35:36 2018
  Type:         Kernel Image
  Compression:  uncompressed
  Data Size:    3922136 Bytes = 3830.21 kB = 3.74 MB
  Architecture: ARM
  OS:           Linux
  Load Address: 0x22000000
  Entry Point:  0x22000000
  Hash algo:    crc32
  Hash value:   b62def66
  Hash algo:    sha1
  Hash value:   16b86871561ac58f8e0ae1d2e532cc9cdfb559ba
 Image 1 (base_fdt)
  Description:  Flattened Device Tree blob
  Created:      Tue Nov  6 14:35:36 2018
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    44591 Bytes = 43.55 kB = 0.04 MB
  Architecture: ARM
  Hash algo:    crc32
  Hash value:   9c933a6d
  Hash algo:    sha1
  Hash value:   c249364df161f1158f084ab0191c034a519a9fdd
 Image 2 (fdt_isc)
  Description:  Device Tree blob ISC overlay
  Created:      Tue Nov  6 14:35:36 2018
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    1074 Bytes = 1.05 kB = 0.00 MB
  Architecture: ARM
  Hash algo:    crc32
  Hash value:   ea22f84e
  Hash algo:    sha1
  Hash value:   6feab4a58949dd88593c8aba3ad6d73d8124403f
 Image 3 (fdt_ov7670)
  Description:  Device Tree blob Ov7670 overlay
  Created:      Tue Nov  6 14:35:36 2018
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    2045 Bytes = 2.00 kB = 0.00 MB
  Architecture: ARM
  Hash algo:    crc32
  Hash value:   44c22b8b
  Hash algo:    sha1
  Hash value:   8e319fc07d00806b866bfe60b9b87849813ecefd
 Image 4 (fdt_ov7740)
  Description:  Device Tree blob OV7740 overlay
  Created:      Tue Nov  6 14:35:36 2018
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    2045 Bytes = 2.00 kB = 0.00 MB
  Architecture: ARM
  Hash algo:    crc32
  Hash value:   cc72f933
  Hash algo:    sha1
  Hash value:   3c44d90fe915d0e1fb63dfc50038fb0fc861b8a5
 Image 5 (fdt_pda4)
  Description:  Device Tree blob pda4300 overlay
  Created:      Tue Nov  6 14:35:36 2018
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    4499 Bytes = 4.39 kB = 0.00 MB
  Architecture: ARM
  Hash algo:    crc32
  Hash value:   c9b532e8
  Hash algo:    sha1
  Hash value:   a7f75ea4a91884840d40b379e7b843a95b9b9da4
 Image 6 (fdt_pda5)
  Description:  Device Tree blob pda5000 overlay
  Created:      Tue Nov  6 14:35:36 2018
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    4499 Bytes = 4.39 kB = 0.00 MB
  Architecture: ARM
  Hash algo:    crc32
  Hash value:   591d531b
  Hash algo:    sha1
  Hash value:   f9f3c25e8591f603492451b4e4eb369eba818ab2
 Image 7 (fdt_pda7)
  Description:  Device Tree blob pda7000 overlay
  Created:      Tue Nov  6 14:35:36 2018
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    4507 Bytes = 4.40 kB = 0.00 MB
  Architecture: ARM
  Hash algo:    crc32
  Hash value:   3fc0c1ec
  Hash algo:    sha1
  Hash value:   d202bd4cc83aef48b33fae2a1b104c5bc597956c
 Image 8 (fdt_pda7b)
  Description:  Device Tree blob pda7000b overlay
  Created:      Tue Nov  6 14:35:36 2018
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    4507 Bytes = 4.40 kB = 0.00 MB
  Architecture: ARM
  Hash algo:    crc32
  Hash value:   a27df839
  Hash algo:    sha1
  Hash value:   94f77b4afd7718cd309be34147c49753abf53375
 Image 9 (fdt_i2s0_proto)
  Description:  Device Tree blob PROTO Audio board overlay
  Created:      Tue Nov  6 14:35:36 2018
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    1066 Bytes = 1.04 kB = 0.00 MB
  Architecture: ARM
  Hash algo:    crc32
  Hash value:   38a511f6
  Hash algo:    sha1
  Hash value:   74d5c3996811a9307097969d8fe3c5e63b9973a0
 Image 10 (fdt_qspi)
  Description:  Device Tree blob QSPI overlay
  Created:      Tue Nov  6 14:35:36 2018
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    461 Bytes = 0.45 kB = 0.00 MB
  Architecture: ARM
  Hash algo:    crc32
  Hash value:   df13d1c0
  Hash algo:    sha1
  Hash value:   0abdc429d44d5f0fc7f97bea47e5c58308e8c5b1
 Default Configuration: 'kernel_dtb'
 Configuration 0 (kernel_dtb)
  Description:  Linux kernel and base FDT blob for SAMA5D2_XPLAINED board
  Kernel:       kernel@1
  FDT:          base_fdt
 Configuration 1 (base_dtb)
  Description:  Base FDT blob for SAMA5D2_XPLAINED 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 (pda4)
  Description:  FDT overlay blob for PDA TM4300 screen
  Kernel:       unavailable
  FDT:          fdt_pda4
 Configuration 6 (pda5)
  Description:  FDT overlay blob for PDA TM5000 screen
  Kernel:       unavailable
  FDT:          fdt_pda5
 Configuration 7 (pda7)
  Description:  FDT overlay blob for PDA TM7000 screen
  Kernel:       unavailable
  FDT:          fdt_pda7
 Configuration 8 (pda7b)
  Description:  FDT overlay blob for PDA TM7000B screen
  Kernel:       unavailable
  FDT:          fdt_pda7b
 Configuration 9 (i2s0_proto)
  Description:  FDT overlay blob for I2S0 PROTO audio board
  Kernel:       unavailable
  FDT:          fdt_i2s0_proto
 Configuration 10 (qspi)
  Description:  FDT overlay blob for QSPI memory
  Kernel:       unavailable
  FDT:          fdt_qspi

   

The following example shows how to build a FIT image for SAM9X60-EK board using the KERNEL_DIR and KERNEL_BUILD_DIR environment variables that are handled by the dt-overlay-at91 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.

   $ KERNEL_DIR=/<path_to_kernel_sources>/linux-git KERNEL_BUILD_DIR=/<path_to_kernel_build_dir>/build_9x60  mlx sam9x60ek.itb
    ....
mkimage -D "-i/work/nferre/linux-git/build_9x60/arch/arm/boot/ -i/work/nferre/linux-git/build_9x60/arch/arm/boot/dts -p 1000 -@ -Wno-unit_address_vs_reg -Wno-graph_child_address -Wno-pwms_property" -f sam9x60ek.its sam9x60ek.itb
FIT description: Microchip SAM9x60-EK FIT Image
Created:         Wed Dec 12 11:54:01 2018
 Image 0 (kernel@1)
  Description:  Linux4SAM Linux kernel
  Created:      Wed Dec 12 11:54:01 2018
  Type:         Kernel Image
  Compression:  uncompressed
  Data Size:    2690024 Bytes = 2626.98 kB = 2.57 MB
  Architecture: ARM
  OS:           Linux
  Load Address: 0x22000000
  Entry Point:  0x22000000
  Hash algo:    crc32
  Hash value:   2042bec6
  Hash algo:    sha1
  Hash value:   438f1c356d4535edff7637c0628cc960cf42e603
 Image 1 (sam9x60ek_fdt)
  Description:  SAM9X60-EK Flattened Device Tree blob
  Created:      Wed Dec 12 11:54:01 2018
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    40794 Bytes = 39.84 kB = 0.04 MB
  Architecture: ARM
  Hash algo:    crc32
  Hash value:   07c23b18
  Hash algo:    sha1
  Hash value:   f2216f83b895f3b3f4af99d1b14af28fbc01eb08
 Default Configuration: 'kernel_dtb'
 Configuration 0 (kernel_dtb)
  Description:  Linux kernel and base FDT blob for SAM9X60-EK board
  Kernel:       kernel@1
  FDT:          sam9x60ek_fdt
 Configuration 1 (base_dtb)
  Description:  Base FDT blob for SAM9X60-EK board
  Kernel:       unavailable
  FDT:          sam9x60ek_fdt

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'

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-at91

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

Tags

linux4sam_6.0 tag

  • Include all features in linux4sam_6.0

Recent FAQ