Barebox · source analysis

BBU update handler와 self-update

보드가 등록한 update handler를 선택하고 새 Barebox image를 검증해 boot medium에 기록하는 흐름을 읽습니다.

Barebox v2026.06.1은 이 글의 원본 코드 분석 기준입니다. 최신 보안 버전 권고는 아니며, 제품 적용 전 사용하는 보드의 등록 handler·부팅 매체·복구 절차를 별도로 확인하세요.

Series
19 / 19
Baseline
v2026.06.1
Commit
314c679eea2d
Source
common/bbu.c:290-378 (발췌 범위)

BBU update handler와 self-update 단계에서 실제로 바뀌는 상태는 무엇인가?

공통 BBU는 입력과 handler를 연결하고 image metadata를 검사한 뒤 등록된 callback을 호출한다. 매체를 지우고 쓰거나 다른 부트 사본을 선택하는 절차는 선택된 handler에 달려 있다.

표준 파일 handler는 복제본 보존·readback·flush·선택자 commit을 보편적으로 제공하지 않는다. 업데이트 전 보드의 실제 handler와 복구 경로를 확인한다.

공통 계층과 매체별 handler의 책임

그림 1. barebox-update에서 매체 쓰기까지의 소유 경계

공통 command / BBU core

01-t 이름, -d device, 기본 handler 중 선택

02image 파일을 읽고 bbu_data 구성

03가능한 경우 image metadata·compatible·CRC 검사

04handler->handler() 호출·결과 출력

등록된 handler / 매체 구현

01image type·보드 형식 추가 검사 여부 결정

02확인 프롬프트와 실제 target 선택

03필요한 protect·erase·write 수행

04중복 사본·부트 선택자 처리는 구현별로 다름

고정 버전 command와 BBU core를 분리해 읽는다. 모든 handler가 같은 flash·검증 단계를 수행한다는 뜻이 아니다.

공통 호출 흐름과 분기점

그림 2. command가 선택한 handler로 제어를 넘기는 경로
등록된 handler 선택
image 읽기 또는 refresh 입력
공통 metadata 검사
handler->handler()
반환값으로 성공·실패 표시

handler가 없거나 image 읽기·metadata 검사에서 오류가 나면 다음 단계로 가지 않는다. BBU_HANDLER_CAN_REFRESH가 없는 handler에는 image가 필요하다. 호출 성공 표시는 공통 core가 별도 readback을 했다는 증거가 아니다.

단계별 상태와 실패 경계

단계고정 소스의 동작실패하면확인할 것
handler 선택-t → -d → default 중 해당 조건으로 검색목록 출력 후 명령 실패선택된 이름·device
image 입력지정 파일 또는 기본 fetch 경로를 읽음; -r은 자동 파일 설정 생략읽기 오류 반환파일과 길이, refresh 지원
공통 검사bbu_check_metadata() 후 callback 호출검사 오류 반환IMD/compatible/CRC 설정과 force 수준
표준 파일 handlertype 검사 뒤 bbu_flash()의 confirm·protect·erase·pwrite_full()callback 오류 반환대상 크기·쓰기 결과; 자동 readback 없음
MMC boot wrapper반대 boot partition에 chained handler 실행 후 <dev>.boot 변경chained/boot ack 오류면 전환 전 중단해당 handler 사용 여부·boot ack flag

표준 파일 경로와 MMC boot wrapper는 예시다. SoC/board handler의 ROM 형식·중복 사본 정책은 해당 구현과 실기기에서 별도로 확인한다.

선택된 handler에 따라 달라지는 기록

그림 3. 표준 파일 handler의 실제 쓰기 경로

bbu_register_std_file_update()가 등록한 callback의 v2026.06.1 경로다.

01image type 검사
(force 가능)
02bbu_confirm()
03device open · unprotect
04지원되면 erase
05pwrite_full() · reprotect · close
그림 4. MMC boot wrapper의 대상 선택과 전환

bbu_mmcboot_handler()를 선택한 경우의 추가 단계이며 모든 BBU handler의 기본 단계가 아니다.

기록 전

01<dev>.boot 현재 값 읽기

02boot0이면 boot1, 그 밖에는 boot0을 대상에 선택

03/dev/<dev>.<target>로 chained handler 실행

기록 성공 뒤

01옵션 flag가 있으면 <dev>.boot_ack=1

02<dev>.boot=<target> 설정

03chained/boot ack 오류면 전환 전 반환

원본 코드

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

commit314c679eea2d0ca847c64d1b646a1cf91225c0ecanchor · L314int bbu_register_handler(struct bbu_handler *handler)
290}
291EXPORT_SYMBOL(bbu_handlers_available);
292
293/*
294 * print a list of all registered update handlers
295 */
296void bbu_handlers_list(void)
297{
298	struct bbu_handler *handler;
299
300	if (list_empty(&bbu_image_handlers))
301		printf("(none)\n");
302
303	list_for_each_entry(handler, &bbu_image_handlers, list)
304		printf("%s%-11s -> %-10s\n",
305				handler->flags & BBU_HANDLER_FLAG_DEFAULT ?
306				"* " : "  ",
307				handler->name,
308				handler->devicefile);
309}
310
311/*
312 * register a new update handler
313 */
314int bbu_register_handler(struct bbu_handler *handler)
315{
316	if (bbu_find_handler_by_name(handler->name))
317		return -EBUSY;
318
319	if (handler->flags & BBU_HANDLER_FLAG_DEFAULT &&
320	    bbu_find_handler_by_name(NULL))
321		return -EBUSY;
322
323	list_add_tail(&handler->list, &bbu_image_handlers);
324
325	return 0;
326}
327
328struct bbu_std {
329	struct bbu_handler handler;
330	enum filetype filetype;
331};
332
333int bbu_mmcboot_handler(struct bbu_handler *handler, struct bbu_data *data,
334			int (*chained_handler)(struct bbu_handler *, struct bbu_data *))
335{
336	struct bbu_data _data = *data;
337	int ret;
338	char *devicefile = NULL, *bootpartvar = NULL, *bootackvar = NULL;
339	const char *bootpart;
340	const char *devname = devpath_to_name(data->devicefile);
341
342	ret = device_detect_by_name(devname);
343	if (ret) {
344		pr_err("Couldn't detect device '%s'\n", devname);
345		return ret;
346	}
347
348	ret = asprintf(&bootpartvar, "%s.boot", devname);
349	if (ret < 0)
350		return ret;
351
352	bootpart = getenv(bootpartvar);
353	if (!bootpart) {
354		ret = -ENOENT;
355		goto out;
356	}
357
358	if (!strcmp(bootpart, "boot0")) {
359		bootpart = "boot1";
360	} else {
361		bootpart = "boot0";
362	}
363
364	ret = asprintf(&devicefile, "/dev/%s.%s", devname, bootpart);
365	if (ret < 0)
366		goto out;
367
368	_data.devicefile = devicefile;
369
370	ret = chained_handler(handler, &_data);
371	if (ret < 0)
372		goto out;
373
374	if (handler->flags & BBU_HANDLER_FLAG_MMC_BOOT_ACK) {
375		ret = asprintf(&bootackvar, "%s.boot_ack", devname);
376		if (ret < 0)
377			goto out;
378

발췌 범위와 읽기 기준

원문 290-378줄에는 앞뒤 문맥이 포함됩니다. 기준 구문 int bbu_register_handler(struct bbu_handler *handler)은 L314에 있습니다. 발췌 첫 줄을 함수 정의의 시작으로 해석하지 않습니다.

이 발췌는 handler 등록과 MMC boot wrapper의 시작 부분이다. 명령의 handler 선택과 image 읽기, 공통 metadata 검사, 표준 파일 쓰기·MMC 선택자 변경은 각각 해당 고정 버전 원문에서 구분해 읽는다.

bbu_flash()에 명시적 flush 호출이 없다는 말은 하위 장치에서도 flush가 일어나지 않는다는 뜻이 아니다. 블록 cdev의 block_op_close()는 block_op_flush()와 필요한 파티션 재탐색을 호출하지만 그 반환값을 전달하지 않고 0을 반환한다. 따라서 BBU 성공 메시지나 close 반환만으로 readback·영속화·전원 차단 복구를 증명할 수 없다.

함께 읽어야 하는 원본 코드

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

01. handler 선택 뒤 metadata 검사와 update를 수행

common/bbu.c 244-328줄이다.

filecommon/bbu.canchor · L254int barebox_update
244	ret = imd_verify_crc32((void *)data->image, data->len);
245	if (ret == -EILSEQ && !(data->flags & BBU_FLAG_FORCE))
246		return ret;
247
248	return 0;
249}
250
251/*
252 * do a barebox update with data from *data
253 */
254int barebox_update(struct bbu_data *data, struct bbu_handler *handler)
255{
256	int ret;
257
258	if (!data->image && !data->imagefile &&
259	    !(handler->flags & BBU_HANDLER_CAN_REFRESH)) {
260		pr_err("No Image file given\n");
261		return -EINVAL;
262	}
263
264	if (!data->handler_name)
265		data->handler_name = handler->name;
266
267	if (!data->devicefile)
268		data->devicefile = handler->devicefile;
269
270	ret = bbu_check_metadata(data);
271	if (ret)
272		return ret;
273
274	ret = handler->handler(handler, data);
275	if (ret) {
276		printf("update %s\n", (ret == -EINTR) ? "aborted" : "failed");
277		return ret;
278	}
279
280	printf("update succeeded\n");
281	return 0;
282}
283
284/*
285 * report whether any update handlers have been registered so far
286 */
287bool bbu_handlers_available(void)
288{
289	return !list_empty(&bbu_image_handlers);
290}
291EXPORT_SYMBOL(bbu_handlers_available);
292
293/*
294 * print a list of all registered update handlers
295 */
296void bbu_handlers_list(void)
297{
298	struct bbu_handler *handler;
299
300	if (list_empty(&bbu_image_handlers))
301		printf("(none)\n");
302
303	list_for_each_entry(handler, &bbu_image_handlers, list)
304		printf("%s%-11s -> %-10s\n",
305				handler->flags & BBU_HANDLER_FLAG_DEFAULT ?
306				"* " : "  ",
307				handler->name,
308				handler->devicefile);
309}
310
311/*
312 * register a new update handler
313 */
314int bbu_register_handler(struct bbu_handler *handler)
315{
316	if (bbu_find_handler_by_name(handler->name))
317		return -EBUSY;
318
319	if (handler->flags & BBU_HANDLER_FLAG_DEFAULT &&
320	    bbu_find_handler_by_name(NULL))
321		return -EBUSY;
322
323	list_add_tail(&handler->list, &bbu_image_handlers);
324
325	return 0;
326}
327
328struct bbu_std {

내부 동작을 더 깊게 읽기

01

진입 조건을 먼저 고정한다

do_barebox_update()는 등록된 handler를 이름·device·default 조건으로 찾고 image를 읽은 뒤 barebox_update()를 호출한다. handler가 없거나 파일을 읽지 못하면 callback까지 진행하지 않는다.

공통 metadata 검사와 handler별 image type 검사는 별개다. -f가 어느 검사를 우회하는지도 해당 분기에서 확인한다.

02

중심 객체의 생성과 공개를 나눈다

bbu_register_handler()는 중복 이름·중복 default를 거절하고 handler를 목록에 추가한다. 명령은 별도로 image buffer를 읽어 bbu_data에 담고 callback 반환 뒤 해제한다. 등록 수명과 한 번의 update 입력 수명을 구분한다.

빌드 산출물 관점에서는 최종 부트로더 이미지 안에 해당 symbol과 section이 실제로 포함되었는지도 map과 objdump로 검증한다.

03

주소, 크기와 정렬을 계산한다

부트 코드에서는 주소 계산 오류를 주의해야 한다. 원본과 목적지의 주소 범위, 헤더에 기록된 데이터 크기, 블록·페이지 단위를 표로 정리하고 각 구간의 끝 주소를 계산한다. 끝 주소가 start + size - 1처럼 마지막 바이트를 가리키는지, 구간 바로 다음 주소를 가리키는지는 API 규약에서 확인한다.

04

성공 flag와 실제 완료 시점을 맞춘다

공통 update succeeded는 handler callback이 0을 반환했다는 뜻이다. 표준 파일 handler는 pwrite_full()의 반환을 확인하지만 readback·flush는 수행하지 않는다. 다른 handler의 완료·검증 기준은 그 구현에서 확인한다.

MMC boot wrapper는 chained handler의 음수 오류 뒤에는 boot 선택자를 바꾸지 않는다. 선택자 설정과 실제 ROM의 다음 부팅 결과가 같은지는 보드에서 따로 확인한다.

05

명령 반환과 매체 상태를 구분한다

이 명령의 공통 경로는 handler 반환값을 받아 성공·실패를 출력한 뒤 호출자에게 돌아간다. 공통 코드에 비복귀 image handoff, readback 또는 선택자 commit 단계는 없다.

어느 매체가 실제로 갱신되고 실패 시 이전 사본을 쓸 수 있는지는 선택한 handler와 보드의 부팅 정책에 달려 있다.

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

01

generic BBU와 board handler의 책임을 나눈다

명령은 handler 선택·image 입력·flags를, 공통 BBU는 가능한 metadata 검사와 callback 호출을 담당한다. 표준 파일 handler와 MMC boot wrapper 외의 ROM 형식·offset·redundancy 정책은 등록된 보드/SoC handler마다 확인한다.

handler name과 default 여부가 여러 boot medium에서 모호하지 않아야 한다.

02

사본 보존은 선택한 handler에서 확인한다

표준 파일 handler는 지정 device에 쓰며 이전 부팅 사본 보존을 보장하지 않는다. MMC boot wrapper는 다른 eMMC boot partition에 chained handler를 실행한 뒤 boot 선택자를 설정하지만, readback이나 원자적 전환을 추가로 보장하지 않는다.

중복 header·ROM fallback이 있는 보드는 실제 handler, 매체 배치와 다음 부팅 결과를 별도로 검증한다.

03

image 검사와 저장 매체 검증을 구분한다

공통 metadata/CRC 검사와 표준 handler의 image type 검사는 저장 매체의 실제 byte를 다시 읽는 검사가 아니다. bbu_flash()에는 readback·flush가 없으므로 필요한 보드는 별도 검증 방법을 설계해야 한다.

erase·write·selector 변경 중 무엇이 존재하는지는 handler별로 다르다. 오류·전원 차단 시험도 그 단계가 실제로 있는 복구 가능한 시험 환경에서만 계획한다.

객체와 수명

대상만들어지는 시점유효 범위확인할 조건
struct bbu_handlerbbu_register_handler()등록 목록에서 선택·사용하는 동안이름·default 중복과 callback
입력 image buffer / metadata명령의 read_file()handler 반환 뒤 buffer 해제까지길이, IMD 존재 여부, callback이 참조하는 기간
handler 목록보드별 handler 등록 시명령이 handler를 찾고 callback을 호출하는 동안중복 등록 거절, 선택된 이름·device
target 매체 / boot 선택자선택한 handler의 write / 조건부 변경 시매체·보드 정책에 따름표준 write 결과와 MMC wrapper 선택자 변경을 구분
최종 부트로더 이미지link/image 생성 시점다음 stage가 새 image로 교체할 때까지적재 주소, 진입점, 섹션, 헤더의 일치 여부

실패 지점과 증상

#조건관찰되는 증상먼저 볼 단계
01잘못된 handler 선택실제 callback이 다른 매체를 갱신할 수 있음명령의 이름·device/default 선택
02표준 handler 쓰기 중 실패단일 사본이면 다음 부팅 실패 가능bbu_flash() 반환과 매체 배치
03image type 검사 강제 우회ROM 형식이 안 맞으면 거부 가능선택된 handler의 type 검사

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

BBU 등록과 매체 경계의 읽기 전용 확인

아래 확인은 매체를 쓰지 않는다. build 설정, 등록된 handler, 보드별 callback을 차례로 대조한다. 실제 write와 전원 차단 검증은 복구 가능한 시험 환경에서 별도 계획으로 수행한다.

#확인 대상읽기 전용 명령·자료판정 기준
01빌드 설정빌드 호스트에서 grep '^CONFIG_BAREBOX_UPDATE=' .config사용 중인 빌드에서 BBU 명령 활성 여부를 확인한다.
02등록된 handlerBarebox 셸에서 barebox-update -l이름·device 경로와 * default 표시를 기록한다. 목록 출력은 매체를 쓰지 않는다.
03보드별 대상보드 소스의 bbu_register_handler() 또는 등록 helper 호출을 읽는다.실제 등록 이름, devicefile, callback, flags를 목록과 대조한다.
04표준 파일 경로고정 common/bbu.c의 bbu_std_file_handler_checked()와 bbu_flash()를 읽는다.type·force·confirm·write 경로를 찾고 자동 readback 단계가 없음을 구분한다.
05MMC boot 조건부 경로해당 handler를 등록한 보드에서만 bbu_mmcboot_handler()와 <dev>.boot 관측값을 대조한다.반대 boot partition 선택, chained handler 성공 뒤 전환, 선택적 boot ack를 확인한다.

직접 확인할 실험

  1. 01
    barebox-update -l로 handler 목록 확인

    default 표시, 이름과 device를 기록하고 명령의 -t/-d 선택 조건과 대조한다. 목록 출력은 매체를 쓰지 않는다.

  2. 02
    쓰지 않고 경로를 확인

    이 명령에는 보편적인 dry-run 옵션이 없다. 고정 소스에서 선택된 handler의 callback과 target device를 먼저 확인한다. 별도 시험 cdev가 필요하면 복구 가능한 환경에 구성한다.

  3. 03
    MMC wrapper의 조건부 경로 대조

    해당 handler를 실제 사용하는 보드에서만 boot0/boot1 선택, chained handler 반환, 선택자 변경 순서를 계측한다. readback과 전원 차단 복구는 별도 시험 계획으로 다룬다.

원문과 다음 글