인스턴스 생성과 사용 가능 시점
Zephyr 3.7.0 드라이버는 enabled devicetree node와 driver C 파일의 인스턴스 매크로가 만나는 지점에서 정적 장치 객체를 정의한다. 그 뒤 부팅 중 init 함수를 실행한다. status = "okay", 객체의 링크 성공, device_is_ready()는 각각 다른 질문에 답한다.
위쪽은 컴파일·링크 시 객체가 만들어지는 경로다. 아래쪽은 부팅 후 init 결과와 API 사용 경로다. 작은 화면에서는 그림을 좌우로 스크롤해 읽을 수 있다.
| 시점 | 관찰 대상 | 잘못 혼동하기 쉬운 것 |
|---|---|---|
| 빌드 입력 | compatible, status, Kconfig | node가 있어도 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.h | enabled compatible 인스턴스 반복: 4518–4531행 |
| include/zephyr/device.h | DEVICE_DT_DEFINE / INST_DEFINE: 165–213행; GET의 링크 계약: 231–246행 |
| include/zephyr/device.h | device_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의 반환값도 별도로 처리한다.
원본 매크로의 실제 연결
#define DEVICE_DT_INST_DEFINE(inst, ...) \
DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
#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 false | init 로그 / 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와 같은 호출 재시도 계약으로 읽지 않는다. 두 운영체제에서 “장치 없음”이 빌드·링크·부팅 중 어느 시점에 드러나는지 먼저 표시한다.
생성부터 사용까지의 시간축
- 최종 DTS에서 compatible·status를 정하고 Kconfig/CMake가 driver C 파일을 포함한다.
DT_INST_FOREACH_STATUS_OKAY()가 해당 인스턴스를 펼치고DEVICE_DT_INST_DEFINE()가 정적 객체와 init entry를 정의한다.- 링커가 객체·entry를 이미지에 배치한다.
DEVICE_DT_GET()은 이 객체를 참조한다. - 부팅 init level에서 init 함수를 호출한다. deferred 장치는 명시적
device_init()을 기다린다. - 소비자가
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에 초기화 함수를 실행시키는 항목 |
| ready | device init이 성공했음을 나타내는 사용 전 검사 결과 |