리눅스 Device Tree compatible는 어떻게 써야 할까? 순서와 작성 기준 정리

리눅스 Device Tree compatible는 어떻게 써야 할까? 순서와 작성 기준 정리

리눅스에서 Device Tree를 읽을 때 compatible 속성은 단순한 이름표가 아니다. Devicetree Specification은 이 속성이 노드가 따르는 바인딩을 나타낸다고 설명하고, Linux 커널 문서는 커널이 이 값을 보고 플랫폼 식별과 디바이스 생성에 활용한다고 설명한다. 실무에서는 이 문자열의 순서, fallback 범위, 문서화 여부를 같이 봐야 안전하다.

결론부터 말하면 compatible은 가장 구체적인 값부터 더 일반적인 값 순서로 적는 것이 기준이다. 그리고 보드가 실제로 보장하는 호환성만 넣어야 하며, DTS에 쓴 문자열은 대응하는 바인딩 문서에도 먼저 정의돼 있어야 한다. 이 세 가지를 놓치면 드라이버 매칭과 유지보수 모두가 흔들리기 쉽다.

compatible는 정확히 무엇을 뜻하나?

Devicetree Specification은 디바이스 노드의 compatible이 그 노드가 따르는 바인딩 또는 바인딩들의 목록이라고 설명한다. 하나의 장치가 상위 호환 관계를 가질 수 있으므로 값은 하나가 아니라 여러 문자열일 수 있고, 이때는 가장 구체적인 바인딩에서 가장 일반적인 바인딩 순서로 적는다.

uart@12340000 {
    compatible = "vendor,soc1234-uart", "vendor,soc1200-uart";
    reg = <0x12340000 0x1000>;
    interrupts = <5>;
};

이런 형태는 새 SoC의 UART가 이전 세대 UART와 프로그래밍 모델이 같을 때 유용하다. 드라이버는 첫 번째 값이 정확히 일치하면 가장 좋고, 그렇지 않으면 뒤의 더 일반적인 값을 fallback으로 사용할 수 있다.

왜 순서가 중요한가?

Linux 커널의 Device Tree usage 문서는 루트 노드의 compatible 목록이 가장 구체적인 값에서 가장 덜 구체적인 값으로 정렬된다고 설명한다. ARM 초기 부팅에서는 커널이 이 목록을 보고 가장 잘 맞는 machine_desc를 고른다. 즉 순서는 단순한 관례가 아니라, 어떤 수준의 호환성을 먼저 주장하는지 드러내는 정보다.

루트 노드뿐 아니라 일반 디바이스 노드에서도 같은 원칙이 유지된다. 먼저 SoC 전용 문자열을 두고, 그 뒤에 동일한 레지스터 모델을 공유하는 상위 호환 문자열을 두는 패턴이 가장 무난하다.

어디까지 fallback을 주장해도 되나?

커널 문서는 보드 수준 호환성은 특히 조심하라고 경고한다. 같은 제품군이라도 보드 간 차이가 커질 수 있어서, 실제로 보장하지 못하는 다른 보드 호환성을 루트 compatible에 섞는 것은 안전하지 않다. 예외에 가까운 경우는 CPU 모듈과 캐리어 보드처럼 구조적으로 호환성이 명확한 조합이다.

실무 판단은 단순하다. 레지스터 배치, 인터럽트 동작, 필요한 속성, 드라이버 기대값이 같아서 같은 바인딩으로 취급할 수 있을 때만 fallback을 추가하면 된다. 반대로 새 속성을 따로 추가해야만 차이를 설명할 수 있다면, 기존 문자열 재사용보다 새 compatible이 더 맞을 가능성이 크다.

새 compatible를 만들 때 기준은 무엇인가?

Linux 커널의 Devicetree 바인딩 가이드는 디바이스별 속성 이름에는 vendor prefix를 쓰고, 공통 속성을 다시 정의하지 말며, compatible으로 구분해야 할 차이를 다른 임시 속성으로 우회하지 말라고 권한다. 또한 큰 장치의 하위 블록은 임의 버전 문자열보다 실제 디바이스 중심 이름을 선호한다.

• vendor,device 형태를 기본으로 본다.
• 차이가 프로그래밍 모델 차이라면 새 compatible을 만든다.
• 공통 속성은 기존 표준 속성을 그대로 쓴다.
• 기존 문자열의 의미를 바꾸는 방식으로 ABI를 깨면 안 된다.

커널 문서는 Devicetree 바인딩의 ABI 영향이 리눅스 커널 바깥 프로젝트까지 이어질 수 있다고 설명한다. 한 번 배포된 compatible은 사실상 외부 계약으로 다루는 편이 맞다.

문서화는 왜 같이 봐야 하나?

Linux 커널 문서는 DTS 파일에서 쓰는 모든 compatible 문자열이 대응하는 바인딩 문서에 먼저 기록돼 있어야 한다고 명시한다. 이 규칙은 아직 드라이버가 그 문자열을 직접 매치하지 않더라도 적용된다. 즉 DTS에 문자열부터 넣고 문서를 나중에 맞추는 방식은 권장 흐름이 아니다.

리뷰와 장기 유지보수 관점에서도 이 규칙이 중요하다. 바인딩 문서가 있어야 어떤 속성이 필수인지, 어떤 fallback이 허용되는지, 기존 ABI와 충돌하지 않는지 판단할 수 있기 때문이다.

리눅스는 compatible를 실제로 어떻게 쓰나?

커널 usage 문서는 루트에서 시작해 compatible 속성이 있는 노드를 찾고, 이를 바탕으로 디바이스를 등록한다고 설명한다. 루트에 직접 연결된 노드는 보통 platform_device로 등록되고, I2C나 SPI 같은 버스 아래 자식 노드는 해당 버스 드라이버가 다시 생성한다. 결국 compatible은 사람이 읽는 설명이 아니라, 커널이 노드를 어떤 장치로 해석할지 결정하는 핵심 단서다.

실무에서 바로 적용할 체크리스트

• 첫 번째 문자열은 현재 보드나 SoC의 가장 구체적인 식별자인가?
• 뒤의 fallback 문자열은 실제로 같은 바인딩과 드라이버 모델을 공유하는가?
• 새 차이를 숨기려고 임시 속성을 추가하고 있지는 않은가?
• 사용한 문자열이 바인딩 문서에 이미 정의돼 있는가?
• 향후에도 의미를 바꾸지 않을 ABI로 유지할 수 있는가?

FAQ

Q. compatible에 여러 문자열을 넣는 이유는 무엇인가?

가장 구체적인 장치부터 더 일반적인 상위 호환 장치까지 fallback 경로를 제공하기 위해서다. Devicetree Specification은 여러 바인딩을 순서대로 적을 수 있다고 설명한다.

Q. 같은 제품군 보드면 이전 보드 compatible를 같이 넣어도 되나?

항상 그렇지는 않다. Linux 커널 문서는 보드 수준 호환성 주장을 조심하라고 설명한다. 실제 하드웨어 차이가 크면 잘못된 매칭과 보드별 예외 처리가 늘어날 수 있다.

Q. 새 SoC지만 레지스터 모델이 같다면 새 compatible가 꼭 필요한가?

대개는 새 SoC 전용 문자열을 앞에 두고, 뒤에 기존 fallback 문자열을 두는 방식이 안전하다. 이렇게 하면 새 모델을 명시하면서도 기존 드라이버 재사용 경로를 남길 수 있다.

정리

compatible을 쓸 때 핵심은 세 가지다. 가장 구체적인 값부터 적고, 실제로 보장되는 호환성만 fallback으로 남기고, 문자열 자체를 바인딩 문서와 함께 관리하는 것이다. Device Tree에서 이 필드는 장치 이름이 아니라 커널과의 계약에 가깝다.

새 보드나 새 SoC를 추가할 때 문자열 하나만 맞추면 된다고 보기 쉽지만, 커널 문서와 명세를 보면 그렇지 않다. 순서, 범위, 문서화가 모두 맞아야 이후 드라이버 재사용과 리뷰가 덜 흔들린다.

참고 자료

• Devicetree.org Specifications
• Devicetree Specification: Device Bindings
• Linux Kernel Documentation: Linux and the Devicetree
• Linux Kernel Documentation: DOs and DON’Ts for designing and writing Devicetree bindings
• Linux Kernel Documentation: Submitting Devicetree binding patches