Power Supply / Battery / Charger

리눅스 커널의 power_supply 프레임워크를 "배터리 퍼센트를 보여 주는 sysfs 클래스" 수준이 아니라, 배터리 상태 모델과 충전 정책을 연결하는 공용 ABI 계층으로 정리합니다. AC/USB/무선 전원 소스, USB Type-C/PD 입력, charger IC, fuel gauge, 배터리 팩 보호 회로, power_supply_property 기반 표준 속성 체계, power_supply_changed()와 notifier/uevent 전파, Device Tree의 배터리 정보, charger-manager 같은 집계 정책, suspend/resume 및 현장 디버깅 절차까지 실무 기준으로 자세히 다룹니다.

개요와 역할 분리

power_supply 프레임워크의 핵심은 전원 관련 하드웨어를 레지스터 목록이 아니라 상태 모델로 다루는 것입니다. 사용자 공간이 알고 싶은 것은 "0x12 레지스터 bit 4가 켜졌는가"가 아니라 "외부 전원이 연결되어 있는가", "배터리는 충전 중인가", "잔량은 얼마나 남았는가", "건강 상태는 정상인가", "배터리 보호 때문에 충전이 중단되었는가"입니다. 이 프레임워크는 이런 질문을 표준 sysfs와 uevent ABI로 바꿔 줍니다.

실제 제품에서는 하나의 장치가 모든 기능을 혼자 수행하지 않는 경우가 대부분입니다. 스마트폰, 노트북, SBC, 산업용 장치 모두 전원 입력 감지, 충전 전류/전압 제어, 배터리 잔량 추정, 온도 보호, LED 표시가 분리되는 경우가 흔합니다. 커널 설계도 이를 반영해 "배터리", "충전기", "외부 입력"을 별도 객체로 모델링하는 편이 일반적입니다.

여기서 중요한 것은 power_supply가 전원 시스템 전체를 대체하지 않는다는 점입니다.

코어 객체와 등록 경로

커널은 보통 struct power_supply_desc와 struct power_supply_config를 통해 전원 객체를 등록합니다. 드라이버는 "이 객체가 어떤 타입인가", "어떤 속성을 제공하는가", "어떤 속성이 쓰기 가능한가", "외부 전원 변화가 들어오면 무엇을 다시 계산해야 하는가"를 선언하고, 사용자 공간은 표준 sysfs와 uevent를 통해 일관된 이름으로 이를 읽습니다.

가장 중요한 설계 포인트는 다음 네 가지입니다.

• 타입 선언 — battery, mains, USB, wireless, UPS 등 객체의 성격을 분명히 합니다.
• 속성 집합 선언 — 지원하는 enum power_supply_property 목록을 명시합니다.
• 읽기/쓰기 경계 설정 — get_property(), set_property(), property_is_writeable()를 통해 ABI 경계를 고정합니다.
• 관계 선언 — 어떤 외부 전원 공급이 어떤 배터리/소비자에 영향을 주는지 명시하고, 변화 전파 경로를 설계합니다.

#include <linux/power_supply.h>

struct my_battery {
    struct device *dev;
    struct power_supply *psy;
    int status;
    int health;
    int capacity;
    int voltage_now_uv;
    int current_now_ua;
    int temp_deci_c;
};

static enum power_supply_property battery_props[] = {
    POWER_SUPPLY_PROP_STATUS,
    POWER_SUPPLY_PROP_HEALTH,
    POWER_SUPPLY_PROP_PRESENT,
    POWER_SUPPLY_PROP_CAPACITY,
    POWER_SUPPLY_PROP_VOLTAGE_NOW,
    POWER_SUPPLY_PROP_CURRENT_NOW,
    POWER_SUPPLY_PROP_CHARGE_NOW,
    POWER_SUPPLY_PROP_TEMP,
};

static int my_battery_get_property(struct power_supply *psy,
                                   enum power_supply_property psp,
                                   union power_supply_propval *val)
{
    struct my_battery *bat = power_supply_get_drvdata(psy);

    switch (psp) {
    case POWER_SUPPLY_PROP_CAPACITY:
        val->intval = bat->capacity;
        return 0;
    case POWER_SUPPLY_PROP_STATUS:
        val->intval = bat->status;
        return 0;
    case POWER_SUPPLY_PROP_HEALTH:
        val->intval = bat->health;
        return 0;
    case POWER_SUPPLY_PROP_VOLTAGE_NOW:
        val->intval = bat->voltage_now_uv;
        return 0;
    case POWER_SUPPLY_PROP_CURRENT_NOW:
        val->intval = bat->current_now_ua;
        return 0;
    case POWER_SUPPLY_PROP_TEMP:
        val->intval = bat->temp_deci_c;
        return 0;
    default:
        return -EINVAL;
    }
}

static const struct power_supply_desc battery_desc = {
    .name = "BAT0",
    .type = POWER_SUPPLY_TYPE_BATTERY,
    .properties = battery_props,
    .num_properties = ARRAY_SIZE(battery_props),
    .get_property = my_battery_get_property,
};

객체 이름과 타입은 사용자 공간 정책에 직접 영향을 줍니다. 예를 들어 BAT0는 사람이 보기 쉬운 이름이고, USB-C나 usb-pd0는 입력 소스 객체임을 암시합니다. 이름이 불안정하면 사용자 공간이 장치를 식별하기 어려워지고, 타입이 틀리면 동일 속성이라도 의미가 달라집니다.

속성 ABI와 단위 규칙

power_supply에서 가장 자주 헷갈리는 부분은 "속성 이름이 비슷한데 단위와 의미가 다르다"는 점입니다. 공식 커널 문서는 전압, 전류, 전하량, 에너지량, 시간, 온도를 각각 microvolt, microamp, microamp-hour, microwatt-hour, seconds, 0.1도 Celsius 기준으로 통일하라고 요구합니다. 드라이버는 raw ADC 값이나 레지스터 값을 이 단위로 변환해서 반환해야 합니다.

배터리 상태 추정의 실제

사용자는 보통 배터리 잔량을 단일 숫자 하나로 봅니다. 그러나 커널 드라이버 입장에서는 이 숫자가 가장 어려운 값입니다. 리튬이온 배터리는 부하, 온도, 셀 노화, 직전 충방전 이력에 따라 전압-잔량 관계가 달라집니다. 그래서 실제 fuel gauge는 대개 다음 방법을 섞습니다.

• coulomb counting — 전류 적분으로 이동한 전하량을 추적합니다.
• OCV(open-circuit voltage) 보정 — 충분히 안정된 상태에서 전압을 기준으로 잔량 추정값을 보정합니다.
• 온도 보정 — 저온에서는 내부 저항 증가와 usable capacity 감소를 반영합니다.
• 노화 보정 — 설계 완충 용량과 현재 완충 용량 차이를 반영합니다.
• 상태 전이 히스테리시스 — 충전기 연결 직후, 부하 급변 직후의 값 튐을 완만하게 합니다.

입력 소스 분류와 충전 정책

충전기 드라이버는 단순히 "전원이 들어왔으니 충전 시작"만 하면 끝나지 않습니다. 어떤 입력 소스인지, 허용 전류가 얼마인지, 배터리 온도가 안전한지, 시스템 부하가 큰지, 이미 다른 charger가 붙어 있는지에 따라 충전 전류와 전압 목표를 바꿔야 합니다.

중요한 것은 power_supply가 PD 협상 자체를 수행하지는 않는다는 점입니다. Type-C/PD 계층이 입력 계약을 만들고, charger 드라이버는 그 결과를 안전한 충전 정책으로 바꿉니다. 이후 그 결과가 power_supply 속성으로 노출됩니다.

입력 소스가 여러 개인 시스템도 많습니다. 예를 들어 USB와 전용 AC 어댑터를 동시에 받을 수 있고, 태양광 입력이나 독 스테이션 전원까지 붙을 수 있습니다. 이런 경우 각 charger나 입력 power_supply가 각자 상태를 노출하고, 상위 정책 계층이 이들을 집계하는 구조가 자연스럽습니다. 공식 커널의 charger-manager 문서도 "배터리 하나에 여러 charger가 붙을 수 있다"는 전제를 중심으로 설명합니다.

쓰기 가능한 속성과 정책 제어

많은 power_supply 속성은 읽기 전용이지만, 일부 장치에서는 정책 제어가 가능한 쓰기 속성도 제공합니다. 대표적으로 charge start/end threshold, 입력 전류 제한, charge current/voltage 제한, charging enable/disable 같은 항목이 있습니다. 다만 이들은 하드웨어 지원이 있을 때만 노출하는 편이 안전합니다.

static int my_battery_property_is_writeable(struct power_supply *psy,
                                          enum power_supply_property psp)
{
    switch (psp) {
    case POWER_SUPPLY_PROP_CHARGE_CONTROL_START_THRESHOLD:
    case POWER_SUPPLY_PROP_CHARGE_CONTROL_END_THRESHOLD:
        return 1;
    default:
        return 0;
    }
}

static int my_battery_set_property(struct power_supply *psy,
                                   enum power_supply_property psp,
                                   const union power_supply_propval *val)
{
    struct my_battery *bat = power_supply_get_drvdata(psy);

    switch (psp) {
    case POWER_SUPPLY_PROP_CHARGE_CONTROL_START_THRESHOLD:
        if (val->intval < 40 || val->intval > 95)
            return -EINVAL;
        /* 실제 레지스터 쓰기 또는 펌웨어 호출 */
        /* ... */
        power_supply_changed(psy);
        return 0;
    default:
        return -EINVAL;
    }
}

상태 변화와 이벤트 전파

power_supply는 정적인 레지스터 덤프가 아니라 변화가 중요한 상태 기계입니다. 케이블 삽입, 충전 시작, 배터리 가열, 과전압 fault, 전류 제한 갱신, 완충 도달 같은 사건이 생기면 드라이버는 내부 상태를 갱신하고 power_supply_changed()를 호출합니다.

이 호출은 단순히 sysfs 값을 바꾸는 것에서 끝나지 않습니다. notifier를 통해 커널 소비자에 변화를 알리고, uevent를 통해 사용자 공간에도 갱신을 전파합니다. 또한 외부 전원 공급 객체가 supplicant 관계를 가지고 있다면 배터리 객체의 external_power_changed가 불려 재평가가 이어질 수 있습니다.

static void my_charger_update_state(struct my_charger *chg)
{
    /* PMIC / TCPC / ADC에서 상태를 다시 읽음 */
    /* online, input_current_limit, status, health 갱신 */
}

static void my_charger_irq_work(struct work_struct *work)
{
    struct my_charger *chg = container_of(work, struct my_charger, irq_work);

    my_charger_update_state(chg);

    /* 공급자 객체 갱신 */
    power_supply_changed(chg->usb_psy);

    /* 배터리 객체는 external_power_changed 또는 별도 changed로 재평가 */
    power_supply_changed(chg->battery_psy);
}

static void my_battery_external_power_changed(struct power_supply *psy)
{
    struct my_battery *bat = power_supply_get_drvdata(psy);

    /* 외부 전원 연결/해제에 따라 status, current, time_to_full 재계산 */
    /* ... */
    power_supply_changed(bat->psy);
}

실전에서는 IRQ 컨텍스트에서 바로 모든 레지스터를 읽고 changed를 남발하는 것보다, workqueue에서 상태를 모아 한 번에 갱신하는 편이 안정적입니다. 특히 I2C/SPI 기반 fuel gauge는 읽기 비용이 작지 않고, 값이 짧은 시간 안에 여러 번 흔들릴 수 있으므로 캐시와 debounce가 중요합니다.

Device Tree와 펌웨어 정보

임베디드 제품에서는 배터리의 설계 특성과 보드 연결 관계가 드라이버 코드보다 펌웨어 설명에 더 가깝습니다. 공식 커널 문서는 드라이버가 Device Tree의 배터리 노드에서 특성 정보를 읽기 위해 power_supply_get_battery_info()를 사용할 수 있다고 설명합니다. 즉 배터리 chemistry와 설계 용량, 전압 한계 같은 값은 가능한 한 DT나 firmware node에 두는 편이 좋습니다.

/* charger + battery + gauge + thermal sensor 연결 예시 */
charger: charger@6b {
    compatible = "vendor,my-charger";
    reg = <0x6b>;
    interrupt-parent = <&gpio3>;
    interrupts = <7 0>;
    input-current-limit-microamp = <3000000>;
    monitored-battery = <&battery>;
};

battery: battery {
    compatible = "simple-battery";
    voltage-min-design-microvolt = <3400000>;
    voltage-max-design-microvolt = <4350000>;
    charge-full-design-microamp-hours = <4200000>;
    energy-full-design-microwatt-hours = <15540000>;
    precharge-current-microamp = <250000>;
    charge-term-current-microamp = <150000>;
    constant-charge-current-max-microamp = <2500000>;
    constant-charge-voltage-max-microvolt = <4350000>;
};

fuel_gauge@55 {
    compatible = "vendor,my-gauge";
    reg = <0x55>;
    monitored-battery = <&battery>;
};

usb_power: tcpc@50 {
    compatible = "vendor,my-tcpc";
    reg = <0x50>;
};

다른 서브시스템과의 경계

power_supply 문서를 길게 써도 실제 구현은 단독으로 끝나지 않습니다. 다른 프레임워크와의 경계를 분명히 잡아 두지 않으면 ABI 중복과 정책 충돌이 생깁니다.

hwmon과의 관계는 특히 자주 헷갈립니다. hwmon은 "숫자 센서"가 중심이고, power_supply는 "전원 객체 상태"가 중심입니다. 같은 배터리 칩이라도 온도와 전압은 hwmon에 bridge될 수 있지만, status, capacity, charge_control_end_threshold 같은 값은 power_supply 문맥에서만 의미가 있습니다.

polling, 인터럽트, suspend-resume 전략

전원 장치는 "항상 실시간으로 읽어야 한다"는 인상이 있지만, 실제로는 polling과 인터럽트, resume 재동기화 전략을 잘 섞는 쪽이 효율적입니다. 특히 배터리 gauge는 I2C 트랜잭션이 비싸고, SoC가 suspend 상태일 때는 접근 자체가 어렵거나 깨울 가치가 없을 수 있습니다.

공식 커널의 charger-manager는 배터리 하나에 여러 charger가 붙는 경우와 suspend 중 온도 모니터링, 외부 전원 연결 시에만 polling 하는 정책 같은 실전 문제를 다룹니다. 모든 플랫폼이 charger-manager를 써야 하는 것은 아니지만, 다중 charger 집계와 절전 중 관리가 필요하다면 참고 가치가 큽니다.

1. IRQ나 timer에서 최소한의 wakeup만 수행합니다.
2. workqueue에서 charger/gauge 상태를 읽어 캐시를 갱신합니다.
3. resume 시에는 stale cache를 신뢰하지 말고 한 번 재동기화합니다.
4. 값이 실질적으로 바뀌었을 때만 power_supply_changed()를 호출해 uevent 폭주를 피합니다.

사용자 공간 ABI와 이름 설계

사용자 공간은 커널 내부 자료구조를 모릅니다. 오직 sysfs와 uevent만 봅니다. 따라서 power_supply 드라이버 품질은 "레지스터 접근이 맞는가"뿐 아니라 "사용자 공간이 오해 없이 읽을 수 있는 이름과 값인가"로 결정됩니다.

# 등록된 객체 확인
ls /sys/class/power_supply/

# 배터리 상태를 한 번에 덤프
grep . /sys/class/power_supply/BAT0/{type,status,health,present,capacity,capacity_level,voltage_now,current_now,temp}

# 입력 전원 상태 확인
grep . /sys/class/power_supply/USB*/{type,online,voltage_now,current_now}

# uevent 실시간 추적
udevadm monitor --kernel --property --subsystem-match=power_supply

POWER_SUPPLY_NAME=BAT0
POWER_SUPPLY_TYPE=Battery
POWER_SUPPLY_STATUS=Charging
POWER_SUPPLY_HEALTH=Good
POWER_SUPPLY_PRESENT=1
POWER_SUPPLY_CAPACITY=78
POWER_SUPPLY_VOLTAGE_NOW=4012000
POWER_SUPPLY_CURRENT_NOW=1280000
POWER_SUPPLY_TEMP=315

위 같은 uevent 내용은 사용자 공간에게 사실상의 계약서입니다. 같은 하드웨어라도 드라이버 버전마다 이름이나 단위가 달라지면 상위 정책이 깨집니다. 따라서 debug용으로 편한 이름보다 장기적으로 안정적인 ABI를 우선해야 합니다.

드라이버 구현 패턴

실무에서 안정적인 power_supply 드라이버는 보통 "하드웨어 읽기"와 "ABI 노출"을 분리합니다. 즉 get_property()가 매번 비싼 I2C 트랜잭션을 수행하기보다, 별도 update 경로가 캐시를 유지하고 get_property()는 정규화된 값을 빠르게 반환하는 식입니다.

struct my_chg {
    struct device *dev;
    struct mutex lock;
    struct delayed_work poll_work;
    struct power_supply *usb_psy;
    struct power_supply *bat_psy;
    bool online;
    int input_current_limit_ua;
    int charge_status;
    int bat_capacity;
};

static int my_hw_refresh_locked(struct my_chg *chg)
{
    /* I2C/SPI/PMIC register read */
    /* raw 값 → 표준 단위로 정규화 */
    /* chg->online, chg->input_current_limit_ua, chg->charge_status 갱신 */
    return 0;
}

static void my_poll_workfn(struct work_struct *work)
{
    struct my_chg *chg = container_of(work, struct my_chg, poll_work.work);

    mutex_lock(&chg->lock);
    my_hw_refresh_locked(chg);
    mutex_unlock(&chg->lock);

    power_supply_changed(chg->usb_psy);
    power_supply_changed(chg->bat_psy);
}

static int my_probe(struct platform_device *pdev)
{
    struct my_chg *chg;
    struct power_supply_config psy_cfg = {};

    chg = devm_kzalloc(&pdev->dev, sizeof(*chg), GFP_KERNEL);
    if (!chg)
        return -ENOMEM;

    chg->dev = &pdev->dev;
    mutex_init(&chg->lock);
    INIT_DELAYED_WORK(&chg->poll_work, my_poll_workfn);

    psy_cfg.drv_data = chg;
    psy_cfg.of_node = pdev->dev.of_node;

    chg->usb_psy = devm_power_supply_register(&pdev->dev, &usb_desc, &psy_cfg);
    chg->bat_psy = devm_power_supply_register(&pdev->dev, &battery_desc, &psy_cfg);

    /* 초기 상태 동기화 */
    schedule_delayed_work(&chg->poll_work, 0);
    return 0;
}

이 패턴의 장점은 get_property() 경로가 빨라지고, 상태 갱신 시점을 한 곳으로 모을 수 있다는 점입니다. 반면 캐시 일관성과 락 설계를 잘못하면 오래된 값을 오래 보여 줄 수 있으므로 "얼마나 자주 동기화할 것인가"를 함께 설계해야 합니다.

디버깅과 운영 점검

전원 문제는 재현성이 낮고 현장 환경 의존성이 큽니다. 따라서 디버깅은 "값 하나 읽기"보다 상태 전이 기록에 초점을 맞추는 편이 낫습니다. 아래 순서로 접근하면 대부분의 문제를 구조적으로 좁힐 수 있습니다.

1. 객체 목록 확인
   /sys/class/power_supply/ 아래에 어떤 객체가 등록되었는지 확인합니다. 배터리만 있고 입력 객체가 없거나, 반대로 입력은 있는데 배터리 객체가 없으면 모델 자체가 불완전합니다.
2. 정적 속성 덤프
   type, present, status, health, capacity, voltage_now, current_now, temp를 한 번에 저장합니다.
3. 이벤트 추적
   udevadm monitor --kernel --property --subsystem-match=power_supply로 케이블 삽입/제거, 충전 시작/종료 순간에 어떤 이벤트가 오는지 봅니다.
4. 로그와 레지스터 상관관계 확인
   커널 로그의 charger/fuel gauge 메세지와 sysfs 값이 동시에 움직이는지 확인합니다.
5. 경계 시스템 확인
   Type-C/PD, thermal, regulator, PMIC IRQ가 실제로 먼저 바뀌는지 확인합니다. power_supply는 종종 "최종 반영 계층"입니다.

# 객체 목록
ls -l /sys/class/power_supply/

# BAT0의 핵심 상태 한 번에 보기
for f in type present online status health capacity capacity_level \
         charge_now charge_full energy_now energy_full \
         voltage_now current_now temp time_to_empty_now time_to_full_now
do
  [ -f /sys/class/power_supply/BAT0/$f ] && printf "%-24s %s\n" "$f" "$(cat /sys/class/power_supply/BAT0/$f)"
done

# 입력 소스의 online 변화 감시
watch -n 1 'for d in /sys/class/power_supply/*; do [ -f "$d/online" ] && echo "$(basename "$d"): $(cat "$d/online")"; done'

# power_supply uevent 실시간 관찰
udevadm monitor --kernel --property --subsystem-match=power_supply

# 관련 로그
dmesg | grep -i -E "battery|charger|gauge|power_supply|typec|pd"

• Type-C/PD 계층이 입력 계약을 제대로 반영하지 못함
• thermal 정책이 충전 전류를 강제로 낮춤
• fuel gauge 보정 데이터가 틀림
• resume 후 stale cache가 갱신되지 않음
• 단위 변환이 맞지 않아 사용자 공간이 말이 안 되는 값을 표시함

흔한 실패 패턴과 원인 추적

끝까지 따라가는 상태 전이 예제

아래는 방전 중이던 장치에 USB Type-C PD 어댑터를 연결했을 때, 커널 내부와 사용자 공간에 어떤 변화가 일어나는지 단계별로 따라가는 예제입니다.

관련 문서

• Regulator 프레임워크 — 전압 레일과 전원 공급 제어
• hwmon — 온도/전압/전류 센서 관측 인터페이스와 power_supply bridge
• Thermal Management — 과열에 따른 충전 제한과 보호 정책
• USB — USB BC/Type-C/PD 입력 전원 경로
• LED / Backlight — power_supply 상태와 연결되는 LED 표시
• 디바이스 드라이버 — 플랫폼/I2C 전원 장치 드라이버 기본기
• I2C/SPI/GPIO — fuel gauge 및 charger 칩 연결 버스
• 전원 관리 — 시스템 suspend/resume, runtime PM와의 연결