전체 흐름
Zephyr devicetree의 DTS와 overlay는 빌드 입력이다. binding YAML은 노드의 속성을 해석하고 검증하는 별도 입력이다. 빌드 과정은 두 입력을 바탕으로 최종 DTS와 C 매크로가 담긴 헤더를 만든다.
이 글은 Zephyr 3.7.0 LTS3 기준이다. 아래 그림에서는 입력, 생성 파일, C 코드에서 쓰는 공개 매크로를 구분한다. devicetree 자체가 부팅 뒤 순서대로 상태를 바꾸는 런타임 객체는 아니다.
SoC .dtsi를 포함한 board .dts와 선택한 overlay가 하드웨어 노드와 값을 제공한다.
binding YAML은 compatible에 맞는 속성의 타입과 의미를 제공한다. overlay 다음에 실행되는 단계가 아니다.
DTS는 C 전처리로 zephyr.dts.pre가 되고, edtlib과 gen_defines.py가 binding을 함께 사용한다.
build/zephyr/zephyr.dts에서 overlay가 반영된 노드·속성·status를 확인한다.
build/zephyr/include/generated/zephyr/devicetree_generated.h에 노드·속성·ordinal 데이터 매크로가 담긴다.
C 소스는 생성 헤더를 직접 포함하지 않고 <zephyr/devicetree.h>의 공개 API를 쓴다.
DT_NODELABEL(uart0)은 노드 식별자, DT_PROP(...)은 컴파일 시점 속성값이다. DEVICE_DT_GET(...)은 별도 드라이버가 정의한 device 객체를 참조하며, 생성 헤더가 그 객체를 자동 생성하는 것은 아니다.
두 입력은 병렬로 해석에 참여한다. zephyr.dts는 확인용, devicetree_generated.h는 C 컴파일용이다. 공개 DT_* API는 devicetree.h에 정의되어 있다.
소스 코드 위치
먼저 확인할 Zephyr 3.7.0 LTS3 소스 파일
include/zephyr/devicetree.h
scripts/dts/gen_defines.py
dts/bindings
boards
설명: 입력 DTS와 binding을 확인한 다음, gen_defines.py가 만든 헤더와 공개 devicetree.h API를 대조한다. device 객체가 필요한 코드라면 driver의 Kconfig 조건과 링크 결과, 부팅 뒤 준비 상태를 따로 확인한다.
원본 코드와 사용 예
아래 코드는 Devicetree를 읽을 때 실제 원본에서 찾게 되는 macro와 API의 최소 단위다. 전체 파일을 통째로 붙이면 읽기보다 스크롤이 많아지므로, 각 조각이 빌드 입력·C 매크로·디바이스 참조 중 무엇을 나타내는지 붙였다.
1. overlay에서 node 켜기
&uart0 {
status = "okay";
current-speed = <115200>;
pinctrl-0 = <&uart0_default>;
pinctrl-names = "default";
};
&uart0
SoC dtsi가 제공한 node를 board/application overlay에서 수정한다.
status
driver instance 생성 여부에 직접 연결된다. disabled면 DT_INST_FOREACH_STATUS_OKAY에 잡히지 않는다.
pinctrl
device init이 성공하려면 pin 상태와 clock/reset dependency도 같이 맞아야 한다.
읽는 방법: 이 overlay는 그림 1의 DTS 입력에 속한다. 빌드가 이를 전처리한 뒤 최종 zephyr.dts에서 uart0의 값과 status를 확인한다. 실행 중의 device 상태를 직접 바꾸는 코드는 아니다.
2. C 코드에서 devicetree 값 읽기
#define UART_NODE DT_NODELABEL(uart0)
BUILD_ASSERT(DT_NODE_HAS_STATUS(UART_NODE, okay));
static const uint32_t baud =
DT_PROP(UART_NODE, current_speed);
DT_NODELABEL
node id를 만든다. 포인터가 아니라 preprocessor token이다.
BUILD_ASSERT
hardware description 오류를 런타임이 아니라 빌드 타임에 잡는다.
DT_PROP
binding이 정의한 property 이름을 C constant로 가져온다.
읽는 방법: DT_NODELABEL은 노드 식별자를, DT_PROP은 생성 헤더에 담긴 속성값을 컴파일 시점에 참조한다. BUILD_ASSERT는 조건이 틀린 빌드를 거부한다. 어느 것도 런타임 devicetree 상태 전이가 아니다.
3. chosen/alias 사용
#define CONSOLE_NODE DT_CHOSEN(zephyr_console)
#define LED0_NODE DT_ALIAS(led0)
const struct device *console = DEVICE_DT_GET(CONSOLE_NODE);
chosen
특정 역할의 device를 지정한다. console, flash, entropy처럼 subsystem default에 자주 쓰인다.
alias
application-friendly 이름이다. board마다 실제 controller가 달라도 app 코드는 led0 같은 이름을 쓸 수 있다.
DEVICE_DT_GET
node id에서 device symbol reference로 이동한다.
읽는 방법: DT_CHOSEN과 DT_ALIAS는 노드 식별자를 고른다. DEVICE_DT_GET은 선택된 노드에 대응하는 device 객체를 참조하므로 그림 2처럼 링크 결과와 실행 중 device_is_ready()를 별도로 확인한다.
소스 추적 순서
Devicetree를 추적할 때는 입력 DTS와 선택된 overlay, 생성 파일, C 매크로, 드라이버 빌드 조건을 순서대로 대조한다. 노드 식별자와 실행 중 device 객체는 서로 다른 대상이다.
1단계. 공개 API에서 시작한다
먼저 응용 프로그램이나 드라이버에서 쓰는 DT_NODELABEL, DT_PROP 같은 공개 매크로를 확인한다. 매크로의 노드 식별자가 어떤 생성 헤더 데이터로 이어지는지, 그 데이터의 원천이 되는 DTS·binding 입력은 무엇인지 역으로 추적한다.
include/zephyr/devicetree.h
scripts/dts/gen_defines.py
dts/bindings
설명: devicetree.h는 공개 매크로를 정의하고, gen_defines.py와 binding은 생성 데이터가 어디서 왔는지 확인하는 경로다. 컴파일 시점 속성 조회와 device 객체 참조를 한 단계로 묶지 않는다.
2단계. 노드 식별자·속성값·device 참조를 분리한다
다음은 실제 전처리 결과가 아니라 공개 API별 결과 종류를 구분하는 읽기 스케치다. uart0 노드 레이블과 current-speed 속성이 최종 DTS에 있어야 해당 예를 적용할 수 있다.
DT_NODELABEL(uart0) /* 노드 식별자: C 매크로 토큰 */
DT_PROP(DT_NODELABEL(uart0), current_speed) /* 컴파일 시점 속성값 */
DEVICE_DT_GET(DT_NODELABEL(uart0)) /* 드라이버가 정의한 device 참조 */
설명: DTS의 하이픈은 C 매크로에서 밑줄로 바뀐다. 앞의 두 표현은 생성 헤더의 데이터로 해석하고, 마지막 표현은 해당 device 객체가 링크되는지와 실행 중 준비됐는지를 추가로 확인한다.
3단계. 입력·생성 파일·C 매크로를 따로 대조한다
생성 헤더가 있다는 사실만으로 device 객체가 만들어진 것은 아니다. 다음 표에서 DTS 입력과 binding 규칙, 빌드 산출물, 공개 C 매크로가 하는 일을 분리해 확인한다.
| 구분 | 파일·표현 | 확인할 결과 |
|---|---|---|
| 하드웨어 입력 | SoC .dtsi + board .dts + 선택한 overlay | 노드, status, 속성값이 전처리 입력에 반영되는가 |
| 해석 규칙 | dts/bindings/*.yaml | compatible과 속성 타입이 맞는가. DTS 뒤에 실행되는 별도 런타임 단계는 아니다. |
| 중간 파일 | build/zephyr/zephyr.dts.pre | include와 overlay가 C 전처리 후 합쳐졌는가 |
| 최종 DTS | build/zephyr/zephyr.dts | 실제 빌드에서 해석한 노드와 속성을 읽는다. C 코드가 이 파일을 런타임에 파싱하는 경로는 아니다. |
| 생성 헤더 | build/zephyr/include/generated/zephyr/devicetree_generated.h | 노드·속성·dependency ordinal을 나타내는 내부 DT_* 데이터 매크로를 확인한다. |
| C API 결과 | <zephyr/devicetree.h>의 DT_NODELABEL, DT_PROP | 노드 식별자와 컴파일 시점 속성값을 얻는다. 공개 API 매크로 자체는 생성 파일의 산출물이 아니다. |
| device 참조 | DEVICE_DT_GET(node_id) | 해당 driver가 device 객체를 정의했는지 링크 단계에서 확인하고, 실행 중에는 device_is_ready()로 준비 상태를 확인한다. |
4단계. device 객체와 준비 상태를 확인한다
노드가 status = "okay"여도 driver가 빌드되지 않으면 DEVICE_DT_GET의 device 참조가 링크 오류가 될 수 있다. 링크에 성공해도 초기화 실패는 별도이므로 device_is_ready()를 확인한다. 아래 파일은 이 경계를 추적할 때 함께 보는 산출물이다.
build/zephyr/zephyr.dts
build/zephyr/include/generated/zephyr/devicetree_generated.h
build/zephyr/.config
drivers/<subsystem>/CMakeLists.txt
device_is_ready(dev)
설명: 최종 DTS에서 노드와 status를, 생성 헤더에서 노드·속성 매크로와 ordinal을, .config 및 드라이버 CMake 파일에서 빌드 여부를 확인한다. 마지막 줄은 파일 경로가 아니라 링크 성공 뒤 실행 중 확인할 API다.
내부 동작 분석
핵심 확인 사항: DTS와 overlay는 부팅 중 읽는 설정 파일이 아니다. C 전처리와 binding 해석을 거쳐 생성 헤더의 매크로 데이터가 되고, device 객체는 별도로 빌드된 드라이버가 정의한다.
1. 실제 선택된 DTS·overlay부터 확인한다
board DTS가 SoC의 .dtsi를 포함하고, 선택된 overlay가 뒤에서 노드와 속성을 덮어쓴다. 어떤 overlay가 선택됐는지는 구성 로그와 DTC_OVERLAY_FILE의 CMake 캐시를 확인한다. 입력이 바뀌었는데 결과가 오래된 경우에는 새 빌드 디렉터리나 pristine 빌드로 구성 단계를 다시 실행한다.
전처리 결과는 build/zephyr/zephyr.dts.pre에 남는다. 이 파일은 확인용 최종 DTS나 C 코드가 사용하는 공개 헤더와 역할이 다르다.
2. binding과 두 생성 파일의 역할을 분리한다
edtlib은 DTS를 binding YAML과 함께 해석하고 gen_defines.py는 최종 build/zephyr/zephyr.dts와 devicetree_generated.h를 만든다. 최종 DTS에서는 실제 노드·compatible·속성값을, 생성 헤더에서는 노드 식별자와 속성 매크로를 확인한다.
C 소스는 생성 헤더를 직접 포함하지 않고 <zephyr/devicetree.h>의 공개 매크로를 사용한다. DTS의 current-speed와 C의 current_speed처럼 이름 표기 규칙도 다르다.
3. 노드 활성화와 드라이버 포함을 별도로 검사한다
노드의 status = "okay" 또는 status 생략은 사용 가능한 하드웨어 인스턴스를 나타내지만 드라이버 소스의 빌드까지 보장하지 않는다. compatible을 처리하는 드라이버를 찾고, 해당 소스를 선택하는 Kconfig 심벌이 build/zephyr/.config에서 켜졌는지 본다. DT_INST_FOREACH_STATUS_OKAY를 쓰는 드라이버라면 DT_DRV_COMPAT 대응도 확인한다.
4. 링크 성공과 초기화 성공을 다시 나눈다
DEVICE_DT_GET(node_id)은 노드에 대응하는 struct device의 주소를 참조한다. 드라이버가 객체를 정의하지 않았다면 __device_dts_ord_<N> 미정의 참조가 링크 단계에서 날 수 있다. 이때 생성 헤더의 ordinal 목록으로 노드를 찾은 뒤 최종 DTS와 드라이버 Kconfig를 대조한다.
링크가 되어도 device 초기화가 실패할 수 있다. API를 쓰기 전에 device_is_ready()를 확인하고 거짓이면 해당 드라이버의 초기화 결과와 로그를 조사한다.
불변 조건 확인 목록
한 보드의 빌드에서 Devicetree 관련 주장이 성립하려면 다음 다섯 경계를 각각 확인해야 한다. 다른 보드나 overlay로 빌드하면 결과가 바뀔 수 있다.
| 조건 | 확인할 질문 | 증거 |
|---|---|---|
| 선택된 입력 | 이 빌드에 의도한 overlay가 적용됐는가 | 구성 로그·CMakeCache.txt의 DTC_OVERLAY_FILE, 최종 zephyr.dts |
| 노드와 binding | compatible에 맞는 binding과 필요한 속성이 있는가 | zephyr.dts와 dts/bindings/*.yaml |
| C 이름 | DTS 이름을 C API 규칙으로 바꿔 참조했는가 | current-speed와 current_speed, 생성 헤더 |
| device 정의 | 활성 노드에 대응하는 드라이버가 빌드되어 객체를 정의했는가 | status, 드라이버 Kconfig·CMake, 링크 결과 |
| 사용 가능 상태 | 링크된 device의 초기화가 성공했는가 | device_is_ready()와 드라이버 초기화 로그 |
노드가 생성 헤더에 있다는 사실만으로 device 객체의 존재나 초기화 성공을 결론 내리지 않는다. 근거: Devicetree HOWTOs와 문제 해결 안내.
빌드 결과와 device 준비 상태의 경계
devicetree에는 declared → linked → ready 같은 런타임 상태 전이가 없다. DTS에서 계산된 값, driver가 정의하는 device 객체, 부팅 중 초기화 결과는 서로 다른 경계다.
최종 DTS에서 노드의 status와 속성을 확인한다. DT_PROP은 생성 헤더의 데이터를 컴파일 시점에 읽는다.
compatible에 대응하는 driver 소스가 Kconfig 조건에 따라 빌드되고 device 객체를 정의해야 한다.
두 조건을 대조한 뒤 DEVICE_DT_GET(node_id)의 링크 결과를 갈라 본다.
driver가 해당 device 객체를 정의했다. C 코드의 device 참조가 실제 객체를 가리킨다.
노드 식별자는 있어도 device 객체가 없으면 __device_dts_ord_<N> 미정의 참조가 날 수 있다. node status와 driver Kconfig를 확인한다.
링크된 device라도 초기화가 실패할 수 있다. 소비자는 device_is_ready(dev)를 확인한 뒤 API를 사용한다.
device_is_ready(dev)가 거짓이면 드라이버 초기화 로그와 의존 device 상태를 조사한다. DTS를 다시 파싱하는 단계가 아니다.
위쪽은 구성·컴파일·링크, 구분선 아래쪽은 링크 성공 뒤 부팅 중 검사다. DEVICE_DT_GET은 런타임 devicetree 탐색 함수가 아니다.
생성 헤더에서 얻는 값
DT_NODELABEL은 노드 식별자를 만들고 DT_PROP은 그 노드의 속성값을 컴파일 시점에 참조한다. 둘 다 devicetree.h의 공개 매크로이며, 생성 헤더가 그 뒤의 데이터 매크로를 제공한다.
device 객체의 존재
DEVICE_DT_GET은 해당 노드의 device 객체를 참조한다. 노드가 있어도 device를 정의할 driver가 빠지면 링크 단계에서 오류가 날 수 있다. 노드의 status와 driver Kconfig를 함께 확인한다.
device 객체의 사용 가능 여부
device 객체가 링크되었다고 초기화 성공까지 보장되지는 않는다. C 코드에서 device_is_ready()를 확인해 사용 가능할 때만 장치 API를 호출한다. 실패하면 해당 driver의 초기화 결과를 조사한다.
실패 조건표
증상이 나타난 단계를 먼저 나누면 DTS 입력 오류와 드라이버 초기화 오류를 혼동하지 않는다. 다음 표의 파일 경로는 기본 build 디렉터리 기준이다.
| 증상 | 먼저 볼 결과물 | 가능한 원인 | 다음 확인 |
|---|---|---|---|
| overlay 변경이 보이지 않음 | CMakeCache.txt, zephyr.dts | 다른 overlay가 선택됐거나 이전 구성 결과를 재사용 | DTC_OVERLAY_FILE과 구성 로그를 확인하고 pristine 빌드 |
DT_PROP 컴파일 오류 | zephyr.dts, 생성 헤더 | 노드 식별자·속성 이름이 틀리거나 matching binding에 속성이 없음 | DTS 이름과 C 토큰 표기 차이, binding 경로 확인 |
DT_INST_* 컴파일 오류 | 드라이버 C 파일, 생성 헤더 | DT_DRV_COMPAT이 compatible과 맞지 않음 | 문자열을 소문자·밑줄 형태로 바꾼 심벌 대조 |
__device_dts_ord_<N> 링크 오류 | 생성 헤더의 ordinal 목록, zephyr.dts, .config | 노드 비활성 또는 device를 정의할 드라이버가 빌드되지 않음 | ordinal의 노드 경로, status, 드라이버 Kconfig 확인 |
| 링크는 되지만 장치를 못 씀 | device_is_ready(), 드라이버 로그 | device 초기화 미완료 또는 실패 | 초기화 결과와 의존 device의 준비 상태 확인 |
| 보드마다 다른 노드를 참조 | 각 보드의 zephyr.dts | /aliases나 /chosen 값, overlay 선택 차이 | 최종 노드 경로와 DT_ALIAS·DT_CHOSEN 대상 대조 |
링크 오류의 N은 생성 헤더 맨 위 ordinal 목록에서 실제 노드 경로로 되돌린다. zephyr.map에서 헤더 파일 이름을 검색해도 이 대응 관계는 확인되지 않는다. 근거: Zephyr 3.7.0 Devicetree 문제 해결.
자주 발생하는 오해와 잘못된 접근
다음 오해는 같은 증상을 입력 선택, C 매크로, 드라이버 빌드, 초기화 중 잘못된 단계에서 찾게 만든다.
잘못된 접근 1. 수정한 overlay가 적용됐다고 가정한다
파일을 고쳤어도 그 파일이 이번 빌드에 선택됐는지 별도로 확인해야 한다. 구성 로그와 DTC_OVERLAY_FILE 캐시를 보고, 최종 zephyr.dts의 노드 값까지 대조한다.
잘못된 접근 2. 구성 캐시를 무시한다
이미 구성한 빌드 디렉터리에 이전 overlay 선택이 남을 수 있다. 입력 선택이 의심스러우면 캐시를 확인하고 west build -p=always로 새 구성 결과를 만든다.
잘못된 접근 3. DTS 철자를 C 매크로에 그대로 넣는다
current-speed 같은 DTS 속성은 C에서 current_speed로 참조한다. 노드 레이블, alias, 속성 이름도 각각 대응하는 공개 매크로를 사용하고 생성 헤더로 결과를 검증한다.
잘못된 접근 4. 활성 노드가 device 객체를 보장한다고 생각한다
status = "okay"는 드라이버 소스가 빌드됐다는 뜻이 아니다. DEVICE_DT_GET의 ordinal 링크 오류가 나면 노드 경로를 찾은 뒤 해당 드라이버 Kconfig와 CMake 조건을 검사한다.
잘못된 접근 5. 준비 상태 확인을 생략한다
device 객체가 링크됐어도 초기화에 실패했을 수 있다. 장치 API 호출 전 device_is_ready()를 확인하고 거짓일 때 드라이버 초기화 결과를 조사한다.
근거: Devicetree HOWTOs, 문제 해결 안내, west 빌드.
Linux와의 차이
Devicetree를 읽는 시점이 다르다
Linux는 바이너리 devicetree를 실행 중 파싱한다. Zephyr 3.7.0은 빌드 중 DTS를 처리해 C 전처리 매크로가 담긴 헤더를 생성한다. 따라서 Zephyr에서 실제 적용 노드를 확인할 때는 그 빌드의 zephyr.dts와 생성 헤더를 본다.
노드 식별자는 실행 중 포인터가 아니다
Zephyr의 DT_NODELABEL과 DT_ALIAS는 C 매크로가 사용할 노드 식별자를 고른다. 속성값은 DT_PROP으로 얻고, 실제 struct device가 필요할 때 별도로 DEVICE_DT_GET을 사용한다.
하드웨어 기술과 소프트웨어 선택을 나눈다
Zephyr의 devicetree는 하드웨어와 초기 설정을 기술하고 Kconfig는 빌드할 소프트웨어를 고른다. 노드가 존재해도 드라이버가 빠질 수 있으므로 zephyr.dts와 .config를 함께 확인한다.
빌드와 부팅의 확인 순서
이 표는 devicetree 객체의 런타임 상태표가 아니라, 빌드 오류를 좁혀 가는 확인 순서다. 앞의 두 구성 행은 하드웨어 기술과 소프트웨어 선택을 각각 살펴보는 축이다.
| 단계 | 무엇을 확인하나 | 파일·API | 틀리면 먼저 보이는 것 |
|---|---|---|---|
| 구성: 하드웨어 입력 | board DTS, 포함된 SoC DTSI, 선택된 overlay | DTC_OVERLAY_FILE, 구성 로그 | 기대한 overlay가 선택되지 않음 |
| 구성: 드라이버 선택 | 해당 compatible의 드라이버를 빌드하는 Kconfig | build/zephyr/.config, 드라이버 CMakeLists.txt | 노드는 있어도 드라이버 소스가 빠짐 |
| DTS 전처리 | include·overlay·DTS 매크로가 합쳐졌는가 | build/zephyr/zephyr.dts.pre | 입력 변경이 결과에 반영되지 않음 |
| DTS 해석·생성 | binding 해석 후 최종 노드와 C 매크로 데이터 | zephyr.dts, devicetree_generated.h | 속성·status 오류 또는 기대한 매크로 없음 |
| C 컴파일·링크 | 공개 DT_* 매크로 확장과 device 객체 정의 | devicetree.h, DEVICE_DT_GET | 속성 컴파일 오류 또는 __device_dts_ord_<N> 링크 오류 |
| 부팅·API 사용 | 드라이버 초기화가 끝나 장치를 사용할 수 있는가 | device_is_ready(), 드라이버 로그 | 링크는 성공했지만 준비 상태가 거짓 |
표 해석 방법
zephyr.dts가 맞는데 속성 매크로가 틀리면 binding과 생성 헤더를 확인한다. 링크에서 ordinal 오류가 나면 노드 경로·status·드라이버 Kconfig를 대조한다. 링크 성공 뒤에는 DTS를 다시 파싱하는 대신 device_is_ready()로 초기화 결과를 확인한다. 근거: 빌드 단계와 device 참조 방법.
Bring-up 문제 사례
같은 "장치가 안 된다"는 증상도 구성 입력, 링크, 부팅 중 초기화에서 원인이 달라진다. 아래 예시는 그 경계마다 확인할 산출물을 지정한다. 경로는 기본 build 디렉터리를 가정한다.
시나리오 A. overlay를 고쳤는데 최종 노드 값은 그대로다
먼저 실제 선택된 overlay와 최종 DTS를 확인한다. DTC_OVERLAY_FILE은 CMake 캐시에 남으며, 구성 단계에서 선택한 overlay 파일 경로가 출력된다. 소스 overlay만 고쳐 놓고 이전 구성 결과를 읽고 있을 수 있다.
grep -n "DTC_OVERLAY_FILE" build/CMakeCache.txt
grep -n -A8 "uart0:" build/zephyr/zephyr.dts
설명: 예시의 uart0는 확인하려는 노드 레이블로 바꾼다. 첫 줄은 overlay 선택을, 둘째 줄은 최종 노드와 status·속성값을 살핀다. 기대한 변경이 없으면 구성 로그를 확인하고 pristine 빌드로 재생성한다. zephyr.map에서 헤더 경로를 찾는 명령은 이 검증에 맞지 않아 제거했다.
시나리오 B. __device_dts_ord_<N> 링크 오류가 난다
DEVICE_DT_GET이 가리키는 노드 식별자는 유효하지만 드라이버가 그 노드의 struct device를 정의하지 않은 경우다. 오류 번호 N을 실제 노드 경로로 되돌린 다음 노드 활성화와 드라이버 포함을 각각 검사한다.
| 확인 지점 | 질문 | 읽을 곳 |
|---|---|---|
| ordinal | N이 어느 노드 경로인가 | devicetree_generated.h 맨 위의 ordinal 목록 |
| 노드 | 그 경로의 status와 compatible은 무엇인가 | build/zephyr/zephyr.dts |
| 드라이버 | 그 compatible을 처리하는 소스가 빌드됐는가 | 드라이버 CMakeLists.txt와 build/zephyr/.config |
시나리오 C. 링크는 성공했지만 device가 준비되지 않았다
device 객체를 참조할 수 있다는 사실은 초기화 성공을 뜻하지 않는다. 소비자 함수 안에서 준비 상태를 확인하고, 거짓이면 해당 드라이버의 초기화 결과와 의존 장치 로그를 본다.
#define UART_NODE DT_NODELABEL(uart0)
const struct device *uart = DEVICE_DT_GET(UART_NODE);
if (!device_is_ready(uart)) {
return -ENODEV;
}
설명: 이 예시는 반환형이 int인 함수 안의 코드 조각이다. DEVICE_DT_GET은 빌드 시점에 device 참조를 만들고, device_is_ready()는 실행 중 사용할 수 있는지 검사한다.
시나리오 D. 보드를 바꾸자 alias가 다른 장치를 가리킨다
DT_ALIAS와 DT_CHOSEN은 각 빌드의 최종 DTS에서 결정된다. 보드 전환 전후의 zephyr.dts와 .config를 함께 저장해, 노드 선택과 드라이버 선택 중 어느 쪽이 달라졌는지 비교한다.
cp build/zephyr/zephyr.dts before.zephyr.dts
cp build/zephyr/.config before.config
west build -p=always -b <BOARD> <APP>
diff -u before.zephyr.dts build/zephyr/zephyr.dts
diff -u before.config build/zephyr/.config
설명: BOARD와 APP을 실제 보드·애플리케이션으로 바꾼다. -p=always는 이전 구성 산출물을 제거하고 다시 구성한다. 두 빌드의 /aliases·/chosen과 드라이버 Kconfig 차이를 읽는다.
근거: Zephyr 3.7.0 Devicetree HOWTOs, 문제 해결 안내, west pristine 빌드.
추가 분석 항목
보드 이식이나 드라이버 도입을 분석할 때는 C 소스만 비교하지 말고, 빌드 입력에서 device 준비 상태까지 어떤 증거가 달라졌는지 기록한다.
1. overlay 선택과 재구성
같은 애플리케이션에서도 보드와 DTC_OVERLAY_FILE 선택에 따라 최종 노드가 달라진다. 구성 로그와 CMake 캐시의 입력 파일 목록을 남기고, zephyr.dts.pre와 zephyr.dts를 대조한다.
선택값이 의심스러우면 pristine 빌드로 재구성한 뒤 결과를 비교한다. 소스 overlay의 변경과 실제 빌드에 반영된 변경을 분리해 기록한다.
2. binding과 속성의 대응
최종 노드의 compatible에 어떤 binding YAML이 맞는지 확인한다. binding이 해석하는 속성의 타입과 기본값을 읽은 뒤, 생성 헤더에서 C 매크로 데이터가 어떻게 나타났는지 대조한다.
속성 이름의 DTS 표기와 C 토큰 표기가 다른지도 기록한다. 예를 들어 current-speed는 C 매크로 호출에서 current_speed가 된다.
3. 보드 간 노드 선택
응용 코드에서 하드웨어 노드 레이블을 직접 지정할지, 보드가 정의한 /aliases나 /chosen을 사용할지 확인한다. 같은 DT_ALIAS 호출도 보드별 최종 DTS에서는 다른 노드를 가리킬 수 있다.
보드를 바꾸기 전후 zephyr.dts에서 alias·chosen의 대상 경로와 그 노드의 status를 비교한다.
4. 드라이버 인스턴스와 준비 상태
활성 노드마다 드라이버 인스턴스가 정의된다고 가정하지 않는다. 드라이버의 DT_DRV_COMPAT, DT_INST_FOREACH_STATUS_OKAY, Kconfig·CMake 조건을 확인하고 링크 오류가 있다면 생성 헤더의 ordinal로 노드를 되찾는다.
링크가 성공한 뒤에도 device_is_ready() 결과와 드라이버 초기화 로그를 남긴다. 이 결과는 생성 헤더의 노드 존재 여부와 별개다.
근거: 빌드 단계, Devicetree HOWTOs, 문제 해결 안내.
코드 리뷰 확인 사항
다른 보드와 overlay로 다시 빌드해도 같은 의도가 유지되는지 확인하는 질문들이다. 답은 원본 파일 이름보다 그 빌드의 최종 산출물에 근거해 적는다.
입력과 구성
- 이번 빌드의 board DTS와 선택된 overlay 파일은 무엇인가.
DTC_OVERLAY_FILE의 캐시 값과 구성 로그가 의도한 입력을 가리키는가.- 최종
zephyr.dts에서 대상 노드의status와 속성값은 무엇인가. - 입력을 바꿨다면 pristine 빌드로 다시 확인했는가.
binding과 C API
compatible에 맞는 binding YAML과 필요한 속성이 확인되는가.DT_NODELABEL,DT_ALIAS,DT_CHOSEN중 의도한 선택 API를 썼는가.- DTS 속성의 하이픈을 C 매크로에서 밑줄로 바꿨는가.
- 노드 식별자와
DEVICE_DT_GET의 device 참조를 혼동하지 않았는가.
드라이버 인스턴스와 링크
- 노드의
status가 드라이버 인스턴스 생성 조건과 맞는가. - 드라이버의
DT_DRV_COMPAT이 노드compatible에 대응하는가. build/zephyr/.config와 CMake 조건에서 해당 드라이버가 포함되는가.- ordinal 링크 오류가 있다면 생성 헤더에서 노드 경로를 확인했는가.
실행 중 사용 가능 여부
DEVICE_DT_GET으로 얻은 객체에device_is_ready()를 호출하는가.- 준비 상태가 거짓일 때 장치 API 사용을 중단하는가.
- 초기화 실패 로그와 의존 device 상태를 구분해 확인했는가.
- 보드 전환 후 alias 대상과 드라이버 설정 차이를 함께 기록했는가.
근거: Devicetree HOWTOs와 문제 해결 안내.
디버깅 및 계측 지점
빌드 결과 확인
west build -p=always -b <board> <app>
grep -n "DTC_OVERLAY_FILE" build/CMakeCache.txt
grep -n -A8 "uart0:" build/zephyr/zephyr.dts
grep -n "CONFIG_<DRIVER>=" build/zephyr/.config
설명: 예시의 uart0와 <DRIVER>는 대상 노드 레이블과 실제 드라이버 Kconfig 심벌로 바꾼다. 첫 줄은 기존 구성을 지우고 다시 빌드한다. 이어서 선택 overlay, 최종 노드 값, 드라이버 포함 조건을 각각 확인한다.
device 준비 상태 확인
const struct device *dev = DEVICE_DT_GET(DT_NODELABEL(uart0));
if (!device_is_ready(dev)) {
return -ENODEV;
}
설명: 반환형이 int인 함수 안의 코드 조각이다. DEVICE_DT_GET이 링크에 성공해야 실행할 수 있으며, device_is_ready()가 거짓이면 드라이버 초기화 로그와 의존 장치 상태를 살핀다.
실험 과제
- 선택 overlay에서 노드의
status를 바꾸고, 최종 DTS와 생성 헤더에서 어떤 값이 달라지는지 비교한다. - 보드별
/aliases값을 바꾸고DT_ALIAS가 선택한 최종 노드 경로를 비교한다. - 드라이버 Kconfig를 바꾼 뒤
.config, 링크 결과,device_is_ready()결과를 별도로 기록한다.
근거: Devicetree HOWTOs, 문제 해결 안내, west 빌드.
실험 기록 양식
나중에 같은 문제를 다시 만나지 않으려면 bring-up 로그를 일정한 형식으로 남겨야 한다. 아래 양식은 Devicetree를 실험할 때 그대로 복사해서 쓸 수 있는 형태로 넣었다.
[실험 주제] Zephyr 3.7.0 Devicetree
[보드/SoC와 west manifest revision]
[선택한 overlay와 DTC_OVERLAY_FILE 값]
[최종 zephyr.dts의 노드 경로/status/compatible]
[대응 binding YAML과 속성]
[생성 헤더의 노드 식별자/ordinal]
[드라이버 Kconfig와 .config 값]
[DEVICE_DT_GET 링크 결과]
[device_is_ready 결과와 초기화 로그]
[다음 입력 변경과 예상 결과]
설명: 실제 입력, 생성 결과, 드라이버 빌드 조건, 실행 중 준비 상태를 서로 다른 줄에 적는다. west revision과 최종 .config·zephyr.dts를 함께 남겨 비교 가능한 빌드를 만든다.
overlay에 적힌 의도와 zephyr.dts에 남은 값, device_is_ready()로 확인한 결과를 구분한다. 노드 속성의 정적 값이 곧 드라이버 초기화 결과라는 오해를 피할 수 있다.
주요 용어
같은 노드를 가리키는 표현이라도 빌드 입력, 생성 데이터, C API, 실행 중 객체는 서로 다르다.
| 용어 | 이 글에서 확인하는 대상 |
|---|---|
| DTS·overlay | 보드·SoC 하드웨어 기술과 이 빌드에서 선택된 노드·속성 입력 |
| binding YAML | compatible에 대응해 속성의 타입과 의미를 해석하는 규칙 |
zephyr.dts·생성 헤더 | 각각 최종 노드 확인용 파일과 C 매크로가 사용하는 생성 데이터 |
| 노드 식별자 | DT_NODELABEL·DT_ALIAS 등이 만드는 컴파일 시점 C 매크로 토큰 |
| device 객체 | 드라이버가 정의하고 DEVICE_DT_GET으로 참조하는 struct device; 실행 중 준비 상태는 별도 확인 |
분석 순서
먼저 zephyr.dts에서 노드·status·속성을 확인한다. 이어 binding과 생성 헤더를 읽고, C 코드의 DT_* 매크로가 어느 노드 식별자를 쓰는지 대조한다.
장치를 사용하는 코드라면 드라이버 Kconfig와 링크 결과를 확인한 뒤 device_is_ready()까지 내려간다. 이 순서를 따르면 노드 데이터와 실행 중 device 객체를 혼동하지 않는다. 근거: Devicetree C API와 HOWTOs.