QUESTION
Barebox 빌드 산출물과 PBL image 단계에서 실제로 바뀌는 상태는 무엇인가?
barebox 실행 파일과 images/ 아래 ROM 투입 파일을 구분한다. main payload 압축, 헤더, load address가 최종 파일에서 어디에 놓이는지 본다.
ROM용 image의 header, load address, entry와 포함된 PBL/main payload의 위치가 보드 부트 규약과 일치해야 한다. 이 문장을 기준으로 코드를 위에서 아래로 읽으면, 함수 이름을 외우는 대신 어느 시점에 어떤 상태를 신뢰할 수 있는지 판단할 수 있다.
STRUCTURE
서로 다른 빌드 입력과 선택된 산출물
main/PBL 구성과 보드 image target을 선택한다.
built-in.a 묶음이 barebox ELF를 링크한다.
별도의 built-in.pbl.a 묶음이다.
image-y와 보드 규칙이 요구한 파일만 생성된다.
두 object 묶음은 서로를 생산하지 않는다. main 산출물은 기본 piggy 경로에서 압축 payload가 되어 PBL 링크에 합류한다.
BUILD GRAPH
main과 PBL 경로가 합류하는 지점
main과 PBL에 쓰일 archive 목록 및 보드 image target 선택
built-in.a → barebox ELF → BAREBOX_PROPER
built-in.pbl.a · PBL 전용 링크 입력
기본 경로: BAREBOX_PROPER → barebox.z → piggy.o·sha_sum.o
보드·설정에 따라 SoC wrapper 또는 다른 형식·파일명을 사용
CONFIG_PBL_IMAGE_NO_PIGGY에서는 압축 piggy 대신 BAREBOX_PROPER가 PBL 링크에 직접 들어간다. images/* 전체가 모든 보드에서 생기는 것은 아니다.
STATE LEDGER
단계별 입력과 출력
고정 v2026.06.1 Makefile의 target 의존 관계다. main archive와 PBL archive는 병렬적인 입력이며, payload 준비 뒤 PBL 링크에서 합류한다.
| # | 경로·target | 핵심 입력 | 생성물 | 조건·다음 소비자 |
|---|---|---|---|---|
| 01 | 구성 | defconfig·Kconfig·arch Makefile | common-y와 pbl-common-y | 서로 다른 main/PBL archive 목록 |
| 02 | main link | BAREBOX_OBJS (built-in.a) | barebox ELF → BAREBOX_PROPER | 기본값은 barebox.bin, PBL ELF 설정은 vmbarebox |
| 03 | payload 준비 | BAREBOX_PROPER | 기본: barebox.z → piggy.o·sha_sum.o | NO_PIGGY이면 원본을 직접 PBL 링크에 사용 |
| 04 | PBL link | pbl.lds + BAREBOX_PBL_OBJS + BAREBOX_PIGGY_OBJS | %.pbl ELF; 요청 시 %.pblb raw | 선택된 PBL entry와 image 규칙 |
| 05 | board image | pblb-y, image-y, FILE_* | 설정으로 선택된 images/* | SoC wrapper·header는 형식별 규칙에 따름 |
분석 범위의 전제와 비교해, 잘못된 archive, payload 또는 image target이 선택된 지점부터 조사한다.
VISUAL WALKTHROUGH
PBL 링크의 합류 입력과 형식별 출력
make V=1, PBL map과 최종 image header를 함께 읽어 구성별 실제 입력·entry·크기를 확인한다.
BAREBOX_PBL_OBJS는 두 경우 모두 별도의 입력이다. main 산출물이 들어오는 방법만 설정에 따라 달라진다.
압축 main payload가 piggy.o와 sha_sum.o로 준비된다.
BAREBOX_PIGGY_OBJS가 압축 객체 대신 main 산출물을 가리킨다.
%.pbl ELF를 링크하고 필요하면 %.pblb raw binary를 만든다.왼쪽 생산자가 가운데 파일·목록을 만들고 오른쪽 target이 소비한다. 조건부 경로는 별도로 표시했다.
common-y→BAREBOX_OBJS→barebox ELFpbl-common-y→BAREBOX_PBL_OBJS→%.pbl linkBAREBOX_PROPER→barebox.z·piggy.o (기본)→%.pbl linkpbl.lds·PBL inputs→%.pbl → 필요 시 %.pblb→선택된 image targetimage-y·FILE_*→보드별 형식·파일명→images/*UPSTREAM SOURCE
원본 코드
아래 코드는 Barebox v2026.06.1의 Makefile에서 1074-1162줄을 그대로 가져온 것이다.
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
READING CONTRACT
발췌 범위와 읽기 기준
원문 1074-1162줄에는 앞뒤 문맥이 포함됩니다. 기준 구문 barebox: $(BAREBOX_LDS)은 L1098에 있습니다. 발췌 첫 줄을 함수 정의의 시작으로 해석하지 않습니다.
barebox 실행 파일과 images/ 아래 ROM 투입 파일을 구분한다. main payload 압축, 헤더, load address가 최종 파일에서 어디에 놓이는지 본다.
RELATED SOURCE
함께 읽어야 하는 원본 코드
첫 코드 조각만으로 동작이 완성되지 않는 경우 호출 매크로, 객체 정의와 실제 실행 목록을 같은 페이지에 묶었다. 각 조각은 같은 기준 commit에서 가져왔다.
01. PBL ELF와 binary image를 링크하는 규칙
images/Makefile 61-137줄이다.
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)
DETAILS
빌드 규칙을 더 깊게 읽기
구성과 target을 먼저 고정한다
Kconfig와 arch Makefile이 CONFIG_PBL_IMAGE, BAREBOX_PROPER, 보드별 image-y를 어떻게 선택하는지 확인한다. 같은 소스라도 이 설정에 따라 PBL과 최종 image 이름이 달라진다.
barebox ELF와 ROM 또는 다음 loader가 소비할 images/ 파일은 서로 다른 산출물이다.
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을 각각 확인한다.
주소와 크기 제한을 대조한다
pbl.lds와 PBL map으로 text, BSS, payload의 범위를 계산한다. PBL_CODE_SIZE, PBL_MEMORY_SIZE, PBL_IMAGE_SIZE와 보드가 지정한 상한은 서로 다른 구간을 검사한다.
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 링크의 핵심 입력이다.
보드별 image 규칙을 끝까지 추적한다
pblb-y, image-y, FILE_*가 실제로 요청한 파일만 만든다. %.pblb 변환, SoC header, embedded DTB는 해당 target이 요구하는 경우에만 적용된다.
선택된 결과 파일의 entry, 크기와 header를 PBL map 및 보드의 부트 규약에 대조한다.
IMPLEMENTATION NOTES
구현을 읽을 때 놓치기 쉬운 부분
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 구현이 따로 선택될 수 있다.
링크 주소와 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를 같은 표로 대조한다.
크기 제한은 section과 기능 단위로 관리한다
SRAM 제한을 넘으면 header 생성은 성공해도 runtime stack이나 decompressor 영역이 겹칠 수 있다. text/data/BSS, embedded DT와 stack의 최대치를 따로 계산한다.
feature toggle 전후 section delta와 PBL call graph를 기록해 full-only code가 끌려 들어온 원인을 찾는다.
BUILD ARTIFACTS
입력과 산출물의 소비 시점
| 대상 | 생성 규칙·입력 | 다음 소비자 | 확인할 조건 |
|---|---|---|---|
BAREBOX_OBJS | common-y → built-in.a | barebox ELF 링크 | main archive 목록과 linker script |
BAREBOX_PBL_OBJS | pbl-common-y → built-in.pbl.a | 선택된 %.pbl 링크 | PBL archive와 entry symbol |
BAREBOX_PROPER | barebox에서 barebox.bin 또는 vmbarebox | 기본 piggy 압축 또는 NO_PIGGY 직접 입력 | payload 형식과 크기 |
%.pbl·%.pblb | PBL objects + payload + pbl.lds | 선택된 board image 규칙 | map, entry, size 상한 |
images/* | 조건부 image-y·FILE_* | 보드 ROM 또는 다음 loader | 부트 규약에 필요한 header·DTB 여부 |
FAILURE PATH
실패 지점과 증상
| # | 조건 | 관찰되는 증상 | 먼저 볼 단계 |
|---|---|---|---|
| 01 | 선택된 image-y·FILE_* 불일치 | 원하는 파일이 없거나 형식이 다름 | 보드 image 규칙 |
| 02 | PBL과 main payload 주소가 겹침 | 적재·압축 해제 중 손상 | PBL map과 payload 크기 |
| 03 | 보드가 요구한 header·DTB 누락 | ROM 적재 또는 보드 식별 실패 | 해당 형식의 packing 규칙 |
링크 명령, map, 최종 파일 header를 거꾸로 추적해 잘못된 입력이나 형식이 선택된 지점을 찾는다.
EVIDENCE
빌드 산출물에서 확인할 증거
보드 defconfig, entry 이름, 최종 파일명은 실제 설정이 선택한 값으로 바꾼다. 기존 산출물이 있으면 ELF·map·파일 목록부터 읽고, make는 재현 빌드가 필요할 때 실행한다.
| # | 목적 | 명령 또는 파일 | 판정 기준 |
|---|---|---|---|
| 01 | 선택된 빌드 경로 | make <board>_defconfig && make V=1 images | main/PBL 링크 입력과 BAREBOX_PROPER, 보드별 image 명령을 구분해 기록한다. |
| 02 | main ELF | ${CROSS_COMPILE}readelf -h -S barebox | main section·entry를 확인하고 barebox.bin 또는 vmbarebox로 이어진 경로를 대조한다. |
| 03 | PBL ELF·map | ${CROSS_COMPILE}readelf -h -S images/<entry>.pbl, images/<entry>.pbl.map | PBL entry·section과 기본 piggy 또는 NO_PIGGY 입력을 확인한다. |
| 04 | 실제 image 목록 | barebox-flash-images | 선택된 image-y 중 실제 만들어진 파일만 목록에 있는지 확인한다. |
| 05 | 보드별 형식 | make V=1 images/<selected>와 해당 파일 header | FILE_* 원본과 packing 명령을 따라 load/entry·header·DTB 요구 사항을 보드 규약과 대조한다. |
LAB
직접 확인할 실험
- 01make V=1로 main/PBL 링크 명령 분리
BAREBOX_OBJS와BAREBOX_PBL_OBJS가 각각 어느 링크에 들어가는지 기록한다. - 02readelf와 PBL map으로 payload 확인
기본 piggy 경로의
barebox.z·piggy.o와NO_PIGGY의 직접 입력 중 실제 설정이 택한 쪽을 확인한다. - 03선택된 images/* 형식 검사
image-y·FILE_*가 지정한 결과 파일의 entry·크기·header를 확인하고, DTB는 해당 보드 규칙이 요구할 때 대조한다.
PRIMARY REFERENCES