U-Boot · source analysis

SPL의 image 선택과 적재

SPL이 후보 boot device와 loader를 순회하고, 형식별로 이미지를 읽어 선택된 다음 stage에 제어권을 넘기는 경로를 읽습니다.

Series
07 / 22
Baseline
v2026.07
Commit
ece349ade297
Source
common/spl/spl.c:648-736 (발췌 범위)

v2026.07은 이 글의 소스 분석 기준이며 보안 업데이트 권고 버전이 아닙니다. 제품 적용에는 U-Boot 보안 정책과 FIT 서명 문서를 확인하고, 활성화한 검증 설정·키·fallback 정책을 함께 점검하세요.

어떤 loader가 다음 stage를 결정하는가?

SPL은 U-Boot가 반드시 거치는 단계가 아니다. Boot ROM의 적재 주소·크기 제한, DDR 초기화 주체와 보드의 후속 이미지·검증 정책에 따라 ROM → U-Boot proper 또는 ROM → SPL → U-Boot proper 같은 경로를 사용한다. 공식 부트 단계 문서에서 TPL/VPL/SPL은 선택 단계다. 아래 loader 분석은 SPL을 사용하는 빌드에 관한 것이며, SPL이 Linux나 다른 펌웨어를 적재하는 구성도 있다.

NXP의 2020년 i.MX 포팅 가이드 §3.2.1에서는 i.MX 6Quad 구성 예의 ROM이 이미지 헤더의 DCD 명령으로 DDR을 초기화한다. 같은 문서의 i.MX 8M Quad/Mini/Nano/Plus BSP 경로는 SPL에서 DDR controller/PHY 초기화와 training을 수행한다. 이는 해당 가이드의 구성 대비이며 모든 i.MX 6·8 보드에 적용되는 부팅 경로를 뜻하지 않는다.

board_init_r()는 board_boot_order()가 채운 후보 장치를 순서대로 시도한다. 같은 장치 번호를 등록한 loader를 호출해 성공한 첫 결과가 spl_image_info와 boot_device를 확정한다. 모든 후보가 실패하면 이 경로는 hang()한다.

FIT, legacy, raw 및 매체별 loader는 빌드 설정과 보드 선택에 따라 달라진다. spl_image_info의 주소·크기·OS 필드는 실행 계획이며, 그 자체가 암호학적 검증 완료 표시가 아니다.

Rockchip에서는 ROM과 적재 이미지를 구분합니다

BootROM 자체와 저장 매체에 기록하는 초기 로더 이미지는 서로 다릅니다. idbloader.img를 기록하는 작업을 BootROM 코드를 바꾸는 작업으로 표현하지 않습니다. 이 글과 같은 U-Boot 고정 소스의 Rockchip 문서는 TPL/SPL 경로와 Rockchip miniloader 패키징을 나누어 설명합니다. 일부 SoC에서는 DRAM 초기화를 위해 ROCKCHIP_TPL로 공급하는 DDR 바이너리를 사용하며, ARM64 이미지에는 해당 플랫폼의 TF-A/BL31 구성도 확인해야 합니다. 모든 보드가 같은 초기 로더를 쓰는 것은 아닙니다.

초기 부팅 실패는 ROM의 매체 접근, 초기 로더의 DDR 초기화, 후속 이미지 적재를 나누어 기록합니다. USB 복구 상태와 정상 매체 부팅도 구분해야 합니다. 예를 들어 문서는 RK3066 ROM의 SDMMC 미지원과 다른 부팅 경로 실패 시 USB OTG 복구를 설명하지만, 이를 모든 Rockchip 보드의 진입 조건으로 일반화하지 않습니다. 이미지 파일명·기록 위치·복구 진입 방법은 정확한 SoC, 보드, 펌웨어 조합의 문서로 확인해야 합니다.

후보·loader·결과의 관계

그림 1. SPL이 소유하는 객체와 적재 경계
splv-objectsboard_boot_order가 후보 배열을 채우고 loader linker list와 장치 번호가 결합하여 spl_load_image가 spl_image_info 및 메모리 적재를 만든다.board_boot_order()board/weak 기본값spl_boot_list[]순서 있는 후보 장치loader linker list빌드 시 등록한 방법bootdev match장치 번호가 같은 loaderspl_load_image()read / parse / checkspl_image_infoload / entry / os / sizepayload memory선택된 load_addr장치와 형식에 따라 read buffer · 목적지 메모리 배치는 달라진다.

↔ 그림을 좌우로 밀어 이어지는 경로를 확인하세요.

배열은 실행 중 후보 순서를, linker list는 빌드에 포함된 loader 방법을 나타낸다. spl_image_info와 payload의 메모리 주소는 형식·보드에 따라 달라진다.

성공과 실패가 갈라지는 지점

그림 2. SPL을 사용하는 구성의 boot_from_devices() 반복·종료
splv-choices후보 장치를 순서대로 돌며 같은 장치의 loader를 시도한다. 성공은 boot_device를 설정하고 handoff로, 실패는 다음 loader 또는 장치로, 모두 실패하면 hang으로 간다.board_init_r()board_boot_orderboot list 순회NONE 전까지loader 순회boot_device 일치spl_load_image()매체 / 형식 / board 검사ret == 0boot_device 설정fixups → jumper선택된 OS/entry후보 소진board_init_r: hang()ret ≠ 0: 다음 loader / 장치성공더는 시도할 후보 없음OS별 jumper와 준비 단계는 board_init_r의 후반부(L768–854)

↔ 그림을 좌우로 밀어 이어지는 경로를 확인하세요.

이 그림은 SPL 진입 뒤의 내부 반복을 나타낸다. 앞선 TPL/VPL 단계는 구성에 따라 존재하거나 생략되며, ROM이 U-Boot proper로 직접 들어가는 구성에는 이 SPL 내부 경로가 없다. 한 loader의 실패가 곧바로 종료를 뜻하지 않는다. 다음 등록 loader 또는 다음 boot device를 계속 살핀다. ret == 0에서만 선택 장치가 기록된다.

단계별 입력과 출력

아래 그림과 상태 표는 SPL을 사용하는 빌드의 내부 동작에만 적용된다. 앞선 TPL/VPL 및 SPL의 존재와 다음 stage는 보드 구성에서 확인한다.

부트 구성 예SPL 경로이 글의 적용 범위
ROM → U-Boot proper사용하지 않음아래 SPL loader 반복과 상태 표를 거치지 않는다.
ROM → SPL → 선택된 다음 stage사용함아래는 SPL 진입 뒤 후보 장치·loader·형식 적재를 설명한다. TPL/VPL이 앞에 있을 수도 있다.

↔ 적용 범위 표를 좌우로 밀어 나머지 열을 확인하세요.

단계소스 위치진입 상태성공 후 상태
후보 구성spl.c:674, 755spl_boot_list[]가 NONE으로 초기화됨보드가 장치 순서를 채움. weak 기본은 단일 spl_boot_device()
loader 선택spl.c:626–650장치 번호와 linker-list loader장치 번호가 일치하는 loader의 load_image() 호출
형식/매체 적재spl_load.h:13–96 등매체별 read와 offset, 버퍼설정된 형식 parser가 load_addr, size, entry_point, os 등을 채움
추가 검사spl.c:599–611loader 반환값과 파싱 결과조건부 legacy data CRC, board image check까지 ret == 0
최종 선택spl.c:651–654, 757–854성공한 loader 결과boot_device 기록, arch/board fixup 및 OS별 handoff 준비

↔ 상태 표를 좌우로 밀어 나머지 열을 확인하세요.

실패 시 partial 상태를 성공한 이미지처럼 사용하지 않는다. 다음 후보를 시도한 뒤 모두 실패하면 board_init_r()에서 hang()한다.

형식과 검증 경로를 분리해서 읽기

그림 3. 헤더 이후의 조건부 형식 분기
splv-formatsspl_load는 헤더를 읽고 FIT magic이면 full 또는 simple FIT 경로, 아니면 구성된 container, legacy LZMA 또는 header parser 경로로 간다. 각 경로의 검증은 설정 조건부다.spl_load_info.read헤더 / 매체별 offsetFDT_MAGIC?FIT 여부FIT full / simple설정별 선택i.MX / legacy LZMA일치하면 별도 적재parse headerlegacy / board / rawload_addr / entry형식별 결과FIT그 외불일치CONFIG와 헤더 결과에 따라 실제 적재 함수가 다르다.읽기 실패 · 헤더 거부 · 검증 실패는 ret ≠ 0 → 다음 loader 후보

↔ 그림을 좌우로 밀어 이어지는 경로를 확인하세요.

_spl_load()는 매체별 read 계약을 사용한다. FIT magic과 SPL 설정이 형식별 경로를 가르며, raw fallback은 CONFIG_SPL_RAW_IMAGE_SUPPORT 등 parser 조건에 좌우된다.

경로조건/선택검증·적재상 주의
FIT full/simpleFDT_MAGIC + LOAD_FIT_FULL 또는 LOAD_FIT일반 simple FIT 처리에서는 configuration을 찾고 firmware → 조건부 kernel → loadables를 선택한다. config/image 검증은 관련 CONFIG가 켜져야 한다.
i.MX container / legacy LZMA해당 기능이 빌드된 경우별도 parser/해제 경로다. FIT의 configuration·signature 단계를 일반화하면 안 된다.
legacy / board header / rawspl_parse_image_header()와 설정legacy data CRC는 CONFIG_SPL_LEGACY_IMAGE_CRC_CHECK 조건부이며 서명 검증과 다르다. raw 허용 여부는 빌드 정책이다.
그림 4. simple FIT: 검증 대상과 목적지의 차이
splv-trustsimple FIT 경로에서 configuration 선택 뒤 설정이 있으면 configuration signature를 검증하고, 이미지 payload는 설정이 있으면 서명 또는 해시 검사 후 postprocess와 압축 해제 또는 memmove를 거쳐 목적지에 놓인다.FIT config 선택fit_find_config_nodeconfig 검증SPL_FIT_SIGNATURE일 때payload sourceembedded / externalimage verifyFIT_SIGNATURE일 때post-process설정된 경우에만destinationdecompress / memmoveconfig 검사 OFFimage 검사 OFF검증 대상 source 표현과 최종 목적지 byte는 압축 해제·후처리로 달라질 수 있다.신뢰 경계: 선택된 config + 검증 범위 + 변환 뒤 load/entry를 함께 확인

↔ 그림을 좌우로 밀어 이어지는 경로를 확인하세요.

spl_fit.c:325–369, 771–854. image 검증은 읽어 온 source payload에 수행되고, 후처리·압축 해제 시 최종 destination byte는 달라질 수 있다. 보안 검토에서는 선택한 config, 검증 범위, 변환 후 entry를 각각 확인한다.

원본 코드

아래 코드는 U-Boot v2026.07의 common/spl/spl.c에서 648-736줄을 그대로 가져온 것이다.

commitece349ade2973e220f524ce59e59711cc919263fanchor · L672void board_init_r(gd_t *dummy1, ulong dummy2)
648			}
649
650			ret = spl_load_image(spl_image, loader);
651			if (!ret) {
652				spl_image->boot_device = bootdev;
653				return 0;
654			}
655			printf("Error: %d\n", ret);
656		}
657
658		if (!CONFIG_IS_ENABLED(SILENT_CONSOLE)) {
659			if (CONFIG_IS_ENABLED(SHOW_ERRORS))
660				printf(PHASE_PROMPT
661				       "Unsupported Boot Device %d\n",
662				       bootdev);
663			else
664				printf(PHASE_PROMPT
665				       "Unsupported Boot Device!\n");
666		}
667	}
668
669	return ret;
670}
671
672void board_init_r(gd_t *dummy1, ulong dummy2)
673{
674	u32 spl_boot_list[] = {
675		BOOT_DEVICE_NONE,
676		BOOT_DEVICE_NONE,
677		BOOT_DEVICE_NONE,
678		BOOT_DEVICE_NONE,
679		BOOT_DEVICE_NONE,
680	};
681	spl_jump_to_image_t jumper = &jump_to_image;
682	struct spl_image_info spl_image;
683	int ret, os;
684	void *fdt;
685
686	debug(">>" PHASE_PROMPT "board_init_r()\n");
687
688	spl_set_bd();
689
690	if (IS_ENABLED(CONFIG_SPL_SYS_MALLOC)) {
691		mem_malloc_init(SPL_SYS_MALLOC_START, SPL_SYS_MALLOC_SIZE);
692		gd->flags |= GD_FLG_FULL_MALLOC_INIT;
693	}
694	if (!(gd->flags & GD_FLG_SPL_INIT)) {
695		if (spl_init())
696			hang();
697	}
698	timer_init();
699	if (CONFIG_IS_ENABLED(BLOBLIST)) {
700		ret = bloblist_init();
701		if (ret) {
702			debug("%s: Failed to set up bloblist: ret=%d\n",
703			      __func__, ret);
704			puts(PHASE_PROMPT "Cannot set up bloblist\n");
705			hang();
706		}
707	}
708	if (CONFIG_IS_ENABLED(HANDOFF)) {
709		int ret;
710
711		ret = setup_spl_handoff();
712		if (ret) {
713			puts(PHASE_PROMPT "Cannot set up SPL handoff\n");
714			hang();
715		}
716	}
717
718	if (CONFIG_IS_ENABLED(SOC_INIT))
719		spl_soc_init();
720
721	if (IS_ENABLED(CONFIG_SPL_WATCHDOG) && CONFIG_IS_ENABLED(WDT))
722		initr_watchdog();
723
724	if (IS_ENABLED(CONFIG_SPL_OS_BOOT) || CONFIG_IS_ENABLED(HANDOFF) ||
725	    IS_ENABLED(CONFIG_SPL_ATF) || IS_ENABLED(CONFIG_SPL_NET))
726		dram_init_banksize();
727
728	if (IS_ENABLED(CONFIG_SPL_LMB))
729		lmb_init();
730
731	if (CONFIG_IS_ENABLED(PCI) && !(gd->flags & GD_FLG_DM_DEAD)) {
732		ret = pci_init();
733		if (ret)
734			puts(PHASE_PROMPT "Cannot initialize PCI\n");
735		/* Don't fail. We still can try other boot methods. */
736	}

발췌 범위와 읽기 기준

형식 그림은 관련 적재 기능이 켜진 경로를 요약한다. FDT_MAGIC이 있어도 두 FIT 적재 기능이 꺼져 있으면 _spl_load()는 No FIT support를 남긴 뒤 나머지 형식·헤더 처리로 내려간다. magic 확인만으로 FIT 검증 실행을 단정하지 않는다. 또 spl_load_simple_fit_skip_processing()이 참인 load-only 경로는 FIT 버퍼를 읽은 뒤 configuration 선택·payload 처리 전에 0을 반환한다. 위의 일반 simple FIT 도식과 성공 상태 설명을 이 특수 경로에 그대로 적용하지 않는다.

아래 고정 원문은 common/spl/spl.c:648–736이다. L648–670은 boot_from_devices()의 끝이고, void board_init_r(gd_t *dummy1, ulong dummy2)는 L672에서 시작한다. 발췌 첫 줄을 함수 시작으로 읽지 않는다.

이 글의 반환 경로를 완성하려면 발췌 밖의 board_boot_order() L755, boot_from_devices() 호출 L757, 실패 hang() L759–765와 OS별 진입 L771–854도 함께 읽어야 한다.

내부 동작을 더 깊게 읽기

01

보드가 후보 순서를 정한다

spl_boot_list[]는 BOOT_DEVICE_NONE으로 초기화되고 board_boot_order()가 순서를 채운다. weak 기본 구현은 spl_boot_device() 하나를 넣는다. 복수 장치와 우선순위는 보드 구현을 확인해야 한다.

02

loader는 등록된 방법 중 번호가 맞는 것만 사용한다

boot_from_devices()는 linker list의 spl_image_loader 항목을 돌며 장치 번호가 맞을 때만 spl_load_image()를 호출한다. 실패하면 다른 loader나 후보를 시도한다. 성공한 순간에만 spl_image->boot_device를 기록한다.

03

형식 parser와 매체 read를 구분한다

MMC raw-sector·filesystem·eMMC boot partition, SPI 등은 시작 offset과 읽기 방법이 다르다. spl_load_info의 bl_len과 read가 정렬 단위를 제공하고, 형식 parser는 header를 읽어 load/entry/size를 정한다.

04

검사는 빌드 설정별이다

simple FIT의 configuration signature 검사와 image payload 검사는 각각 CONFIG_SPL_FIT_SIGNATURE, CONFIG_IS_ENABLED(FIT_SIGNATURE) 조건을 확인한다. legacy data CRC 역시 별도 설정이다. 성공 반환만으로 암호학적 검증을 추론할 수 없다.

05

다음 stage는 OS에 따라 달라진다

성공 뒤 arch/board fixup과 spl_board_prepare_for_boot()를 거쳐 OS별 jumper로 간다. U-Boot proper 외에도 빌드된 경로에서는 ATF, OP-TEE, OpenSBI 또는 Linux 등으로 이어질 수 있다. entry와 인수·FDT는 선택된 경로에서 확인한다.

검증 경계와 fallback 정책

01

서명과 CRC의 의미는 다르다

FIT 검증은 선택한 config와 image에 대해 활성 설정·키·서명 범위를 함께 봐야 한다. legacy CRC는 전송 오류 검출이며 신뢰된 발행자 확인이 아니다. raw 경로가 허용되면 제품 verified-boot 정책과 충돌할 수 있다.

02

source와 destination은 같은 byte열일 필요가 없다

simple FIT는 embedded/external source를 읽어 조건부 image 검증을 수행하고, 이후 보드 post-process나 gzip/LZMA 압축 해제 또는 memmove()로 목적지에 적재한다. 검증 대상 표현과 실행 대상 메모리 범위, entry가 서로 어떻게 연결되는지 확인해야 한다.

03

fallback은 바깥 반복까지 본다

예를 들어 MMC/SPI의 CONFIG_SPL_OS_BOOT_SECURE는 해당 loader 안의 OS boot → U-Boot fallback을 제한한다. 하지만 boot_from_devices()는 nonzero 반환 뒤 다른 loader/장치를 계속 시도할 수 있다. 서명 실패 뒤 미검증 대체 경로가 열리는지 후보 전체를 감사해야 한다.

객체와 수명

대상만들어지는 곳유효 기간과 의미
spl_boot_list[]board_init_r() 스택board_boot_order()가 채우고 boot_from_devices()의 후보 순회를 이끈다.
spl_image_loader linker listSPL 링크 시빌드에 포함된 loader descriptor. 실행 중 전역 list에 삽입/제거하는 객체가 아니다.
spl_boot_device bootdevspl_load_image() 지역 변수선택 loader 번호를 callback에 전달한다. 성공 후 spl_image_info.boot_device에 번호를 복사한다.
spl_image_infoboard_init_r()에서 초기화load 주소, 크기, entry, OS 등 handoff용 필드를 담는다. 검증 verdict 전용 객체가 아니다.
payload / read buffer형식·매체 loader 내부header, external/embedded source, 임시 압축 입력, destination을 구별해 실제 주소 범위를 검토한다.
spl/u-boot-spl ELF · spl/u-boot-spl.map · spl/u-boot-spl.binSPL 빌드·링크 시ELF와 map에서 symbol·section을 확인한다. bin은 별도 바이너리 산출물이며 보드별 배포용 부트 이미지에 헤더나 다른 구성 요소가 더해질 수 있다. 파일 수명과 적재된 SPL 메모리 수명은 다르다.

실패 지점과 다음 동작

조건대표 반환/현상다음 확인
매체 short read 또는 offset 오류_spl_load() 및 FIT 외부 데이터 read가 -EIO 가능장치·mode·offset·읽은 길이·정렬 단위
header/형식 불일치설정된 parser가 거부하거나 raw fallback 사용CONFIG_SPL_RAW_IMAGE_SUPPORT, board parser, 기대한 형식
FIT/CRC 검사 실패설정된 검사에서 nonzero 반환검증 대상·키·서명 범위·뒤이은 다른 loader/장치
후보 전체 실패board_init_r()의 hang()실제 boot list와 각 loader 반환값. 자동 복구 경로로 단정하지 않음

검증 실패 후 다른 장치로 넘어가는 경로는 제품의 허용 목록과 대조해야 한다. 여기의 반복 로직 자체는 오류 종류별 보안 정책을 분류하지 않는다.

SPL 자체에서 확인할 증거

보드 이름과 툴체인 접두사는 빌드 환경에 맞게 바꾼다. 아래 명령은 호스트의 빌드 산출물을 읽는다. 대상 보드에서는 SPL serial log를 관찰한다. 이 글에서 특정 보드의 빌드·실행을 재현한 것은 아니다. bdinfo, dm tree, printenv는 해당 명령을 포함한 U-Boot proper에서 확인하는 항목이며 SPL 내부 상태의 직접 증거로 쓰지 않는다.

목적명령/계측 예판정 기준
설정 확인grep -E '^CONFIG_SPL_(LOAD_FIT(_FULL)?|FIT_SIGNATURE|RAW_IMAGE_SUPPORT|LEGACY_IMAGE_CRC_CHECK|OS_BOOT(_SECURE)?|LZMA|LOAD_IMX_CONTAINER)=' .config그림의 조건부 분기가 해당 보드에서 실제로 켜졌는지 확인
SPL 심벌${CROSS_COMPILE}nm -n spl/u-boot-spl | grep ' board_init_r$'full U-Boot의 u-boot가 아니라 SPL ELF에서 실제 심벌명과 주소를 확인한다. nm 출력은 C 함수 선언문이 아니다
분기·링크실행 명령: ${CROSS_COMPILE}objdump -drS spl/u-boot-spl
별도로 읽을 지도 파일: spl/u-boot-spl.map
선택된 loader와 실제 주소·section을 확인한다. 지도 파일 자체는 실행 명령이 아니다. objdump -S의 소스 줄 병기는 디버그 정보와 소스 파일을 찾을 수 있는지에 달려 있다
실행 로그SPL UART의 Trying to boot from …, Error: …와 보드별 간단 계측장치·loader·반환값·최종 OS/entry 순서 확인. SPL shell 존재를 가정하지 않음

실험 보드에서 확인할 분기

  1. 01
    후보와 loader를 같은 로그에 기록

    board_boot_order()의 실제 배열과 boot_from_devices()의 loader 이름·ret를 대응시킨다. 성공한 장치만 spl_image.boot_device에 남는지 본다.

  2. 02
    FIT 검증 설정별 결과 비교

    동일한 테스트 이미지에 대해 빌드된 FIT 관련 설정과 서명/해시 로그를 확인한다. config·image 검사가 생략되는 빌드라면 그 사실을 결과에 적는다.

  3. 03
    격리된 매체 이미지로 실패 경로 점검

    시험용 장치에서 short read 또는 잘못된 header를 재현하고, 다음 loader/장치 시도 또는 전체 실패 hang()까지 추적한다.

고정 소스와 공식 문서