Bootloader Internals · 3/37

U-Boot 빌드 시스템 분석 — Kconfig·Makefile·defconfig 동작 추적

2026년 5월 9일 · Hawk · 6분 읽기

embedded bootloader u-boot kconfig build

#한 줄 요약

“U-Boot은 Linux Kbuild를 그대로 가져다 씁니다.” — make <board>_defconfig로 옵션 한 묶음을 한 번에 적용하고, menuconfig로 세부 조정하고, make로 빌드합니다. 흐름은 커널과 똑같습니다.

U-Boot 소스 트리를 처음 열면 수만 개의 파일에 압도됩니다. arch/ 아래만 해도 수십 개의 아키텍처, drivers/ 아래는 수백 개의 driver, configs/ 아래는 천 개가 넘는 defconfig. 다행히 빌드 시스템은 단순합니다. Linux 커널과 같은 Kbuild입니다. 한 번 익히면 어떤 보드든 같은 흐름으로 빌드합니다.

#빌드의 세 단계

U-Boot 빌드는 세 단계입니다.

U-Boot 빌드 흐름 — defconfig → menuconfig → make와 주요 산출물

가장 자주 쓰는 흐름은 다음과 같습니다.

1
# 1. U-Boot 소스 받기
2
git clone https://source.denx.de/u-boot/u-boot.git
3
cd u-boot
4

5
# 2. cross-compiler 환경 변수
6
export ARCH=arm
7
export CROSS_COMPILE=aarch64-linux-gnu-
8

9
# 3. defconfig 적용
10
make qemu_arm64_defconfig
11

12
# 4. 빌드
13
make -j$(nproc)

빌드 결과는 소스 트리 루트에 생깁니다.

1
u-boot.bin           ← raw binary (TF-A의 BL33으로 사용)
2
u-boot              ← ELF binary (디버깅용)
3
u-boot.dtb           ← control DTB (CONFIG_OF_SEPARATE인 경우)
4
u-boot-dtb.bin       ← u-boot.bin + u-boot.dtb (concat)
5
u-boot-spl.bin       ← SPL (CONFIG_SPL=y인 경우)
6
u-boot-spl-dtb.bin   ← SPL + SPL용 DTB
7
spl/u-boot-spl       ← SPL ELF
8
u-boot.itb           ← FIT image (CONFIG_FIT=y인 경우)

#디렉터리 구조

U-Boot 소스 트리는 영역별로 디렉터리가 나뉩니다.

1
u-boot/
2
├── arch/                      ← 아키텍처별 코드
3
│   ├── arm/
4
│   │   ├── cpu/               ← cortex-a53, armv8 등
5
│   │   ├── mach-imx/          ← SoC 패밀리 코드
6
│   │   ├── mach-rockchip/
7
│   │   ├── dts/               ← Device Tree source
8
│   │   └── lib/               ← 아키텍처 헬퍼
9
│   ├── riscv/
10
│   └── x86/
11
│
12
├── board/                     ← 보드별 코드
13
│   ├── freescale/imx8mp_evk/
14
│   ├── ti/am335x/
15
│   ├── rockchip/evb_rk3399/
16
│   └── beagle/beagleboneblack/
17
│
18
├── configs/                   ← defconfig 모음
19
│   ├── qemu_arm64_defconfig
20
│   ├── am335x_evm_defconfig
21
│   ├── imx8mp_evk_defconfig
22
│   └── ...
23
│
24
├── include/                   ← 헤더
25
│   ├── configs/               ← 보드별 헤더 (CONFIG_*)
26
│   ├── dt-bindings/
27
│   └── ...
28
│
29
├── common/                    ← 공통 코드
30
│   ├── board_f.c              ← board_init_f
31
│   ├── board_r.c              ← board_init_r
32
│   ├── main.c                 ← 명령 인터프리터
33
│   ├── cli.c
34
│   └── spl/
35
│       └── spl.c              ← SPL 메인
36
│
37
├── drivers/                   ← 드라이버 (DM 기반)
38
│   ├── mmc/
39
│   ├── net/
40
│   ├── serial/
41
│   ├── usb/
42
│   └── ...
43
│
44
├── fs/                        ← 파일 시스템
45
│   ├── ext4/
46
│   ├── fat/
47
│   └── ubifs/
48
│
49
├── lib/                       ← 라이브러리
50
│   ├── libfdt/                ← DT 처리
51
│   ├── crypto/
52
│   └── ...
53
│
54
├── cmd/                       ← 명령 구현
55
│   ├── mmc.c
56
│   ├── tftp.c
57
│   ├── boot.c
58
│   └── ...
59
│
60
├── tools/                     ← 호스트 도구
61
│   ├── mkimage.c
62
│   └── ...
63
│
64
├── Kconfig                    ← 최상위 Kconfig
65
├── Makefile
66
├── scripts/
67
│   ├── Kbuild.include
68
│   └── ...
69
└── doc/

이 중 보드 포팅에 가장 자주 손대는 곳은 board/, configs/, arch/<arch>/dts/, include/configs/입니다. BSP Ch 6에서 다룬 적이 있습니다.

#Kconfig — 옵션 정의

Kconfig 파일이 모든 옵션을 정의합니다. 옵션은 bool, tristate, string, int, hex가 가능하고, 의존 관계를 표현할 수 있습니다.

1
# drivers/mmc/Kconfig (발췌)
2

3
menu "MMC Host controller Support"
4

5
config MMC
6
    bool "MMC/SD/SDIO card support"
7
    default ARM || PPC || SANDBOX
8
    help
9
      MMC/SD card support.
10

11
config DM_MMC
12
    bool "Enable MMC controllers using Driver Model"
13
    depends on MMC && DM
14
    help
15
      Use Driver Model for MMC.
16

17
config FSL_USDHC
18
    bool "Freescale/NXP i.MX uSDHC controller"
19
    depends on DM_MMC && BLK
20
    select MMC_SDHCI
21
    help
22
      Driver for i.MX MMC controller.
23

24
endmenu

depends on은 활성화 조건, select는 자동 활성화. CONFIG_FSL_USDHC=y를 켜면 MMC_SDHCI가 자동으로 켜집니다.

#menuconfig

make menuconfig는 대화식 TUI로 .config를 편집합니다.

U-Boot Configuration 최상위 메뉴:

General setup --->
ARM architecture --->
Boot media --->
Boot images --->
Boot timing --->
Boot count support --->
Console --->
Device Tree Control --->
Environment --->
Network --->
Library routines --->

옵션을 검색하려면 /를 누르고 검색어를 입력합니다.

1
Search Results
2
──────────────
3
Symbol: SPL [=y]
4
Type  : bool
5
Prompt: Enable SPL
6
  Location:
7
    -> Boot images
8
  Defined at common/spl/Kconfig:33
9
  Selected by:
10
    - ARCH_OMAP2PLUS && ...
11
  Selects:
12
    SUPPORT_OF_CONTROL && ...

옵션 하나를 찾는 가장 빠른 방법입니다.

#defconfig — 옵션 묶음

configs/<board>_defconfig는 해당 보드에서 활성화된 옵션만 모은 압축 .config입니다.

1
# configs/qemu_arm64_defconfig (발췌)
2
CONFIG_ARM=y
3
CONFIG_ARCH_QEMU=y
4
CONFIG_SYS_TEXT_BASE=0x00000000
5
CONFIG_NR_DRAM_BANKS=1
6
CONFIG_DEFAULT_DEVICE_TREE="qemu-arm64"
7
CONFIG_OF_BOARD=y
8
CONFIG_DISTRO_DEFAULTS=y
9
CONFIG_FIT=y
10
CONFIG_FIT_SIGNATURE=y
11
CONFIG_BOOTDELAY=0
12
CONFIG_SYS_PROMPT="=> "
13
CONFIG_CMD_BOOTEFI_HELLO=y
14
CONFIG_CMD_BOOTEFI_SELFTEST=y
15
CONFIG_CMD_PCI=y
16
CONFIG_CMD_DHCP=y
17
CONFIG_CMD_TFTPBOOT=y
18
CONFIG_CMD_EXT2=y
19
CONFIG_CMD_EXT4=y
20
CONFIG_CMD_FAT=y
21
CONFIG_OF_CONTROL=y
22
CONFIG_NET=y
23
CONFIG_DM=y
24
CONFIG_DM_USB=y
25
CONFIG_USB=y
26
CONFIG_USB_XHCI_HCD=y
27
CONFIG_USB_XHCI_PCI=y
28
CONFIG_VIRTIO_PCI=y
29
CONFIG_VIRTIO_NET=y
30
CONFIG_VIRTIO_BLK=y
31
CONFIG_EFI_LOADER=y

make <board>_defconfig는 이 파일을 .config로 풀어, Kconfig의 default 값을 채워, 전체 .config를 만듭니다.

#새 defconfig 만들기

menuconfig로 옵션을 수정한 뒤 defconfig를 저장하려면 make savedefconfig를 씁니다.

1
# 1. 적용
2
make qemu_arm64_defconfig
3

4
# 2. 수정
5
make menuconfig
6
# (옵션 추가/삭제)
7

8
# 3. 새 defconfig 저장
9
make savedefconfig
10

11
# 4. configs/ 안으로
12
cp defconfig configs/my_board_defconfig

savedefconfig는 기본값과 다른 옵션만 저장합니다. 그래서 defconfig 파일이 짧고 가독성 있게 유지됩니다.

#Makefile — Kbuild

U-Boot의 Makefile은 Linux Kbuild를 거의 그대로 씁니다. 모듈 단위 Makefile은 obj-y로 해당 디렉터리에서 빌드할 파일을 명시합니다.

1
# drivers/mmc/Makefile (발췌)
2
obj-$(CONFIG_$(SPL_TPL_)MMC)      += mmc.o mmc-uclass.o
3
obj-$(CONFIG_DM_MMC)              += mmc-uclass.o
4
obj-$(CONFIG_FSL_USDHC)           += fsl_esdhc_imx.o
5
obj-$(CONFIG_MMC_SDHCI)           += sdhci.o
6
obj-$(CONFIG_MMC_BCM2835)         += bcm2835_sdhost.o

obj-$(CONFIG_FSL_USDHC) += fsl_esdhc_imx.o는 CONFIG_FSL_USDHC=y일 때만 fsl_esdhc_imx.o를 빌드 대상에 추가합니다.

#SPL vs U-Boot Proper 빌드

$(SPL_TPL_) 접두사가 어느 단계에서 활성화할지를 분리합니다.

1
obj-$(CONFIG_$(SPL_TPL_)MMC) += mmc.o

빌드되는 경우:

U-Boot Proper 빌드 시: CONFIG_MMC=y이면 컴파일
SPL 빌드 시: CONFIG_SPL_MMC=y이면 컴파일
TPL 빌드 시: CONFIG_TPL_MMC=y이면 컴파일

같은 소스를 다른 .config로 세 번 컴파일하는 구조입니다. SPL은 공간이 작으므로 CONFIG_SPL_MMC=y지만 CONFIG_SPL_MMC_WRITE는 꺼서 코드를 줄이는 식입니다.

#out-of-tree 빌드

소스 트리를 건드리지 않고 빌드 산출물을 별도 디렉터리에 두려면 O=를 씁니다.

1
# 소스는 ~/u-boot, 빌드는 ~/build/u-boot
2
mkdir -p ~/build/u-boot
3
make -C ~/u-boot O=~/build/u-boot qemu_arm64_defconfig
4
make -C ~/u-boot O=~/build/u-boot -j$(nproc)

여러 보드를 동시에 개발할 때 유용합니다. 같은 소스로 여러 빌드 디렉터리를 만들 수 있습니다.

1
~/build/qemu_arm64/
2
~/build/beagle/
3
~/build/imx8mp_evk/

#cross-compile 환경

ARM 보드를 빌드하려면 aarch64 cross-compiler가 필요합니다. Ubuntu/Debian:

1
sudo apt install gcc-aarch64-linux-gnu

환경 변수:

1
export ARCH=arm
2
export CROSS_COMPILE=aarch64-linux-gnu-

ARCH=arm은 ARMv7과 ARMv8 공통으로 씁니다. CROSS_COMPILE이 aarch64- 또는 *arm-*인지로 32/64 비트를 구분합니다.

타깃	ARCH	CROSS_COMPILE
ARMv7-A 32bit	arm	arm-linux-gnueabihf-
ARMv8-A 64bit	arm	aarch64-linux-gnu-
RISC-V 64bit	riscv	riscv64-linux-gnu-
MIPS	mips	mips-linux-gnu-

CROSS_COMPILE의 끝 dash가 중요합니다. aarch64-linux-gnu-gcc가 컴파일러 이름인데, Makefile은 $(CROSS_COMPILE)gcc로 조립합니다.

#빌드 출력 읽기

make의 출력을 읽을 줄 알아야 어디서 실패했는지 압니다.

1
$ make -j8
2
  HOSTCC  scripts/basic/fixdep
3
  HOSTCC  scripts/kconfig/conf.o
4
  ...
5
  GEN     include/autoconf.mk
6
  CHK     include/config/uboot.release
7
  CHK     include/generated/version_autogenerated.h
8
  ...
9
  CC      arch/arm/cpu/armv8/cache.o
10
  CC      arch/arm/cpu/armv8/cpu.o
11
  ...
12
  CC      common/board_f.o
13
  CC      common/board_r.o
14
  ...
15
  LD      u-boot
16
  OBJCOPY u-boot-nodtb.bin
17
  CAT     u-boot-dtb.bin
18
  COPY    u-boot.bin
19
  SYM     u-boot.sym

HOSTCC는 host 컴파일러(scripts/, tools/), CC는 cross 컴파일러. LD는 링크, OBJCOPY는 binary 변환.

빌드 실패 시 줄의 맨 앞 단어가 어느 도구가 실패했는지 알려 줍니다.

1
arch/arm/mach-imx/spl.c:42:5: error: 'CONFIG_FOO' undeclared

이런 메시지는 Kconfig에서 옵션 누락입니다. defconfig를 점검합니다.

#binary 크기 확인

산출물 크기를 보려면:

1
$ ls -l u-boot*.bin
2
-rw-r--r-- 1 user user  812032 May 19 09:00 u-boot.bin
3
-rw-r--r-- 1 user user   84368 May 19 09:00 u-boot-spl.bin

SPL은 수십 KB 안에 들어가야 합니다. SoC 내부 SRAM 크기를 넘으면 빌드는 통과해도 부팅이 안 됩니다.

make u-boot.map을 열면 심볼별 크기를 봅니다.

1
.text          0x40200000   0x6a2c8
2
 ...
3
 mmc.o          .text       0x402030c0   0x2c84
4
 net.o          .text       0x40205d44   0x4a18
5
 ...

크기를 줄이려면 불필요한 driver를 끄거나 CONFIG_LTO=y(link-time optimization)를 활성화합니다.

#자주 하는 실수

#`make clean` 안 하고 defconfig 변경

.config가 덮어쓰기는 되지만 .o 파일이 stale 상태가 됩니다. Kconfig 옵션이 바뀐 파일은 재컴파일되는데, 간접 의존이 빠질 수 있습니다. 큰 변경 후에는:

1
make distclean
2
make <board>_defconfig
3
make

#`ARCH` 환경 변수 누락

make qemu_arm64_defconfig 시 ARCH가 호스트로 잡혀 빌드 산출물이 x86이 되는 경우. 항상 환경 변수를 셸 프로필이나 export로 고정합니다.

#`CROSS_COMPILE`을 상대 경로로

1
# Bad
2
export CROSS_COMPILE=./toolchain/bin/aarch64-linux-gnu-
3

4
# Good (절대 경로 또는 PATH)
5
export PATH=$HOME/toolchain/bin:$PATH
6
export CROSS_COMPILE=aarch64-linux-gnu-

빌드 중 sub-make에서 cwd가 바뀌면 상대 경로가 깨집니다.

#`savedefconfig`로 만든 파일 그대로 커밋

savedefconfig가 정확히 정렬해 주지만, 알파벳 순이 아닌 Kconfig 트리 순입니다. 가독성을 위해 그룹별 빈 줄을 수동으로 넣지 마세요. 다음 savedefconfig에서 사라집니다.

#`obj-y` 대신 `obj-$(CONFIG_X)`를 빼먹음

새 driver 파일을 추가할 때 Makefile에 obj-y += my_driver.o라고 쓰면 모든 빌드에 무조건 포함됩니다. 보통은 obj-$(CONFIG_MY_DRIVER) += my_driver.o로 Kconfig와 연결합니다.

#`menuconfig`가 `ncurses-dev` 없이 안 됨

1
*** Unable to find the ncurses libraries.
2
*** make[1]: *** [scripts/kconfig/Makefile:14: menuconfig] Error 1

Ubuntu/Debian: sudo apt install libncurses-dev. macOS: brew install ncurses.

#정리

U-Boot은 Linux Kbuild를 그대로 사용합니다. make <board>_defconfig → make menuconfig → make.
디렉터리는 영역별입니다. arch/, board/, configs/, include/configs/, common/, drivers/, cmd/.
Kconfig가 옵션을 정의하고, defconfig가 옵션 묶음을 저장합니다.
같은 소스를 SPL용 .config, U-Boot Proper용 .config로 두 번 빌드해 두 binary를 만듭니다.
make savedefconfig로 menuconfig 변경을 defconfig 형태로 저장합니다.
out-of-tree 빌드는 O=<dir>로 합니다. 여러 보드 개발에 편리합니다.
cross-compile은 ARCH=arm CROSS_COMPILE=aarch64-linux-gnu- 환경 변수로 정합니다.
SPL binary 크기는 SoC 내부 SRAM 크기 안에 들어가야 합니다. u-boot.map으로 점검합니다.

#다음 편

Ch 4: 부트 단계 — BL1 → SPL → TPL → U-Boot Proper에서는 ARMv8-A의 BL1·BL2·BL31·BL33과 U-Boot의 SPL·TPL·U-Boot Proper의 책임을 정리합니다. 각 단계의 메모리 모델과 권한 수준도 함께 봅니다.

U-Boot 빌드 시스템 분석 — Kconfig·Makefile·defconfig 동작 추적

#한 줄 요약

#빌드의 세 단계

#디렉터리 구조

#Kconfig — 옵션 정의

#menuconfig

#defconfig — 옵션 묶음

#새 defconfig 만들기

#Makefile — Kbuild

#SPL vs U-Boot Proper 빌드

#out-of-tree 빌드

#cross-compile 환경

#빌드 출력 읽기

#binary 크기 확인

#자주 하는 실수

#`make clean` 안 하고 defconfig 변경

#`ARCH` 환경 변수 누락

#`CROSS_COMPILE`을 상대 경로로

#`savedefconfig`로 만든 파일 그대로 커밋

#`obj-y` 대신 `obj-$(CONFIG_X)`를 빼먹음

#`menuconfig`가 `ncurses-dev` 없이 안 됨

#정리

#다음 편

#관련 항목

Bootloader Internals · 3 of 37

관련 글

U-Boot PCIe Enumeration — 부트로더가 디바이스를 찾는 흐름 분석

U-Boot Distro Boot — extlinux·boot.scr 표준화 분석

SPL·TPL 내부 해부 — 가장 작은 부트 단계의 동작 추적

이 글을 참조하는 글 (4)

#한 줄 요약

#빌드의 세 단계

#디렉터리 구조

#Kconfig — 옵션 정의

#menuconfig

#defconfig — 옵션 묶음

#새 defconfig 만들기

#Makefile — Kbuild

#SPL vs U-Boot Proper 빌드

#out-of-tree 빌드

#cross-compile 환경

#빌드 출력 읽기

#binary 크기 확인

#자주 하는 실수

#make clean 안 하고 defconfig 변경

#ARCH 환경 변수 누락

#CROSS_COMPILE을 상대 경로로

#savedefconfig로 만든 파일 그대로 커밋

#obj-y 대신 obj-$(CONFIG_X)를 빼먹음

#menuconfig가 ncurses-dev 없이 안 됨

#정리

#다음 편

#관련 항목

Bootloader Internals · 3 of 37

관련 글

U-Boot PCIe Enumeration — 부트로더가 디바이스를 찾는 흐름 분석

U-Boot Distro Boot — extlinux·boot.scr 표준화 분석

SPL·TPL 내부 해부 — 가장 작은 부트 단계의 동작 추적

이 글을 참조하는 글 (4)

#`make clean` 안 하고 defconfig 변경

#`ARCH` 환경 변수 누락

#`CROSS_COMPILE`을 상대 경로로

#`savedefconfig`로 만든 파일 그대로 커밋

#`obj-y` 대신 `obj-$(CONFIG_X)`를 빼먹음

#`menuconfig`가 `ncurses-dev` 없이 안 됨