새 보드 U-Boot 포팅 실전 — defconfig 작성부터 첫 부팅까지

새 보드를 받아 U-Boot부터 띄울 때, 백지에서 시작하면 며칠을 그냥 잡아먹습니다. 다행히 거의 항상 비슷한 보드가 이미 mainline U-Boot에 들어 있습니다. 그 보드를 복사해 차이만 고치는 게 정석입니다.

#한 줄 요약

같은 SoC·비슷한 주변 회로의 reference 보드를 템플릿으로 복사한 다음, defconfig·DT·보드 코드·환경 변수 다섯 군데를 차례로 바꾸면 대부분 첫 시리얼 출력까지 도달합니다.

#시작 — 비슷한 보드 찾기

U-Boot 소스에서 configs/를 훑어봅니다.

1
ls configs | grep -i imx8m
2
imx8mm_evk_defconfig
3
imx8mn_evk_defconfig
4
imx8mp_evk_defconfig
5
imx8mq_evk_defconfig
6
imx8mq_phanbell_defconfig
7
verdin-imx8mm_defconfig
8
verdin-imx8mp_defconfig

SoC가 같고 DDR 종류와 PMIC가 비슷한 것이 후보입니다. imx8mm_evk처럼 NXP reference는 가장 많이 검증되어 있으니 후보 1번으로 둡니다.

1
# 후보 보드의 파일 리스트
2
grep -l "imx8mm_evk" configs/ \
3
    board/freescale/imx8mm_evk/* \
4
    arch/arm/dts/imx8mm-evk*.dts*

#바꿀 파일 여섯 군데

새 보드 boardx를 추가한다고 하면, 손대는 곳은 보통 이렇습니다.

1. configs/boardx_defconfig

2. board/myvendor/boardx/

• ├── Kconfig
• ├── Makefile
• ├── boardx.c (보드 초기화, DRAM 크기 검출)
• ├── spl.c (SPL 단계 DDR 초기화)
• ├── lpddr4_timing.c (DDR 타이밍, NXP 도구로 생성)
• └── MAINTAINERS

3. arch/arm/dts/boardx.dts

• arch/arm/dts/boardx-u-boot.dtsi

4. include/configs/boardx.h

5. board/myvendor/Kconfig (subsystem 등록)

6. arch/arm/mach-imx/imx8m/Kconfig (보드 선택 옵션 추가)

-u-boot.dtsi는 U-Boot 단계 전용 DT 추가분입니다. 본 DT는 Linux와 공유하고, U-Boot 만의 필요(예: SPL 단계 사용 device, bootph-pre-ram 같은 노드 속성)는 .dtsi로 끼워 넣습니다.

#defconfig 복사

1
cp configs/imx8mm_evk_defconfig configs/boardx_defconfig

열어서 보드 식별 부분을 바꿉니다.

1
CONFIG_ARM=y
2
CONFIG_ARCH_IMX8M=y
3
CONFIG_SYS_TEXT_BASE=0x40200000
4
CONFIG_TARGET_BOARDX=y
5
CONFIG_SYS_LOAD_ADDR=0x40400000
6
CONFIG_SYS_CONFIG_NAME="boardx"
7
CONFIG_DEFAULT_DEVICE_TREE="boardx"
8
CONFIG_SPL_LDSCRIPT="arch/arm/cpu/armv8/u-boot-spl.lds"
9
CONFIG_SPL=y
10
CONFIG_SPL_FIT=y
11
CONFIG_BOOTCOMMAND="run distro_bootcmd"
12
CONFIG_BOOTSTD_FULL=y
13
CONFIG_DEFAULT_FDT_FILE="boardx.dtb"

CONFIG_TARGET_BOARDX=y는 우리가 아직 만들지 않은 옵션입니다. 그래서 arch/arm/mach-imx/imx8m/Kconfig에 등록해 둬야 합니다.

1
# arch/arm/mach-imx/imx8m/Kconfig 에 추가
2
config TARGET_BOARDX
3
    bool "boardx"
4
    select BINMAN
5
    select IMX8MM
6
    select SUPPORT_SPL
7
    select OF_BOARD_FIXUP
8
    help
9
      boardx is a custom imx8mm-based industrial board.

#board/myvendor/boardx/Kconfig·Makefile

board/myvendor/Kconfig에 등록:

1
if TARGET_BOARDX
2
config SYS_BOARD
3
    default "boardx"
4

5
config SYS_VENDOR
6
    default "myvendor"
7

8
config SYS_CONFIG_NAME
9
    default "boardx"
10

11
source "board/myvendor/boardx/Kconfig"
12
endif

board/myvendor/boardx/Kconfig:

1
config SYS_BOARD_PINMUX
2
    default "boardx_pinmux"
3

4
config IMX_CONFIG
5
    default "board/myvendor/boardx/imximage.cfg"

board/myvendor/boardx/Makefile:

1
obj-y += boardx.o
2
ifdef CONFIG_SPL_BUILD
3
obj-y += spl.o lpddr4_timing.o
4
endif

SPL_BUILD 시점에는 SPL용 파일만, U-Boot proper 시점에는 보드 본체 코드만 빌드됩니다. 두 단계가 한 트리에서 분리 컴파일된다는 점이 처음엔 헷갈리지만 익숙해지면 자연스럽습니다.

#boardx.c — 최소 보드 초기화

1
#include <common.h>
2
#include <init.h>
3
#include <asm/arch/sys_proto.h>
4
#include <asm/io.h>
5

6
int board_init(void)
7
{
8
    /* DRAM, console 이후 한 번만 호출 */
9
    return 0;
10
}
11

12
int dram_init(void)
13
{
14
    /* DRAM 크기를 SoC 레지스터에서 읽음 */
15
    gd->ram_size = imx_ddr_size();
16
    return 0;
17
}
18

19
int board_phys_sdram_size(phys_size_t *size)
20
{
21
    *size = imx_ddr_size();
22
    return 0;
23
}
24

25
int board_late_init(void)
26
{
27
    /* env로 보드 식별, MAC 주소 등 */
28
    env_set("board_name", "boardx");
29
    env_set("board_rev", "A1");
30
    return 0;
31
}

처음 한 사이클에는 이 정도면 충분합니다. 나중에 PHY reset·LED·watchdog feed 등을 더해 갑니다.

#spl.c — SPL 단계 DDR

가장 위험한 부분입니다. DDR 타이밍이 틀리면 SPL이 메모리 첫 접근에서 hang합니다.

1
#include <common.h>
2
#include <hang.h>
3
#include <init.h>
4
#include <spl.h>
5
#include <asm/arch/clock.h>
6
#include <asm/arch/ddr.h>
7

8
extern struct dram_timing_info dram_timing;
9

10
void spl_dram_init(void)
11
{
12
    ddr_init(&dram_timing);
13
}
14

15
void board_init_f(ulong dummy)
16
{
17
    int ret;
18

19
    arch_cpu_init();
20
    init_uart_clk(1);
21

22
    ret = spl_init();
23
    if (ret) {
24
        debug("spl_init failed: %d\n", ret);
25
        hang();
26
    }
27

28
    preloader_console_init();
29
    enable_tzc380();
30
    spl_dram_init();
31
    board_init_r(NULL, 0);
32
}

dram_timing은 NXP DDR Tool 또는 벤더가 제공한 calibration 결과를 그대로 가져옵니다. 직접 계산하지 않습니다. 잘못된 timing은 언젠가 메모리 corruption으로 드러나는데, 그 시점이 부팅 직후가 아니라 부팅한 지 한참 뒤 random crash로 나타나니 무서운 버그입니다.

#DT — boardx.dts

reference 보드의 DT를 복사해서 시작합니다.

1
/dts-v1/;
2

3
#include "imx8mm.dtsi"
4
#include "imx8mm-boardx.dtsi"
5

6
/ {
7
    model = "MyVendor BoardX";
8
    compatible = "myvendor,boardx", "fsl,imx8mm";
9

10
    chosen {
11
        stdout-path = &uart2;
12
    };
13

14
    memory@40000000 {
15
        device_type = "memory";
16
        reg = <0x0 0x40000000 0 0x40000000>;  /* 1 GB */
17
    };
18

19
    reg_usdhc2_vmmc: regulator-usdhc2-vmmc {
20
        compatible = "regulator-fixed";
21
        regulator-name = "VSD_3V3";
22
        regulator-min-microvolt = <3300000>;
23
        regulator-max-microvolt = <3300000>;
24
        gpio = <&gpio2 19 GPIO_ACTIVE_HIGH>;
25
        enable-active-high;
26
    };
27
};
28

29
&uart2 {
30
    pinctrl-names = "default";
31
    pinctrl-0 = <&pinctrl_uart2>;
32
    status = "okay";
33
};
34

35
&usdhc2 {
36
    pinctrl-names = "default";
37
    pinctrl-0 = <&pinctrl_usdhc2>;
38
    vmmc-supply = <&reg_usdhc2_vmmc>;
39
    cd-gpios = <&gpio2 12 GPIO_ACTIVE_LOW>;
40
    bus-width = <4>;
41
    status = "okay";
42
};

-u-boot.dtsi로 U-Boot 전용 속성을 추가합니다.

1
&{/soc@0} {
2
    bootph-all;
3
};
4

5
&osc_24m {
6
    bootph-all;
7
};
8

9
&uart2 {
10
    bootph-all;
11
};
12

13
&usdhc2 {
14
    bootph-pre-ram;
15
};

bootph-pre-ram이 SPL에서 쓰이는 노드, bootph-all이 모든 단계에서 쓰이는 노드를 표시합니다. 이걸 빠뜨리면 SPL이 해당 device를 못 봅니다.

#첫 빌드와 첫 부팅

다 채웠으면 빌드:

1
make boardx_defconfig
2
make -j$(nproc) ARCH=arm CROSS_COMPILE=aarch64-linux-gnu-

u-boot.bin·spl/u-boot-spl.bin·flash.bin(NXP의 묶인 이미지)이 나옵니다. flash.bin을 SD에 dd해 보드를 켭니다.

1
sudo dd if=flash.bin of=/dev/sdb bs=1k seek=33 conv=fsync

시리얼 콘솔(115200 8N1)을 띄우고 전원을 넣습니다. 아무것도 안 나오는 게 흔한 첫 결과입니다.

#첫 시리얼 출력까지의 단계

이 흐름이 사실상 표준 디버깅 순서입니다.

각 단계에서 어떤 출력이 나오는지 예시:

1
[2] U-Boot SPL 2026.04 (May 09 2026 - 16:01:23)
2
    DDRINFO: start DRAM init
3
    DDRINFO: DRAM rate 3000MTS
4
    DDRINFO: ddrphy calibration done
5
    DDRINFO: complete DRAM PHY training
6

7
[3] U-Boot 2026.04 (May 09 2026 - 16:01:23)
8
    CPU:   i.MX8MM rev1.0 1600 MHz (running at 1200 MHz)
9
    ...
10
    Net:   eth0: ethernet@30be0000
11
    Hit any key to stop autoboot:

각 단계에서 멈추면 그 구간의 코드가 의심 대상입니다. 1단계가 안 되면 DEBUG_UART 설정·UART pinmux·UART clock, 2단계가 안 되면 DDR timing, 3단계가 안 되면 cache/MMU/clock, 4단계가 안 되면 MMC/Net driver, 5단계가 안 되면 DTB·cmdline·kernel ABI입니다.

#MAINTAINERS와 commit 분리

mainline에 올릴 생각이면 board/myvendor/boardx/MAINTAINERS에 자신을 넣습니다.

1
BOARDX BOARD
2
M:  Hawk Yoon <hawking90a@gmail.com>
3
S:  Maintained
4
F:  arch/arm/dts/boardx.dts
5
F:  arch/arm/dts/boardx-u-boot.dtsi
6
F:  board/myvendor/boardx/
7
F:  configs/boardx_defconfig
8
F:  include/configs/boardx.h

commit은 기능별로 분리합니다. 통째로 한 patch보다 다음 흐름이 받아들여지기 좋습니다.

1. arm: dts: add boardx device tree
2. board: myvendor: add boardx board support
3. configs: add boardx_defconfig
4. doc: add boardx documentation

#자주 하는 실수

새 보드 포팅에서 자주 만나는 함정입니다.

• DDR timing을 reference 보드 그대로 둔다. 같은 SoC라도 PCB layout·DDR chip·전압이 다르면 언젠가 깨집니다. DDR Tool로 재calibration이 정석입니다.
• -u-boot.dtsi를 잊는다. bootph-pre-ram 속성이 없어 SPL에서 device가 안 보이는데, 에러는 *“MMC not found”*처럼 device 차원에서 나오기 때문에 원인 찾기 까다롭습니다.
• CONFIG_SYS_TEXT_BASE를 reference에서 안 바꾼다. DRAM 크기와 layout이 다르면 부팅 도중 자기 자신을 덮어쓰기 합니다.
• UART 핀mux는 켰는데 UART clock이 안 켜진 상태. 가장 흔한 “첫 출력이 안 나오는” 원인. init_uart_clk() 호출 빠짐.
• defconfig 옵션을 너무 많이 켠다. 첫 부팅까지는 최소 기능만 켜고, 부팅 후 하나씩 추가하는 편이 디버깅하기 좋습니다.
• DT 노드는 추가했는데 status="okay"를 빼먹어 device가 disable된 채로 부팅.
• eMMC·NOR boot mode 핀이 안 맞아서 SoC ROM이 SD가 아닌 다른 매체를 본다. SoC datasheet의 BOOT_MODE 핀 도해를 PCB와 한 번 더 대조해야 합니다.

#정리

• 새 보드는 비슷한 reference 보드 복사로 시작하는 것이 가장 빠르고 안전합니다.
• 손대는 곳은 configs/·board/<vendor>/<board>/·arch/arm/dts/·include/configs/ 네 곳이 핵심입니다.
• DDR timing은 직접 계산하지 않고 벤더 도구의 결과를 그대로 가져옵니다.
• -u-boot.dtsi로 SPL 단계의 device를 명시(bootph-pre-ram)해야 합니다.
• 첫 시리얼 출력 → SPL → DDR init → proper U-Boot → autoboot → Linux 다섯 단계의 어디서 멈췄는지가 디버깅 분기점입니다.
• CONFIG_DEBUG_UART는 SPL보다도 이른 시점의 출력을 켜는 마지막 보루입니다.
• mainline 제출을 위해서는 기능별 commit 분리와 MAINTAINERS 등록이 필요합니다.

#다음 장 예고

다음 장이 시리즈 마지막입니다. 새 보드를 포팅하면서 자주 만나는 부팅 안 됨 상황을 어떻게 진단하는지를 정리합니다. DEBUG_UART·JTAG·OpenOCD·post-mortem·실패 매트릭스까지 다루고, 그다음 시리즈로 어떻게 이어갈지도 안내합니다.

#관련 항목

• Ch 20: RAUC / SWUpdate — 펌웨어 업데이트 프레임워크
• Ch 22: 디버깅 — DEBUG, JTAG, serial, post-mortem
• BSP Development Ch 6: BSP 첫 단계 — 부트로더에서 첫 시리얼까지 — 같은 흐름을 BSP 시점에서
• 원문 — U-Boot doc/board/