U-Boot · source analysis

빌드 산출물과 단계별 이미지

Kconfig와 Makefile의 선택이 u-boot, SPL, TPL, DTB와 결합 이미지로 굳어지는 과정을 정리합니다.

표의 버전은 소스 분석 기준이며 최신 보안 버전 권고가 아닙니다. TF-A LTS 2.14.3 이후에는 보안 수정이 있습니다. 제품 적용 시 공식 변경 기록과 사용 플랫폼의 errata를 확인하세요.

Series
01 / 22
Baseline
v2026.07
Commit
ece349ade297
Source
Makefile:1176-1264 (발췌 범위)

QUESTION

빌드 산출물과 단계별 이미지 단계에서 실제로 바뀌는 상태는 무엇인가?

실행 파일 하나만 보지 말고 링크 주소, 포함된 DTB, 패딩과 SoC 전용 헤더까지 산출물의 계보를 확인해야 한다.

ROM이 읽는 형식과 링크된 실행 주소가 보드의 부트 규약과 일치해야 한다. 이 문장을 기준으로 코드를 위에서 아래로 읽으면, 함수 이름을 외우는 대신 어느 시점에 어떤 상태를 신뢰할 수 있는지 판단할 수 있다.

STRUCTURE

객체와 주소가 놓이는 구조

그림 1. 빌드 산출물과 단계별 이미지에서 입력, 내부 상태, 출력의 경계
입력과 전제내부 상태외부로 공개되는 결과
01source objects
02linker script
03u-boot ELF
04u-boot.bin / u-boot.dtb
CONTRACT

이 흐름의 전제와 실패 조건

INPUTS-y += u-boot.srec를 중심에 놓고 왼쪽의 입력이 어떤 검사를 거쳐 오른쪽 결과로 공개되는지 표시했다. 실제 디버깅에서는 각 블록의 주소와 크기를 로그에 대입한다.

CALL PATH

실행 흐름

그림 2. 정상 경로의 주요 호출과 상태 전달
Kconfig
object list
u-boot ELF
binary and DTB
ROM image

화살표는 단순 호출 순서만 뜻하지 않는다. 각 단계가 성공을 반환할 때 다음 단계가 읽을 수 있는 상태가 무엇인지 함께 확인한다. 오류 반환이 발생하면 바로 다음 화살표로 진행하지 않고 해당 단계의 정리 경로를 따라간다.

STATE LEDGER

단계별 입력과 출력

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

#단계진입 시 신뢰할 상태성공 뒤 남아야 할 상태다음 소비자
01Kconfig빌드 시점source objectsobject list
02object listKconfig 완료 상태linker scriptu-boot ELF
03u-boot ELFobject list 완료 상태u-boot ELFbinary and DTB
04binary and DTBu-boot ELF 완료 상태u-boot.bin / u-boot.dtbROM image
05ROM imagebinary and DTB 완료 상태u-boot.bin / u-boot.dtb최종 u-boot, u-boot.bin, SPL/TPL, binman image 또는 다음 stage

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

UPSTREAM SOURCE

원본 코드

아래 코드는 U-Boot v2026.07의 Makefile에서 1176-1264줄을 그대로 가져온 것이다. 설명을 위해 실제 코드를 가짜 의사 코드로 바꾸지 않았다.

commitece349ade2973e220f524ce59e59711cc919263fanchor · L1200INPUTS-y += u-boot.srec
1176TPL_SIZE_CHECK =
1177endif
1178
1179ifneq ($(CONFIG_VPL_SIZE_LIMIT),0x0)
1180VPL_SIZE_CHECK = @$(call size_check,$@,$(CONFIG_VPL_SIZE_LIMIT))
1181else
1182VPL_SIZE_CHECK =
1183endif
1184
1185# Statically apply RELA-style relocations (currently arm64 only)
1186# This is useful for arm64 where static relocation needs to be performed on
1187# the raw binary, but certain simulators only accept an ELF file (but don't
1188# do the relocation).
1189ifneq ($(CONFIG_STATIC_RELA),)
1190# $(2) is u-boot ELF, $(3) is u-boot bin, $(4) is text base
1191quiet_cmd_static_rela = RELOC   $@
1192cmd_static_rela = \
1193	tools/relocate-rela $(3) $(2)
1194else
1195quiet_cmd_static_rela =
1196cmd_static_rela =
1197endif
1198
1199# Always append INPUTS so that arch config.mk's can add custom ones
1200INPUTS-y += u-boot.srec u-boot.bin u-boot.sym System.map binary_size_check
1201
1202ifeq ($(CONFIG_SPL_FSL_PBL),y)
1203INPUTS-$(CONFIG_RAMBOOT_PBL) += u-boot-with-spl-pbl.bin
1204else
1205ifneq ($(CONFIG_NXP_ESBC), y)
1206# For Secure Boot The Image needs to be signed and Header must also
1207# be included. So The image has to be built explicitly
1208INPUTS-$(CONFIG_RAMBOOT_PBL) += u-boot.pbl
1209endif
1210endif
1211INPUTS-$(CONFIG_SPL) += spl/u-boot-spl.bin
1212ifeq ($(CONFIG_MX6)$(CONFIG_IMX_HAB), yy)
1213INPUTS-$(CONFIG_SPL_FRAMEWORK) += u-boot-ivt.img
1214else
1215ifeq ($(CONFIG_MX7)$(CONFIG_IMX_HAB), yy)
1216INPUTS-$(CONFIG_SPL_FRAMEWORK) += u-boot-ivt.img
1217else
1218INPUTS-$(CONFIG_SPL_FRAMEWORK) += u-boot.img
1219endif
1220endif
1221INPUTS-$(CONFIG_TPL) += tpl/u-boot-tpl.bin
1222INPUTS-$(CONFIG_VPL) += vpl/u-boot-vpl.bin
1223
1224# Allow omitting the .dtb output if it is not normally used
1225INPUTS-$(CONFIG_OF_SEPARATE) += $(if $(CONFIG_OF_OMIT_DTB),dts/dt.dtb,u-boot.dtb)
1226ifeq ($(CONFIG_SPL_FRAMEWORK),y)
1227INPUTS-$(CONFIG_OF_SEPARATE) += u-boot-dtb.img
1228endif
1229INPUTS-$(CONFIG_SANDBOX) += u-boot.dtb
1230ifneq ($(CONFIG_SPL_TARGET),)
1231INPUTS-$(CONFIG_SPL) += $(CONFIG_SPL_TARGET:"%"=%)
1232endif
1233INPUTS-$(CONFIG_REMAKE_ELF) += u-boot.elf
1234INPUTS-$(CONFIG_SPL_REMAKE_ELF) += spl/u-boot-spl.elf
1235INPUTS-$(CONFIG_EFI_APP) += u-boot-app.efi
1236INPUTS-$(CONFIG_EFI_STUB) += u-boot-payload.efi
1237
1238# Generate this input file for binman
1239ifeq ($(CONFIG_SPL),)
1240ifneq ($(patsubst "%",%,$(CONFIG_MTK_BROM_HEADER_INFO)),)
1241INPUTS-$(CONFIG_ARCH_MEDIATEK) += u-boot-mtk.bin
1242endif
1243endif
1244
1245ifdef CONFIG_FUNCTION_TRACER
1246ifdef CONFIG_FTRACE_MCOUNT_USE_CC
1247  CC_FLAGS_FTRACE	+= -mrecord-mcount
1248  ifdef CONFIG_HAVE_NOP_MCOUNT
1249    ifeq ($(call cc-option-yn, -mnop-mcount),y)
1250      CC_FLAGS_FTRACE	+= -mnop-mcount
1251      CC_FLAGS_USING	+= -DCC_USING_NOP_MCOUNT
1252    endif
1253  endif
1254endif
1255ifdef CONFIG_FTRACE_MCOUNT_USE_OBJTOOL
1256  CC_FLAGS_USING	+= -DCC_USING_NOP_MCOUNT
1257endif
1258ifdef CONFIG_FTRACE_MCOUNT_USE_RECORDMCOUNT
1259  ifdef CONFIG_HAVE_C_RECORDMCOUNT
1260    BUILD_C_RECORDMCOUNT := y
1261    export BUILD_C_RECORDMCOUNT
1262  endif
1263endif
1264ifdef CONFIG_HAVE_FENTRY

READING CONTRACT

발췌 범위와 읽기 기준

원문 1176-1264줄에는 앞뒤 문맥이 포함됩니다. 기준 구문 INPUTS-y += u-boot.srec은 L1200에 있습니다. 발췌 첫 줄을 함수 정의의 시작으로 해석하지 않습니다.

실행 파일 하나만 보지 말고 링크 주소, 포함된 DTB, 패딩과 SoC 전용 헤더까지 산출물의 계보를 확인해야 한다.

DETAILS

내부 동작을 더 깊게 읽기

01

진입 조건을 먼저 고정한다

Kconfig에서 들어온 실행은 빌드 시점에 놓여 있다. 이때 interrupt, MMU/cache, stack, heap 중 무엇이 이미 준비되었는지 소스의 호출자까지 올라가 확인한다. 같은 함수라도 SPL, relocation 전후, app thread처럼 호출 문맥이 달라지면 허용되는 API와 지연 시간이 달라진다.

실행 파일 하나만 보지 말고 링크 주소, 포함된 DTB, 패딩과 SoC 전용 헤더까지 산출물의 계보를 확인해야 한다.

02

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

이 글의 중심 객체는 INPUTS-y += u-boot.srec다. 메모리를 확보한 시점, 필드를 채운 시점, 전역 list나 다른 subsystem에 공개한 시점을 구분한다. 공개 뒤 오류가 발생한다면 목록에서 제거하고 child, buffer, reference를 역순으로 정리하는지 확인한다.

빌드 산출물 관점에서는 u-boot, u-boot.bin, SPL/TPL, binman image 안에 해당 symbol과 section이 실제로 포함되었는지도 map과 objdump로 검증한다.

03

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

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

04

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

object list → u-boot ELF → binary and DTB 구간에서는 부분 초기화 상태가 생길 수 있다. flag, list insertion, callback 등록, storage write 완료 중 무엇이 성공의 기준인지 찾는다. hardware write나 DMA가 포함되면 함수 반환과 장치 완료가 같은 시점인지도 확인한다.

다른 CPU, 인터럽트 처리기, USB 완료 콜백, 셸 명령에서도 이 상태를 읽는다면 메모리 접근 순서와 잠금 범위를 함께 확인한다.

05

제어권을 넘기기 전에 확인할 조건을 정리한다

정상 경로는 ROM image에서 끝난다. 이 단계가 함수 반환인지, scheduler 전환인지, 다른 image로의 비복귀 분기인지 구분한다. 비복귀 handoff라면 cache clean/invalidate, interrupt disable, 장치 quiesce, argument register와 FDT 또는 image address가 최종 점검 항목이다.

호출한 함수로 돌아오는 경로라면 오류와 일부 처리만 완료된 상태를 구분하는지 확인한다. 이어서 다음 후보를 시도할지, 복구 절차를 실행할지 살펴본다.

IMPLEMENTATION NOTES

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

01

하나의 defconfig가 여러 실행 image를 만든다

U-Boot 빌드는 같은 source tree에서 TPL, SPL, U-Boot proper를 서로 다른 configuration과 object 목록으로 컴파일할 수 있다. obj-y에 보이는 파일이 모든 stage에 들어간다고 가정하면 안 되며 obj-$(CONFIG_...), ifdef CONFIG_XPL_BUILD, CONFIG_SPL_BUILD 조건을 전처리 결과에서 구분해야 한다.

각 stage는 별도 linker script와 link address를 가질 수 있다. ROM이 직접 읽는 SPL의 크기 제한과 DRAM에서 실행하는 U-Boot proper의 주소 제약은 다르므로 최종 u-boot.bin 하나만 확인해서는 초기 부팅 실패를 찾을 수 없다.

02

ELF, raw binary와 binman image의 주소 의미는 다르다

ELF의 section virtual address는 linker가 의도한 실행 주소를 보여 주지만 raw binary에는 주소 정보가 없다. objcopy 뒤 생긴 u-boot.bin의 offset 0은 ELF의 가장 낮은 loadable section에 대응할 뿐 physical address 0을 뜻하지 않는다.

binman이나 SoC 전용 image tool은 raw payload 앞뒤에 header, padding, DTB, firmware를 배치한다. ROM offset, header가 선언한 load address, ELF entry 세 값을 표로 놓고 대조해야 한다.

03

재현 가능한 산출물 계보를 남긴다

make V=1 로그에서 최종 link와 objcopy, image packing 명령을 분리해 보관한다. u-boot.map, readelf -l, objdump -h, binman map을 같은 build ID와 묶어 두면 크기 초과나 section 이동이 어느 단계에서 생겼는지 역추적할 수 있다.

incremental build의 오래된 object와 생성 DTB가 섞이는 문제를 피하려면 비교 실험에서는 output directory를 분리한다. 산출물 hash만 비교하지 말고 configuration, toolchain version, linker script도 함께 기록한다.

OBJECT LIFETIME

객체와 수명

대상만들어지는 시점유효 범위확인할 조건
INPUTS-y += u-boot.srecobject listROM image 또는 오류 정리 완료까지진입 전제와 상태 계약
입력 buffer / metadataKconfigparse와 검증이 끝날 때까지길이, 정렬, 소유권, 변조 가능성
등록된 list / descriptoru-boot ELF하위 시스템을 종료하거나 다음 이미지에 제어권을 넘길 때까지중복 등록, 해제된 객체를 가리키는 포인터, 오류 후 자원 정리
hardware 또는 persistent state실제 write/probe가 완료된 뒤reset 또는 명시적 해제·갱신까지쓰기 완료, 시간 초과, 전원 차단, 이전 상태 복원
u-boot, u-boot.bin, SPL/TPL, binman imagelink/image 생성 시점다음 stage가 새 image로 교체할 때까지적재 주소, 진입점, 섹션, 헤더의 일치 여부

FAILURE PATH

실패 지점과 증상

#조건관찰되는 증상먼저 볼 단계
01잘못된 defconfig필요한 stage가 생성되지 않음object list
02링커 주소 불일치reset 직후 예외u-boot ELF
03패딩 또는 헤더 오류ROM이 이미지를 거부binary and DTB

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

EVIDENCE

소스 밖에서 확인할 증거

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

#목적명령 또는 계측판정 기준
01전처리 결과make <board>_defconfig && make V=1선택된 CONFIG와 실제 compile/link 명령을 보관한다.
02symbol과 section${CROSS_COMPILE}nm -n u-boot | grep 'INPUTS-y += u-boot.srec'symbol 주소가 기대한 stage와 image에 들어갔는지 확인한다.
03어셈블리 대조${CROSS_COMPILE}objdump -drS u-bootC 한 줄이 실제 branch, relocation, memory access로 어떻게 바뀌었는지 본다.
04주소 배치bdinforelocaddr, malloc, FDT, stack과 DRAM bank 주소를 한 번에 기록한다.
05runtime 관찰dm tree; dm uclass; printenvdriver model과 환경이 이 단계에서 실제로 공개되었는지 확인한다.

LAB

직접 확인할 실험

  1. 01
    make V=1로 실제 링크 명령 기록

    object list 진입 전후에 source objects의 주소·크기·반환값과 timestamp를 함께 남긴다.

  2. 02
    readelf -h와 objdump -h로 ELF 주소 확인

    u-boot ELF 진입 전후에 linker script의 주소·크기·반환값과 timestamp를 함께 남긴다.

  3. 03
    binman map과 최종 이미지 offset 대조

    binary and DTB 진입 전후에 u-boot ELF의 주소·크기·반환값과 timestamp를 함께 남긴다.

PRIMARY REFERENCES

원문과 다음 글

Makefilev2026.07 원본 파일 U-Boot source tree기준 commit ece349ade297