Device Tree Overlay 적용 — Runtime fragment·dtoverlay

#한 줄 요약

“DT overlay는 base DTB에 fragment를 덮어쓰는 패치입니다.” I2C sensor 한 개를 추가하려고 base DT 전체를 재컴파일할 필요가 없습니다.

#어떤 상황에서 쓰나

같은 board에 옵션으로 LCD나 sensor를 다는 경우, 사용자가 GPIO에 외부 module을 꽂는 경우, 한 device family가 여러 변형(variant)을 가지는 경우 overlay가 답입니다. Base DTB는 board의 고정 구성만 담고, 옵션은 .dtbo 파일로 분리해 boot time에 선택합니다.

Raspberry Pi와 BeagleBone은 overlay 사용 사례가 잘 알려져 있습니다. 다른 SoC에서도 DT overlay를 지원할 수 있지만, bootloader·kernel·vendor tooling의 지원 범위를 확인해야 합니다.

#핵심 개념

overlay 한 장의 골격입니다.

1
/dts-v1/;
2
/plugin/;       /* overlay임을 선언 */
3

4
/ {
5
    fragment@0 {
6
        target = <&i2c1>;       /* base DT의 i2c1에 덮어쓰기 */
7
        __overlay__ {
8
            #address-cells = <1>;
9
            #size-cells = <0>;
10
            status = "okay";
11

12
            bme280@76 {
13
                compatible = "bosch,bme280";
14
                reg = <0x76>;
15
            };
16
        };
17
    };
18
};

base DT가 &i2c1 symbol을 export 했기에 overlay가 그 위치를 가리킬 수 있습니다.

#코드 / 실제 사용 예

#Base DT의 symbol 활성화

1
# kernel build 시
2
make dtbs DTC_FLAGS=-@
3
# 또는 CONFIG_DTC_PLUGINS_OUTPUT 활성

-@ 옵션이 __symbols__ 노드를 만들어 모든 label을 export합니다. overlay가 target을 phandle로 가리키려면 필수입니다.

#BME280 추가 overlay

1
/dts-v1/;
2
/plugin/;
3

4
/ {
5
    fragment@0 {
6
        target = <&i2c1>;
7
        __overlay__ {
8
            #address-cells = <1>;
9
            #size-cells = <0>;
10
            status = "okay";
11

12
            bme280@76 {
13
                compatible = "bosch,bme280";
14
                reg = <0x76>;
15
            };
16
        };
17
    };
18
};

1
dtc -@ -I dts -O dtb -o bme280.dtbo bme280-overlay.dts
2
sudo cp bme280.dtbo /boot/overlays/

#Raspberry Pi config.txt

1
dtoverlay=bme280
2
dtoverlay=spi1-3cs
3
dtoverlay=disable-bt
4
dtparam=i2c_arm=on

dtoverlay= 라인이 boot loader에게 overlay 적용을 지시합니다. dtparam=은 base DT가 노출한 parameter를 토글합니다.

#/proc/device-tree로 결과 확인

1
$ ls /proc/device-tree/soc/i2c@7e804000/
2
bme280@76  clocks  ...
3
$ cat /proc/device-tree/soc/i2c@7e804000/bme280@76/compatible
4
bosch,bme280

부팅 후 overlay가 적용되었는지 device-tree filesystem으로 확인할 수 있습니다.

#Runtime overlay (configfs)

1
# kernel CONFIG_OF_CONFIGFS=y 필요
2
sudo mkdir /sys/kernel/config/device-tree/overlays/bme
3
sudo cp bme280.dtbo /sys/kernel/config/device-tree/overlays/bme/dtbo
4
# device가 즉시 probe됨
5

6
# 제거
7
sudo rmdir /sys/kernel/config/device-tree/overlays/bme

부팅 후에도 overlay를 활성화할 수 있습니다. Hot-plug 시나리오에 유용하지만, 모든 driver가 cleanly remove를 지원하지는 않습니다.

#GPIO 핀 reassign overlay

1
fragment@0 {
2
    target = <&gpio>;
3
    __overlay__ {
4
        my_pins: my_pins {
5
            brcm,pins = <17 27>;
6
            brcm,function = <1 0>;   /* out, in */
7
        };
8
    };
9
};
10

11
fragment@1 {
12
    target-path = "/";    /* phandle 대신 path */
13
    __overlay__ {
14
        leds {
15
            compatible = "gpio-leds";
16
            heartbeat {
17
                gpios = <&gpio 17 0>;
18
                linux,default-trigger = "heartbeat";
19
            };
20
        };
21
    };
22
};

pin reassign과 새로운 노드 추가를 fragment 두 개로 표현합니다.

#Parameter 노출

1
/ {
2
    fragment@0 { ... };
3

4
    __overrides__ {
5
        addr = <&bme280>, "reg:0";    /* dtoverlay=bme280,addr=0x77 */
6
    };
7
};

__overrides__로 boot loader가 parameter를 주입할 수 있게 합니다. 같은 overlay를 변형해 쓰기 편해집니다.

#측정 / 성능 비교

Overlay 작업이 모두 증분 작업이기 때문에 개발 속도가 크게 향상됩니다.

1
RAM 영향
2
overlay 적용              DT 크기·kernel allocator에 따라 측정
3
device probe              driver·resource init에 따라 측정

#자주 보는 함정

__symbols__ 누락

1
dtc -I dts -O dtb ...        # -@ 없음
2
overlay 적용 → "target = <&i2c1>" resolve 실패

Base DT를 build할 때 반드시 -@을 줍니다. 또는 kernel build system에서 DTC_FLAGS=-@를 설정합니다.

Reg 충돌

1
bme280@76 { reg = <0x76>; };
2
bme280@76 { reg = <0x76>; };   /* 두 overlay가 같은 주소 — 둘 중 하나만 active */

같은 bus에 같은 reg를 두 overlay가 활성화하면 후자가 무시되거나 충돌이 발생합니다.

Driver compatible 불일치

1
compatible = "bosch,bmp280";    /* sensor는 bme280인데 잘못 적음 */

probe가 silently 실패합니다. dmesg | grep -i bme로 driver match 여부를 확인합니다.

Pin function이 base DT와 충돌

1
target = <&gpio>;
2
__overlay__ {
3
    brcm,pins = <14 15>;   /* UART pin을 GPIO로 빼앗음 → console 사라짐 */
4
};

GPIO나 pinmux를 건드리는 overlay는 console과 같은 critical 자원을 빼앗지 않는지 확인합니다.

Runtime overlay remove 시 driver leak

1
rmdir /sys/kernel/config/device-tree/overlays/bme
2
[  ...] WARNING: leaking irq

일부 driver는 remove에서 자원을 cleanup하지 못합니다. Production에서는 가급적 boot time overlay만 사용합니다.

#정리

• DT overlay는 base DTB에 fragment 단위로 덮어쓰는 patch입니다.
• Base DT는 반드시 -@로 build해 __symbols__를 export해야 합니다.
• Raspberry Pi의 dtoverlay=, configfs runtime overlay 두 방식이 표준입니다.
• 한 base DT에 여러 변형(variant) board를 둘 때 가장 깔끔한 해결책입니다.
• __overrides__로 parameter를 노출하면 overlay 한 장으로 여러 device를 다룰 수 있습니다.
• Runtime overlay는 driver의 cleanly remove 지원 여부를 확인 후 사용합니다.

다음 편은 커널 빌드입니다. defconfig, menuconfig, out-of-tree, packaging까지 다룹니다.

#관련 항목

• 7-01: 임베디드 Linux 부팅 흐름
• 7-02: U-Boot 활용
• 7-05: 커널 빌드
• 7-06: Kernel Module
• 7-08: Platform 드라이버