Device / Board · Zephyr 3.7.0 LTS3 · source + diagram note

Device Model

정적 장치 객체가 만들어지는 때, 초기화가 실행되는 때, API를 사용할 수 있는 때를 나눠 읽는다.

고정 버전: Zephyr v3.7.0 범위: DT 기반 정적 장치 증거: device.h · init.c · device.c

본문 기준: Zephyr 3.7.0 LTS3 · 이후 유지보수 패치는 별도입니다.

전체 흐름

일반적인 devicetree 기반 장치에서 드라이버의 DEVICE_DT_DEFINE() 계열은 장치 객체·상태·초기화 엔트리를 이미지에 배치한다. 매크로가 초기화 함수를 바로 호출하는 것은 아니다. 부팅 중 정해진 레벨을 순회할 때 함수를 실행하고 결과를 기록한다. 소비자는 객체 참조와 준비 상태를 따로 확인한다.

그림 1. 정의 → 초기화 → 사용: 서로 다른 세 경계

그림은 좌우로 스크롤하거나 Tab 키로 선택한 뒤 방향키로 이동할 수 있다.

빌드와 링크에서 장치 객체와 초기화 엔트리를 만들고, 부팅 때 do_device_init이 초기화 결과를 기록한다. 지연 초기화 장치는 별도 device_init 호출이 필요하다. 소비자는 DEVICE_DT_GET 후 device_is_ready를 확인하고 API 결과도 검사한다.

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 / config

data는 인스턴스별 가변 상태, 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_ready

NULL이면 거짓이고, 그 외에는 이 장치의 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의 오류도 별도로 처리한다.

근거: init.c:306–392, device.c:142–153.

불변 조건 확인 목록

경계지켜야 할 조건검증
정의소비자가 참조할 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()이 -ENOENTNULL 또는 지연 초기화 장치가 아님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 APIGPIO/UART 같은 공통 API가 장치별 구현을 호출하는 경계

다음 Zephyr RTOS 글