Barebox · source analysis

boot entry provider와 boot 명령

문자열, cdev, directory에서 boot entry를 수집하고 우선순위에 따라 실행하는 공통 boot framework를 읽습니다.

이 글의 v2026.06.1은 Barebox 소스 분석 기준입니다. 제품 적용 시 해당 보드의 설정과 실제 사용 버전을 원본 코드 및 빌드 결과에 대조하세요.

Series
14 / 19
Baseline
v2026.06.1
Commit
314c679eea2d
Source
common/boot.c:159-247 (발췌 범위)

boot entry provider와 boot 명령 단계에서 실제로 바뀌는 상태는 무엇인가?

entry 발견과 실행을 분리한다. provider가 만든 객체의 release callback, dry-run과 실패 후 다음 entry 이동 조건을 확인한다.

기본 실행에서 boot_entry()는 be->boot(be, verbose, dryrun)을 호출한다. 반환값이 0이면 후보 탐색을 끝내고, 0이 아니면 같은 source의 다음 entry를 시도한다. -l/-m은 이 실행 반복을 건너뛰어 목록 또는 메뉴로 간다.

객체와 주소가 놓이는 구조

그림 1. boot entry provider와 boot 명령에서 입력, 내부 상태, 출력의 경계
입력과 전제내부 상태외부로 공개되는 결과
01bootentries collection
02bootentry object
03provider data
04boot result

bootentries는 여러 provider의 결과를 담고 bootentry는 boot/release callback을 가진다. provider priority는 등록 목록의 순서이고, 각 provider가 만든 entry의 내부 순서는 그 provider가 정한다.

실행 흐름

그림 2. source 이름별 수집과 기본 boot 실행 경로
boot 인자 /
기본 source
provider를 priority
내림차순 방문
provider별 entry 생성
순서 유지해 merge
boot_entry
(verbose, dryrun)
be->boot callback
반환값 확인
0이면 종료
그 외 다음 entry

명시적 인자가 없으면 기본 source는 global.boot.default에서 읽는다. 04–06은 -l/-m 없이 실행할 때다. 한 source의 후보를 모두 시도하고도 성공하지 못하면 collection을 해제한 뒤 다음 source 이름을 수집한다. -d는 독립 표시 단계가 아니라 callback 인자이며, -l/-m은 후보를 모아 목록·메뉴로 가는 별도 경로다.

조건별 수집·실행 상태

provider priority는 provider 등록 목록의 순서다. 모든 entry를 수집한 뒤 전역 priority로 다시 정렬하는 단계는 없다.

#조건·단계소스의 동작다음 상태
01provider 등록bootentry_register_provider()가 priority 내림차순으로 provider 목록에 넣는다.이후 source 이름마다 그 순서로 방문
02source 이름 하나bootentry_create_from_name()이 provider별 임시 목록을 만들고 generate()를 호출한다.각 provider가 정한 entry 순서를 유지하며 collection 끝에 합침
03기본 실행현재 source의 entry를 순서대로 boot_entry(entry, verbose, dryrun)에 넘긴다.be->boot() callback에 dryrun 값 전달
04callback 반환0이면 종료; 0이 아니면 다음 entry. 현재 source를 소진하면 목록을 해제하고 다음 source로 간다.성공 또는 후보 소진 뒤 정리
05-l/-msource마다 실행 반복을 건너뛰고 모든 후보를 모은다. 끝에서 -l은 list, -m은 menu를 연다.menu 선택 action은 boot_entry(be, 0, 0) 호출
06일반 out 정리bootentries_free()가 entry마다 release callback을 부르고 collection을 해제한다.명령 종료

실패 코드의 종류가 기본 반복을 멈추게 하지는 않는다. boot_entry()은 -ENOMEDIUM 오류 로그를 생략하지만, 후보 전진 조건은 반환값 0 여부다. -l과 -m을 함께 지정하면 list가 우선한다. -m/-M의 잘못된 기본 선택이 음수를 돌려주는 경로는 out을 거치지 않고 직접 반환한다.

provider 순서와 명령 옵션을 그림으로 읽기

아래 그림은 provider 순서와 명령 옵션이 실행 callback에 미치는 영향을 구분한다. 실제 후보 순서와 callback 반환값은 사용 중인 보드의 boot -l 출력 및 로그로 확인한다.

그림 3. -d callback 인자와 -l/-m 표시 경로의 차이

provider는 priority 순서로 방문하고 각 provider가 정한 entry 순서를 유지한다. 이후 명령 옵션이 실행과 표시를 가른다.

기본 실행 + 선택적 -d

01현재 source의 entry 순회

02-d 횟수를 dryrun 값으로 전달

03boot_entry → be->boot(..., dryrun)

040이면 종료; 비0이면 다음 후보

05source 소진 시 다음 이름

-l 또는 -m

01모든 source에서 entry 수집

02수집 중 boot_entry 호출 안 함

03-l: bootsources_list

04-m: bootsources_menu

05menu 선택 시 boot_entry(be,0,0)

그림 4. bootentries collection과 개별 bootentry

두 열의 객체는 이름이 비슷해도 생성 시점, 사용 가능한 API와 해제 책임이 다르다.

Collection

01여러 provider 결과

02provider 순서·내부 entry 순회

03공통 release

04entry 순회 위치

05-l/-m일 때 표시

Entry

01title·path

02provider private data

03boot callback

04한 번의 결과

05개별 release

원본 코드

아래 코드는 Barebox v2026.06.1의 common/boot.c에서 159-247줄을 그대로 가져온 것이다.

commit314c679eea2d0ca847c64d1b646a1cf91225c0ecanchor · L183int boot_entry(struct bootentry *be
159	if (!global_boot_default)
160		global_boot_default = xstrdup(
161			IF_ENABLED(CONFIG_EFI_LOADER_BOOTMGR,  "efibootmgr ")
162			IF_ENABLED(CONFIG_BOOT_DEFAULTS,       "bootsource ")
163			IF_ENABLED(CONFIG_BOOT_DEFAULTS,       "storage.builtin.nonbootsource ")
164			IF_ENABLED(CONFIG_BOOT_DEFAULTS,       "storage.removable.nonbootsource ")
165			IF_ENABLED(CONFIG_NET,                 "net")
166			""
167		);
168
169	globalvar_add_simple_string("boot.default", &global_boot_default);
170	globalvar_add_simple_int("boot.watchdog_timeout",
171				 &boot_watchdog_timeout, "%u");
172	globalvar_add_simple("linux.bootargs.base", NULL);
173	global_user = xstrdup("none");
174	globalvar_add_simple_string("user", &global_user);
175
176	return 0;
177}
178late_initcall(init_boot);
179
180BAREBOX_MAGICVAR(global.boot.watchdog_timeout,
181		"Watchdog enable timeout in seconds before booting");
182
183int boot_entry(struct bootentry *be, int verbose, int dryrun)
184{
185	int ret;
186
187	pr_info("Booting entry '%s'\n", be->title);
188
189	if (IS_ENABLED(CONFIG_WATCHDOG) && boot_watchdog_timeout) {
190		boot_enabled_watchdog = watchdog_get_default();
191
192		ret = watchdog_set_timeout(boot_enabled_watchdog, boot_watchdog_timeout);
193		if (ret) {
194			pr_warn("Failed to enable watchdog: %pe\n", ERR_PTR(ret));
195			boot_enabled_watchdog = NULL;
196		}
197	}
198
199	ret = be->boot(be, verbose, dryrun);
200	if (ret && ret != -ENOMEDIUM)
201		pr_err("Booting entry '%s' failed: %pe\n", be->title, ERR_PTR(ret));
202
203	globalvar_set_match("linux.bootargs.dyn.", "");
204
205	return ret;
206}
207
208static void bootsource_action(struct menu *m, struct menu_entry *me)
209{
210	struct bootentry *be = container_of(me, struct bootentry, me);
211
212	boot_entry(be, 0, 0);
213
214	printf("Press any key to continue\n");
215
216	read_key();
217}
218
219static void bootscript_entry_release(struct bootentry *entry)
220{
221	free(entry);
222}
223
224/*
225 * bootscript_create_entry - create a boot entry from a script name
226 */
227static int bootscript_create_entry(struct bootentries *bootentries, const char *name)
228{
229	struct bootentry_script *bs;
230	enum filetype type;
231	int ret;
232
233	ret = file_name_detect_type(name, &type);
234	if (ret)
235		return ret;
236
237	if (type != filetype_sh)
238		return -EINVAL;
239
240	bs = xzalloc(sizeof(*bs));
241	bs->entry.me.type = MENU_ENTRY_NORMAL;
242	bs->entry.release = bootscript_entry_release;
243	bs->entry.boot = bootscript_boot;
244	bs->entry.path = xstrdup_const(name);
245	bs->entry.title = xstrdup_const(kbasename(bs->entry.path));
246	bs->entry.description = basprintf("script: %s", name);
247	bootentries_add_entry(bootentries, &bs->entry);

발췌 범위와 읽기 기준

원문 159-247줄에는 앞뒤 문맥이 포함됩니다. 기준 구문 int boot_entry(struct bootentry *be은 L183에 있습니다. 발췌 첫 줄을 함수 정의의 시작으로 해석하지 않습니다.

entry 발견과 실행을 분리한다. provider가 만든 객체의 release callback, dry-run과 실패 후 다음 entry 이동 조건을 확인한다.

-d도 boot_entry()를 호출하므로 무부작용 조회가 아니다. 설정된 watchdog은 callback보다 먼저 활성화될 수 있다. 명시적 source도 기본 source 변수도 없는 경우에는 do_boot()가 아무 후보도 실행하지 않고 0을 반환하는 예외도 있다.

함께 읽어야 하는 원본 코드

첫 코드 조각만으로 동작이 완성되지 않는 경우 호출 매크로, 객체 정의와 실제 실행 목록을 같은 페이지에 묶었다. 각 조각은 같은 기준 commit에서 가져왔다.

01. 문자열 이름에서 provider와 boot entry를 찾는 함수

common/boot.c 441-527줄이다.

filecommon/boot.canchor · L451int bootentry_create_from_name
441 * - a full path of a boot script
442 * - a full path of a bootloader spec entry
443 * - a device name
444 * - a cdev name
445 * - a full path of a directory containing bootloader spec entries
446 * - a full path of a directory containing bootscripts
447 * - a nfs:// path
448 *
449 * Returns the number of entries found or a negative error code.
450 */
451int bootentry_create_from_name(struct bootentries *bootentries,
452				      const char *name)
453{
454	struct bootentry_provider *p;
455	int found = 0, ret;
456	char *nfspath;
457
458	nfspath = parse_nfs_url(name);
459	if (nfspath)
460		name = nfspath;
461
462	list_for_each_entry(p, &bootentry_providers, list) {
463		BOOTENTRIES(provider_bootentries);
464
465		ret = p->generate(&provider_bootentries, name);
466		if (ret > 0)
467			found += ret;
468
469		/* We want to allow for providers to sort their bootentries as
470		 * they see fit, so they are passed an empty list above with
471		 * only their own entries and then we aggregate here
472		 */
473		bootentries_merge(bootentries, &provider_bootentries);
474	}
475
476	free(nfspath);
477
478	if (IS_ENABLED(CONFIG_COMMAND_SUPPORT) && !found) {
479		const char *path;
480
481		if (*name != '/')
482			path = basprintf("/env/boot/%s", name);
483		else
484			path = xstrdup_const(name);
485
486		ret = bootscript_scan_path(bootentries, path);
487		if (ret > 0)
488			found += ret;
489
490		free_const(path);
491	}
492
493	return found;
494}
495
496/*
497 * bootsources_menu - show a menu from an array of names
498 */
499void bootsources_menu(struct bootentries *bootentries,
500		      unsigned default_entry, int timeout)
501{
502	struct bootentry *entry;
503	struct menu_entry *back_entry;
504	int i = 1;
505
506	if (!IS_ENABLED(CONFIG_MENU)) {
507		pr_warn("no menu support available\n");
508		return;
509	}
510
511	bootentries_for_each_entry(bootentries, entry) {
512		if (!entry->me.display)
513			entry->me.display = xstrdup_const(entry->title);
514		entry->me.action = bootsource_action;
515		menu_add_entry(bootentries->menu, &entry->me);
516
517		if (i++ == default_entry)
518			bootentries->menu->selected = &entry->me;
519	}
520
521	back_entry = xzalloc(sizeof(*back_entry));
522	back_entry->display = "back";
523	back_entry->type = MENU_ENTRY_NORMAL;
524	back_entry->non_re_ent = 1;
525	menu_add_entry(bootentries->menu, back_entry);
526
527	if (i == default_entry)

내부 동작을 더 깊게 읽기

01

source와 옵션을 먼저 확정한다

do_boot()은 명시한 source 이름을 순서대로 사용한다. 인자가 없으면 global.boot.default의 문자열을 복사해 사용한다. -d는 dryrun 값을 증가시키고 -l/-m은 자동 실행 대신 후보를 모으는 경로를 선택한다.

따라서 같은 source라도 boot -d와 boot -l은 callback 호출 여부가 다르다.

02

provider 순서와 entry 수명을 구분한다

bootentry_register_provider()는 provider를 priority 순서에 넣는다. 각 source 이름을 처리할 때 provider의 generate() 결과를 임시 목록에 받은 뒤 전체 collection 끝에 합친다. provider 내부 entry 순서는 그대로 유지된다.

collection을 비울 때 bootentries_free()가 entry마다 release callback을 부른다. 등록된 provider 목록 자체를 매 명령마다 지우는 과정은 아니다.

03

후보가 없거나 소진된 경우를 본다

한 source 이름에서 entry를 얻지 못하거나 모든 callback이 비0으로 돌아오면 그 collection을 정리하고 다음 source 이름으로 진행한다. 전체 source를 마친 뒤에도 0 반환을 얻지 못하면 명령은 실패 결과로 끝난다.

boot -l로 수집 순서를 확인하고, 기본 실행 로그와 비교하면 provider 순서 문제와 callback 실패를 분리할 수 있다.

04

callback 반환값이 탐색을 결정한다

기본 실행에서 boot_entry(entry, verbose, dryrun)는 be->boot()의 반환값을 전한다. do_boot()은 그 값이 0일 때 후보 탐색을 끝내고, 비0이면 같은 collection의 다음 entry를 시도한다. -ENOMEDIUM은 오류 로그 표시의 예외일 뿐 후보 전진 조건을 바꾸지 않는다.

-d의 실제 효과는 provider callback별로 다르다. script entry의 dryrun=1은 “Would run”을 출력하고 0을 반환하므로 첫 script에서 반복이 끝날 수 있다.

05

목록·메뉴와 정리 경로를 확인한다

-l/-m은 수집 중 boot_entry()를 호출하지 않는다. 수집 후 -l은 목록을 표시하고 -m은 메뉴를 연다. 둘을 함께 지정하면 list 분기가 먼저 선택된다. 메뉴에서 사용자가 고른 entry는 boot_entry(be, 0, 0)으로 실행한다.

일반 out 경로는 collection과 기본 source 문자열 복사를 정리한다. 메뉴 기본 index가 음수인 예외 경로는 직접 반환하므로 이 정리 경로에 포함되지 않는다.

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

01

provider priority와 entry 순서는 다른 층이다

bootentry_register_provider()는 provider 목록을 priority 내림차순으로 유지한다. bootentry_create_from_name()은 각 provider에 빈 임시 collection을 주고, 그 provider가 내부 entry를 정렬할 수 있게 한 뒤 결과를 끝에 합친다. 모든 entry를 다시 전역 정렬하지 않는다.

기본 boot 명령은 source 이름 순서와 합쳐진 entry 순서대로 callback을 시도한다.

02

dry-run은 별도 표시 화면이 아니다

-d는 dryrun을 증가시키고 boot_entry()가 그 값을 be->boot()에 전달한다. script callback은 dryrun=1에서 “Would run”을 출력하고 0으로 돌아오지만, 다른 provider callback의 세부 동작은 각각 확인해야 한다.

-l/-m은 수집 중 callback 호출을 생략한다. menu에서 사용자가 entry를 선택하면 action이 boot_entry(be, 0, 0)을 호출한다.

03

반환값과 collection 수명을 같이 본다

기본 실행에서는 callback 반환값이 0이면 종료 경로로, 비0이면 다음 entry로 간다. 현재 source를 모두 소진하면 collection을 해제하고 새 collection으로 다음 source를 조사한다. 마지막 종료 경로의 bootentries_free()는 entry별 release callback을 실행한다.

-ENOMEDIUM은 boot_entry()의 오류 로그 예외지만 fallback 분기의 별도 조건은 아니다. dry-run도 provider scan을 건너뛰지 않으므로 탐색 과정의 부작용은 provider 구현을 확인한다.

객체와 수명

대상만들어지는 시점유효 범위확인할 조건
provider 등록 목록bootentry_register_provider()명령 실행 전부터 runtime 동안priority 내림차순; entry 탐색 전제
bootentries collectiondo_boot()의 bootentries_alloc()source 소진 또는 명령 종료의 free까지entry 순회 중에는 유지
bootentry와 provider data각 provider의 generate() 또는 script fallbackcollection의 bootentries_free()까지entry별 boot·release callback
기본 source 문자열 복사명시적 인자가 없을 때 global.boot.default 복사명령 종료의 free(freep)까지source 이름의 순서 보존

실패 지점과 증상

#조건관찰되는 증상먼저 볼 단계
01release callback 누락반복 boot 명령에서 entry 자원 누적bootentries_free()
02실패 callback이 0 반환다음 후보를 시도하지 않음do_boot()의 if (!ret)
03provider/entry 순서 혼동예상과 다른 후보 먼저 실행provider priority와 provider 내부 list
04-d를 목록 모드로 오해첫 callback의 0 반환 뒤 탐색 종료be->boot(..., dryrun)

오류 코드별로 기본 실행의 중단/전진 정책이 달라진다고 가정하지 않는다. 0은 종료, 비0은 다음 후보라는 조건부터 확인한다.

빌드와 실제 후보 순서를 대조한다

아래 명령은 해당 보드의 설정과 source 이름으로 바꿔 시험한다. boot와 메뉴 선택은 실제 다음 이미지를 실행할 수 있으므로 시험 장비에서 사용한다.

#목적명령 또는 계측판정 기준
01선택된 provider 구성make <board>_defconfig && make V=1해당 보드의 boot command와 provider가 실제 이미지에 포함되는지 빌드 설정·링크 map으로 확인한다.
02공통 실행 함수${CROSS_COMPILE}nm -n barebox | grep ' boot_entry$'링크된 boot_entry()를 확인한다. 이는 개별 provider 등록의 증거와 구분한다.
03수집 결과boot -l <source>source별 entry 이름·순서와 provider가 만든 순서를 기록한다. 이 모드는 수집 중 boot callback을 호출하지 않는다.
04dryrun callbackboot -d -v <source>-d 값을 callback으로 전달하는지 확인하고, script와 다른 provider의 동작을 구분한다.
05실제 후보 fallbackboot <source>의 entry별 반환값 계측0이면 종료하고 비0이면 다음 entry, source 소진 시 정리 후 다음 source로 가는지 확인한다.

직접 확인할 실험

  1. 01
    boot -l로 수집 목록 확인

    여러 source 이름을 지정해 provider별 entry 순서가 어떻게 합쳐지는지 기록한다. -l은 boot callback을 호출하지 않는다.

  2. 02
    boot -d -v의 callback 전달 확인

    script entry에서 “Would run”과 반환값을 보고, 다른 callback에서도 dryrun 인자와 부작용을 따로 관찰한다.

  3. 03
    첫 entry 실패 뒤 fallback 확인

    첫 callback이 비0을 반환하게 해 다음 entry로 진행하는지, source 소진 뒤 목록 release와 다음 source 수집이 일어나는지 기록한다.

원문과 다음 글