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
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.
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
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
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
- 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
- Include all features in
linux4microchip-2024.04
- Include all features in
linux4microchip-2023.10
- Include all features in
linux4microchip-2023.04
- Include all features in
linux4microchip-2022.10
- Include all features in
linux4sam-2022.04
- Include all features in
linux4sam-2021.04
- Include all features in
linux4sam-2020.10
- Include all features in
linux4sam-2020.04
- Include all features in
linux4sam_6.2
- Include all features in
linux4sam_6.1
- Include all features in
linux4sam_6.0
Recent FAQ