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
Linux4SAM GitHub DT Overlays repository
:
- clone the Linux4sam GitHub DT Overlay repository
$ git clone https://github.com/linux4sam/dt-overlay-at91.git
Cloning into 'dt-overlay-at91'...
remote: Enumerating objects: 1140, done.
remote: Counting objects: 100% (137/137), done.
remote: Compressing objects: 100% (87/87), done.
remote: Total 1140 (delta 89), reused 92 (delta 49), pack-reused 1003
Receiving objects: 100% (1140/1140), 446.43 KiB | 896.00 KiB/s, done.
Resolving deltas: 100% (595/595), done.
$ cd dt-overlay-at91/
- 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 sama5d2_xplained:
$ make sama5d2_xplained_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 sama5d2_xplained:
$ make sama5d2_xplained.itb
....
FIT description: Microchip SAMA5D2 Xplained FIT Image
Created: Tue Nov 6 14:35:36 2018
Image 0 (kernel)
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
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)
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
FDT: sam9x60ek_fdt
Configuration 1 (base_dtb)
Description: Base FDT blob for SAM9X60-EK board
Kernel: unavailable
FDT: sam9x60ek_fdt
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
- 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