====== Device Tree Overlay ====== We can use DT overlays to enable/disable or change configuration for peripherals without recompiling the DT kernel source code. ===== DT collections ===== https://github.com/khadas/khadas-linux-kernel-dt-overlays ===== Device Reference Table ====== ^ ^ Kernel Version ^ DT overlays folder ^ DT overlays list variable ^ DT overlays config file ^ ^ VIM1 | 4.9/mainline | /boot/dtb/overlays/kvim | overlays | /boot/env.txt | ^ 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 ===== DT-overlays ''dtbo'' directory: ''/boot/dtb/overlays/**BOARD**'' **BOARD** should be ''kvim1'', ''kvim2'', ''kvim3'', ''kvim3l'' or ''edgev''. Next example for VIM3 device, which can be different for other device, but the structure is the same. ```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) # pwm_f -- Enable PWM_F (GPIO Header PIN35) # i2c3 -- Enable i2c3 (GPIO Header PIN22 & PIN23) # spi1 -- Enable SPI1 (GPIO Header PIN15 & PIN16 & PIN35 & PIN37), pwm_f need to be removed # os08a10 -- Enable OS08A10 Camera # onewire -- Enable onewire bus (PIO Header PIN15) # disable-ts050 -- Disable TS050 LCD # m2x-eth -- Enable M2X 100M ethernet. Note: 1G ethernet will be disabled. # otg-device -- Enable USB OTG Device overlays=uart3 pwm_f i2c3 os08a10 ``` * 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 DT-overlays ''dtbo'' directory: ''/boot/dtb/amlogic/kvim3.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 ``` DT-overlays configuration file: ''/boot/dtb/amlogic/kvim3.dtb.overlay.env''. 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 ``` DT-overlays configuration file: ''/boot/dtb/amlogic/kvim3l.dtb.overlay.env''. DT-overlays ''dtbo'' directory: ''/boot/dtb/amlogic/kvim4.dtb.overlays''. ```shell 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 ``` DT-overlays configuration file: ''/boot/dtb/amlogic/kvim4.dtb.overlay.env''. 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 ``` DT-overlays configuration file is ''/boot/dtb/amlogic/kvim1s.dtb.overlay.env''. 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'' ===== Configuration DT Overlays ===== You need to edit the DT overlays configuration file and add custom DT overlays ''dtbo'' files to special folder. ===== Make custom DT Overlays ===== There are some preparations steps for DT overlays ''dtbo'' files, you can also add custom DT overlays. ==== Write DT Overlay Source==== Basic DT overlay source example: ```dts example.dts /dts-v1/; /plugin/; / { fragment@0 { target = <&i2c3>; __overlay__ { status = "okay"; }; }; }; ``` ==== Compile DT Overlay Source ==== ```sh dtc -I dts -O dtb -o example.dtbo example.dts ``` ==== Copy DT Overlays to Special Folder ==== * 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%%*%%*'' **BOARD** should be ''kvim1'', ''kvim2'', ''kvim3'', ''kvim3l'' or ''edgev''. ==== 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'' ==== Reboot ==== Need reboot board to take effect.