QUESTION
BBU update handler와 self-update 단계에서 실제로 바뀌는 상태는 무엇인가?
공통 BBU는 입력과 handler를 연결하고 image metadata를 검사한 뒤 등록된 callback을 호출한다. 매체를 지우고 쓰거나 다른 부트 사본을 선택하는 절차는 선택된 handler에 달려 있다.
표준 파일 handler는 복제본 보존·readback·flush·선택자 commit을 보편적으로 제공하지 않는다. 업데이트 전 보드의 실제 handler와 복구 경로를 확인한다.
STRUCTURE
공통 계층과 매체별 handler의 책임
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·검증 단계를 수행한다는 뜻이 아니다.
CALL PATH
공통 호출 흐름과 분기점
handler->handler()handler가 없거나 image 읽기·metadata 검사에서 오류가 나면 다음 단계로 가지 않는다. BBU_HANDLER_CAN_REFRESH가 없는 handler에는 image가 필요하다. 호출 성공 표시는 공통 core가 별도 readback을 했다는 증거가 아니다.
STATE LEDGER
단계별 상태와 실패 경계
| 단계 | 고정 소스의 동작 | 실패하면 | 확인할 것 |
|---|---|---|---|
| handler 선택 | -t → -d → default 중 해당 조건으로 검색 | 목록 출력 후 명령 실패 | 선택된 이름·device |
| image 입력 | 지정 파일 또는 기본 fetch 경로를 읽음; -r은 자동 파일 설정 생략 | 읽기 오류 반환 | 파일과 길이, refresh 지원 |
| 공통 검사 | bbu_check_metadata() 후 callback 호출 | 검사 오류 반환 | IMD/compatible/CRC 설정과 force 수준 |
| 표준 파일 handler | type 검사 뒤 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 형식·중복 사본 정책은 해당 구현과 실기기에서 별도로 확인한다.
VISUAL WALKTHROUGH
선택된 handler에 따라 달라지는 기록
bbu_register_std_file_update()가 등록한 callback의 v2026.06.1 경로다.
(force 가능)
bbu_confirm()pwrite_full() · reprotect · closebbu_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 오류면 전환 전 반환
UPSTREAM SOURCE
원본 코드
아래 코드는 Barebox v2026.06.1의 common/bbu.c에서 290-378줄을 그대로 가져온 것이다.
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
READING CONTRACT
발췌 범위와 읽기 기준
원문 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·영속화·전원 차단 복구를 증명할 수 없다.
RELATED SOURCE
함께 읽어야 하는 원본 코드
첫 코드 조각만으로 동작이 완성되지 않는 경우 호출 매크로, 객체 정의와 실제 실행 목록을 같은 페이지에 묶었다. 각 조각은 같은 기준 commit에서 가져왔다.
01. handler 선택 뒤 metadata 검사와 update를 수행
common/bbu.c 244-328줄이다.
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 {
DETAILS
내부 동작을 더 깊게 읽기
진입 조건을 먼저 고정한다
do_barebox_update()는 등록된 handler를 이름·device·default 조건으로 찾고 image를 읽은 뒤 barebox_update()를 호출한다. handler가 없거나 파일을 읽지 못하면 callback까지 진행하지 않는다.
공통 metadata 검사와 handler별 image type 검사는 별개다. -f가 어느 검사를 우회하는지도 해당 분기에서 확인한다.
중심 객체의 생성과 공개를 나눈다
bbu_register_handler()는 중복 이름·중복 default를 거절하고 handler를 목록에 추가한다. 명령은 별도로 image buffer를 읽어 bbu_data에 담고 callback 반환 뒤 해제한다. 등록 수명과 한 번의 update 입력 수명을 구분한다.
빌드 산출물 관점에서는 최종 부트로더 이미지 안에 해당 symbol과 section이 실제로 포함되었는지도 map과 objdump로 검증한다.
주소, 크기와 정렬을 계산한다
부트 코드에서는 주소 계산 오류를 주의해야 한다. 원본과 목적지의 주소 범위, 헤더에 기록된 데이터 크기, 블록·페이지 단위를 표로 정리하고 각 구간의 끝 주소를 계산한다. 끝 주소가 start + size - 1처럼 마지막 바이트를 가리키는지, 구간 바로 다음 주소를 가리키는지는 API 규약에서 확인한다.
성공 flag와 실제 완료 시점을 맞춘다
공통 update succeeded는 handler callback이 0을 반환했다는 뜻이다. 표준 파일 handler는 pwrite_full()의 반환을 확인하지만 readback·flush는 수행하지 않는다. 다른 handler의 완료·검증 기준은 그 구현에서 확인한다.
MMC boot wrapper는 chained handler의 음수 오류 뒤에는 boot 선택자를 바꾸지 않는다. 선택자 설정과 실제 ROM의 다음 부팅 결과가 같은지는 보드에서 따로 확인한다.
명령 반환과 매체 상태를 구분한다
이 명령의 공통 경로는 handler 반환값을 받아 성공·실패를 출력한 뒤 호출자에게 돌아간다. 공통 코드에 비복귀 image handoff, readback 또는 선택자 commit 단계는 없다.
어느 매체가 실제로 갱신되고 실패 시 이전 사본을 쓸 수 있는지는 선택한 handler와 보드의 부팅 정책에 달려 있다.
IMPLEMENTATION NOTES
구현을 읽을 때 놓치기 쉬운 부분
generic BBU와 board handler의 책임을 나눈다
명령은 handler 선택·image 입력·flags를, 공통 BBU는 가능한 metadata 검사와 callback 호출을 담당한다. 표준 파일 handler와 MMC boot wrapper 외의 ROM 형식·offset·redundancy 정책은 등록된 보드/SoC handler마다 확인한다.
handler name과 default 여부가 여러 boot medium에서 모호하지 않아야 한다.
사본 보존은 선택한 handler에서 확인한다
표준 파일 handler는 지정 device에 쓰며 이전 부팅 사본 보존을 보장하지 않는다. MMC boot wrapper는 다른 eMMC boot partition에 chained handler를 실행한 뒤 boot 선택자를 설정하지만, readback이나 원자적 전환을 추가로 보장하지 않는다.
중복 header·ROM fallback이 있는 보드는 실제 handler, 매체 배치와 다음 부팅 결과를 별도로 검증한다.
image 검사와 저장 매체 검증을 구분한다
공통 metadata/CRC 검사와 표준 handler의 image type 검사는 저장 매체의 실제 byte를 다시 읽는 검사가 아니다. bbu_flash()에는 readback·flush가 없으므로 필요한 보드는 별도 검증 방법을 설계해야 한다.
erase·write·selector 변경 중 무엇이 존재하는지는 handler별로 다르다. 오류·전원 차단 시험도 그 단계가 실제로 있는 복구 가능한 시험 환경에서만 계획한다.
OBJECT LIFETIME
객체와 수명
| 대상 | 만들어지는 시점 | 유효 범위 | 확인할 조건 |
|---|---|---|---|
struct bbu_handler | bbu_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로 교체할 때까지 | 적재 주소, 진입점, 섹션, 헤더의 일치 여부 |
FAILURE PATH
실패 지점과 증상
| # | 조건 | 관찰되는 증상 | 먼저 볼 단계 |
|---|---|---|---|
| 01 | 잘못된 handler 선택 | 실제 callback이 다른 매체를 갱신할 수 있음 | 명령의 이름·device/default 선택 |
| 02 | 표준 handler 쓰기 중 실패 | 단일 사본이면 다음 부팅 실패 가능 | bbu_flash() 반환과 매체 배치 |
| 03 | image type 검사 강제 우회 | ROM 형식이 안 맞으면 거부 가능 | 선택된 handler의 type 검사 |
로그가 끊긴 함수뿐 아니라 그 함수에 주소, 크기, 플래그를 전달한 앞 단계도 조사한다. 오류 처리 후 등록된 객체나 하드웨어 설정이 그대로 남아 있는지도 확인한다.
EVIDENCE
BBU 등록과 매체 경계의 읽기 전용 확인
아래 확인은 매체를 쓰지 않는다. build 설정, 등록된 handler, 보드별 callback을 차례로 대조한다. 실제 write와 전원 차단 검증은 복구 가능한 시험 환경에서 별도 계획으로 수행한다.
| # | 확인 대상 | 읽기 전용 명령·자료 | 판정 기준 |
|---|---|---|---|
| 01 | 빌드 설정 | 빌드 호스트에서 grep '^CONFIG_BAREBOX_UPDATE=' .config | 사용 중인 빌드에서 BBU 명령 활성 여부를 확인한다. |
| 02 | 등록된 handler | Barebox 셸에서 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 단계가 없음을 구분한다. |
| 05 | MMC boot 조건부 경로 | 해당 handler를 등록한 보드에서만 bbu_mmcboot_handler()와 <dev>.boot 관측값을 대조한다. | 반대 boot partition 선택, chained handler 성공 뒤 전환, 선택적 boot ack를 확인한다. |
LAB
직접 확인할 실험
- 01
barebox-update -l로 handler 목록 확인default 표시, 이름과 device를 기록하고 명령의
-t/-d선택 조건과 대조한다. 목록 출력은 매체를 쓰지 않는다. - 02쓰지 않고 경로를 확인
이 명령에는 보편적인 dry-run 옵션이 없다. 고정 소스에서 선택된 handler의 callback과 target device를 먼저 확인한다. 별도 시험 cdev가 필요하면 복구 가능한 환경에 구성한다.
- 03MMC wrapper의 조건부 경로 대조
해당 handler를 실제 사용하는 보드에서만 boot0/boot1 선택, chained handler 반환, 선택자 변경 순서를 계측한다. readback과 전원 차단 복구는 별도 시험 계획으로 다룬다.
PRIMARY REFERENCES