Barebox · source analysis

BAREBOX_CMD_START와 shell 명령 등록

빌드 때의 명령 기술자와 실행 때의 인자 배열은 다른 수명을 가진다. Barebox가 둘을 연결하는 실제 코드를 따라간다.

v2026.06.1은 이 글의 Barebox 소스 분석 기준이다. 실제 보드의 CONFIG_CMD_BOOT와 셸 설정은 해당 빌드 결과로 확인한다.

Series
13 / 19
Baseline
v2026.06.1
Commit
314c679eea2d
Source
commands/boot.c:222-252 (발췌 범위)

명령 기술자는 언제 등록되고, argv는 언제 생기는가?

BAREBOX_CMD_START(boot)은 빌드 시 정적 struct command와 링커 목록의 포인터를 만든다. CONFIG_CMD_BOOT가 켜져 boot.o가 포함되어야 이 항목이 이미지에 존재한다.

시작 시 init_command_list()가 링커 목록을 순회해 명령을 이름순 목록에 등록한다. 셸 입력에서 만들어지는 argc/argv는 그보다 나중의 호출별 데이터이며, find_cmd()가 찾은 기술자의 .cmd가 이를 받는다.

정적 기술자와 호출별 인자

그림 1. 서로 다른 네 상태의 생성 시점
빌드 시 생성시작 시 등록호출 시 생성
01정적 struct command
02링커 목록의 포인터
03command_list 노드
04호출별 argc/argv
BOUNDARY

포인터 목록은 argv를 만들지 않는다. 생성·소비 시점 표

매크로의 __barebox_cmd_boot 기술자와 barebox_cmd_boot 포인터는 이미지에 남는다. init_command_list()가 이 포인터를 읽어 runtime 목록에 넣고, 셸은 각 명령 실행 때 별도의 인자를 만든다.

등록과 실행을 잇는 경로

그림 2. boot 명령의 정적 등록과 runtime 호출
정적 기술자
정의
링커 목록
기술자 포인터
late initcall
목록 등록
Hush 또는 simple
argc/argv 생성
명령 이름 검색
find_cmd
.cmd 호출
do_boot

01의 BAREBOX_CMD_START부터 03의 register_command()까지는 명령 목록을 준비하는 과정이다. 04–06은 이후 셸 호출마다 일어난다. Hush는 execute_binfmt()을 거쳐 명령을 찾고, simple shell은 execute_command()를 직접 호출한다. 선택된 셸은 빌드 설정에 따른다.

단계별 생성물과 소비자

이미지에 고정된 항목과 명령 한 번의 실행에만 쓰이는 인자를 분리한다.

#시점소스의 실제 동작남는 상태·다음 소비자
01빌드: CONFIG_CMD_BOOTcommands/Makefile이 boot.o를 포함한다.매크로가 확장될 컴파일 단위
02컴파일·링크BAREBOX_CMD_START가 정적 기술자와 이를 가리키는 __ll_elem 포인터를 정의한다.__barebox_cmd_start/end 사이의 포인터 목록
03시작: late_initcallinit_command_list()가 각 포인터를 register_command()로 넘긴다.이름순 command_list; find_cmd()가 검색
04명령 호출Hush 또는 simple parser가 입력에서 argc/argv를 만든다.호출별 인자; Hush는 execute_binfmt(), simple은 execute_command()
05명령 실행execute_command()가 find_cmd(argv[0]) 후 cmdtp->cmd(argc, argv)를 호출한다.do_boot()이 자체 getopt()로 옵션 처리
06반환COMMAND_ERROR_USAGE는 usage 출력 후 COMMAND_ERROR로 바뀐다.셸마다 다른 반환 처리; Hush는 $?에 반영

링커 목록·등록 목록의 생성은 argv 파싱과 별개다. simple shell의 shell_get_last_return_code()는 0을 반환하는 stub이므로 $? 동작을 두 셸에 공통으로 가정하지 않는다.

정적 등록과 호출 분기를 그림으로 읽기

기술자 주소는 빌드 결과의 심벌·링커 목록에서, 실제 명령 등록과 인자 전달은 해당 보드의 help boot 및 명령 로그에서 확인한다.

그림 3. boot 기술자가 do_boot 호출로 이어지는 조건부 경로

01–03은 시작 시까지 한 번 준비되고, 04–07은 셸에서 boot 명령을 호출할 때마다 진행된다.

01정적 기술자
.cmd=do_boot
02링커 목록에
기술자 포인터
03late initcall
목록 등록
04Hush / simple
argc·argv 생성
05Hush: binfmt 경유
simple: 직접 실행
06find_cmd(boot)
do_boot 호출
07handler 반환
셸별 처리
그림 4. 포인터·목록·argv의 소유 경계

왼쪽의 생산자와 오른쪽 소비자를 같은 행으로 묶었다.

01BAREBOX_CMD_START정적 struct command이미지 수명
02__ll_elem기술자 포인터init_command_list
03register_command이름순 command_listfind_cmd
04셸 입력호출별 argc/argvexecute_command
05find_cmd(boot)cmdtp->cmddo_boot / getopt

원본 코드

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

commit314c679eea2d0ca847c64d1b646a1cf91225c0ecanchor · L246BAREBOX_CMD_START(boot)
222BAREBOX_CMD_HELP_TEXT("DEFAULT can be:")
223BAREBOX_CMD_HELP_TEXT("- the numeric index of the menu entry to choose")
224BAREBOX_CMD_HELP_TEXT("- the path to the file backing the entry (e.g. bootspec config file)")
225#ifdef CONFIG_FNMATCH
226BAREBOX_CMD_HELP_TEXT("  with wildcards allowed")
227#endif
228BAREBOX_CMD_HELP_TEXT("")
229BAREBOX_CMD_HELP_TEXT("Multiple bootsources may be given which are probed in order until")
230BAREBOX_CMD_HELP_TEXT("one succeeds.")
231BAREBOX_CMD_HELP_TEXT("")
232BAREBOX_CMD_HELP_TEXT("Options:")
233BAREBOX_CMD_HELP_OPT ("-v","Increase verbosity")
234BAREBOX_CMD_HELP_OPT ("-d","Dryrun. See what happens but do no actually boot (pass twice to run scripts)")
235BAREBOX_CMD_HELP_OPT ("-l","List available boot sources")
236BAREBOX_CMD_HELP_OPT ("-m","Show a menu with boot options")
237BAREBOX_CMD_HELP_OPT ("-M DEFAULT","Show a menu with boot options with entry DEFAULT preselected")
238BAREBOX_CMD_HELP_OPT ("-w SECS","Start watchdog with timeout SECS before booting")
239#ifdef CONFIG_BOOT_OVERRIDE
240BAREBOX_CMD_HELP_OPT ("-o VAR[=VAL]","override VAR (bootm.{oftree,initrd}) with VAL")
241BAREBOX_CMD_HELP_OPT ("            ","if VAL is not specified, the value of VAR is taken")
242#endif
243BAREBOX_CMD_HELP_OPT ("-t SECS","specify timeout in SECS")
244BAREBOX_CMD_HELP_END
245
246BAREBOX_CMD_START(boot)
247	.cmd	= do_boot,
248	BAREBOX_CMD_DESC("boot from script, device, ...")
249	BAREBOX_CMD_OPTS("[-vdlmMwt] [BOOTSRC...]")
250	BAREBOX_CMD_GROUP(CMD_GRP_BOOT)
251	BAREBOX_CMD_HELP(cmd_boot_help)
252BAREBOX_CMD_END

발췌 범위와 읽기 기준

원문 222–252줄에는 앞뒤 문맥이 포함된다. 기준 구문 BAREBOX_CMD_START(boot)은 L246에 있고, 발췌 첫 줄은 함수 정의의 시작이 아니다.

발췌 L246–252는 boot의 기술자 필드다. 매크로 확장은 include/command.h, 시작 시 등록은 common/command.c, 호출별 argv와 반환값은 선택된 셸 구현에서 확인한다.

함께 읽어야 하는 원본 코드

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

01. boot 명령의 option 처리와 boot entry 실행

commands/boot.c 78-180줄이다.

filecommands/boot.canchor · L88static int do_boot(int argc, char *argv[])
78	bootentries_for_each_entry(entries, entry) {
79		if ((IS_ENABLED(CONFIG_FNMATCH) && !fnmatch(id, entry->path, 0)) ||
80		    streq_ptr(id, entry->path))
81			return idx;
82		idx++;
83	}
84
85	return 0;
86}
87
88static int do_boot(int argc, char *argv[])
89{
90	char *freep = NULL;
91	int opt, ret = 0, do_list = 0, do_menu = 0;
92	int dryrun = 0, verbose = 0, timeout = -1;
93	char *default_menu_entry = NULL;
94	struct bootentries *entries;
95	struct bootentry *entry;
96	struct bootm_overrides overrides = {};
97	void *handle;
98	const char *name;
99	char *(*next)(void *);
100
101	while ((opt = getopt(argc, argv, "vldmM:t:w:o:")) > 0) {
102		switch (opt) {
103		case 'v':
104			verbose++;
105			break;
106		case 'l':
107			do_list = 1;
108			break;
109		case 'd':
110			dryrun++;
111			break;
112		case 'M':
113			default_menu_entry = optarg;
114			fallthrough;
115		case 'm':
116			do_menu = 1;
117			break;
118		case 't':
119			timeout = simple_strtoul(optarg, NULL, 0);
120			break;
121		case 'w':
122			boot_set_watchdog_timeout(simple_strtoul(optarg, NULL, 0));
123			break;
124		case 'o':
125			ret = boot_add_override(&overrides, optarg);
126			if (ret)
127				return ret;
128			break;
129		default:
130			return COMMAND_ERROR_USAGE;
131		}
132	}
133
134	if (optind < argc) {
135		handle = &argv[optind];
136		next = next_argv;
137	} else {
138		const char *def;
139
140		def = getenv("global.boot.default");
141		if (!def)
142			return 0;
143
144		handle = freep = xstrdup(def);
145		next = next_word;
146	}
147
148	entries = bootentries_alloc();
149
150	while ((name = next(&handle)) != NULL) {
151		if (!*name)
152			continue;
153		ret = bootentry_create_from_name(entries, name);
154		if (ret <= 0)
155			printf("Nothing bootable found on '%s'\n", name);
156
157		if (do_list || do_menu)
158			continue;
159
160		bootentries_for_each_entry(entries, entry) {
161			bootm_merge_overrides(&entry->overrides, &overrides);
162
163			ret = boot_entry(entry, verbose, dryrun);
164			if (!ret)
165				goto out;
166		}
167
168		bootentries_free(entries);
169		entries = bootentries_alloc();
170	}
171
172	if (list_empty(&entries->entries)) {
173		printf("Nothing bootable found\n");
174		ret = COMMAND_ERROR;
175		goto out;
176	}
177
178	if (do_list) {
179		bootsources_list(entries);
180	} else if (do_menu) {

구현 경계를 더 깊게 읽기

01

빌드 포함 여부를 먼저 확인한다

commands/Makefile의 CONFIG_CMD_BOOT가 boot.o 포함을 결정한다. BAREBOX_CMD_START(boot)은 실행 중 호출되는 함수가 아니라 컴파일 시 기술자와 포인터 정의로 확장된다.

CONFIG_LONGHELP가 꺼져 있으면 BAREBOX_CMD_HELP 필드는 비어도 .cmd, 이름, 짧은 설명은 별개다.

02

링커 포인터와 runtime 목록을 분리한다

링커 목록의 각 원소는 struct command 자체가 아니라 이를 가리키는 포인터다. init_command_list()가 __barebox_cmd_start/end를 순회하고 register_command()가 기술자의 list 노드를 이름순 command_list에 넣는다.

이 과정에서 셸의 입력 buffer나 argv는 생성되지 않는다.

03

선택한 셸에 따라 진입 경로가 갈린다

CONFIG_SHELL_HUSH의 hush.c는 확장·glob 처리 후 execute_binfmt()를 호출한다. 이 함수가 명령 이름을 찾으면 execute_command()로 보낸다. CONFIG_SHELL_SIMPLE의 parser.c는 parse_line()으로 argv를 만들고 execute_command()를 직접 호출한다.

따라서 Hush 파싱을 모든 Barebox 명령 실행의 필수 단계로 그리지 않는다.

04

실제 option 처리는 handler 안에 있다

execute_command()는 이름 검색 뒤 cmdtp->cmd(argc, argv)를 호출한다. boot의 .cmd는 do_boot()이고, 그 함수가 getopt(argc, argv, "vldmM:t:w:o:")로 옵션을 처리한다.

잘못된 옵션 등으로 COMMAND_ERROR_USAGE가 돌아오면 공통 실행 함수가 사용법을 출력하고 COMMAND_ERROR로 변환한다.

05

반환 상태는 셸 구현까지 따라간다

Hush는 실행 결과를 last_return_code에 반영하고 조건문·$?에 사용한다. 음수 결과를 127로 바꾸는 경로도 있다. simple parser는 명령이 성공이 아니면 자신의 rc=-1로 표시하지만 shell_get_last_return_code() 구현은 0을 돌려주는 stub이다.

명령 handler의 정수 반환값이 두 셸에서 모두 그대로 $?가 된다고 해석하지 않는다.

코드에서 놓치기 쉬운 분기

01

매크로는 option parser를 생성하지 않는다

include/command.h의 매크로는 이름, callback, 설명 등 정적 필드를 정의한다. commands/boot.c의 do_boot()가 실행될 때 getopt()를 호출한다.

.opts는 표시용 문자열이고 .help는 CONFIG_LONGHELP에 따라 존재한다.

02

이름 검색에는 두 층이 있다

Hush의 execute_binfmt()는 이름에 slash가 있으면 파일 실행 경로를 우선한다. 명령 이름이면 find_cmd()로 확인한 뒤 execute_command()를 부른다. simple shell은 공통 실행 함수를 바로 호출한다.

공통 실행 함수도 find_cmd(argv[0])를 하고 명령이 없으면 unknown-command 오류를 돌려준다.

03

목록 등록과 호출 상태는 다른 수명이다

register_command()는 기술자의 노드를 이름순 list에 더한다. alias가 있으면 별도 복제 기술자를 만들지만, 이 글의 boot 정의에는 alias 필드가 없다.

셸이 전달한 문자열 포인터는 현재 실행의 입력 처리에 묶인다. 명령 기술자의 image 수명과 혼동하지 않는다.

객체와 수명

대상만들어지는 시점유효 범위소비자
__barebox_cmd_boot매크로 확장·컴파일포함된 Barebox 이미지의 수명링커 포인터와 등록 목록
barebox_cmd_boot 포인터__ll_elem 섹션 배치링크된 이미지의 수명init_command_list()
command_list 노드register_command()runtime 명령 목록에 등록된 동안find_cmd(), 도움말 목록
셸의 argc/argv각 입력의 Hush 또는 simple 파싱해당 명령 호출 동안execute_command()와 do_boot()
getopt_contextexecute_command() 진입handler 호출과 복원까지do_boot()의 옵션 처리

실패 지점과 증상

#조건관찰되는 증상먼저 볼 코드
01CONFIG_CMD_BOOT 꺼짐boot.o가 빌드되지 않아 기술자가 없음commands/Makefile
02링커 포인터 또는 등록 누락이미지에 기술자가 있어도 runtime 목록에 없음__barebox_cmd_start/end, init_command_list()
03명령 이름을 못 찾음execute_command()가 unknown command 출력find_cmd(argv[0])
04잘못된 boot 옵션usage 출력 뒤 공통 오류로 변환do_boot()의 getopt(), COMMAND_ERROR_USAGE

명령 누락은 포함·등록 문제이고 옵션 오류는 handler 실행 뒤의 문제다. Hush의 파일 실행 fallback 및 상태값 처리도 simple shell과 별개로 확인한다.

빌드와 대상 보드에서 확인할 증거

실제 보드 설정에서 명령 포함, 링커 원소, 등록된 이름, 셸 경로를 차례로 확인한다. 아래의 빌드 산출물 이름은 해당 빌드의 경로로 바꾼다.

#목적명령 또는 계측판정 기준
01빌드 설정grep -E 'CONFIG_(COMMAND_SUPPORT|CMD_BOOT|SHELL_HUSH|SHELL_SIMPLE)=' .configboot.o와 셸 구현의 포함 조건을 확인한다.
02실제 기술자·포인터${CROSS_COMPILE}nm -an barebox | grep -E '(__barebox_cmd_boot|barebox_cmd_boot|__barebox_cmd_(start|end))'매크로 이름 자체가 아니라 생성된 심벌을 찾는다. 최종 이미지가 stripped면 중간 ELF를 검사한다.
03등록된 명령help boot명령 검색·도움말이 동작하는지 확인한다. 긴 help의 유무는 CONFIG_LONGHELP에 따른다.
04실행과 usageboot -? 또는 시험 장비의 무효 옵션do_boot()의 usage 반환이 공통 실행 함수에서 오류로 바뀌는지 관찰한다.
05셸 상태Hush에서 오류 명령 뒤 echo $?; simple 구현은 소스 확인Hush의 반환 상태와 simple parser stub을 같은 동작으로 단정하지 않는다.

직접 확인할 실험

  1. 01
    빌드 설정을 바꿔 명령 포함 확인

    CONFIG_CMD_BOOT 변경 전후의 boot.o, 기술자 심벌과 help boot 결과를 비교한다.

  2. 02
    등록 경계를 추적

    init_command_list()에서 barebox_cmd_boot 포인터를 읽는 시점과 register_command() 뒤 find_cmd("boot") 결과를 확인한다. 이 시점에 argv는 필요 없다.

  3. 03
    옵션 오류를 셸별로 구분

    안전한 시험 보드에서 잘못된 boot 옵션을 넣고 do_boot()의 usage 반환, execute_command()의 변환, 선택한 셸의 상태 표시를 각각 확인한다.

원문과 다음 글