Regulator 프레임워크

Regulator 프레임워크를 SoC 전력 도메인 안정성과 보드 전원 시퀀스 관점에서 심층 분석합니다. regulator_desc/regulator_ops 기반 공급자 드라이버 작성, consumer API(regulator_get/enable/set_voltage) 사용 원칙, always-on/boot-on 제약과 전원 의존성 그래프, PMIC 레일 공유 충돌 해결, runtime PM 및 DVFS와의 연동, 과전류·저전압 이벤트 대응, Device Tree 전원 트리 모델링과 디버깅까지 안전한 전원 제어를 위한 실무 포인트를 다룹니다.

전원 트리에서 Regulator의 역할

Regulator는 시스템 전원 트리에서 "전압/전류 정책 계층"을 담당합니다. 소비자 드라이버는 필요한 전압 범위만 요청하고, 실제 PMIC 제어와 제약 검증은 프레임워크가 수행해 보드 의존성을 크게 줄입니다.

Regulator 서브시스템

Regulator 서브시스템(drivers/regulator/)은 시스템의 전압 및 전류 공급 장치(레귤레이터)를 추상화하여 관리하는 프레임워크입니다. PMIC(Power Management IC), DC-DC 컨버터, LDO(Low-Dropout Regulator), 스위치 레귤레이터 등 다양한 전원 공급 장치를 통합 관리하며, 디바이스 드라이버가 필요한 전압/전류를 요청하면 프레임워크가 하드웨어 제약 조건을 검증하고 적용합니다.

핵심 데이터 구조

Regulator 프레임워크의 핵심 구조체는 regulator_desc(레귤레이터 하드웨어 기술), regulator_ops(하드웨어 제어 콜백), regulator_config(등록 시 설정), regulation_constraints(전압/전류 제한)입니다.

/* include/linux/regulator/driver.h */

struct regulator_desc {
    const char             *name;           /* 레귤레이터 이름 (예: "BUCK1") */
    const char             *supply_name;    /* 입력 공급 이름 (예: "vin1") */
    int                    id;              /* 인스턴스 ID */
    enum regulator_type    type;            /* REGULATOR_VOLTAGE / CURRENT */
    const struct regulator_ops *ops;        /* HW 제어 콜백 */

    /* 전압 테이블 방식 (이산 전압 목록) */
    unsigned int           n_voltages;      /* 전압 단계 수 */
    const struct regulator_linear_range *linear_ranges;
    int                    n_linear_ranges;

    /* 선형 범위: min_uV + step × selector */
    unsigned int           min_uV;          /* 최소 전압 (µV) */
    unsigned int           uV_step;         /* 전압 단계 크기 (µV) */

    /* 레지스터 매핑 (regmap 기반 자동화) */
    unsigned int           vsel_reg;        /* 전압 선택 레지스터 */
    unsigned int           vsel_mask;       /* 전압 선택 비트마스크 */
    unsigned int           enable_reg;      /* 활성화 레지스터 */
    unsigned int           enable_mask;     /* 활성화 비트마스크 */
    unsigned int           enable_val;      /* 활성화 시 쓸 값 */
    unsigned int           disable_val;     /* 비활성화 시 쓸 값 */

    unsigned int           enable_time;     /* 안정화 시간 (µs) */
    unsigned int           ramp_delay;      /* 전압 변경 속도 (µV/µs) */

    unsigned int           active_discharge_reg;
    unsigned int           active_discharge_mask;
    unsigned int           active_discharge_on;
    unsigned int           active_discharge_off;
};

/* Regulator 하드웨어 제어 콜백 */
struct regulator_ops {
    /* 전압 제어 */
    int (*list_voltage)(struct regulator_dev *, unsigned int selector);
    int (*set_voltage_sel)(struct regulator_dev *, unsigned int sel);
    int (*get_voltage_sel)(struct regulator_dev *);
    int (*map_voltage)(struct regulator_dev *, int min_uV, int max_uV);

    /* 활성화/비활성화 */
    int (*enable)(struct regulator_dev *);
    int (*disable)(struct regulator_dev *);
    int (*is_enabled)(struct regulator_dev *);

    /* 전류 제한 */
    int (*set_current_limit)(struct regulator_dev *, int min_uA, int max_uA);
    int (*get_current_limit)(struct regulator_dev *);

    /* 동작 모드 (NORMAL, IDLE, STANDBY, FAST) */
    int (*set_mode)(struct regulator_dev *, unsigned int mode);
    unsigned int (*get_mode)(struct regulator_dev *);

    /* Suspend 상태 제어 */
    int (*set_suspend_voltage)(struct regulator_dev *, int uV);
    int (*set_suspend_enable)(struct regulator_dev *);
    int (*set_suspend_disable)(struct regulator_dev *);
    int (*set_suspend_mode)(struct regulator_dev *, unsigned int mode);

    /* 전압 변경 완료 시간 (µs) */
    int (*set_ramp_delay)(struct regulator_dev *, int ramp_delay);

    /* 에러/이벤트 감지 */
    int (*get_error_flags)(struct regulator_dev *, unsigned int *flags);
};

/* include/linux/regulator/machine.h — 제약 조건 */
struct regulation_constraints {
    const char        *name;          /* 설명 문자열 */

    int               min_uV;         /* 허용 최소 전압 (µV) */
    int               max_uV;         /* 허용 최대 전압 (µV) */
    int               min_uA;         /* 허용 최소 전류 (µA) */
    int               max_uA;         /* 허용 최대 전류 (µA) */

    unsigned int      valid_modes_mask;  /* 허용 동작 모드 */
    unsigned int      valid_ops_mask;    /* 허용 작업 (아래 표 참조) */

    int               input_uV;       /* 입력 전압 (µV) */
    unsigned int      ramp_delay;     /* 전압 변경 속도 (µV/µs) */
    unsigned int      settling_time;  /* 안정화 대기 시간 (µs) */
    unsigned int      enable_time;    /* 활성화 후 안정화 시간 (µs) */

    unsigned          always_on:1;     /* 항상 켜짐 (끌 수 없음) */
    unsigned          boot_on:1;       /* 부팅 시 자동 활성화 */
    unsigned          apply_uV:1;      /* 등록 시 즉시 전압 적용 */

    /* Suspend 상태별 설정 */
    struct regulator_state state_mem;  /* S3 Suspend-to-RAM */
    struct regulator_state state_disk; /* S4 Hibernate */
    struct regulator_state state_standby;
};

Consumer API — Regulator 사용하기

/* Regulator Consumer API — 주요 함수 */
#include <linux/regulator/consumer.h>

/* 1. Regulator 획득 */
struct regulator *devm_regulator_get(struct device *dev,
                                     const char *id);
/* id = "vdd" → DT에서 vdd-supply 프로퍼티 검색 */

struct regulator *devm_regulator_get_optional(struct device *dev,
                                              const char *id);
/* optional: 없으면 -ENODEV 반환 (dummy 생성 안 함) */

/* 벌크 획득 (여러 regulator를 한 번에) */
int devm_regulator_bulk_get(struct device *dev, int num_consumers,
                           struct regulator_bulk_data *consumers);

/* 2. 활성화/비활성화 (참조 카운팅됨) */
int regulator_enable(struct regulator *reg);
int regulator_disable(struct regulator *reg);
int regulator_is_enabled(struct regulator *reg);

/* 벌크 활성화/비활성화 */
int regulator_bulk_enable(int num, struct regulator_bulk_data *consumers);
int regulator_bulk_disable(int num, struct regulator_bulk_data *consumers);

/* 3. 전압 제어 */
int regulator_set_voltage(struct regulator *reg,
                         int min_uV, int max_uV);
int regulator_get_voltage(struct regulator *reg);

/* 4. 전류 제한 */
int regulator_set_current_limit(struct regulator *reg,
                               int min_uA, int max_uA);

/* 5. 동작 모드 */
int regulator_set_load(struct regulator *reg, int load_uA);
/* DRMS: 부하 전류에 따라 자동으로 최적 모드 선택 */

/* 6. 이벤트 알림 */
int regulator_register_notifier(struct regulator *reg,
                               struct notifier_block *nb);
/* REGULATOR_EVENT_UNDER_VOLTAGE, OVER_CURRENT, OVER_TEMP 등 */

/* 소비자 사용 예제 — 센서 디바이스 드라이버 */

struct my_sensor {
    struct regulator  *vdd;       /* 코어 전원 */
    struct regulator  *vddio;     /* I/O 전원 */
    struct i2c_client *client;
};

static int my_sensor_probe(struct i2c_client *client)
{
    struct device *dev = &client->dev;
    struct my_sensor *sensor;
    int ret;

    sensor = devm_kzalloc(dev, sizeof(*sensor), GFP_KERNEL);
    if (!sensor)
        return -ENOMEM;

    /* DT에서 vdd-supply, vddio-supply 프로퍼티로 레귤레이터 획득 */
    sensor->vdd = devm_regulator_get(dev, "vdd");
    if (IS_ERR(sensor->vdd))
        return dev_err_probe(dev, PTR_ERR(sensor->vdd),
                              "failed to get vdd regulator\\n");

    sensor->vddio = devm_regulator_get(dev, "vddio");
    if (IS_ERR(sensor->vddio))
        return dev_err_probe(dev, PTR_ERR(sensor->vddio),
                              "failed to get vddio regulator\\n");

    /* 전압 설정 (필요한 경우) */
    ret = regulator_set_voltage(sensor->vdd, 2800000, 2800000);
    if (ret)
        return dev_err_probe(dev, ret, "failed to set vdd voltage\\n");

    /* 전원 활성화 — 순서 중요! (코어 → I/O) */
    ret = regulator_enable(sensor->vdd);
    if (ret)
        return ret;

    usleep_range(1000, 1500);  /* 전원 안정화 대기 */

    ret = regulator_enable(sensor->vddio);
    if (ret) {
        regulator_disable(sensor->vdd);
        return ret;
    }

    usleep_range(5000, 6000);  /* 디바이스 부팅 대기 */

    /* ... 센서 초기화 ... */
    return 0;
}

static void my_sensor_remove(struct i2c_client *client)
{
    struct my_sensor *sensor = i2c_get_clientdata(client);

    /* 전원 해제 — 역순! (I/O → 코어) */
    regulator_disable(sensor->vddio);
    regulator_disable(sensor->vdd);
}

Provider 드라이버 구현

PMIC 레귤레이터 드라이버는 regulator_desc에 레지스터 매핑을 기술하면 프레임워크의 regmap 헬퍼 함수가 대부분의 regulator_ops를 자동 구현합니다.

/* drivers/regulator/example-regulator.c — PMIC 드라이버 예제 */
#include <linux/module.h>
#include <linux/i2c.h>
#include <linux/regmap.h>
#include <linux/regulator/driver.h>
#include <linux/regulator/of_regulator.h>

/* PMIC 레지스터 맵 */
#define PMIC_BUCK1_CTRL    0x10   /* [0]: enable */
#define PMIC_BUCK1_VSEL    0x11   /* [6:0]: voltage selector */
#define PMIC_LDO1_CTRL     0x30
#define PMIC_LDO1_VSEL     0x31

/* regulator_ops — regmap 헬퍼 함수 사용으로 직접 구현 최소화 */
static const struct regulator_ops example_buck_ops = {
    .list_voltage     = regulator_list_voltage_linear,
    .map_voltage      = regulator_map_voltage_linear,
    .get_voltage_sel  = regulator_get_voltage_sel_regmap,
    .set_voltage_sel  = regulator_set_voltage_sel_regmap,
    .enable           = regulator_enable_regmap,
    .disable          = regulator_disable_regmap,
    .is_enabled       = regulator_is_enabled_regmap,
};

static const struct regulator_ops example_ldo_ops = {
    .list_voltage     = regulator_list_voltage_linear_range,
    .map_voltage      = regulator_map_voltage_linear_range,
    .get_voltage_sel  = regulator_get_voltage_sel_regmap,
    .set_voltage_sel  = regulator_set_voltage_sel_regmap,
    .enable           = regulator_enable_regmap,
    .disable          = regulator_disable_regmap,
    .is_enabled       = regulator_is_enabled_regmap,
};

/* LDO용 비선형 범위: 0.8V~1.5V(50mV step) + 1.8V~3.3V(100mV step) */
static const struct regulator_linear_range example_ldo_ranges[] = {
    REGULATOR_LINEAR_RANGE(800000,  0,  14, 50000),   /* 0.8V~1.5V */
    REGULATOR_LINEAR_RANGE(1800000, 15, 30, 100000),  /* 1.8V~3.3V */
};

enum { EXAMPLE_BUCK1, EXAMPLE_LDO1, EXAMPLE_NUM_REGULATORS };

static const struct regulator_desc example_regulators[] = {
    [EXAMPLE_BUCK1] = {
        .name            = "BUCK1",
        .supply_name     = "vin1",
        .id              = EXAMPLE_BUCK1,
        .type            = REGULATOR_VOLTAGE,
        .ops             = &example_buck_ops,
        .n_voltages      = 128,          /* 7비트 selector */
        .min_uV          = 600000,       /* 0.6V */
        .uV_step         = 12500,        /* 12.5mV step */
        /* 0.6V + 12.5mV × 127 = 2.1875V */
        .vsel_reg        = PMIC_BUCK1_VSEL,
        .vsel_mask       = 0x7F,
        .enable_reg      = PMIC_BUCK1_CTRL,
        .enable_mask     = BIT(0),
        .enable_val      = BIT(0),
        .disable_val     = 0,
        .enable_time     = 300,          /* 300µs 안정화 */
        .ramp_delay      = 12500,        /* 12.5mV/µs */
        .owner           = THIS_MODULE,
    },
    [EXAMPLE_LDO1] = {
        .name            = "LDO1",
        .supply_name     = "vin2",
        .id              = EXAMPLE_LDO1,
        .type            = REGULATOR_VOLTAGE,
        .ops             = &example_ldo_ops,
        .n_voltages      = 31,
        .linear_ranges   = example_ldo_ranges,
        .n_linear_ranges = ARRAY_SIZE(example_ldo_ranges),
        .vsel_reg        = PMIC_LDO1_VSEL,
        .vsel_mask       = 0x1F,
        .enable_reg      = PMIC_LDO1_CTRL,
        .enable_mask     = BIT(0),
        .enable_val      = BIT(0),
        .disable_val     = 0,
        .enable_time     = 200,
        .owner           = THIS_MODULE,
    },
};

static const struct regmap_config example_regmap_config = {
    .reg_bits  = 8,
    .val_bits  = 8,
    .max_register = 0x80,
};

static int example_pmic_probe(struct i2c_client *client)
{
    struct device *dev = &client->dev;
    struct regmap *regmap;
    struct regulator_config config = {};
    int i;

    regmap = devm_regmap_init_i2c(client, &example_regmap_config);
    if (IS_ERR(regmap))
        return PTR_ERR(regmap);

    config.dev     = dev;
    config.regmap  = regmap;

    for (i = 0; i < EXAMPLE_NUM_REGULATORS; i++) {
        struct regulator_dev *rdev;

        rdev = devm_regulator_register(dev, &example_regulators[i],
                                        &config);
        if (IS_ERR(rdev))
            return dev_err_probe(dev, PTR_ERR(rdev),
                                  "failed to register %s\\n",
                                  example_regulators[i].name);
    }

    dev_info(dev, "PMIC registered (%d regulators)\\n",
             EXAMPLE_NUM_REGULATORS);
    return 0;
}

static const struct of_device_id example_pmic_of_match[] = {
    { .compatible = "vendor,example-pmic" },
    { }
};
MODULE_DEVICE_TABLE(of, example_pmic_of_match);

static struct i2c_driver example_pmic_driver = {
    .probe  = example_pmic_probe,
    .driver = {
        .name           = "example-pmic",
        .of_match_table = example_pmic_of_match,
    },
};
module_i2c_driver(example_pmic_driver);

Device Tree 바인딩:

/* PMIC 노드와 레귤레이터 정의 */
pmic@48 {
    compatible = "vendor,example-pmic";
    reg = <0x48>;

    regulators {
        buck1: BUCK1 {
            regulator-name = "vdd_cpu";
            regulator-min-microvolt = <800000>;   /* 0.8V */
            regulator-max-microvolt = <1500000>;  /* 1.5V */
            regulator-always-on;
            regulator-boot-on;
            regulator-ramp-delay = <12500>;      /* 12.5mV/µs */
        };

        ldo1: LDO1 {
            regulator-name = "vdd_sensor";
            regulator-min-microvolt = <2800000>;  /* 2.8V */
            regulator-max-microvolt = <2800000>;  /* 고정 2.8V */
        };
    };
};

/* 소비자 노드에서 레귤레이터 참조 */
sensor@68 {
    compatible = "vendor,my-sensor";
    reg = <0x68>;
    vdd-supply = <&ldo1>;        /* 코어 전원 */
    vddio-supply = <&buck1>;     /* I/O 전원 */
};

/* 고정 전압 레귤레이터 (GPIO 스위치) */
reg_3v3: regulator-3v3 {
    compatible = "regulator-fixed";
    regulator-name = "vdd_3v3";
    regulator-min-microvolt = <3300000>;
    regulator-max-microvolt = <3300000>;
    gpio = <&gpio1 5 GPIO_ACTIVE_HIGH>;
    enable-active-high;
    regulator-boot-on;
};

Regulator 디버깅

# === Regulator sysfs/debugfs 인터페이스 ===

# 등록된 모든 레귤레이터 목록
ls /sys/class/regulator/

# 개별 레귤레이터 정보
cat /sys/class/regulator/regulator.0/name
cat /sys/class/regulator/regulator.0/state          # enabled/disabled
cat /sys/class/regulator/regulator.0/microvolts     # 현재 전압 (µV)
cat /sys/class/regulator/regulator.0/min_microvolts
cat /sys/class/regulator/regulator.0/max_microvolts
cat /sys/class/regulator/regulator.0/num_users      # 활성 소비자 수
cat /sys/class/regulator/regulator.0/type           # voltage/current

# debugfs — 상세 정보 (CONFIG_DEBUG_FS 필요)
cat /sys/kernel/debug/regulator/regulator_summary
# 트리 형태로 공급 체인, 전압, 소비자, use_count 표시

# dmesg에서 regulator 관련 로그
dmesg | grep -i regulator
dmesg | grep -i "supply\|voltage\|ldo\|buck"

# Device Tree에서 supply 바인딩 확인
grep -r "supply" /proc/device-tree/ 2>/dev/null | head -20

관련 문서

이 주제와 관련된 다른 문서를 더 깊이 이해하고 싶다면 다음을 참고하세요.

• 디바이스 드라이버 — 디바이스 드라이버 모델
• 버스 서브시스템 — 버스 아키텍처
• 인터럽트 처리 — IRQ 핸들링
• 전원 관리 — 디바이스 전원 관리
• 디버깅 — 드라이버 디버깅
• PCI/PCIe — PCIe 디바이스