전체 흐름
일반적인 devicetree 기반 장치에서 드라이버의 DEVICE_DT_DEFINE() 계열은 장치 객체·상태·초기화 엔트리를 이미지에 배치한다. 매크로가 초기화 함수를 바로 호출하는 것은 아니다. 부팅 중 정해진 레벨을 순회할 때 함수를 실행하고 결과를 기록한다. 소비자는 객체 참조와 준비 상태를 따로 확인한다.
그림은 좌우로 스크롤하거나 Tab 키로 선택한 뒤 방향키로 이동할 수 있다.
status = "disabled" 또는 드라이버 인스턴스 부재는 런타임 초기화 실패와 다르다. device_is_ready()가 참이어도 개별 API의 성공은 별도 문제다.
소스 코드 위치
include/zephyr/device.hkernel/init.ckernel/device.cinclude/zephyr/devicetree.h
아래 설명은 공식 Zephyr 3.7.0 Device Driver Model 문서와 같은 릴리스의 device.h, init.c, device.c를 기준으로 한다. 실제 보드에서는 merged DTS·최종 .config·링커 map도 함께 보아야 한다.
범위: 모든 Zephyr 장치가 devicetree에서 출발하는 것은 아니다. DEVICE_DEFINE() 같은 비-DT 정의도 있다. 이 글의 그림은 DT 기반 정적 장치의 대표 경로다.
원본 코드와 사용 예
다음 세 조각은 드라이버 정의, 소비자 참조, 하위 시스템 API의 역할을 분리한다. 첫째·셋째 조각은 설명용 축약 예제로, 특정 보드에 그대로 붙여 빌드했다는 기록은 아니다.
1. 드라이버가 장치 인스턴스를 정의한다
DEVICE_DT_DEFINE(DT_NODELABEL(uart0),
uart_init, NULL,
&uart_data, &uart_config,
PRE_KERNEL_1, CONFIG_SERIAL_INIT_PRIORITY,
&uart_api);
DT_NODELABEL대상 node의 식별자다. 보드에 이 node가 있고 드라이버가 해당 인스턴스를 정의해야 한다.
data / configdata는 인스턴스별 가변 상태, config는 고정 설정을 가리킨다. struct device의 state는 초기화 결과를 보관한다.
level / prio초기화 함수의 부팅 실행 순서를 정한다. PRE_KERNEL_1에서는 커널 서비스를 사용할 수 없으므로 실제 드라이버의 의존성을 검토해야 한다.
원본 매크로 정의는 상태와 장치 객체, 초기화 엔트리 생성으로 이어진다. 위 이름과 우선순위는 특정 보드 구현을 주장하지 않는 예시다.
2. 소비자가 포인터와 준비 상태를 분리한다
const struct device *uart = DEVICE_DT_GET(DT_NODELABEL(uart0));
if (!device_is_ready(uart)) {
return -ENODEV;
}
DEVICE_DT_GET정적으로 정의된 장치 객체를 참조한다. 해당 장치를 정의한 드라이버가 없으면 대표적으로 __device_dts_ord_<N> 링크 오류가 난다.
device_is_readyNULL이면 거짓이고, 그 외에는 이 장치의 initialized와 init_res를 확인한다.
-ENODEV이 반환은 소비자 예제의 선택이다. 실제 초기화 실패 코드를 그대로 전달한다는 뜻은 아니다.
3. 준비 확인 뒤 공개 하위 시스템 API를 사용한다
const struct device *gpio = DEVICE_DT_GET(DT_NODELABEL(gpio0));
if (!device_is_ready(gpio)) {
return -ENODEV;
}
return gpio_pin_configure(gpio, pin, flags);
응용 코드는 3.7.0 공개 GPIO API를 부른다. 내부적으로 하위 시스템 API table이 드라이버 구현에 연결되지만, 응용 코드가 dev->api를 직접 캐스팅해 호출하는 예제로 쓰지 않는다. 준비 확인은 사용 전 경계이고, gpio_pin_configure()의 반환값은 작업 결과다. gpio0 역시 보드별 존재를 확인해야 한다.
소스 추적 순서
이하 넓은 표도 선택한 뒤 방향키로 좌우 이동할 수 있다.
| 질문 | 살펴볼 것 | 확인 가능한 사실 |
|---|---|---|
| 대상이 빌드됐나? | zephyr.dts, .config, 드라이버 매크로 | node 상태·드라이버 선택·인스턴스 정의 |
| 객체가 링크됐나? | zephyr.map, DEVICE_DT_GET() | 정적 장치 객체의 존재 또는 링크 오류 |
| 언제 초기화되나? | device.h의 엔트리, west build -t initlevels | 일반 부팅 엔트리와 지연 초기화 엔트리 구분 |
| 실패는 어디에 남나? | init.c의 do_device_init() | init 함수 반환과 device_state 갱신 |
| 이제 사용할 수 있나? | device.c의 device_is_ready() | 현재 장치의 준비 판정, 개별 API 결과는 별도 |
부팅 init level과 우선순위 확인에는 공식 initlevels 안내를 따른다. 소스의 선언 순서만으로 런타임 순서를 추측하지 않는다.
내부 동작 분석
객체와 가변 상태는 분리된다
struct device는 이름·설정·API·가변 데이터·device_state 포인터를 묶는다. device_state에는 초기화 결과와 시도 여부가 남는다. config와 data는 드라이버가 해석하는 인스턴스별 저장소이며, 그 자체가 readiness 값은 아니다.
초기화 함수 호출과 성공 표시는 다르다
z_sys_init_run_level()이 일반 엔트리를 순회하고 do_device_init()이 장치 init 함수를 호출한다. 실패하면 반환값의 절댓값을 최대 UINT8_MAX로 줄여 init_res에 저장하고, 성공·실패와 무관하게 initialized를 참으로 만든다. init 함수가 NULL이어도 이 표시는 설정된다. 따라서 initialized만 검사하면 안 된다.
지연 초기화는 다른 엔트리 경로다
DT에 zephyr,deferred-init을 둔 장치는 일반 init level 순회 대상 대신 지연 엔트리를 받는다. device_init(dev)은 이 엔트리를 찾아 do_device_init()을 호출한다. NULL 또는 지연 엔트리가 아닌 장치에는 -ENOENT를 반환하므로, 일반 부팅 초기화 실패를 재시도하는 API로 해석할 수 없다. 3.7.0 구현에는 호출 횟수 제한이 없고, 성공 경로에서 이전 init_res를 지우지도 않는다. 따라서 실패 후 재호출로 ready 상태가 회복된다고 가정할 수 없다.
준비 상태와 동작 결과는 다른 검사다
device_is_ready()는 해당 장치의 initialized && init_res == 0을 검사한다. 의존 장치 전체를 재귀적으로 검사하거나 이후 전원·연결·핀 상태를 보장하지 않는다. 드라이버별 API의 오류도 별도로 처리한다.
불변 조건 확인 목록
| 경계 | 지켜야 할 조건 | 검증 |
|---|---|---|
| 정의 | 소비자가 참조할 node에 대응하는 장치 객체가 링크된다 | 최종 DTS·Kconfig와 map, 링크 오류 대조 |
| 순서 | init 함수가 쓰는 provider가 먼저 준비된다 | init level·priority, 실제 init 결과 확인 |
| 문맥 | PRE_KERNEL_1/2 init은 커널 서비스를 요구하지 않는다 | 드라이버 init 함수의 호출 경로 점검 |
| 소비 | 포인터 획득 뒤 readiness와 API 반환값을 각각 검사한다 | device_is_ready()와 호출 오류 기록 |
객체와 초기화 상태 판별
장치의 빌드 포함 여부, 초기화 시도, API 수행 결과를 하나의 직선 상태로 그리면 원인을 혼동한다. 같은 장치를 다음 세 축으로 따로 관찰한다.
| 축 | 관찰 | 해석 |
|---|---|---|
| 이미지에 객체가 있는가? | 정의/링크 여부 | 부재는 런타임 init_res 실패가 아니다 |
| init을 시도했는가? | state->initialized | 참이어도 성공이라고 할 수 없다 |
| init 결과가 0인가? | state->init_res | 두 상태 필드가 ready 판정에 사용된다 |
| 작업이 성공했는가? | GPIO/UART 등의 API 반환 | ready가 참이어도 이후 작업 실패는 가능하다 |
return dev->state->initialized && (dev->state->init_res == 0U);
이 식은 device.c의 3.7.0 판별식이다. NULL 포인터는 그 앞에서 거짓으로 처리한다.
실패 조건표
| 보이는 현상 | 먼저 찾을 경계 | 다음 확인 |
|---|---|---|
__device_dts_ord_<N> 링크 오류 | 해당 node의 장치 정의 없음 | 최종 DTS 상태, 드라이버 Kconfig, 인스턴스 매크로 |
| 포인터는 있으나 ready가 거짓 | 초기화 미실행 또는 실패 | 지연 초기화 여부, init 함수 반환, 순서 |
device_init()이 -ENOENT | NULL 또는 지연 초기화 장치가 아님 | DT 속성과 실제 엔트리 분기 |
| ready인데 API 호출 실패 | 작업 단위 오류 | API 반환값, 하드웨어·자원 상태 |
자주 발생하는 오해와 잘못된 접근
DT node가 있으니 장치 객체도 있다고 단정한다
DT node와 드라이버 인스턴스 정의는 별개다. enabled node도 대응 장치 객체가 없을 수 있다. DEVICE_DT_GET()에서 링크 오류가 나면 드라이버 빌드와 정의 매크로를 본다.
initialized만 보고 성공으로 판단한다
do_device_init()은 실패를 기록한 뒤에도 이 플래그를 참으로 만든다. device_is_ready()의 두 조건을 함께 확인한다.
실패한 부팅 초기화를 device_init()으로 다시 시도한다
이 호출은 deferred entry를 찾는다. 일반 init level의 실패 장치를 다시 실행하지 않는다.
ready이면 모든 API가 성공한다고 가정한다
초기화 성공과 개별 작업의 성공은 다르다. API 반환값, PM 상태, 실제 연결 상태를 각각 관찰한다.
Linux와의 차이
Linux도 DT와 정적 내장 드라이버를 사용할 수 있다. 비교의 핵심은 “Linux는 모두 동적, Zephyr는 모두 정적”이라는 구분이 아니다. 보통의 Zephyr MCU 보드에서는 최종 DT·Kconfig와 장치 정의 매크로가 사용 가능한 인스턴스를 빌드 전에 강하게 좁히며, 소비자가 DEVICE_DT_GET()으로 그 정적 객체를 참조한다. Linux의 bus/driver core에서 보는 probe·bind·hotplug 흐름을 이 경로에 그대로 대입하면, Zephyr의 링크 오류와 init level 문제를 놓친다.
두 환경 모두 하위 시스템 API와 드라이버별 구현의 분리는 존재한다. 여기서 디버깅할 질문은 “어느 bus에서 probe됐나?”보다 먼저 “어느 장치 객체와 init entry가 이 이미지에 들어갔나?”다.
시간 순서에 따른 실행 흐름
| 때 | 장치에 관한 변화 | 확인 자료 |
|---|---|---|
| 구성·빌드 | node, Kconfig, 드라이버 매크로의 조건 결정 | merged DTS, .config |
| 링크 | 장치 객체·상태·init entry 배치 | map, initlevels |
| 부팅 | 일반 init entry 실행, 결과 기록 | init log, device_state |
| 명시적 초기화 | deferred 장치에만 device_init() 호출 | DT 속성, 반환값 |
| 소비 | readiness 확인 뒤 드라이버 API 호출 | device_is_ready(), API 반환값 |
Bring-up 문제 사례
A. DEVICE_DT_GET() 뒤 링크가 실패한다
DT node의 최종 status와 해당 드라이버 Kconfig를 확인한다. enabled node여도 드라이버의 DEVICE_DT_DEFINE() 인스턴스가 없으면 객체가 없을 수 있다. 오류를 런타임 init 실패로 분류하지 않는다.
B. 포인터는 있지만 ready가 거짓이다
zephyr,deferred-init 여부를 먼저 보고, 일반 장치라면 init level·priority와 init 함수 반환을 본다. 의존 provider가 뒤에 초기화되면 순서를 바로잡고, 실패한 결과를 ready 검사로 덮어 숨기지 않는다.
C. ready는 참인데 GPIO 설정은 실패한다
ready는 초기화 결과 판정이다. gpio_pin_configure() 반환값과 핀·전원·권한·드라이버 구현을 조사한다. init 상태를 강제로 바꾸는 처방은 원인을 가린다.
추가 확인 사항
DEVICE_DT_DEFINE()의 level은 일반 장치의 부팅 엔트리 순서에 쓰인다. deferred 장치는 별도 엔트리로 분기하므로 표시된 level만으로 실행 시점을 판단할 수 없다. 선택적 CONFIG_DEVICE_DEPS가 의존 관계 데이터를 제공할 수 있어도 device_is_ready() 자체가 그 관계를 재귀 검사하지는 않는다.
런타임 PM 자동 활성화 pm_device_runtime_auto_enable()는 do_device_init()의 성공 뒤에 시도되지만, 이 호출의 반환은 버려진다. readiness를 전원 상태의 총괄 검사로 삼지 말고, PM을 쓰는 보드에서는 별도 계측한다. 이는 3.7.0 소스 경로에서 읽히는 한계다.
코드 리뷰 확인 사항
- 소비자가 참조하는 node의 최종 상태와 드라이버 인스턴스 정의가 일치하는가?
- init level·priority가 의존 장치보다 늦으며, pre-kernel 문맥에서 금지된 커널 서비스를 쓰지 않는가?
device_init()을 호출한다면 실제로 deferred 장치이며, 재호출 정책이 정해져 있는가?device_is_ready()와 하위 시스템 API 반환값을 각기 처리하는가?
디버깅 및 계측 지점
west build -b <board> <app>
west build -t initlevels
# build/zephyr/zephyr.dts, build/zephyr/.config,
# build/zephyr/zephyr.map에서 같은 장치를 대조
대상 node의 식별자, driver Kconfig, init level과 priority, init 함수 반환, device_is_ready(), 작업 API 반환을 같은 기록에 나란히 둔다. initlevels는 링크된 초기화 순서를 보여 주지만, 지연 장치의 실제 device_init() 호출 시점까지 알려 주지는 않는다.
실험 기록 양식
보드와 설정이 바뀌어도 링크 경계·초기화 경계·작업 경계를 다시 비교할 수 있도록 다음을 기록한다.
[실험 주제] Device Model
[Zephyr 버전/commit] v3.7.0 / 36940db9
[보드/SoC]
[west manifest revision]
[대상 DT node / 최종 status]
[드라이버 Kconfig / DEVICE_DT_DEFINE 위치]
[일반 또는 deferred / init level·priority]
[init 함수 반환 / init_res / device_is_ready 결과]
[첫 API 호출과 반환]
[관찰한 로그·링크 오류]
[다음 실험]
위 양식은 실제 측정 결과가 아니다. .config, merged zephyr.dts, map과 로그를 함께 보관해야 같은 현상을 재현할 수 있다.
주요 용어
| 용어 | 이 글에서의 의미 |
|---|---|
| device object | 이름·config·data·API·state를 연결하는 정적 장치 객체 |
| init entry | 초기화 함수와 장치를 이어 부팅 순회 또는 deferred 경로에 배치하는 엔트리 |
| deferred init | 부팅 자동 실행을 미루고 명시적 device_init()을 요구하는 DT 속성 |
| ready | 해당 장치가 초기화됐고 기록된 init 결과가 0인 상태 |
| subsystem API | GPIO/UART 같은 공통 API가 장치별 구현을 호출하는 경계 |