U-Boot · source analysis

FDT scan과 ofnode

U-Boot v2026.07의 dm_scan_fdt_node()가 어느 자식만 살피고, 어떤 노드는 건너뛰며, 언제 첫 오류를 반환하는지 원문으로 따라갑니다.

U-Boot v2026.07은 이 글의 코드 분석 기준입니다. 보드의 DT·Kconfig·SPL 구성에 따라 실제 bind 결과가 달라집니다.

Series
11 / 22
Baseline
v2026.07
Commit
ece349ade297
Source
drivers/core/root.c:172-260 (발췌 범위)

DT 노드가 보이는데 왜 dm tree에는 없을까?

dm_scan_fdt_node()는 전달받은 부모 노드의 직계 자식을 검사한다. status로 비활성화된 자식을 건너뛰고, 나머지는 lists_bind_fdt()에 맡긴다. DT에 존재한다는 사실만으로 udevice가 생기지는 않는다.

이 글의 결과는 bind까지다. 장치가 동작하도록 만드는 probe와 커널에 넘길 working FDT 편집은 별개의 경로다. 표와 그림은 U-Boot v2026.07 root.c와 lists.c 기준이다.

한 번의 호출은 한 부모의 자식만 본다

그림 1. 같은 control FDT를 읽는 세 스캔 입구
control FDT · ofnode
A · ROOTdm_scan_fdt()

gd->dm_root와 ofnode_root()를 넘긴다. 루트의 직계 자식만 이번 반복에서 살핀다.

B · EXTENDEDdm_extended_scan()

A가 성공한 뒤 /chosen, /clocks, /firmware, /reserved-memory 각각의 직계 자식을 추가로 스캔한다.

C · DEVICEdm_scan_fdt_dev(dev)

별도 호출 시 dev_ofnode(dev)의 직계 자식을 dev 아래에 bind한다. GD_FLG_RELOC로 필터 인자를 정한다.

A·B가 전체 DT를 재귀 순회하는 것은 아니다. B는 A가 오류를 반환하면 실행되지 않고, C는 해당 부모 장치 경로에서 호출되어야 한다.

근거: root.c L196–260의 dm_scan_fdt_node, dm_scan_fdt_dev, dm_scan_fdt, dm_extended_scan.

driver model 초기화부터 FDT bind까지

그림 2. dm_init_and_scan(pre_reloc_only)에서 일반 driver-model 스캔이 실행될 때의 순서
  1. 01dm_init()

    driver model 루트와 uclass 목록을 준비한다.

  2. 02dm_scan_plat()

    driver_info 경로를 bind한다. FDT 노드와 구분한다.

  3. 03 · OF_REALdm_extended_scan()

    먼저 루트 직계 자식, 다음 네 특수 경로의 자식을 살핀다.

  4. 04dm_scan_other()

    보드가 재정의할 수 있는 별도 경로다.

스캔 성공bind된 장치가 남을 수 있다

각 장치의 probe 완료를 뜻하지 않는다. 필요하면 별도 device_probe() 또는 dm_autoprobe() 경로를 확인한다.

스캔 실패해당 단계에서 반환

dm_scan_fdt_node()는 형제 노드를 계속 보며 첫 bind 오류를 기억하지만, 상위 dm_extended_scan()은 비영 오류를 받으면 다음 확장 경로로 가지 않는다.

CONFIG_OF_PLATDATA_INST가 활성화된 빌드는 dm_init_and_scan()에서 이 dm_scan() 경로를 건너뛴다. 근거: root.c의 dm_scan()·dm_init_and_scan()와 원본 코드 L205–260.

노드 하나에서 실제로 일어나는 일

관문v2026.07 소스 조건이번 스캔의 결과근거
부모 ofnode유효하지 않음자식 반복 없이 0 반환root.c L202–203
직계 자식ofnode_is_enabled(node) 거짓그 자식을 건너뛰고 다음 형제 진행L205–213
compatible속성 없음 / 읽기 오류없으면 0으로 미bind; 실제 DT 읽기 오류는 음수 반환lists.c lists_bind_fdt()
driver matchcompatible 문자열을 순서대로 검사, 일치 없음그 노드는 미bind, 함수는 0 반환lists.c driver_check_compatible()
pre-relocationpre_reloc_only 참이고 노드 표시와 driver flag 둘 다 없음일치 driver가 있어도 이번 단계에서는 미bind, 0 반환lists.c ofnode_pre_reloc / DM_FLAG_PRE_RELOC
bind 시도device_bind_with_driver_data() 성공 / -ENODEV / 그 외 오류성공이면 udevice 생성; -ENODEV면 다른 driver 후보; 그 외 음수는 상위로 전달lists.c lists_bind_fdt()
형제 반복bind 오류를 만남첫 오류를 ret에 보관하고 형제 반복을 계속한 뒤 반환root.c L214–224

0 반환은 모든 노드가 bind되었다는 뜻이 아니다. 미지원·필터 제외 노드도 정상적인 0 경로가 있다.

같은 DT 노드의 두 가지 결과

그림 3. enabled 자식이 udevice에 이르는 관문
01 · root.cstatus 유효?

비활성 노드면 즉시 다음 형제로 간다. 이 검사에서는 driver 검색도 하지 않는다.

02 · lists.ccompatible 획득?

없으면 0으로 끝난다. 속성 읽기 오류이면 음수를 돌려준다.

03 · lists.c문자열과 driver가 일치?

compatible 문자열 순서로 driver의 of_match를 찾는다. 후보가 없으면 미bind다.

04 · lists.c이 단계에서 허용?

pre_reloc_only면 노드의 pre-reloc 표시 또는 driver flag가 필요하다.

bind 성공 → udevice · bind 거부 -ENODEV → 다른 driver 후보 · 다른 bind 오류 → 첫 오류를 상위 스캔에 기록.

이 그림은 device_bind_with_driver_data()까지다. 위 후보 재탐색은 이 스캔처럼 drv=NULL인 호출에 한한다. dm tree의 Probed 열은 별도로 확인한다.

그림 4. DT에 있는 노드와 실제 활성 장치 사이의 간격
SOURCEcontrol FDT node

U-Boot 내부 설정이다. 커널용 working FDT와 구분해 본다.

BINDudevice 등록

driver와 node를 연결한다. 부모 driver의 bind 동작은 자식 스캔 범위를 바꿀 수 있다.

PROBE장치 사용 준비

bind와 별개다. dm tree의 Probed 표시에 차이가 난다.

fdt print의 기본 대상은 working FDT다. 인자 주소 없이 fdt addr -c만 실행하면 control FDT 주소를 표시하며 working FDT를 전환하지 않는다. 주소를 추가하는 설정 명령이나 control FDT 수정은 이 글의 범위가 아니다.

원본 코드

아래 코드는 U-Boot v2026.07의 drivers/core/root.c에서 172-260줄을 그대로 가져온 것이다.

commitece349ade2973e220f524ce59e59711cc919263fanchor · L196static int dm_scan_fdt_node(struct udevice *parent
172	}
173
174	ret = lists_bind_drivers(DM_ROOT_NON_CONST, pre_reloc_only);
175	if (ret == -ENOENT) {
176		dm_warn("Some drivers were not found\n");
177		ret = 0;
178	}
179
180	return ret;
181}
182
183#if CONFIG_IS_ENABLED(OF_REAL)
184/**
185 * dm_scan_fdt_node() - Scan the device tree and bind drivers for a node
186 *
187 * This scans the subnodes of a device tree node and and creates a driver
188 * for each one.
189 *
190 * @parent: Parent device for the devices that will be created
191 * @node: Node to scan
192 * @pre_reloc_only: If true, bind only drivers with the DM_FLAG_PRE_RELOC
193 * flag. If false bind all drivers.
194 * Return: 0 if OK, -ve on error
195 */
196static int dm_scan_fdt_node(struct udevice *parent, ofnode parent_node,
197			    bool pre_reloc_only)
198{
199	int ret = 0, err = 0;
200	ofnode node;
201
202	if (!ofnode_valid(parent_node))
203		return 0;
204
205	for (node = ofnode_first_subnode(parent_node);
206	     ofnode_valid(node);
207	     node = ofnode_next_subnode(node)) {
208		const char *node_name = ofnode_get_name(node);
209
210		if (!ofnode_is_enabled(node)) {
211			pr_debug("   - ignoring disabled device\n");
212			continue;
213		}
214		err = lists_bind_fdt(parent, node, NULL, NULL, pre_reloc_only);
215		if (err && !ret) {
216			ret = err;
217			dm_warn("%s: ret=%d\n", node_name, ret);
218		}
219	}
220
221	if (ret)
222		dm_warn("Some drivers failed to bind\n");
223
224	return ret;
225}
226
227int dm_scan_fdt_dev(struct udevice *dev)
228{
229	return dm_scan_fdt_node(dev, dev_ofnode(dev),
230				gd->flags & GD_FLG_RELOC ? false : true);
231}
232
233int dm_scan_fdt(bool pre_reloc_only)
234{
235	return dm_scan_fdt_node(gd->dm_root, ofnode_root(), pre_reloc_only);
236}
237
238static int dm_scan_fdt_ofnode_path(const char *path, bool pre_reloc_only)
239{
240	ofnode node;
241
242	node = ofnode_path(path);
243
244	return dm_scan_fdt_node(gd->dm_root, node, pre_reloc_only);
245}
246
247int dm_extended_scan(bool pre_reloc_only)
248{
249	int ret, i;
250	const char * const nodes[] = {
251		"/chosen",
252		"/clocks",
253		"/firmware",
254		"/reserved-memory",
255	};
256
257	ret = dm_scan_fdt(pre_reloc_only);
258	if (ret) {
259		dm_warn("dm_scan_fdt() failed: %d\n", ret);
260		return ret;

발췌 범위와 읽기 기준

위 89줄은 U-Boot v2026.07 commit ece349ade2973e220f524ce59e59711cc919263f의 drivers/core/root.c L172–260 그대로다. L196이 dm_scan_fdt_node()의 시작이며, L172–181은 앞 함수 dm_scan_plat()의 끝이다. L260에서 dm_extended_scan() 본문은 끝나지 않는다.

따라서 확장 경로의 후속 반복과 lists_bind_fdt() 내부 조건은 별도 root.c 원문·lists.c 원문으로 대조했다. 아래 표는 인용하지 않은 부분을 의사 코드인 양 제시하지 않는다.

반환값을 따라 읽는 순서

01

부모가 유효하지 않으면 조용히 끝난다

dm_scan_fdt_node()는 ofnode_valid(parent_node)가 거짓일 때 0을 반환한다(L202–203). 확장 스캔에서 경로가 없더라도 이 함수 자체는 자식 반복을 시작하지 않는다. 0을 장치 발견의 증거로 읽을 수 없는 첫 이유다.

02

형제 한 개씩 검사한다

ofnode_first_subnode()와 ofnode_next_subnode() 반복은 전달된 부모의 직접 자식을 돈다(L205–207). disabled 자식은 lists_bind_fdt() 호출 전에 건너뛴다(L210–214).

03

후보가 없거나 지금 제외되어도 정상 0이다

lists_bind_fdt()는 compatible 속성이 없거나 일치 driver가 없으면 미bind 상태로 0을 반환한다. pre_reloc_only일 때 ofnode_pre_reloc(node)와 DM_FLAG_PRE_RELOC이 모두 거짓인 경우도 0이다. 이 조건은 matched driver를 찾은 뒤 적용된다.

04

첫 bind 오류를 기억하고 계속한다

lists_bind_fdt()에서 음수 오류가 오면 dm_scan_fdt_node()는 첫 오류만 ret에 보관하고 현재 반복을 중단하지 않는다(L214–224). 호출자가 받은 오류와 이미 bind된 형제 장치가 함께 존재할 수 있다.

05

상위 스캔에서는 오류가 경로를 자른다

dm_extended_scan()은 dm_scan_fdt() 오류 시 네 확장 경로로 진행하지 않는다. 각 확장 경로에서도 오류를 받으면 반환한다. 따라서 어느 형제까지 검사했는지와 어느 추가 경로까지 도달했는지를 나눠 기록해야 한다.

dm_autoprobe()의 0 반환 역시 모든 자식의 성공을 증명하지 않는다. 이 고정 버전의 dm_probe_devices()는 현재 장치의 probe 오류를 반환하지만, 자식에 대한 재귀 호출의 반환값은 검사하지 않는다. 장치별 flag와 오류 로그를 따로 확인해야 한다.

위 -ENODEV 후보 계속 탐색은 이 글의 dm_scan_fdt_node()가 lists_bind_fdt(..., drv=NULL, ...)로 호출하는 경우다. 특정 driver를 지정한 별도 호출에서는 !drv 조건이 성립하지 않아 같은 오류가 그대로 반환된다. 스캔 성공 뒤의 조건부 DM_EVENT 알림 오류도 dm_init_and_scan()의 최종 반환값과 구분해 기록한다.

진단할 때 혼동하기 쉬운 경계

01

DT 구성과 compile된 driver가 모두 필요하다

control FDT의 compatible 문자열은 driver를 새로 만들어 주지 않는다. matching U_BOOT_DRIVER가 빌드에 포함되어야 한다. 노드의 문자열 순서도 후보 선택 순서에 영향을 준다. dm drivers와 보드의 DT를 함께 확인한다.

02

pre-relocation은 단계별 선택이다

루트 코드의 pre_reloc_only 인자가 lists_bind_fdt()까지 전달된다. 노드의 pre-reloc 표시나 driver의 DM_FLAG_PRE_RELOC에 따라 이번 단계에서 bind할지 결정한다. SPL에는 DT의 일부만 포함될 수도 있으므로 이미지별 DT·Kconfig를 함께 본다.

03

bind와 probe를 따로 측정한다

dm tree에 나타난 장치가 모두 활성화된 것은 아니다. 별도 사용 시점의 device_probe()와 DM_FLAG_PROBE_AFTER_BIND 관련 dm_autoprobe()를 구분한다. 부모 driver의 bind callback이 자식을 스캔하는 경우도 별도로 추적한다.

서로 다른 객체를 하나로 세지 않는다

대상이 글에서의 역할존재만으로 알 수 없는 것
control FDT / ofnodeofnode_root() 또는 부모 장치의 dev_ofnode()가 스캔 입력노드가 실제로 bind·probe되었는지
driver_infodm_scan_plat()가 사용하는 별도 platform-data 경로이 글의 DT 노드에서 만들어진 객체인지
struct driver / of_matchlists_bind_fdt()가 compatible 후보를 비교해당 노드가 pre-relocation 조건을 통과했는지
struct udevice성공한 device_bind_with_driver_data()의 결과probe가 끝나 실제 사용 준비가 되었는지
working FDT운영체제에 전달할 별도 DT 경로U-Boot의 control FDT 스캔 결과와 동일한지

보이지 않는 노드와 실제 오류를 가른다

관찰가능한 소스 경로첫 확인 지점
DT에는 있는데 dm tree에는 없음disabled, 직계 자식 범위 밖, compatible 없음/불일치, pre-reloc 제외control FDT의 node path·status·compatible와 해당 스캔 부모
스캔이 음수를 반환DT 속성 읽기 오류 또는 bind의 -ENODEV 이외 오류첫 dm_warn("%s: ret=%d")와 lists_bind_fdt() 로그
일부 장치만 남고 확장 경로 중단형제 반복 중 첫 오류 보관 후 상위 dm_extended_scan() 조기 반환첫 오류가 난 부모와 그 뒤 네 특수 경로 도달 여부
tree에는 있는데 장치를 못 씀bind 성공, probe 미실행 또는 probe 오류dm tree의 Probed 열과 해당 driver의 probe 로그

주소를 생략한 fdt addr -c의 조회 전용 분기는 고정 cmd/fdt.c에서 확인했다. 아래 명령을 이 검토 과정에서 실제 보드에 실행하지는 않았다.

보드에서 비교할 읽기 전용 자료

명령 가용성은 보드 빌드 설정에 달려 있다. control FDT를 수정하지 말고, 같은 부팅 단계의 DT와 driver model 출력을 비교한다.

대상명령 또는 관찰판정 포인트
빌드 설정grep -E 'CONFIG_(OF_CONTROL|OF_LIVE|OF_PLATDATA(_INST)?|DM)=' .configFDT 스캔·live tree·platform-data 경로의 빌드 조건
control FDT 주소fdt addr -cfdt addr 기본 working FDT와 혼동하지 않음
bind된 장치dm tree; dm drivers; dm uclassnode 이름·driver·uclass와 Probed 열을 따로 기록
기준 소스root.c L196–260와 lists.c lists_bind_fdt()첫 오류와 0 반환의 여러 의미를 코드로 대조

한 노드를 추적하는 순서

  1. 01
    스캔 부모를 먼저 정한다

    문제 노드가 루트 직계 자식인지, 네 확장 경로의 직계 자식인지, 특정 bound 부모의 자식인지 표시한다. 현재 단계의 control DT를 사용한다.

  2. 02
    미bind의 0 경로를 소거한다

    status, compatible 속성, compile된 driver의 of_match, pre_reloc_only와 노드/driver flag를 차례로 확인한다.

  3. 03
    bind와 probe를 따로 기록한다

    dm tree에서 해당 장치와 Probed 열을 비교한다. 음수 오류가 있다면 첫 오류가 난 형제와 확장 경로의 중단 위치를 함께 남긴다.

원문과 다음 글