Differences

This shows you the differences between two versions of the page.

--- products:sbc:common:configurations:device-tree-overlay [2022/09/05 02:53]
nick [Table]
+++ products:sbc:common:configurations:device-tree-overlay [2023/11/07 04:18] (current)
nick
@@ Line 1: / Line 1: @@
 ====== Device Tree Overlay ======
-===== Introduction =====
+We can use DT overlays to enable/disable or change configuration for peripherals without recompiling the DT kernel source code.
-You can use Device Tree Overlay to enable or disable the peripherals without recompiling the kernel source code.
+===== DT collections  =====
-^         ^  DT Overlays Directory                                 ^  DT Overlays Node  ^  DT Overlays Configuration File                           ^
+https://github.com/khadas/khadas-linux-kernel-dt-overlays
-^  VIM1   |  /boot/dtb/overlays/kvim                               |  overlays          |  /boot/env.txt                                            |
-^  VIM2   |  /boot/dtb/overlays/kvim2                              | :::                | :::                                                       |
-^  VIM3   |  /boot/dtb/overlays/kvim3                              | :::                | :::                                                       |
-^  VIM3L  |  /boot/dtb/overlays/kvim3l                             | :::                | :::                                                       |
-^  VIM1S  |  /boot/dtb/amlogic/kvim1s.dtb.overlays                 |  fdt_overlays      |  /boot/dtb/amlogic/kvim1s.dtb.overlay.env                 |
-^  VIM4   |  /boot/dtb/amlogic/kvim4.dtb.overlays                  | :::                |  /boot/dtb/amlogic/kvim4.dtb.overlay.env                  |
-^  Edge2  |  /boot/dtb/rockchip/rk3588s-khadas-edge2.dtb.overlays  |  fdt_overlays      |  /boot/dtb/rockchip/rk3588s-khadas-edge2.dtb.overlay.env  |
-^  Edge1  |  /boot/dtb/rockchip/overlays/caption                   |  overlays          |  /boot/env.txt                                            |
-| :::     |  /boot/dtb/rockchip/overlays/edgev                     | :::                | :::                                                       |
-<tabbox VIM1/2/3/3L/Edge1>
+===== Device Reference Table ======
-<WRAP tip >
+^         ^  Kernel Version  ^  DT overlays folder                                    ^  DT overlays list variable  ^  DT overlays config file                                  ^
-This page takes VIM3 as an example, which can be different from yours but the structure is the same.
+^  VIM1   |  4.9/mainline    |  /boot/dtb/overlays/kvim                               |  overlays                   |  /boot/env.txt                                            |
-</WRAP>
+^  VIM2   |  4.9/mainline    |  /boot/dtb/overlays/kvim2                              | :::                         | :::                                                       |
+^  VIM3   |  4.9/mainline    |  /boot/dtb/overlays/kvim3                              | :::                         | :::                                                       |
+| :::     |  5.15            |  /boot/dtb/amlogic/kvim3.dtb.overlays                  |  fdt_overlays               |  /boot/dtb/amlogic/kvim3l.dtb.overlay.env                 |
+^  VIM3L  |  4.9/mainline    |  /boot/dtb/overlays/kvim3l                             |  overlays                   |  /boot/env.txt                                            |
+| :::     |  5.15            |  /boot/dtb/amlogic/kvim3l.dtb.overlays                 |  fdt_overlays               |  /boot/dtb/amlogic/kvim3l.dtb.overlay.env                 |
+^  VIM1S  |  5.4/5.15        |  /boot/dtb/amlogic/kvim1s.dtb.overlays                 | :::                         |  /boot/dtb/amlogic/kvim1s.dtb.overlay.env                 |
+^  VIM4   |  5.4/5.15        |  /boot/dtb/amlogic/kvim4.dtb.overlays                  | :::                         |  /boot/dtb/amlogic/kvim4.dtb.overlay.env                  |
+^  Edge2  |  5.10            |  /boot/dtb/rockchip/rk3588s-khadas-edge2.dtb.overlays  | :::                         |  /boot/dtb/rockchip/rk3588s-khadas-edge2.dtb.overlay.env  |
+^  Edge1  |  4.4             |  /boot/dtb/rockchip/overlays/captain                   |  overlays                   |  /boot/env.txt                                            |
+| :::     | :::              |  /boot/dtb/rockchip/overlays/edgev                     | :::                         | :::                                                       |
+===== Device Configurations =====
-The dtbo files are stored in directory ''/boot/dtb/overlays/#BOARD#'':
+<tabbox VIM1/2/3/3L/Edge1>
-```txt
+DT-overlays ''dtbo'' directory: ''/boot/dtb/overlays/**BOARD**''
-khadas@Khadas:~$ ll /boot/dtb/overlays/kvim3
-total 40
-drwxr-xr-x 2 root root 4096 Jan 29 11:13 ./
-drwxr-xr-x 6 root root 4096 Jan 29 11:13 ../
--rw-r--r-- 1 root root  352 Jan 29 09:35 disable-ts050.dtbo
--rw-r--r-- 1 root root  223 Jan 29 09:35 i2c3.dtbo
--rw-r--r-- 1 root root  277 Jan 29 09:35 m2x-eth.dtbo
--rw-r--r-- 1 root root  472 Jan 29 09:35 onewire.dtbo
--rw-r--r-- 1 root root 1072 Jan 29 09:35 os08a10.dtbo
--rw-r--r-- 1 root root  345 Jan 29 09:35 pwm_f.dtbo
--rw-r--r-- 1 root root  447 Jan 29 09:35 spi1.dtbo
--rw-r--r-- 1 root root  225 Jan 29 09:35 uart3.dtbo
-```
 <WRAP important >
-**#BOARD#** should be ''vim1'', ''vim2'', ''vim3'', ''vim3l'' or ''edge''.
+**BOARD** should be ''kvim1'', ''kvim2'', ''kvim3'', ''kvim3l'' or ''edgev''.
 </WRAP>
-The releated dtbo configuration file is ''/boot/env.txt''.
+<WRAP tip >
+Next example for VIM3 device, which can be different for other device, but the structure is the same.
+</WRAP>
 ```shell
+khadas@Khadas:~$ ls -1 /boot/dtb/overlays/kvim3/
+disable-ts050.dtbo
+i2c3.dtbo
+m2x-eth.dtbo
+onewire.dtbo
+os08a10.dtbo
+pwm_f.dtbo
+spi1.dtbo
+uart3.dtbo
+```
+DT-overlays configuration file:
+```txt /boot/env.txt
 # Device Tree Overlays
 #   uart3           -- Enable UART3 (uart_C, GPIO Header PIN15 & PIN16)
@@ Line 61: / Line 64: @@
 ```
-''uart3 pwm_f i2c3 os08a10'' are enabled by default.
+  * default ''overlays'' list variable value: ''uart3 pwm_f i2c3 os08a10''
+  * If you want to disable ''pwm_f'' you can remove ''pwm_f'' from ''overlays'' list variable
+  * If you want to enable ''onewire'', you can add ''onewire'' to ''overlays'' list variable
-  * If you want to disable ''pwm_f'' you can remove ''pwm_f'' in ''overlays'' node.
+<tabbox VIM3 with 5.15 kernel>
-  * If you want to enable ''onewire'', you can add ''onewire'' to ''overlays'' node.
+DT-overlays ''dtbo'' directory: ''/boot/dtb/amlogic/kvim3.dtb.overlays''.
-<tabbox VIM4>
+```shell
+khadas@Khadas:~$ ls -1 /boot/dtb/amlogic/kvim3.dtb.overlays/
+uart3.dtbo
+pwm_f.dtbo
+i2c3.dtbo
+spi1.dtbo
+os08a10.dtbo
+onewire.dtbo
+disable-ts050.dtbo
+m2x-eth.dtbo
+otg-device.dtbo
+```
-The dtbo files are stored in directory ''/boot/dtb/amlogic/kvim4.dtb.overlays'':
+DT-overlays configuration file: ''/boot/dtb/amlogic/kvim3.dtb.overlay.env''.
+<tabbox VIM3L with 5.15 kernel>
+DT-overlays ''dtbo'' directory: ''/boot/dtb/amlogic/kvim3l.dtb.overlays''.
+```shell
+khadas@Khadas:~$ ls -1 /boot/dtb/amlogic/kvim3.dtb.overlays/
+uart3.dtbo
+pwm_f.dtbo
+i2c3.dtbo
+spi1.dtbo
+os08a10.dtbo
+onewire.dtbo
+disable-ts050.dtbo
+m2x-eth.dtbo
+otg-device.dtbo
 ```
-khadas@Khadas:~$ ls -al /boot/dtb/amlogic/kvim4.dtb.overlays/
-total 28
+DT-overlays configuration file: ''/boot/dtb/amlogic/kvim3l.dtb.overlay.env''.
-drwxr-xr-x 2 root root 4096 Jul  6 14:55 .
-drwxr-xr-x 3 root root 4096 Jul  6 14:55 ..
+<tabbox VIM4>
--rwxr-xr-x 1 root root  462 Jul  6 14:55 ext_board.dtbo
--rwxr-xr-x 1 root root  223 Jul  6 14:55 i2cm_a.dtbo
+DT-overlays ''dtbo'' directory: ''/boot/dtb/amlogic/kvim4.dtb.overlays''.
--rwxr-xr-x 1 root root  223 Jul  6 14:55 i2cm_f.dtbo
--rwxr-xr-x 1 root root  225 Jul  6 14:55 pwm_f.dtbo
+```shell
--rwxr-xr-x 1 root root  225 Jul  6 14:55 uart_e.dtbo
+khadas@Khadas:~$ ls -1 /boot/dtb/amlogic/kvim4.dtb.overlays/
+ext_board.dtbo
+i2cm_a.dtbo
+i2cm_f.dtbo
+pwm_f.dtbo
+uart_e.dtbo
 ```
-The releated dtbo configuration file is ''/boot/dtb/amlogic/kvim4.dtb.overlay.env''.
+DT-overlays configuration file: ''/boot/dtb/amlogic/kvim4.dtb.overlay.env''.
 <tabbox VIM1S>
-The dtbo files are stored in directory ''/boot/dtb/amlogic/kvim1s.dtb.overlays'':
+DT-overlays ''dtbo'' directory: ''/boot/dtb/amlogic/kvim1s.dtb.overlays''
+```shell
+khadas@Khadas:~$ ls -1 /boot/dtb/amlogic/kvim1s.dtb.overlays/
+i2cm_b.dtbo
+i2cm_e.dtbo
+pwm_f.dtbo
+uart_c.dtbo
 ```
-khadas@Khadas:~$ ls -al /boot/dtb/amlogic/kvim1s.dtb.overlays/
+DT-overlays configuration file is ''/boot/dtb/amlogic/kvim1s.dtb.overlay.env''.
-total 28
-drwxrwxr-x 2 root root 4096 Aug 19 09:21 ./
-drwxr-xr-x 3 root root 4096 Aug 19 09:21 ../
--rw-rw-r-- 1 root root  223 Aug 12 10:59 i2cm_b.dtbo
--rw-rw-r-- 1 root root  223 Aug 12 10:59 i2cm_e.dtbo
--rw-rw-r-- 1 root root  345 Aug 12 10:59 pwm_f.dtbo
--rw-rw-r-- 1 root root  225 Aug 12 10:59 uart_c.dtbo
-```
-The releated dtbo configuration file is ''/boot/dtb/amlogic/kvim1s.dtb.overlay.env''.
+<tabbox Edge2>
+DT-overlays ''dtbo'' directory: ''/boot/dtb/rockchip/rk3588s-khadas-edge2.dtb.overlays''
+```shell
+khadas@Khadas:~$ ls /boot/dtb/rockchip/rk3588s-khadas-edge2.dtb.overlays
+mipi-panel.dtbo
+```
+DT-overlays configuration file: ''/boot/dtb/rockchip/rk3588s-khadas-edge2.dtb.overlay.env''
 </tabbox>
-===== Configuration =====
+===== Configuration DT Overlays =====
-If you want to enable the peripherals, you can edit the dtbo configuration file and add the dtbo name to the node.
+You need to edit the DT overlays configuration file and add custom DT overlays ''dtbo'' files to special folder.
+===== Make custom DT Overlays =====
-===== Make Your Own DTBO Files =====
+There are some preparations steps for DT overlays ''dtbo'' files, you can also add custom DT overlays.
-There are some preparations using dtbo files, you can also add your own dtbos to enable or disable the peripherals.
+==== Write DT Overlay Source====
+Basic  DT overlay source example:
-  * Write your own Device Tree Overlay file, for example: ```dts overlay_example.dts
+```dts example.dts
 /dts-v1/;
 /plugin/;
@@ Line 130: / Line 174: @@
 ```
-  * Compile it to dtbo ```shell
+==== Compile DT Overlay Source ====
-khadas@Khadas:~$ dtc -I dts -O dtb -o example.dtbo example.dts
-khadas@Khadas:~$ ls example.dtbo
+```sh
-example.dtbo
+dtc -I dts -O dtb -o example.dtbo example.dts
 ```
-  * Copy the dtbo file to dtbo directory
+==== Copy DT Overlays to Special Folder ====
-    * VIM1/2/3/3L/Edge1 is ''/boot/dtb/overlays/#BOARD#'' <WRAP important >
-**#BOARD#** should be ''vim1'', ''vim2'', ''vim3'', ''vim3l'' or ''edge''.
+  * VIM3 with 5.15 kernel is ''/boot/dtb/amlogic/kvim3.dtb.overlays''
+  * VIM3L with 5.15 kernel is ''/boot/dtb/amlogic/kvim3l.dtb.overlays''
+  * VIM4 is ''/boot/dtb/amlogic/kvim4.dtb.overlays''
+  * VIM1S is ''/boot/dtb/amlogic/kvim1s.dtb.overlays''
+  * Edge2 is ''/boot/dtb/rockchip/rk3588s-khadas-edge2.dtb.overlays''
+  * VIM1/2/3/3L/Edge1 is ''/boot/dtb/overlays/%%*%%*BOARD%%*%%*''
+<WRAP important >
+**BOARD** should be ''kvim1'', ''kvim2'', ''kvim3'', ''kvim3l'' or ''edgev''.
 </WRAP>
-    * VIM4 is ''/boot/dtb/amlogic/kvim4.dtb.overlays/''
-    * VIM1S is ''/boot/dtb/amlogic/kvim1s.dtb.overlays/''
+==== Edit DT Overlays Configuration ====
+Edit list variable value inside DT overlay configuration file:
+  * VIM1/2/3/3L/Edge1 is ''/boot/env.txt''
+  * VIM3 with 5.15 kernel is ''/boot/dtb/amlogic/kvim3.dtb.overlay.env''
+  * VIM3L with 5.15 kernel is ''/boot/dtb/amlogic/kvim3l.dtb.overlay.env''
+  * VIM4 is ''/boot/dtb/amlogic/kvim4.dtb.overlay.env''
+  * VIM1S is ''/boot/dtb/amlogic/kvim4.dtb.overlay.env''
+  * Edge2 is ''/boot/dtb/rockchip/rk3588s-khadas-edge2.dtb.overlay.env''
-  * Edit dtbo configuration file and add ''example'' to the node
+==== Reboot ====
-    * VIM1/2/3/3L/Edge1 is ''/boot/env.txt''
-    * VIM4 is ''/boot/dtb/amlogic/kvim4.dtb.overlay.env''
-    * VIM1S is ''/boot/dtb/amlogic/kvim4.dtb.overlay.env''
-  * Reboot the board
+Need reboot board to take effect.

Khadas Docs

User Tools

Site Tools

Differences

Page Tools