BAREBOX_CMD_START와 shell 명령 등록

QUESTION

BAREBOX_CMD_START와 shell 명령 등록 단계에서 실제로 바뀌는 상태는 무엇인가?

STRUCTURE

객체와 주소가 놓이는 구조

CALL PATH

실행 흐름

STATE LEDGER

단계별 입력과 출력

각 단계의 입력과 처리 후 바뀌는 상태를 정리한 표다. 사용 중인 소스 버전에서 다른 필드를 변경한다면 그에 맞춰 표도 수정한다.

분석 범위의 전제와 비교해, 다음 단계에 잘못된 입력을 넘긴 부분부터 조사한다.

VISUAL WALKTHROUGH

주소와 객체의 이동을 그림으로 읽기

아래 그림은 주소, 객체를 사용하는 기간, 제어권을 넘기는 시점을 중심으로 정리했다. 실제 주소와 크기는 사용 중인 보드의 bdinfo, 맵 파일과 링커 심벌로 확인한다.

UPSTREAM SOURCE

원본 코드

아래 코드는 Barebox v2026.06.1의 commands/boot.c에서 222-252줄을 그대로 가져온 것이다. 설명을 위해 실제 코드를 가짜 의사 코드로 바꾸지 않았다.

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

READING CONTRACT

발췌 범위와 읽기 기준

원문 222-252줄에는 앞뒤 문맥이 포함됩니다. 기준 구문 BAREBOX_CMD_START(boot)은 L246에 있습니다. 발췌 첫 줄을 함수 정의의 시작으로 해석하지 않습니다.

매크로가 만드는 descriptor와 help text, Kconfig 조건을 함께 본다. command가 보이지 않을 때 parser보다 빌드 설정과 linker section부터 확인한다.

RELATED SOURCE

함께 읽어야 하는 원본 코드

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

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) {

DETAILS

내부 동작을 더 깊게 읽기

IMPLEMENTATION NOTES

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

OBJECT LIFETIME

객체와 수명

FAILURE PATH

실패 지점과 증상

로그가 끊긴 함수뿐 아니라 그 함수에 주소, 크기, 플래그를 전달한 앞 단계도 조사한다. 오류 처리 후 등록된 객체나 하드웨어 설정이 그대로 남아 있는지도 확인한다.

EVIDENCE

소스 밖에서 확인할 증거

소스에서 파악한 동작을 실제 빌드 결과와 대상 보드의 로그로 확인한다. 아래 명령의 보드 이름과 툴체인 접두사는 사용 중인 빌드 환경에 맞게 바꾼다.

LAB

직접 확인할 실험

1. 01
   help 목록과 map command section 비교

   linker command section 진입 전후에 command descriptor의 주소·크기·반환값과 timestamp를 함께 남긴다.

2. 02
   Kconfig toggle 전후 binary symbol diff

   hush parse 진입 전후에 argv buffer의 주소·크기·반환값과 timestamp를 함께 남긴다.

3. 03
   긴 argv와 ctrl-c 처리 경로 시험

   command lookup 진입 전후에 shell context의 주소·크기·반환값과 timestamp를 함께 남긴다.

PRIMARY REFERENCES

원문과 다음 글