Barebox · source analysis

Barebox 빌드 산출물과 PBL image

Kconfig와 linker 단계가 barebox ELF, PBL, DTB와 보드별 images를 만드는 구조를 정리합니다.

Series
01 / 19
Baseline
v2026.06.1
Commit
314c679eea2d
Source
Makefile:1074-1162 (발췌 범위)

Barebox 빌드 산출물과 PBL image 단계에서 실제로 바뀌는 상태는 무엇인가?

barebox 실행 파일과 images/ 아래 ROM 투입 파일을 구분한다. main payload 압축, 헤더, load address가 최종 파일에서 어디에 놓이는지 본다.

ROM용 image의 header, load address, entry와 포함된 PBL/main payload의 위치가 보드 부트 규약과 일치해야 한다. 이 문장을 기준으로 코드를 위에서 아래로 읽으면, 함수 이름을 외우는 대신 어느 시점에 어떤 상태를 신뢰할 수 있는지 판단할 수 있다.

서로 다른 빌드 입력과 선택된 산출물

그림 1. 순서가 아닌 네 가지 역할
CONFIGKconfig·arch 설정

main/PBL 구성과 보드 image target을 선택한다.

MAIN INPUTBAREBOX_OBJS

built-in.a 묶음이 barebox ELF를 링크한다.

PBL INPUTBAREBOX_PBL_OBJS

별도의 built-in.pbl.a 묶음이다.

OUTPUT선택된 images/*

image-y와 보드 규칙이 요구한 파일만 생성된다.

두 object 묶음은 서로를 생산하지 않는다. main 산출물은 기본 piggy 경로에서 압축 payload가 되어 PBL 링크에 합류한다.

main과 PBL 경로가 합류하는 지점

그림 2. Make target 의존 관계
01 · CONFIGdefconfig · Kconfig · arch Makefile

main과 PBL에 쓰일 archive 목록 및 보드 image target 선택

MAINBAREBOX_OBJS

built-in.a → barebox ELF → BAREBOX_PROPER

PBLBAREBOX_PBL_OBJS

built-in.pbl.a · PBL 전용 링크 입력

02 · PBL LINKpbl.lds + PBL objects + main payload

기본 경로: BAREBOX_PROPER → barebox.z → piggy.o·sha_sum.o

03 · OUTPUT%.pbl → 필요 시 %.pblb → image-y

보드·설정에 따라 SoC wrapper 또는 다른 형식·파일명을 사용

CONFIG_PBL_IMAGE_NO_PIGGY에서는 압축 piggy 대신 BAREBOX_PROPER가 PBL 링크에 직접 들어간다. images/* 전체가 모든 보드에서 생기는 것은 아니다.

단계별 입력과 출력

고정 v2026.06.1 Makefile의 target 의존 관계다. main archive와 PBL archive는 병렬적인 입력이며, payload 준비 뒤 PBL 링크에서 합류한다.

#경로·target핵심 입력생성물조건·다음 소비자
01구성defconfig·Kconfig·arch Makefilecommon-y와 pbl-common-y서로 다른 main/PBL archive 목록
02main linkBAREBOX_OBJS (built-in.a)barebox ELF → BAREBOX_PROPER기본값은 barebox.bin, PBL ELF 설정은 vmbarebox
03payload 준비BAREBOX_PROPER기본: barebox.z → piggy.o·sha_sum.oNO_PIGGY이면 원본을 직접 PBL 링크에 사용
04PBL linkpbl.lds + BAREBOX_PBL_OBJS + BAREBOX_PIGGY_OBJS%.pbl ELF; 요청 시 %.pblb raw선택된 PBL entry와 image 규칙
05board imagepblb-y, image-y, FILE_*설정으로 선택된 images/*SoC wrapper·header는 형식별 규칙에 따름

분석 범위의 전제와 비교해, 잘못된 archive, payload 또는 image target이 선택된 지점부터 조사한다.

PBL 링크의 합류 입력과 형식별 출력

make V=1, PBL map과 최종 image header를 함께 읽어 구성별 실제 입력·entry·크기를 확인한다.

그림 3. PBL 링크의 payload 선택

BAREBOX_PBL_OBJS는 두 경우 모두 별도의 입력이다. main 산출물이 들어오는 방법만 설정에 따라 달라진다.

DEFAULT · PIGGYBAREBOX_PROPER → barebox.z

압축 main payload가 piggy.o와 sha_sum.o로 준비된다.

CONFIG_PBL_IMAGE_NO_PIGGYBAREBOX_PROPER 직접

BAREBOX_PIGGY_OBJS가 압축 객체 대신 main 산출물을 가리킨다.

공통 합류: pbl.lds + BAREBOX_PBL_OBJS + BAREBOX_PIGGY_OBJS선택된 entry의 %.pbl ELF를 링크하고 필요하면 %.pblb raw binary를 만든다.
그림 4. 빌드 산출물의 입력과 소비자

왼쪽 생산자가 가운데 파일·목록을 만들고 오른쪽 target이 소비한다. 조건부 경로는 별도로 표시했다.

01common-yBAREBOX_OBJSbarebox ELF
02pbl-common-yBAREBOX_PBL_OBJS%.pbl link
03BAREBOX_PROPERbarebox.z·piggy.o (기본)%.pbl link
04pbl.lds·PBL inputs%.pbl → 필요 시 %.pblb선택된 image target
05image-y·FILE_*보드별 형식·파일명images/*

원본 코드

아래 코드는 Barebox v2026.06.1의 Makefile에서 1074-1162줄을 그대로 가져온 것이다.

commit314c679eea2d0ca847c64d1b646a1cf91225c0ecanchor · L1098barebox: $(BAREBOX_LDS)
1074# This target has pytest select the YAML env matching CONFIG_NAME if available.
1075# Use pytest --lg-env $labgrid_env_yaml directly if you need more than that.
1076
1077labgrid-env := $(srctree)/test/$(SRCARCH)/$(CONFIG_NAME).yaml
1078
1079check:
1080ifeq ($(CONFIG_NAME),"")
1081	@echo "error: can't autoload labgrid env with CONFIG_NAME unset!" >&2
1082	@exit 1
1083endif
1084	@if [ ! -r "$(labgrid-env)" ]; then \
1085		echo "error: No Labgrid environment at $(labgrid-env)!" >&2; \
1086		echo "Choose a different config (or change CONFIG_NAME)" >&2; \
1087		echo "that can be automatically tested" >&2; \
1088		exit 1; \
1089	fi
1090	@echo
1091	@# This is intentionally not @suppressed, to make it easier to reproduce
1092	(cd $(srctree); KBUILD_OUTPUT=$(abs_objtree) $(PYTEST))
1093
1094PHONY += check
1095
1096# barebox image
1097# ---------------------------------------------------------------------------
1098barebox: $(BAREBOX_LDS) $(BAREBOX_OBJS) $(kallsyms.o) FORCE
1099	$(call if_changed_rule,barebox__)
1100ifeq ($(BAREBOX_PROPER),barebox)
1101	$(Q)rm -f .old_version
1102endif
1103
1104barebox.fit: images/barebox-$(CONFIG_ARCH_LINUX_NAME).fit
1105	$(Q)ln -fsn $< $@
1106
1107barebox.srec: barebox
1108	$(OBJCOPY) -O srec $< $@
1109
1110OBJCOPYFLAGS_vmbarebox = $(call objcopy-option,--strip-section-headers,--strip-all)  \
1111			 --remove-section=.comment \
1112			 --remove-section=.note* \
1113			 --remove-section=.gnu.hash
1114
1115vmbarebox: barebox FORCE
1116	$(call if_changed,objcopy)
1117
1118quiet_cmd_barebox_proper__ = CC      $@
1119      cmd_barebox_proper__ = $(CC) -r -o $@ -Wl,--whole-archive $(BAREBOX_OBJS)
1120
1121.tmp_barebox.o: $(BAREBOX_OBJS) $(kallsyms.o) FORCE
1122	$(if $(CONFIG_KALLSYMS),,+$(call cmd,barebox_version))
1123	$(call cmd,barebox_proper__)
1124	$(Q)echo 'savedcmd_$@ := $(cmd_barebox_proper__)' > $(@D)/.$(@F).cmd
1125	$(Q)rm -f .old_version
1126
1127barebox.o: .tmp_barebox.o FORCE
1128	$(call if_changed,objcopy)
1129
1130# The actual objects are generated when descending,
1131# make sure no implicit rule kicks in
1132$(sort $(BAREBOX_OBJS)) $(BAREBOX_LDS) $(BAREBOX_PBL_OBJS): $(barebox-dirs) ;
1133
1134# Handle descending into subdirectories listed in $(barebox-dirs)
1135# Preset locale variables to speed up the build process. Limit locale
1136# tweaks to this spot to avoid wrong language settings when running
1137# make menuconfig etc.
1138# Error messages still appears in the original language
1139
1140PHONY += $(barebox-dirs)
1141$(barebox-dirs): prepare scripts
1142	$(Q)$(MAKE) $(build)=$@
1143
1144# Store (new) KERNELRELASE string in include/config/kernel.release
1145localversion = $(shell $(srctree)/scripts/setlocalversion $(srctree))
1146include/config/kernel.release: FORCE
1147	$(Q)rm -f $@
1148	$(Q)echo $(KERNELVERSION)$(localversion) > $@
1149
1150# Additional helpers built in scripts/
1151# Carefully list dependencies so we do not try to build scripts twice
1152# in parallel
1153PHONY += scripts
1154scripts: scripts_basic scripts_dtc include/generated/utsrelease.h
1155	$(Q)$(MAKE) $(build)=$(@)
1156
1157# Things we need to do before we recursively start building the kernel
1158# or the modules are listed in "prepare".
1159# A multi level approach is used. prepareN is processed before prepareN-1.
1160# archprepare is used in arch Makefiles and when processed asm symlink,
1161# version.h and scripts_basic is processed / created.
1162

발췌 범위와 읽기 기준

원문 1074-1162줄에는 앞뒤 문맥이 포함됩니다. 기준 구문 barebox: $(BAREBOX_LDS)은 L1098에 있습니다. 발췌 첫 줄을 함수 정의의 시작으로 해석하지 않습니다.

barebox 실행 파일과 images/ 아래 ROM 투입 파일을 구분한다. main payload 압축, 헤더, load address가 최종 파일에서 어디에 놓이는지 본다.

함께 읽어야 하는 원본 코드

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

01. PBL ELF와 binary image를 링크하는 규칙

images/Makefile 61-137줄이다.

fileimages/Makefileanchor · L79$(obj)/%.pbl:
61else
62BAREBOX_PIGGY_OBJS = $(obj)/../$(BAREBOX_PROPER)
63endif
64
65quiet_cmd_elf__ ?= LD      $@
66      cmd_elf__ ?= $(LD) $(LDFLAGS_$(patsubst .%,%,$(suffix $(@F)))) 	\
67		-e $(2) -Map $@.map $(LDFLAGS_$(@F)) -o $@		\
68		--gc-sections --defsym=__pbl_board_entry=$(2)  		\
69		-T $(pbl-lds)						\
70		--whole-archive $(BAREBOX_PBL_OBJS) $(BAREBOX_PIGGY_OBJS) \
71
72PBL_CPPFLAGS	+= -fdata-sections -ffunction-sections
73
74define rule_elf
75	$(call cmd,elf__,$(*F))
76	$(call cmd,prelink__)
77endef
78
79$(obj)/%.pbl: $(pbl-lds) $(BAREBOX_PBL_OBJS) $(BAREBOX_PIGGY_OBJS) FORCE
80	$(call if_changed_rule,elf)
81
82$(obj)/%.elf: $(pbl-lds) $(BAREBOX_PBL_OBJS) $(BAREBOX_PIGGY_OBJS) FORCE
83	$(call if_changed_rule,elf)
84
85
86# Convert the ELF into a linear binary, check for missing firmware
87# and verify file sizes:
88#
89# For each start symbol create three variables containing the
90# relevant sizes in the image:
91# PBL_CODE_SIZE_$(symbol)   - contains the pure code size of the image
92# PBL_MEMORY_SIZE_$(symbol) - contains the code size + bss size of the
93#                             image
94# PBL_IMAGE_SIZE_$(symbol)  - contains the full image size including the
95#                             compressed payload
96#
97# if MAX_PBL_xxx_SIZE_$(symbol) is defined it contains the maximum size the
98# code/memory/image for this PBL may get. Check these values.
99define rule_pblb
100	$(call cmd,objcopy_bin,$(*F))
101	$(call cmd,check_missing_fw,$@,$<)
102	$(call cmd,check_file_size,$@,$(CONFIG_BAREBOX_MAX_IMAGE_SIZE))
103
104	$(if $(MAX_PBL_CODE_SIZE_$*), \
105		$(call cmd,check_size,$(PBL_CODE_SIZE_$*),$(MAX_PBL_CODE_SIZE_$*)) \
106	)
107
108	$(if $(MAX_PBL_MEMORY_SIZE_$*), \
109		$(call cmd,check_size,$(PBL_MEMORY_SIZE_$*),$(MAX_PBL_MEMORY_SIZE_$*)) \
110	)
111
112	$(if $(MAX_PBL_IMAGE_SIZE_$*), \
113		$(call cmd,check_size,$(PBL_IMAGE_SIZE_$*),$(MAX_PBL_IMAGE_SIZE_$*)) \
114	)
115endef
116
117$(obj)/%.pblb: $(obj)/%.pbl FORCE
118	$(eval PBL_CODE_SIZE_$* = \
119		$(shell $(srctree)/scripts/extract_symbol_offset pbl_code_size $^))
120	$(eval PBL_MEMORY_SIZE_$*= \
121		$(shell $(srctree)/scripts/extract_symbol_offset pbl_memory_size $^))
122	$(eval PBL_IMAGE_SIZE_$*= \
123		$(shell $(srctree)/scripts/extract_symbol_offset pbl_image_size $^))
124
125	$(call if_changed_rule,pblb)
126
127$(obj)/%.s: $(obj)/% FORCE
128	$(call if_changed,disasm)
129
130quiet_cmd_itb = FIT.ITS $@
131cmd_itb = $(CPP) $(dtc_cpp_flags) -x assembler-with-cpp -o $(dtc-tmp) \
132	-D'$(subst -,_,$(*F))_dts=1' $(foreach f,$< $(2),-include '$(f)') /dev/null ; \
133	$(MKIMAGE) -f $(dtc-tmp) $@ -E \
134	cat $(depfile).pre $(depfile).dtc > $(depfile)
135
136$(obj)/%.itb: $(obj)/%.its FORCE
137	$(call if_changed,itb)

빌드 규칙을 더 깊게 읽기

01

구성과 target을 먼저 고정한다

Kconfig와 arch Makefile이 CONFIG_PBL_IMAGE, BAREBOX_PROPER, 보드별 image-y를 어떻게 선택하는지 확인한다. 같은 소스라도 이 설정에 따라 PBL과 최종 image 이름이 달라진다.

barebox ELF와 ROM 또는 다음 loader가 소비할 images/ 파일은 서로 다른 산출물이다.

02

main과 PBL archive를 분리한다

common-y는 main built-in.a, pbl-common-y는 별도 built-in.pbl.a 목록으로 이어진다. PBL object를 barebox ELF에서 추출한다고 해석하지 않는다.

make V=1의 링크 명령과 map에서 두 목록, 선택된 entry와 실제 section을 각각 확인한다.

03

주소와 크기 제한을 대조한다

pbl.lds와 PBL map으로 text, BSS, payload의 범위를 계산한다. PBL_CODE_SIZE, PBL_MEMORY_SIZE, PBL_IMAGE_SIZE와 보드가 지정한 상한은 서로 다른 구간을 검사한다.

04

payload 분기 뒤 PBL 링크를 확인한다

기본 경로에서는 BAREBOX_PROPER → barebox.z → piggy.o·sha_sum.o가 된다. CONFIG_PBL_IMAGE_NO_PIGGY면 BAREBOX_PROPER가 압축 객체 대신 직접 들어간다.

두 경우 모두 pbl.lds, BAREBOX_PBL_OBJS, BAREBOX_PIGGY_OBJS가 선택된 %.pbl 링크의 핵심 입력이다.

05

보드별 image 규칙을 끝까지 추적한다

pblb-y, image-y, FILE_*가 실제로 요청한 파일만 만든다. %.pblb 변환, SoC header, embedded DTB는 해당 target이 요구하는 경우에만 적용된다.

선택된 결과 파일의 entry, 크기와 header를 PBL map 및 보드의 부트 규약에 대조한다.

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

01

PBL과 full barebox는 서로 다른 실행 환경을 가진다

PBL의 진입 메모리는 보드 부트 경로에 따라 SRAM 또는 이미 준비된 DRAM일 수 있다. Boot ROM에서 직접 들어오는지 앞선 loader가 넘기는지, stack과 DDR을 누가 준비하는지 보드 entry에서 확인한다. full barebox의 driver, malloc, shell API가 source tree에 있다고 PBL에서 호출할 수 있는 것은 아니며 __PBL__ 조건과 PBL object 목록을 확인해야 한다.

같은 함수 이름도 PBL용 구현과 runtime 구현이 따로 선택될 수 있다.

02

링크 주소와 image packing 단계를 분리한다

PBL ELF의 text 주소, raw payload offset, SoC header가 선언한 load/entry 주소가 모두 맞아야 ROM에서 첫 instruction에 도달한다. piggydata로 full image를 포함하면 압축 data의 source와 decompression destination도 memory map에 추가한다.

map, objdump, final image hexdump에서 각 boundary를 같은 표로 대조한다.

03

크기 제한은 section과 기능 단위로 관리한다

SRAM 제한을 넘으면 header 생성은 성공해도 runtime stack이나 decompressor 영역이 겹칠 수 있다. text/data/BSS, embedded DT와 stack의 최대치를 따로 계산한다.

feature toggle 전후 section delta와 PBL call graph를 기록해 full-only code가 끌려 들어온 원인을 찾는다.

입력과 산출물의 소비 시점

대상생성 규칙·입력다음 소비자확인할 조건
BAREBOX_OBJScommon-y → built-in.abarebox ELF 링크main archive 목록과 linker script
BAREBOX_PBL_OBJSpbl-common-y → built-in.pbl.a선택된 %.pbl 링크PBL archive와 entry symbol
BAREBOX_PROPERbarebox에서 barebox.bin 또는 vmbarebox기본 piggy 압축 또는 NO_PIGGY 직접 입력payload 형식과 크기
%.pbl·%.pblbPBL objects + payload + pbl.lds선택된 board image 규칙map, entry, size 상한
images/*조건부 image-y·FILE_*보드 ROM 또는 다음 loader부트 규약에 필요한 header·DTB 여부

실패 지점과 증상

#조건관찰되는 증상먼저 볼 단계
01선택된 image-y·FILE_* 불일치원하는 파일이 없거나 형식이 다름보드 image 규칙
02PBL과 main payload 주소가 겹침적재·압축 해제 중 손상PBL map과 payload 크기
03보드가 요구한 header·DTB 누락ROM 적재 또는 보드 식별 실패해당 형식의 packing 규칙

링크 명령, map, 최종 파일 header를 거꾸로 추적해 잘못된 입력이나 형식이 선택된 지점을 찾는다.

빌드 산출물에서 확인할 증거

보드 defconfig, entry 이름, 최종 파일명은 실제 설정이 선택한 값으로 바꾼다. 기존 산출물이 있으면 ELF·map·파일 목록부터 읽고, make는 재현 빌드가 필요할 때 실행한다.

#목적명령 또는 파일판정 기준
01선택된 빌드 경로make <board>_defconfig && make V=1 imagesmain/PBL 링크 입력과 BAREBOX_PROPER, 보드별 image 명령을 구분해 기록한다.
02main ELF${CROSS_COMPILE}readelf -h -S bareboxmain section·entry를 확인하고 barebox.bin 또는 vmbarebox로 이어진 경로를 대조한다.
03PBL ELF·map${CROSS_COMPILE}readelf -h -S images/<entry>.pbl, images/<entry>.pbl.mapPBL entry·section과 기본 piggy 또는 NO_PIGGY 입력을 확인한다.
04실제 image 목록barebox-flash-images선택된 image-y 중 실제 만들어진 파일만 목록에 있는지 확인한다.
05보드별 형식make V=1 images/<selected>와 해당 파일 headerFILE_* 원본과 packing 명령을 따라 load/entry·header·DTB 요구 사항을 보드 규약과 대조한다.

직접 확인할 실험

  1. 01
    make V=1로 main/PBL 링크 명령 분리

    BAREBOX_OBJS와 BAREBOX_PBL_OBJS가 각각 어느 링크에 들어가는지 기록한다.

  2. 02
    readelf와 PBL map으로 payload 확인

    기본 piggy 경로의 barebox.z·piggy.o와 NO_PIGGY의 직접 입력 중 실제 설정이 택한 쪽을 확인한다.

  3. 03
    선택된 images/* 형식 검사

    image-y·FILE_*가 지정한 결과 파일의 entry·크기·header를 확인하고, DTB는 해당 보드 규칙이 요구할 때 대조한다.

원문과 다음 글