리눅스 Device Tree label과 overlay 기준 정리

본문 중간의 쿠팡 추천 상품 구매시 쿠팡 파트너스에서 일정액의 수수료를 제공받습니다.

리눅스 Device Tree label과 overlay 기준 정리

Device Tree에서 label은 보기 편한 별칭 정도로 오해되기 쉽지만, 실제로는 DTS 작성과 overlay 적용 위치를 안정적으로 지정할 때 자주 쓰이는 참조 기준이다. 2026년 5월 25일 기준 Devicetree Specification과 Linux 커널 문서를 보면, label은 소스 형식에서만 쓰이며 DTB 바이너리에 그대로 저장되는 이름은 아니다.

실무에서 헷갈리는 지점은 세 가지다. label이 정확히 어디에 붙는지, &label로 노드를 확장하는 것과 overlay에서 대상을 찾는 것이 같은 원리인지, 그리고 base DT와 overlay를 만들 때 무엇을 준비해야 하는지다. 이 글은 공식 명세와 커널 문서만 기준으로 그 차이를 정리한다.

Device Tree label은 정확히 무엇일까?

Devicetree Specification의 DTS 형식 문서는 label을 노드나 속성값에 붙일 수 있는 소스 레벨 식별자로 설명한다. label을 참조하면 명시적인 phandle 값이나 전체 경로를 직접 쓰지 않아도 참조를 만들 수 있다. 문서상 label은 1자 이상 31자 이하이며 숫자로 시작할 수 없고, 영문자와 숫자, 밑줄만 사용할 수 있다.

uart0: serial@12340000 {
    compatible = "vendor,soc-uart";
    reg = <0x12340000 0x1000>;
};

위 예시에서 uart0가 label이고, 이후 다른 위치에서 &uart0로 이 노드를 참조할 수 있다. 중요한 점은 이 이름이 사람이 읽는 편의 장치이면서 동시에 컴파일 단계에서 phandle 참조를 만드는 입력이라는 점이다.

label은 DTB에도 그대로 남을까?

명세는 label이 DTS source format에서만 사용되며 DTB binary에는 인코딩되지 않는다고 설명한다. 그래서 일반적인 base DTS만 컴파일한 결과물만 보고 label 문자열이 항상 남아 있다고 가정하면 안 된다.

다만 Linux 커널 overlay 문서는 base DT가 -@ 옵션으로 컴파일되지 않으면 &ocp 같은 label을 overlay 대상 해석에 쓸 수 없다고 설명한다. 즉 overlay 해석이 가능한 환경에서는 dtc가 별도의 symbol 정보를 만들어 두지만, 그것은 "label 문자열이 DTB 표준 본문에 그대로 저장된다"는 뜻과는 다르다.

&label로 노드를 확장하는 것은 무엇을 의미할까?

DTS에서는 이미 정의된 노드를 &label { ... }; 형식으로 다시 열어 속성이나 자식 노드를 추가할 수 있다. Linux 커널의 DTS coding style 문서도 보드 DTS에서 &label로 노드를 확장하는 패턴을 전제로 정렬 규칙을 설명한다.

이 문법은 기존 노드를 새 노드로 대체하는 것이 아니라, 그 노드에 대한 추가 정의를 병합하는 쪽에 가깝다. 그래서 SoC dtsi에서 기본 비활성으로 둔 장치를 보드 DTS에서 다시 열어 status = "okay";를 넣는 패턴이 널리 쓰인다.

&uart0 {
    current-speed = <115200>;
    status = "okay";
};

실무에서는 이것을 흔히 "오버라이드"라고 부르지만, DTS 소스 차원에서는 기존 노드를 label로 찾아 내용을 보강하거나 일부 속성을 갱신하는 방식으로 이해하는 편이 더 정확하다.

overlay에서 label은 왜 더 중요할까?

Linux 커널의 overlay 문서는 overlay가 라이브 Device Tree를 수정하는 용도라고 설명한다. 여기서 overlay는 base tree의 어느 위치에 조각을 붙일지 알아야 하는데, 문서는 label 기반 타깃 지정과 경로 기반 타깃 지정을 모두 보여준다.

/dts-v1/;
/plugin/;

&ocp {
    bar {
        compatible = "corp,bar";
    };
};

커널 문서 기준으로 label 기반 문법은 base DT 안에서 label이 어디에 있든 같은 의미로 대상을 찾을 수 있어서 경로보다 선호된다. 반대로 base DT가 -@ 옵션 없이 컴파일됐다면 label 해석이 불가능할 수 있으므로 &{/ocp} 같은 경로 타깃 문법이 대안이 된다.

overlay의 label 참조는 내부적으로 어떻게 풀릴까?

Linux 커널의 Dynamic Resolver 문서는 overlay 입력이 적절한 dtc 옵션과 /plugin/ 태그로 컴파일되면 __fixups__와 __local_fixups__ 정보가 생성된다고 설명한다. 그리고 resolver는 overlay의 __fixups__ 각 속성 이름을 라이브 트리의 symbol, 즉 label 이름과 매칭해 실제 phandle 값으로 치환한다.

Kernel API 문서도 overlay의 __fixups__ 속성 이름이 라이브 트리의 symbol(label)에 해당한다고 설명한다. 즉 overlay에서 &label을 쓴다는 것은 단순 문자열 검색이 아니라, 컴파일 단계에서 만들어진 symbol 정보를 바탕으로 phandle 참조를 다시 연결하는 절차에 가깝다.

 

 

base DTS와 overlay DTS에서 구분해서 볼 기준은 무엇일까?

base DTS나 dtsi에서는 다른 보드나 overlay가 안정적으로 참조해야 하는 핵심 노드에 일관된 label을 두는 편이 유지보수에 유리하다. 경로는 파일 구조나 버스 배치가 바뀌면 쉽게 흔들리지만, label은 의도한 참조 지점을 명시적으로 드러낸다.

overlay 쪽에서는 첫째, base DT가 label 해석이 가능하도록 준비됐는지, 둘째, 경로보다 label 타깃이 더 이식성 있는지, 셋째, 새로 추가하는 노드 안의 phandle 참조가 local fixup으로 안전하게 조정될 수 있는지를 함께 보는 편이 좋다.

label, alias, path는 어떻게 구분해야 할까?

label은 DTS 소스 안에서 참조를 만들기 위한 식별자다. path는 /soc/serial@12340000 같은 절대 위치 표현이고, overlay에서는 base DT가 label symbol을 제공하지 않을 때 대안으로 쓸 수 있다.

/aliases 노드에 들어가는 alias는 부트 인자나 사용자 공간, 일부 커널 경로에서 사람이 기억하기 쉬운 이름을 제공하는 별도 메커니즘이다. 공식 문서가 설명하는 overlay 타깃 지정은 alias가 아니라 label 또는 path를 기준으로 한다.

실무에서 자주 생기는 오해는 무엇일까?

• label은 노드 이름 자체가 아니다. serial@12340000이 노드 이름이고 uart0는 참조용 label일 수 있다.
• label은 DTS 소스용 식별자다. 일반 DTB 결과만 보고 label 문자열 존재를 전제하면 안 된다.
• overlay의 &label은 base DT에 symbol 정보가 있을 때 가장 안정적으로 동작한다.
• 보드 DTS에서의 &label { ... } 확장은 기존 정의를 병합하는 패턴이지, 별도 노드를 새 이름으로 복제하는 문법이 아니다.
• 경로 타깃은 가능하지만, 커널 문서 기준으로는 label 타깃이 더 이식성이 높다.

FAQ

Q. overlay에서 label을 쓰려면 base DT와 overlay 둘 다 특별한 준비가 필요할까?

Linux 커널 문서 기준으로 overlay 입력은 적절한 dtc 옵션과 /plugin/ 태그가 있어야 resolver가 __fixups__ 정보를 사용할 수 있다. 또 base DT가 -@ 옵션으로 컴파일되지 않았다면 label 기반 타깃을 해석하지 못할 수 있다.

Q. 같은 노드에 label을 붙여 두면 경로가 바뀌어도 overlay를 그대로 쓸 수 있나?

커널 문서는 label 타깃 문법이 base DT 안에서 label 위치가 어디에 있든 적용 가능하므로 경로보다 선호된다고 설명한다. 다만 그 label이 계속 유지된다는 전제가 필요하므로, base DTS 리팩터링 때 label 이름을 바꾸면 overlay도 함께 점검해야 한다.

Q. label로 속성값에도 이름을 붙일 수 있나?

Devicetree Specification은 label을 노드뿐 아니라 속성값에도 붙일 수 있다고 설명한다. 다만 실무에서 overlay 타깃 지정이나 보드 DTS 확장처럼 자주 보는 패턴은 대개 노드 label 참조다.

정리

Device Tree label을 볼 때 핵심은 "소스 형식의 참조 이름", "overlay에서는 symbol 기반 타깃 해석의 출발점", "경로보다 이식성이 높을 수 있음" 이 세 가지다. 그래서 label을 단순 별명으로만 보지 말고, DTS 병합과 overlay 적용을 안정화하는 기준으로 이해하는 편이 맞다.

특히 오버라이드와 overlay를 함께 다룰 때는 보드 DTS의 &label { ... } 확장과 런타임 overlay의 &label 타깃 지정이 비슷해 보여도 적용 시점과 내부 처리 경로가 다르다는 점을 구분해 두면 디버깅이 훨씬 수월하다.

참고 자료

• Devicetree Specification: DTS format and labels
• Linux Kernel Documentation: Devicetree Overlay Notes
• Linux Kernel Documentation: Devicetree Dynamic Resolver Notes
• Linux Kernel Documentation: DeviceTree Kernel API
• Linux Kernel Documentation: Devicetree Sources Coding Style