U-Boot · source analysis

bootstd와 bootflow 탐색

boot method와 boot device를 조합해 부팅 가능한 항목을 찾고 상태를 갱신하는 iterator를 읽습니다.

Series
15 / 22
Baseline
v2026.07
Commit
ece349ade297
Source
boot/bootflow.c:516-604 (발췌 범위)

이 글은 고정 버전의 소스 분석이다. 제품 적용 시에는 대상 보드·SoC의 errata와 보안 공지, 지원 버전을 별도로 확인해야 하며, 여기의 명령 예시는 실제 실행·부팅 검증 기록이 아니다.

bootstd와 bootflow 탐색 단계에서 실제로 바뀌는 상태는 무엇인가?

스크립트 중심의 기존 distro_bootcmd와 달리 bootflow_scan_first()/next()는 struct bootflow_iter에 현재 method·partition·bootdev와 flags·err를 둔다. struct bootflow는 그 후보를 검사한 결과다.

iterator의 dev·method·part가 현재 후보를 가리키고, 결과 bootflow의 filename·state가 어디까지 채워졌는지 구분해 읽는다. BOOTFLOWIF_ALL에서는 오류를 가진 부분 결과도 표시될 수 있다.

탐색 후보를 만드는 객체

그림 1. 탐색 순서 → 현재 후보 → 검사 결과
탐색 순서bootdev 순서 · method_order

label·설정·flags로 일반 장치 후보를 정하고, bootmeth_setup_iter_order()가 method 순서를 정한다.

현재 후보struct bootflow_iter

현재 dev·part·method와 err를 보유한다. 실패하면 다음 조합으로 갱신된다.

검사 결과struct bootflow

후보 검사에서 채워진다. 성공하면 부팅 가능한 결과가 되고, 오류 시에는 부분 상태가 남을 수 있다.

전역 bootmeth는 별도 경로

iter->doing_global이면 현재 bootdev·partition 조합 대신 bootmeth_get_bootflow()로 검사한다. dev나 label이 있으면 전역 method 제외를 요청한다. 명시적인 method 순서와 충돌하면 탐색 준비부터 실패할 수 있다.

일반 후보는 bootdev_get_bootflow()로 검사한다. 왼쪽 순서가 곧 모든 후보의 고정 순서는 아니다. bootdev hunter와 flags가 실제 장치 순서를 바꿀 수 있다.

후보 검사와 다음 후보 분기

그림 2. bootflow_scan_first()가 한 후보를 검사한 뒤 성공·진단·재탐색으로 갈라지는 지점
  1. 01 · 초기화bootflow_scan_first()

    iter와 method 순서를 준비한다. 일반 경로에서는 첫 bootdev도 선택한다.

  2. 02 · 후보 선택method · part · bootdev

    일반 method는 현재 조합을, 전역 method는 장치와 독립된 후보를 나타낸다.

  3. 03 · 검사bootflow_check()

    일반 후보는 bootdev_get_bootflow(), 전역 후보는 bootmeth_get_bootflow()를 부른다.

  • 성공 · ret == 0찾은 bootflow 반환

    호출자가 struct bootflow를 받는다. 실제 부팅은 별도 단계다.

  • 진단 · BOOTFLOWIF_ALL부분 bootflow도 반환

    BF_NO_MORE_PARTS·-ENOSYS가 아닌 검사 오류는 진단용으로 전달한다.

  • 재탐색 · 그 밖의 오류iter->err 기록

    오류에 따라 남은 partition·device를 건너뛰거나 다음 조합을 시도한다.

첫 함수 안의 자동 재탐색bootflow_scan_next() → iter_incr() → 다시 검사

일반 경로는 method, partition, bootdev 순서로 후보를 옮긴다. 전역 method는 별도 순서를 따르며, 후보가 소진되면 BF_NO_MORE_DEVICES로 끝난다.

위의 세 결과는 같은 후보에서 동시에 일어나지 않는다. 성공이나 진단 결과를 받은 호출자도 이후 bootflow_scan_next()를 호출해 탐색을 이어갈 수 있다. BOOTFLOWIF_ALL은 오류가 난 부분 결과를 볼 수 있게 하는 진단 옵션이며, 부분 결과를 부팅 성공으로 표시하지 않는다.

단계별 입력과 출력

한 후보를 검사한 결과에 따라 반환하거나 다음 후보를 찾는 지점을 구분했다. BOOTFLOWIF_ALL은 오류 결과도 보고할 수 있으므로 성공 경로와 따로 읽는다.

탐색 단계별 입력과 출력
#단계진입 시 신뢰할 상태결과 / 분기다음 소비자
01bootflow_scan_first()dev·label·flagsiter 초기화, method 순서와 첫 후보 선택bootflow_check()
02bootflow_check()현재 method와 일반 경로의 bootdev·partition일반 method는 bootdev_get_bootflow(), 전역 method는 bootmeth_get_bootflow() 호출bootflow_scan_first()/next()
03검사 성공ret == 0찾은 struct bootflow 반환scan 호출자
04진단 모드의 검사 오류BOOTFLOWIF_ALL과 특별 종료 오류가 아닌 ret부분 bootflow와 오류 반환scan 호출자의 진단 출력
05그 밖의 검사 오류iter->err = retbootflow_scan_next()의 iter_incr()가 다음 후보 선택다음 bootflow_check() 또는 후보 소진 반환

BF_NO_MORE_PARTS와 -ENOSYS는 BOOTFLOWIF_ALL에서도 부분 결과 반환 조건에서 제외된다. 로그를 읽을 때 현재 후보의 오류인지 후보 전체의 소진인지 구분한다.

원본 코드

아래 코드는 U-Boot v2026.07의 boot/bootflow.c에서 516-604줄을 그대로 가져온 것이다.

commitece349ade2973e220f524ce59e59711cc919263fanchor · L540int bootflow_scan_first(struct udevice *dev
516	ret = bootdev_get_bootflow(dev, iter, bflow);
517
518	/* If we got a valid bootflow, return it */
519	if (!ret) {
520		log_debug("Bootdev '%s' part %d method '%s': Found bootflow\n",
521			  dev->name, iter->part, iter->method->name);
522		return 0;
523	}
524
525	/* Unless there is nothing more to try, move to the next device */
526	if (ret != BF_NO_MORE_PARTS && ret != -ENOSYS) {
527		log_debug("Bootdev '%s' part %d method '%s': Error %d\n",
528			  dev->name, iter->part, iter->method->name, ret);
529		/*
530		 * For 'all' we return all bootflows, even
531		 * those with errors
532		 */
533		if (iter->flags & BOOTFLOWIF_ALL)
534			return log_msg_ret("all", ret);
535	}
536
537	return log_msg_ret("check", ret);
538}
539
540int bootflow_scan_first(struct udevice *dev, const char *label,
541			struct bootflow_iter *iter, int flags,
542			struct bootflow *bflow)
543{
544	int ret;
545
546	if (dev || label)
547		flags |= BOOTFLOWIF_SKIP_GLOBAL;
548	bootflow_iter_init(iter, flags);
549
550	/*
551	 * Set up the ordering of bootmeths. This sets iter->doing_global and
552	 * iter->first_glob_method if we are starting with the global bootmeths
553	 */
554	ret = bootmeth_setup_iter_order(iter, !(flags & BOOTFLOWIF_SKIP_GLOBAL));
555	if (ret)
556		return log_msg_ret("obmeth", -ENODEV);
557
558	/* Find the first bootmeth (there must be at least one!) */
559	iter->method = iter->method_order[iter->cur_method];
560
561	if (!IS_ENABLED(CONFIG_BOOTMETH_GLOBAL) || !iter->doing_global) {
562		struct udevice *dev = NULL;
563		int method_flags;
564
565		ret = bootdev_setup_iter(iter, label, &dev, &method_flags);
566		if (ret)
567			return log_msg_ret("obdev", -ENODEV);
568
569		bootflow_iter_set_dev(iter, dev, method_flags);
570	}
571
572	if (IS_ENABLED(CONFIG_BOOTMETH_GLOBAL)) {
573		iter->methods_done |= BIT(iter->cur_method);
574		log_debug("methods_done now %x\n", iter->cur_method);
575	}
576	ret = bootflow_check(iter, bflow);
577	if (ret) {
578		log_debug("check - ret=%d\n", ret);
579		if (ret != BF_NO_MORE_PARTS && ret != -ENOSYS) {
580			if (iter->flags & BOOTFLOWIF_ALL)
581				return log_msg_ret("all", ret);
582		}
583		iter->err = ret;
584		ret = bootflow_scan_next(iter, bflow);
585		if (ret)
586			return log_msg_ret("get", ret);
587	}
588
589	return 0;
590}
591
592int bootflow_scan_next(struct bootflow_iter *iter, struct bootflow *bflow)
593{
594	int ret;
595
596	do {
597		ret = iter_incr(iter);
598		log_debug("iter_incr: ret=%d\n", ret);
599		if (ret == BF_NO_MORE_DEVICES)
600			return log_msg_ret("done", ret);
601
602		if (!ret) {
603			if (IS_ENABLED(CONFIG_BOOTMETH_GLOBAL)) {
604				iter->methods_done |= BIT(iter->cur_method);

발췌 범위와 읽기 기준

원문 516-604줄에는 앞뒤 문맥이 포함됩니다. 기준 구문 int bootflow_scan_first(struct udevice *dev은 L540에 있습니다. 발췌 첫 줄을 함수 정의의 시작으로 해석하지 않습니다.

발췌에는 bootflow_check()의 끝과 bootflow_scan_first() 전체, bootflow_scan_next()의 앞부분이 나온다. 다음 후보 선택과 정리 동작은 같은 v2026.07 파일의 iter_incr()·bootflow_iter_uninit()·bootflow_free() 정의까지 이어서 확인한다.

내부 동작을 더 깊게 읽기

01

첫 후보의 범위를 정한다

bootflow_scan_first()는 dev 또는 label이 주어지면 BOOTFLOWIF_SKIP_GLOBAL을 설정한다. 이어 bootflow_iter_init()으로 iterator를 초기화하고 bootmeth_setup_iter_order()로 method 순서를 마련한다.

이 고정 구현의 일반 경로에는 인자와 이름이 같은 지역 dev = NULL이 있다. 인자로 받은 장치 포인터가 그대로 선택되는 것이 아니라, bootdev_setup_iter(iter, label, ...)가 label·설정·탐색 순서에 따라 첫 bootdev를 찾는다. 따라서 dev 인자의 전역 method 제외 효과와 실제 장치 선택은 구분해야 한다. 전역 method 경로에서는 iterator의 현재 bootdev 조합 없이 검사한다.

CONFIG_BOOTSTD_FULL에서 명시적인 bootmeth_order가 있으면 include_global == false를 -EPERM으로 거절한다. 이 준비 오류를 bootflow_scan_first()는 -ENODEV로 바꿔 반환한다. 자동으로 순서를 만드는 경우와 구분한다.

02

iterator와 결과 객체의 소유권을 나눈다

bootflow_iter_init()은 탐색 상태를 초기화하고, bootmeth_setup_iter_order()가 method 순서를 준비한다. 이 배열은 탐색이 끝난 뒤 bootflow_iter_uninit()에서 해제한다.

반면 현재 후보의 struct bootflow에는 method가 찾은 이름·파일명·버퍼가 들어갈 수 있다. 결과를 직접 소유한 호출자는 사용 후 bootflow_free()로 소유 필드를 정리한다. 이 함수는 struct bootflow 자체를 해제하지 않고, BOOTFLOWF_STATIC_BUF가 설정된 buf도 해제하지 않는다.

명령 경로는 bootstd_add_bootflow()로 구조체 값을 저장 목록에 복사한다. 문자열과 버퍼를 깊게 복사하는 것이 아니므로, 추가 성공 뒤 임시 bflow의 필드를 즉시 해제하면 저장 목록이 같은 포인터를 참조하게 된다. 이 경로의 필드 정리는 저장 목록 제거 쪽에 맡기며, iterator의 method 배열 정리와 별개다.

03

다음 후보의 증가 순서를 읽는다

bootflow_scan_next()는 iter_incr()로 다음 조합을 고른 뒤 다시 검사한다. 일반 경로에서는 method를 먼저 옮기고, 소진되면 partition, 그다음 bootdev로 넘어간다. iter->max_part는 실제 partition 탐색 중 늘어날 수 있다.

BF_NO_MORE_PARTS가 기록되어도 먼저 남은 method를 확인한다. method가 소진된 뒤 다음 partition 증가를 건너뛰며, BF_NO_MORE_DEVICES는 탐색 종료를 뜻한다. 전역 method와 단일 장치·label flags에는 별도 분기가 있다.

04

검사 반환값과 부분 결과를 분리한다

bootflow_check()가 0을 돌려주면 발견한 bootflow를 반환한다. 오류라면 BF_NO_MORE_PARTS와 -ENOSYS를 먼저 구분하고, BOOTFLOWIF_ALL이 설정된 다른 오류는 부분 bootflow와 함께 진단용으로 반환한다.

첫 함수는 ALL 진단 오류를 iter->err 대입 전에 반환하지만, bootflow_scan_next()는 해당 오류를 먼저 기록한 뒤 반환한다. 그 밖의 검사 오류도 iter->err에 남겨 다음 후보 진행에 사용한다. 부분 결과를 부팅 가능한 READY 결과와 혼동하지 않는다.

05

탐색 반환과 실제 부팅을 구분한다

bootflow_scan_first()/next()는 발견 결과 또는 오류를 호출자에게 돌려준다. bootflow scan -l은 스캔 중 목록을 보여 주지만 -b를 더한 bootflow scan -lb는 유효한 bootflow의 부팅을 실제로 시도한다.

스캔 결과만 확인할 때는 -b를 쓰지 않는다. 오류 후보까지 보려면 bootflow scan -al 뒤 bootflow list -e를 사용한다.

구현을 읽을 때 놓치기 쉬운 부분

01

일반 탐색은 method·partition·bootdev 순서로 후보를 옮긴다

일반 경로에서 iter_incr()는 현재 bootdev의 method를 먼저 바꾸고 partition과 다음 bootdev로 진행한다. bootdev 우선순위·label·flags가 후보 범위를 제한하고, 전역 bootmeth는 장치와 독립된 순서로 검사된다.

network와 block, extlinux와 EFI 같은 method가 함께 있을 때 각 후보의 return code가 다음 조합 진행 여부를 결정한다.

02

bootflow는 발견 결과와 실행 가능한 상태를 함께 가진다

media, partition, filename, OS name, buffer와 state가 단계적으로 채워진다. scan 중 임시 allocation과 최종 bootflow가 소유하는 문자열·buffer를 구분해 반복 scan에서 leak가 없는지 본다.

READY가 되기 전의 bootflow도 진단을 위해 list에 남을 수 있다. 표시된 entry 수와 실제 boot 가능한 수를 구분한다.

03

탐색 지연은 후보별 출력과 순서로 좁힌다

장치 탐지, 파일 검색, network 응답은 서로 다른 지연 원인이다. bootflow scan -al로 후보가 표시되는 bootdev·method·state 순서를 보고, bootflow list -e로 수집된 후보의 상세 error를 확인한다.

첫 성공에서 중단하는 호출 정책과 후보를 모으는 명령 경로를 구분한다. 이 버전의 명령 반복은 -ENODEV 또는 최대 1000회 조건으로 끝나며, 무제한 전수 수집을 보장하지 않는다.

객체와 수명

객체별 수명과 정리 주체
대상만들어지는 시점유효 범위소비자와 정리 조건
struct bootflow_iterbootflow_iter_init()첫 탐색부터 이어지는 bootflow_scan_next() 호출 동안bootflow_check()와 iter_incr()가 사용한다. 호출자는 끝에 bootflow_iter_uninit()으로 정리한다.
iter->method_orderbootmeth_setup_iter_order()iterator가 살아 있는 동안현재 method 선택에 쓰인다. bootflow_iter_uninit()이 배열을 해제한다.
struct bootflow현재 후보를 bootdev_get_bootflow() 또는 전역 bootmeth_get_bootflow()로 검사할 때직접 소유한 결과를 정리하거나 저장 목록 소유로 넘길 때까지scan 호출자가 소비하며, READY 결과는 이후 bootflow_boot()이 method에 전달할 수 있다. 오류 시 부분 상태일 수도 있다.
bflow->name·fname·bufbootmeth가 후보를 읽고 결과 필드를 채울 때해당 struct bootflow의 수명 동안직접 소유한 결과 또는 저장 목록 제거 경로가 bootflow_free()로 필드를 해제한다. 구조체 자체는 별도다. BOOTFLOWF_STATIC_BUF가 있으면 buf는 직접 해제하지 않는다.

실패 지점과 증상

실패 조건과 관찰 위치
#조건관찰되는 증상먼저 볼 단계
01bootdev·bootmeth 순서 불일치예상한 후보가 뒤에 나타남bootdev list·bootmeth list와 boot_targets·bootmeths
02기본 scan만 사용실패한 부분 bootflow가 목록에서 빠짐bootflow scan -al 뒤 bootflow list -e
03BF_NO_MORE_PARTS·BF_NO_MORE_DEVICES현재 bootdev의 남은 partition 또는 전체 후보 탐색 종료iter->err와 iter_incr() 분기

ret == 0의 READY 결과, BOOTFLOWIF_ALL의 오류 부분 결과, 다음 후보를 찾는 iter->err를 나눠 본다. -b는 표시 옵션이 아니라 실제 부팅 시도다.

소스 밖에서 확인할 증거

고정 소스의 분기와 대상 보드의 탐색 결과를 같은 순서로 대조한다. 옵션 처리의 직접 조건은 CONFIG_CMD_BOOTFLOW_FULL이다. 대상 빌드에서 이 설정을 먼저 확인해야 하며, 기능이 제한된 설정의 bootflow scan은 첫 유효 후보의 부팅까지 진행할 수 있다.

보드 검증에 필요한 증거
#목적명령 또는 계측판정 기준
01기능 설정grep -E '^CONFIG_(BOOTSTD_FULL|CMD_BOOTFLOW_FULL|BOOTMETH_GLOBAL)=' .config전체 bootflow 명령과 전역 method 경로가 활성화됐는지 확인한다.
02함수 포함${CROSS_COMPILE}nm -n u-boot | grep ' bootflow_scan_first$'실제 빌드 이미지에 해당 함수 symbol이 있는지 확인한다.
03탐색 순서bootdev list; bootmeth list; printenv boot_targets bootmeths장치와 method 순서 및 환경 설정을 대조한다.
04부분 결과와 오류bootflow scan -al; bootflow list -e-a로 오류 후보를 포함하고 state·error를 비교한다.
05실제 부팅 경계bootflow scan -lb-l은 목록 표시, -b는 유효 후보의 실제 부팅 시도임을 구분한다.

직접 확인할 실험

  1. 01
    오류 후보까지 목록으로 보기

    bootflow scan -al 뒤 bootflow list -e를 실행해 READY 결과와 오류가 있는 부분 결과의 state·error를 나눠 기록한다. 두 명령에는 실제 부팅을 뜻하는 -b가 없다.

  2. 02
    전체 검색과 장치 지정 검색 비교

    전체 bootflow scan -al 결과를 기록하고, 보드에 존재하는 이름으로 bootflow scan -al <bootdev>를 반복한다. 명시적인 label은 전역 bootmeth 제외를 요청한다. 명시적 method 순서가 있는 설정에서는 준비 오류로 끝날 수 있으므로, 반환값과 method 순서를 함께 기록한다.

  3. 03
    표시와 부팅의 경계 확인

    결과만 보려면 bootflow scan -l을 사용한다. bootflow scan -lb의 -b는 유효 후보를 실제로 부팅하므로, 부팅 자체를 검증할 때에만 실행한다.

원문과 다음 글

추가 구현 근거: iterator 초기화와 정리 · 다음 method·partition·bootdev 선택 · 후속 탐색과 결과 필드 정리 · 명시적 method 순서와 전역 제외 충돌 · label과 일반 장치 선택 · 저장 목록으로 복사와 필드 제거 · 옵션·1000회 제한·부팅 실행 경계.