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

Driver Model

DT_INST_FOREACH_STATUS_OKAY, DEVICE_DT_INST_DEFINE, compatible binding이 driver instance를 찍어내는 과정을 읽는다.

기준 버전: Zephyr 3.7.0 LTS3 형식: 사용 예제 + 설명 + 그림 분석 방법: Linux 커널과 비교

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

인스턴스 생성과 사용 가능 시점

Zephyr 3.7.0 드라이버는 enabled devicetree node와 driver C 파일의 인스턴스 매크로가 만나는 지점에서 정적 장치 객체를 정의한다. 그 뒤 부팅 중 init 함수를 실행한다. status = "okay", 객체의 링크 성공, device_is_ready()는 각각 다른 질문에 답한다.

그림 1. 드라이버 인스턴스 생성과 런타임 준비 검사
status okay·compatible 및 Kconfig로 드라이버 인스턴스를 빌드하고 정적 device 객체를 링크한 뒤 init 성공과 device_is_ready를 별도로 검사하는 그림

위쪽은 컴파일·링크 시 객체가 만들어지는 경로다. 아래쪽은 부팅 후 init 결과와 API 사용 경로다. 작은 화면에서는 그림을 좌우로 스크롤해 읽을 수 있다.

시점관찰 대상잘못 혼동하기 쉬운 것
빌드 입력compatible, status, Kconfignode가 있어도 driver 파일이 빠질 수 있다
매크로 확장DT_INST_FOREACH_STATUS_OKAY, DEVICE_DT_INST_DEFINE인스턴스 생성은 init 성공과 다르다
부팅init level·priority·의존 장치포인터 존재만으로 API 사용 가능하지 않다

작은 화면에서는 표를 좌우로 스크롤해 읽을 수 있다.

고정 원본과 공식 설명

소스 줄 번호는 공식 Zephyr v3.7.0 태그의 commit 36940db938a8f4a1e919496793ed439850a221c2을 고정해 확인했다. 아래 두 헤더는 정적 인스턴스 생성과 참조를 뒷받침한다. 초기화 결과는 kernel/init.c, UART 호출 계약은 include/zephyr/drivers/uart.h와 함께 대조한다.

원본읽을 위치
include/zephyr/devicetree.henabled compatible 인스턴스 반복: 4518–4531행
include/zephyr/device.hDEVICE_DT_DEFINE / INST_DEFINE: 165–213행; GET의 링크 계약: 231–246행
include/zephyr/device.hdevice_is_ready 계약: 739–755행

공식 Device Driver Model 문서는 init level과 priority, deferred initialization, west build -t initlevels를 설명한다. 특정 UART/GPIO 구현 파일은 이 글의 검증된 코드 범위에 포함하지 않았다.

설명용 드라이버 매크로 예제

다음은 사용자 정의 드라이버의 형태를 보여 주는 조각이다. 선언된 config/data/API/init 함수가 실제로 존재하고, init level과 priority가 의존성에 맞아야 완성된다.

#define DT_DRV_COMPAT vendor_my_uart

#define MY_UART_DEFINE(inst) \
    DEVICE_DT_INST_DEFINE(inst, my_uart_init, NULL, \
        &my_data_##inst, &my_cfg_##inst, POST_KERNEL, 50, &my_uart_api);

DT_INST_FOREACH_STATUS_OKAY(MY_UART_DEFINE)

DT_INST_FOREACH_STATUS_OKAY는 enabled 인스턴스에 대해서만 매크로를 펼친다. DEVICE_DT_INST_DEFINE은 node ID를 통해 device 정의 매크로를 호출한다. config는 변하지 않는 하드웨어 설정, data는 변경 가능한 실행 상태, api는 드라이버의 함수 표다.

인스턴스마다 다른 config와 data

struct my_uart_config {
    uintptr_t base;
    uint32_t baudrate;
};

struct my_uart_data {
    struct k_spinlock lock;
    uint32_t rx_count;
};

원래 설명용 구조체 예제다. config는 읽기 전용 하드웨어 설정, data는 실행 중 상태라는 분리를 보여 준다. 실제 인스턴스에서는 각 node의 reg 등으로 config를 채우고 필요한 초기화 코드를 별도로 작성해야 한다.

subsystem API와 소비자

static const struct uart_driver_api my_uart_api = {
    .poll_in = my_poll_in,
    .poll_out = my_poll_out,
};

const struct device *uart = DEVICE_DT_GET(DT_NODELABEL(uart0));
if (!device_is_ready(uart)) {
    /* 사용 전에 초기화 실패·지연 여부를 조사한다. */
}

이 역시 전체 빌드 가능한 드라이버가 아닌 설명용 조각이다. uart_driver_api의 polling 함수 표는 v3.7.0 uart.h에 맞췄다. 소비자의 DEVICE_DT_GET()은 포인터 참조이고, device_is_ready()는 init 결과 확인이다. 이후 uart_poll_in() 같은 개별 API의 반환값도 별도로 처리한다.

원본 매크로의 실제 연결

device.h:212–213:

#define DEVICE_DT_INST_DEFINE(inst, ...)                                       \
	DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)

device.h:246:

#define DEVICE_DT_GET(node_id) (&DEVICE_DT_NAME_GET(node_id))

첫 매크로는 인스턴스를 node ID로 바꾸어 정적 device 정의를 만든다. 둘째 매크로는 이미 정의된 device의 주소를 참조할 뿐이다. driver가 객체를 정의하지 않았다면 DEVICE_DT_GET()에서 링크 오류가 발생할 수 있다.

정의·초기화·API 사용은 서로 다른 단계다

DT_INST_FOREACH_STATUS_OKAY(fn)은 DT_DRV_COMPAT와 상태가 맞는 인스턴스마다 fn(inst)을 펼친다. 각 DEVICE_DT_INST_DEFINE()은 해당 node의 정적 device 객체와 init entry를 만든다. 이 단계는 C 전처리·컴파일·링크의 일이며 init 함수를 실행하는 시점이 아니다.

부팅 중에는 kernel/init.c 306–375행이 init entry를 순회해 장치 init 결과를 device state에 기록한다. device_is_ready()가 참이면 해당 장치의 초기화가 성공했다는 뜻이지만, 그 뒤의 uart_poll_in() 같은 개별 작업 성공까지 보증하지는 않는다. zephyr,deferred-init 장치는 명시적 device_init()을 기다린다.

인스턴스별 확인 조건

단계확인할 조건확인 위치
빌드 입력node의 compatible·status와 드라이버의 DT_DRV_COMPAT가 맞는가최종 zephyr.dts·binding·driver C
소스 포함드라이버 C 파일의 Kconfig/CMake 조건이 켜졌는가최종 .config·빌드 로그
객체 정의각 enabled 인스턴스에 DEVICE_DT_INST_DEFINE()이 펼쳐졌는가전처리 결과·link/map
실행 준비init level·priority·선행 장치가 맞고 초기화에 성공했는가initlevels·부팅 로그·device_is_ready()

작은 화면에서는 표를 좌우로 스크롤해 읽을 수 있다. 빌드에서 node가 보인다는 사실과 런타임의 ready 상태를 하나로 묶지 않는다.

빌드와 실행을 분리한 판정표

상황판정필요한 확인
status disabled해당 compatible의 enabled 인스턴스에서 제외최종 zephyr.dts
driver C 파일 미컴파일device 객체가 없음.config와 link 오류
device 객체 링크 성공포인터는 얻을 수 있음DEVICE_DT_GET()
부팅 init 실패 또는 지연아직 API 사용 불가init 결과, deferred 설정, device_is_ready()
init 성공표준 API 호출 조건 충족device_is_ready() true; 개별 API 결과는 별도

초기화 순서는 단순히 DTS의 선언 순서로 결정되지 않는다. init level·priority와 의존 장치의 준비 시점을 함께 확인한다.

증상별 진단표

증상첫 증거해석
인스턴스가 생성되지 않음zephyr.dts의 status / compatible매크로가 enabled node를 발견하는지 확인
__device_dts_ord_* 링크 오류driver Kconfig와 컴파일 로그node는 참조되지만 device 객체가 정의되지 않음
DEVICE_DT_GET 후 ready falseinit 로그 / deferred 설정부팅 init 실패 또는 수동 init 대기
API 호출만 실패API 반환값 / 장치 상태ready와 개별 작업의 성공은 별개

링크 오류를 init 실패로 부르지 않는다

__device_dts_ord_* 참조가 해결되지 않는다면 프로그램이 아직 부팅되지도 않았다. 먼저 enabled node와 driver C 파일 포함, 인스턴스 매크로 확장을 확인한다. 그 뒤 device_is_ready()가 거짓이면 부팅 init 결과와 deferred 설정을 본다. 순서를 거꾸로 하면 다른 단계의 문제를 같은 “probe 실패”로 오진한다.

Linux의 probe와 대응시킬 때 주의할 경계

Linux driver model에는 bus에 등록된 driver의 probe()와 -EPROBE_DEFER 경로가 있다. 여기의 DT_INST_FOREACH_STATUS_OKAY()는 Zephyr 빌드 중 enabled 인스턴스마다 C 정의를 펼치는 매크로다. Zephyr의 zephyr,deferred-init도 Linux의 deferred probe와 같은 호출 재시도 계약으로 읽지 않는다. 두 운영체제에서 “장치 없음”이 빌드·링크·부팅 중 어느 시점에 드러나는지 먼저 표시한다.

생성부터 사용까지의 시간축

  1. 최종 DTS에서 compatible·status를 정하고 Kconfig/CMake가 driver C 파일을 포함한다.
  2. DT_INST_FOREACH_STATUS_OKAY()가 해당 인스턴스를 펼치고 DEVICE_DT_INST_DEFINE()가 정적 객체와 init entry를 정의한다.
  3. 링커가 객체·entry를 이미지에 배치한다. DEVICE_DT_GET()은 이 객체를 참조한다.
  4. 부팅 init level에서 init 함수를 호출한다. deferred 장치는 명시적 device_init()을 기다린다.
  5. 소비자가 device_is_ready()를 검사한 뒤 개별 API를 호출하고 그 결과도 확인한다.

예: node는 보이는데 device가 없다

먼저 zephyr.dts에서 node가 okay인지 확인한다. 그다음 driver C 파일을 빌드하는 Kconfig 값과 DT_DRV_COMPAT 철자를 본다. 링크 오류가 사라진 뒤에도 device_is_ready()가 false라면 init 로그와 초기화 순서를 확인한다. 링크 오류와 런타임 init 실패를 같은 'probe 실패'로 기록하면 원인 추적이 길어진다.

보드와 설정에 따라 달라지는 부분

그림은 정적 devicetree 인스턴스의 일반 경로다. 실제 driver C 파일을 포함하는 Kconfig/CMake 조건, node property를 해석하는 binding, init level·priority, 선행 clock/pinctrl 장치는 드라이버와 보드마다 다르다. 이 글의 vendor_my_uart 조각은 컴파일 완료된 실제 드라이버가 아니므로 특정 Nordic GPIO나 UART의 init 성공을 주장하지 않는다.

인스턴스별 리뷰 질문

최종 zephyr.dts에 원하는 node가 okay인가? DT_DRV_COMPAT의 compatible과 일치하는가? 해당 C 파일을 빌드하는 Kconfig가 켜졌는가? 매크로가 모든 enabled 인스턴스를 정의하는가? init에서 쓰는 provider는 더 이른 level·priority에 준비되는가? 소비자는 ready와 개별 API 반환을 각각 검사하는가?

확인 순서

west build -b <board> <app>
# build/zephyr/zephyr.dts: compatible/status 확인
# build/zephyr/.config: driver Kconfig 확인
west build -t initlevels
# 부팅 로그: init result와 device_is_ready() 확인

initlevels는 v3.7.0 공식 driver 문서가 제시한 초기화 순서 관찰 방법이다. device_is_ready() 확인은 장치를 사용하는 코드에서 실행해야 한다.

같은 기능의 두 구현을 같은 조건에서 비교합니다

추상화 비용을 확인하려면 같은 보드·클록·컴파일러·최적화·입력 부하에서 드라이버 API를 쓰는 구현과 비교 구현을 빌드합니다. 비교 구현에서도 레지스터 접근 폭·순서, 버퍼 소유권, 동기화와 오류 처리를 동일하게 유지해야 합니다. 이런 계약을 생략해 빨라진 결과를 API 호출 비용이라고 해석하지 않습니다.

최종 map 파일과 역어셈블리에서 코드 크기, 남아 있는 호출과 간접 호출을 확인하고, ISR 실행 시간과 사건 발생부터 처리 완료까지의 지연을 별도로 잽니다. inline 선언이나 소스의 계층 수만으로 비용을 판정하지 않습니다. 실제 인라인 여부와 코드 크기는 최적화 조건에 따라 달라집니다. GCC inline 설명 · Zephyr 3.7.0 드라이버 API 구조

Zephyr 3.7.0의 timing 함수로 코드 구간을 잴 때는 사용 타이머가 커널 기본 타이머와 다를 수 있음을 확인합니다. 계측·로그 설정, 스택 사용량, 반복 횟수와 관찰 최대 지연도 남깁니다. 관찰 최대값은 모든 실행 경로를 보증하는 최악 실행 시간(WCET)이 아니며, 계측한 빌드와 제품 빌드의 결과를 구분합니다. 고정 버전 시간 계측 문서

실험 기록 양식

[실험 주제] Driver Model
[Zephyr 버전] Zephyr 3.7.0 LTS3
[보드/SoC]
[west manifest revision]
[관련 Kconfig]
[관련 devicetree node]
[관찰한 원본 코드]
[예상 상태 전이]
[실제 상태 전이]
[실패 시 return/log/assert]
[latency 또는 memory 측정값]
[다음 실험]

기존 기록 필드를 유지했다. 빌드·링크의 증거와 부팅 후 init 결과, API 호출 결과를 서로 다른 줄에 적는다.

용어

용어이 글에서의 뜻
DT_DRV_COMPAT드라이버 C가 담당할 compatible을 나타내는 매크로
instance해당 compatible과 status okay에 맞는 devicetree node의 번호
device object정적으로 정의되고 링크되는 struct device
init entry부팅 중 정해진 level·priority에 초기화 함수를 실행시키는 항목
readydevice init이 성공했음을 나타내는 사용 전 검사 결과

다음 Zephyr RTOS 글