Bootloader Internals · 7/37

U-Boot Driver Model 내부 — uclass·driver·device 추상화 구조

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

#한 줄 요약

**“Driver Model은 uclass(인터페이스)·driver(구현)·udevice(인스턴스)의 삼각 구조입니다.” — DT의 compatible 프로퍼티가 driver와 device를 자동 매칭합니다. 보드 코드는 DT만 잘 쓰면 대부분의 init이 끝납니다.

2014년 이전의 U-Boot은 각 driver가 고유 API를 가졌습니다. MMC는 mmc_*, GPIO는 gpio_*, I2C는 i2c_*. 공통점이 없었고 모든 driver init이 보드 코드의 work였습니다. Linux의 device model을 본떠 *Driver Model(DM)*이 도입되었고, 지금은 거의 모든 driver가 DM 위에서 동작합니다.

#왜 Driver Model인가

legacy 시절의 U-Boot 보드 코드는 모든 device를 명시적으로 init했습니다.

1
/* legacy 방식 (구식) */
2

3
int board_mmc_init(struct bd_info *bis)
4
{
5
    /* MMC controller 1번 init */
6
    init_clk_usdhc(0);
7
    fsl_esdhc_initialize(bis, &usdhc_cfg[0]);
8

9
    /* MMC controller 2번 init */
10
    init_clk_usdhc(1);
11
    fsl_esdhc_initialize(bis, &usdhc_cfg[1]);
12

13
    return 0;
14
}
15

16
int board_eth_init(struct bd_info *bis)
17
{
18
    /* ENET init */
19
    setup_fec();
20
    return cpu_eth_init(bis);
21
}
22

23
int board_i2c_init(void)
24
{
25
    /* I2C 1번 init */
26
    i2c_init(I2C_SPEED, 0);
27
    /* I2C 2번 init */
28
    i2c_init(I2C_SPEED, 0);
29
    return 0;
30
}

보드 추가 시 모든 init 코드를 수동으로 짜야 했습니다. 같은 SoC라도 어떤 페리페럴을 쓰는지에 따라 코드가 다 달랐습니다.

DM 도입 후에는 DT에 device를 정의하기만 하면 됩니다.

1
/* DT */
2
&usdhc1 {
3
    pinctrl-names = "default";
4
    pinctrl-0 = <&pinctrl_usdhc1>;
5
    bus-width = <8>;
6
    status = "okay";
7
};

U-Boot이 부트 시점에 DT를 스캔해서 해당 driver를 찾아 probe합니다. 보드 코드는 touch 안 합니다.

#삼각 구조 — uclass / driver / udevice

U-Boot DM 삼각 구조 — uclass 인터페이스, driver 구현, udevice 인스턴스

#uclass

uclass는 기능 카테고리입니다. “MMC controller”라는 추상 인터페이스가 UCLASS_MMC입니다. uclass는 operation 시그니처를 정의합니다.

1
enum uclass_id {
2
    UCLASS_INVALID = 0,
3
    UCLASS_ROOT,
4
    UCLASS_CLK,
5
    UCLASS_CPU,
6
    UCLASS_GPIO,
7
    UCLASS_I2C,
8
    UCLASS_MMC,
9
    UCLASS_PINCTRL,
10
    UCLASS_PMIC,
11
    UCLASS_REGULATOR,
12
    UCLASS_SERIAL,
13
    UCLASS_ETH,
14
    UCLASS_USB,
15
    UCLASS_BLK,
16
    UCLASS_RTC,
17
    UCLASS_SPI,
18
    ...
19
};

각 uclass는 operation struct를 가집니다. MMC의 경우:

1
struct dm_mmc_ops {
2
    int (*send_cmd)(struct udevice *dev, struct mmc_cmd *cmd,
3
                    struct mmc_data *data);
4
    int (*set_ios)(struct udevice *dev);
5
    int (*get_cd)(struct udevice *dev);
6
    int (*get_wp)(struct udevice *dev);
7
    ...
8
};

driver들이 이 시그니처를 구현합니다.

#driver

driver는 특정 hardware의 구체 코드입니다. U_BOOT_DRIVER 매크로로 정의합니다.

1
/* drivers/mmc/fsl_esdhc_imx.c (간략화) */
2

3
static int fsl_esdhc_probe(struct udevice *dev)
4
{
5
    /* clock enable, pinmux 설정, etc */
6
    return 0;
7
}
8

9
static const struct dm_mmc_ops fsl_esdhc_ops = {
10
    .send_cmd = fsl_esdhc_send_cmd,
11
    .set_ios = fsl_esdhc_set_ios,
12
    .get_cd = fsl_esdhc_get_cd,
13
};
14

15
static const struct udevice_id fsl_esdhc_ids[] = {
16
    { .compatible = "fsl,imx8mp-usdhc" },
17
    { .compatible = "fsl,imx8mm-usdhc" },
18
    { .compatible = "fsl,imx7d-usdhc" },
19
    { /* sentinel */ }
20
};
21

22
U_BOOT_DRIVER(fsl_esdhc) = {
23
    .name           = "fsl-esdhc-mmc",
24
    .id             = UCLASS_MMC,
25
    .of_match       = fsl_esdhc_ids,
26
    .ops            = &fsl_esdhc_ops,
27
    .probe          = fsl_esdhc_probe,
28
    .priv_auto      = sizeof(struct fsl_esdhc_priv),
29
    .platdata_auto  = sizeof(struct fsl_esdhc_plat),
30
    .flags          = DM_FLAG_PRE_RELOC,
31
};

.id = UCLASS_MMC이 어느 uclass에 속하는지 표시합니다. .of_match = fsl_esdhc_ids가 DT의 compatible과 매칭할 문자열 배열입니다.

#udevice

udevice는 driver의 인스턴스입니다. DT에서 해당 driver의 compatible과 매치되는 노드 하나가 udevice 하나가 됩니다.

1
/* DT */
2
soc {
3
    usdhc1: mmc@30b40000 {
4
        compatible = "fsl,imx8mp-usdhc";
5
        reg = <0x30b40000 0x10000>;
6
        ...
7
    };
8

9
    usdhc2: mmc@30b50000 {
10
        compatible = "fsl,imx8mp-usdhc";
11
        reg = <0x30b50000 0x10000>;
12
        ...
13
    };
14
};

이 DT에서 udevice 두 개가 생깁니다.

1
udevice 1: name="mmc@30b40000", driver=fsl-esdhc-mmc, uclass=UCLASS_MMC
2
udevice 2: name="mmc@30b50000", driver=fsl-esdhc-mmc, uclass=UCLASS_MMC

같은 driver가 두 인스턴스를 가지는 것입니다.

#binding — DT가 driver를 찾는 법

U-Boot이 DT를 어떻게 driver로 변환하는지가 binding입니다.

U-Boot이 DT를 scan.
각 노드의 compatible 프로퍼티 확인.
모든 driver의 of_match 배열을 검색.
매치되면 udevice 생성 + driver와 binding.
부모 노드 우선 (root → soc → mmc@xxx 순).

1
int lists_bind_fdt(struct udevice *parent, ofnode node, ...)
2
{
3
    struct driver *entry;
4
    int ret;
5

6
    for (entry = driver_list_start;
7
         entry != driver_list_end;
8
         entry++) {
9
        if (!entry->of_match)
10
            continue;
11

12
        for (id = entry->of_match; id->compatible; id++) {
13
            if (ofnode_device_is_compatible(node, id->compatible)) {
14
                /* 매치! udevice 생성 */
15
                ret = device_bind(parent, entry, ...);
16
                if (ret == 0)
17
                    return 0;
18
            }
19
        }
20
    }
21
    return -ENODEV;
22
}

매치되는 driver를 찾지 못한 노드는 device가 생성되지 않습니다. 동작도 안 합니다. 이것이 가장 흔한 디버깅 포인트입니다.

#bind vs probe

DM은 bind와 probe를 분리합니다.

bind

device 인스턴스 생성
parent-child 관계 설정
driver_data 포인터만 연결
빠름, 메모리만 차지

probe

실제 hardware 초기화
clock enable, pinmux, 레지스터 설정
첫 사용 시점까지 lazy

probe는 해당 device가 처음 사용될 때까지 연기됩니다. 부트 시간을 줄이기 위함입니다. MMC controller가 부트에 안 쓰이면 probe 안 됩니다.

1
int uclass_get_device(enum uclass_id id, int index, struct udevice **devp)
2
{
3
    struct udevice *dev = ...; /* lookup */
4

5
    if (dev->flags & DM_FLAG_ACTIVATED)
6
        return 0;  /* 이미 probe됨 */
7

8
    return device_probe(dev);  /* lazy probe */
9
}

mmc list 같은 명령이 호출되는 시점에 그제서야 MMC가 probe됩니다.

#DM_FLAG — driver 동작 제어

U_BOOT_DRIVER의 .flags 필드가 driver의 동작 방식을 조정합니다.

flag	의미
`DM_FLAG_PRE_RELOC`	relocation 전에도 사용 가능
`DM_FLAG_ACTIVATED`	probe 완료 상태
`DM_FLAG_NAME_ALLOCED`	name이 동적 할당됨
`DM_FLAG_REMOVE_WITH_PD_ON`	power domain 켜진 상태로 remove
`DM_FLAG_OS_PREPARE`	OS 인계 전 호출
`DM_FLAG_PROBE_AFTER_BIND`	bind 직후 즉시 probe
`DM_FLAG_DEFAULT_PD_CTRL_OFF`	power domain 자동 제어 끔

DM_FLAG_PRE_RELOC이 가장 중요합니다. 이 flag 없는 driver는 board_init_r 이후에만 동작합니다. UART, console driver는 반드시 PRE_RELOC.

1
U_BOOT_DRIVER(serial_imx) = {
2
    .name   = "serial_imx",
3
    .id     = UCLASS_SERIAL,
4
    .of_match = serial_imx_ids,
5
    .probe  = imx_serial_probe,
6
    .flags  = DM_FLAG_PRE_RELOC,  /* console은 pre-reloc */
7
};

#dm tree — 런타임 검증

U-Boot 명령 인터프리터에서 dm tree가 전체 device tree를 출력합니다.

1
=> dm tree
2
 Class     Index  Probed  Driver                Name
3
-----------------------------------------------------------
4
 root          0  [ + ]   root_driver           root_driver
5
 simple_bus    0  [ + ]   generic_simple_bus    |-- soc@0
6
 clk           0  [ + ]   imx8mp_clk            |   |-- clock-controller@30380000
7
 pinctrl       0  [ + ]   imx8mp_pinctrl        |   |-- iomuxc@30330000
8
 serial        0  [ + ]   serial_imx            |   |-- serial@30890000
9
 mmc           0  [   ]   fsl-esdhc-mmc         |   |-- mmc@30b40000
10
 mmc           1  [   ]   fsl-esdhc-mmc         |   |-- mmc@30b50000
11
 ethernet      0  [ + ]   eqos_imx              |   |-- ethernet@30bf0000
12
 i2c           0  [ + ]   imx-i2c               |   |-- i2c@30a20000
13
 pmic          0  [ + ]   pca9450               |   |   `-- pmic@25
14
 regulator     0  [ + ]   pca9450_regulator     |   |       `-- regulators
15
 cpu           0  [ + ]   imx8_cpu              |-- cpu@0
16
 cpu           1  [ + ]   imx8_cpu              |-- cpu@1
17
 cpu           2  [ + ]   imx8_cpu              |-- cpu@2
18
 cpu           3  [ + ]   imx8_cpu              |-- cpu@3

[ + ]이 probed, [ ]이 bind만 됨, probe 전. probed가 *모두 +*가 아닐 수도 있습니다. lazy probe이기 때문입니다.

probe 실패는 DT의 incomplete 또는 parent driver bug가 원인입니다. 가장 자주 보이는 패턴:

1
=> dm tree
2
 mmc      0  [   ]   fsl-esdhc-mmc         |   |-- mmc@30b40000
3
=> mmc list
4
Card did not respond to voltage select! : -110
5
=> dm tree
6
 mmc      0  [   ]   fsl-esdhc-mmc         |   |-- mmc@30b40000

probe가 시도되었지만 실패했고, 다음에 다시 probe됩니다. 원인 대부분은 clock 안 잡힘 또는 regulator 안 켜짐.

#dm uclass — uclass별 목록

1
=> dm uclass
2
uclass 0: root
3
0      * root_driver @ ff8e5b80, seq -1
4
uclass 14: clk
5
0        clock-controller@30380000 @ ff8e6b40, seq 0
6
...
7
uclass 47: mmc
8
0      * mmc@30b40000 @ ff8eac80, seq 0
9
1      * mmc@30b50000 @ ff8eba80, seq 1
10
uclass 52: serial
11
0      * serial@30890000 @ ff8e7c80, seq 0

특정 uclass의 모든 device를 한 번에 봅니다. driver 개발 시 빠른 진단 도구입니다.

#SPL에서의 DM

SPL도 DM을 전부 또는 부분적으로 쓸 수 있습니다. CONFIG_SPL_DM=y 옵션입니다.

1
CONFIG_SPL_DM=y
2
CONFIG_SPL_DM_MMC=y
3
CONFIG_SPL_DM_GPIO=y
4
CONFIG_SPL_DM_PMIC=y
5
CONFIG_SPL_OF_CONTROL=y
6
CONFIG_SPL_OF_PLATDATA=y    ← 옵션: DT 대신 platdata 사용 (크기 절약)

CONFIG_SPL_OF_PLATDATA는 SPL에서 DT 파싱을 건너뛰고 미리 생성된 C struct를 사용하는 옵션입니다. SPL 크기를 줄이는 고급 옵션입니다. 빌드 시 dtoc 도구가 DT를 C 코드로 변환합니다.

1
$ make spl/u-boot-spl
2
  DTOC C   spl/dts/dt-plat.c
3
  DTOC H   spl/dts/dt-structs-gen.h

생성된 dt-plat.c는 다음 같이 static 데이터로 device들을 정의합니다.

1
/* spl/dts/dt-plat.c (생성 코드) */
2

3
struct dtd_fsl_imx8mp_usdhc dtv_mmc_30b40000 = {
4
    .reg            = {0x30b40000, 0x10000},
5
    .bus_width      = 0x8,
6
    .pinctrl_0      = 0x40,
7
    ...
8
};
9

10
U_BOOT_DRVINFO(mmc_30b40000) = {
11
    .name   = "fsl_esdhc_imx",
12
    .plat   = &dtv_mmc_30b40000,
13
};

DT 파싱 코드가 빠지므로 SPL 크기가 수 KB 감소합니다.

#새 driver 한 개 — 최소 예시

가상의 가속도 센서 driver를 DM 위에서 짜는 예시입니다.

1
#include <common.h>
2
#include <dm.h>
3
#include <i2c.h>
4
#include <sensor.h>
5

6
struct acme_accel_priv {
7
    struct udevice *i2c_dev;
8
    u8 chip_addr;
9
};
10

11
static int acme_accel_read(struct udevice *dev, int *xyz)
12
{
13
    struct acme_accel_priv *priv = dev_get_priv(dev);
14
    u8 buf[6];
15
    int ret;
16

17
    ret = dm_i2c_read(priv->i2c_dev, 0x32, buf, 6);
18
    if (ret)
19
        return ret;
20

21
    xyz[0] = (buf[1] << 8) | buf[0];
22
    xyz[1] = (buf[3] << 8) | buf[2];
23
    xyz[2] = (buf[5] << 8) | buf[4];
24

25
    return 0;
26
}
27

28
static int acme_accel_probe(struct udevice *dev)
29
{
30
    struct acme_accel_priv *priv = dev_get_priv(dev);
31

32
    /* parent가 i2c bus */
33
    priv->i2c_dev = dev->parent;
34
    priv->chip_addr = dev_read_addr(dev);
35

36
    /* sensor reset */
37
    return dm_i2c_reg_write(priv->i2c_dev, 0x2D, 0x08);
38
}
39

40
static const struct sensor_ops acme_accel_ops = {
41
    .read = acme_accel_read,
42
};
43

44
static const struct udevice_id acme_accel_ids[] = {
45
    { .compatible = "acme,xl345" },
46
    { /* sentinel */ }
47
};
48

49
U_BOOT_DRIVER(acme_xl345) = {
50
    .name       = "acme-xl345",
51
    .id         = UCLASS_SENSOR,
52
    .of_match   = acme_accel_ids,
53
    .ops        = &acme_accel_ops,
54
    .probe      = acme_accel_probe,
55
    .priv_auto  = sizeof(struct acme_accel_priv),
56
};

DT:

1
&i2c1 {
2
    accelerometer@53 {
3
        compatible = "acme,xl345";
4
        reg = <0x53>;
5
    };
6
};

빌드 후 부트:

1
=> dm tree
2
 i2c          0  [ + ]   imx-i2c        |-- i2c@30a20000
3
 sensor       0  [   ]   acme-xl345     |   `-- accelerometer@53

자동으로 device가 생겼습니다. 보드 코드에 한 줄도 안 썼습니다.

#자주 하는 실수

#`of_match`의 sentinel 누락

1
static const struct udevice_id ids[] = {
2
    { .compatible = "vendor,my-driver" },
3
    /* sentinel 누락! */
4
};

배열의 끝을 표시하는 { /* sentinel */ }를 빼면 out-of-bounds로 메모리를 읽어 random match가 일어날 수 있습니다. 항상 끝에 빈 entry를 둡니다.

#`DM_FLAG_PRE_RELOC` 없이 board_init_f에서 사용

UART, console, GPIO는 pre-reloc 가능해야 합니다. 이 flag 없으면 board_init_f 단계에서 device가 안 보입니다.

1
.flags = DM_FLAG_PRE_RELOC,

console에 아무것도 안 나오는데 device 자체는 제대로 정의된 경우, PRE_RELOC 누락이 자주 범인입니다.

#`priv_auto` 크기 mismatch

priv_auto = sizeof(struct acme_accel_priv)가 실제 priv struct 크기와 다르면 메모리 corruption. typedef alias로 큰 struct를 정의했는데 크기를 작게 잡으면 probe 후 주변 메모리가 깨집니다.

#`dev->parent`를 잘못 가정

I2C device의 parent는 I2C bus이지만, SPI device의 parent는 SPI bus입니다. driver별로 parent 사용 패턴이 다릅니다. uclass 문서를 확인.

#`probe`가 DT 노드를 다시 읽음

dev_read_* 함수로 DT 노드의 프로퍼티를 probe 시점에 읽습니다. priv_auto에 캐시해 두지 않으면 매 호출마다 DT 파싱이 일어나 느려집니다.

#`dm tree`에서 device가 안 보임

1
=> dm tree
2
(my device not shown)

원인 후보:

DT의 compatible string 오타
driver의 of_match 배열에 누락
driver 자체가 빌드에 포함 안 됨 (Kconfig 누락)
부모 노드가 status = “disabled”

fdt print /soc/i2c@xxx/my-device로 DT를 확인하고, 빌드 산출물에 .o가 있는지 확인합니다.

#`select` 누락

defconfig에서 CONFIG_MY_DRIVER=y만 켜고 CONFIG_DM=y가 안 켜져 있는 경우. DM은 대부분의 Kconfig에서 default y이지만 명시적으로 확인합니다.

1
CONFIG_DM=y
2
CONFIG_DM_I2C=y
3
CONFIG_DM_SENSOR=y
4
CONFIG_MY_DRIVER=y

#정리

Driver Model은 *uclass(인터페이스) · driver(구현) · udevice(인스턴스)*의 삼각 구조입니다.
DT의 compatible 프로퍼티가 driver의 of_match와 매칭되어 udevice가 자동 생성됩니다.
bind(인스턴스 생성)와 probe(실제 init)가 분리되어 있고, probe는 lazy입니다.
DM_FLAG_PRE_RELOC이 relocation 이전에도 사용 가능한 driver임을 표시합니다. UART, console에 필수.
dm tree로 전체 device 트리와 probe 상태를 봅니다. [ + ]이 probed, [ ]이 bind만 됨.
dm uclass로 특정 uclass의 모든 device를 봅니다.
SPL은 CONFIG_SPL_DM=y로 DM 사용. 크기 절약을 위해 CONFIG_SPL_OF_PLATDATA로 DT 대신 C struct를 쓸 수 있습니다.
새 driver는 U_BOOT_DRIVER 매크로로 정의합니다. uclass id, of_match, probe, ops, priv_auto가 핵심 필드.

#다음 편

Ch 8: 보드 초기화 — board_init_f와 board_init_r에서는 U-Boot의 부트 흐름을 봅니다. relocation 전과 후의 환경 차이, init_sequence_f/init_sequence_r 배열, 보드가 hook할 수 있는 지점.

U-Boot Driver Model 내부 — uclass·driver·device 추상화 구조

#한 줄 요약

#왜 Driver Model인가

#삼각 구조 — uclass / driver / udevice

#uclass

#driver

#udevice

#binding — DT가 driver를 찾는 법

#bind vs probe

#DM_FLAG — driver 동작 제어

#dm tree — 런타임 검증

#dm uclass — uclass별 목록

#SPL에서의 DM

#새 driver 한 개 — 최소 예시

#자주 하는 실수

#`of_match`의 sentinel 누락

#`DM_FLAG_PRE_RELOC` 없이 board_init_f에서 사용

#`priv_auto` 크기 mismatch

#`dev->parent`를 잘못 가정

#`probe`가 DT 노드를 다시 읽음

#`dm tree`에서 device가 안 보임

#`select` 누락

#정리

#다음 편

#관련 항목

Bootloader Internals · 7 of 37

관련 글

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

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

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

이 글을 참조하는 글 (3)

#한 줄 요약

#왜 Driver Model인가

#삼각 구조 — uclass / driver / udevice

#uclass

#driver

#udevice

#binding — DT가 driver를 찾는 법

#bind vs probe

#DM_FLAG — driver 동작 제어

#dm tree — 런타임 검증

#dm uclass — uclass별 목록

#SPL에서의 DM

#새 driver 한 개 — 최소 예시

#자주 하는 실수

#of_match의 sentinel 누락

#DM_FLAG_PRE_RELOC 없이 board_init_f에서 사용

#priv_auto 크기 mismatch

#dev->parent를 잘못 가정

#probe가 DT 노드를 다시 읽음

#dm tree에서 device가 안 보임

#select 누락

#정리

#다음 편

#관련 항목

Bootloader Internals · 7 of 37

관련 글

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

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

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

이 글을 참조하는 글 (3)

#`of_match`의 sentinel 누락

#`DM_FLAG_PRE_RELOC` 없이 board_init_f에서 사용

#`priv_auto` 크기 mismatch

#`dev->parent`를 잘못 가정

#`probe`가 DT 노드를 다시 읽음

#`dm tree`에서 device가 안 보임

#`select` 누락