Charger Manager

개요와 인스턴스 모델

Charger Manager는 suspend-to-RAM 상태에서도 온도를 감시해야 하고, 하나의 배터리에 여러 charger가 연결될 수 있으며, userland가 이들의 집계 정보를 보려는 시스템을 위한 커널 내부 배터리 충전 관리 기능입니다.

Charger Manager는 power-supply-class 항목을 제공하는 `platform_driver`입니다. Charger Manager로 생성한 하나의 platform device 인스턴스는 charger가 연결된 독립 배터리 하나를 나타냅니다. 시스템에 서로 독립적으로 동작하는 배터리와 charger 묶음이 여러 개라면 Charger Manager 인스턴스도 여러 개 필요할 수 있습니다.

===============
Charger Manager
===============

        (C) 2011 MyungJoo Ham <[email protected]>, GPL

Charger Manager provides in-kernel battery charger management that
requires temperature monitoring during suspend-to-RAM state
and where each battery may have multiple chargers attached and the userland
wants to look at the aggregated information of the multiple chargers.

Charger Manager is a platform_driver with power-supply-class entries.
An instance of Charger Manager (a platform-device created with Charger-Manager)
represents an independent battery with chargers. If there are multiple
batteries with their own chargers acting independently in a system,
the system may need multiple instances of Charger Manager.

여러 charger 집계와 suspend 중 polling

Charger Manager는 USB, AC, solar panel처럼 여러 charger 또는 power source가 있는 구성을 지원합니다. 여러 전원이 동시에 활성화될 수 있고 각각 별도의 power-supply-class와 서로 다른 배터리 상태 정보를 제공하더라도, framework는 charger 관련 정보를 합쳐 하나의 power-supply-class로 보여 줍니다.

배터리를 충전하는 동안 시스템이 suspend-to-RAM 상태라면 주변 온도나 배터리 온도로 건강 상태를 감시해야 할 수 있습니다. 시스템 전체를 주기적으로 완전히 깨우면 감시에 필요하지 않은 device, task, user process까지 resume되어 전력을 소모하고 충전을 늦춥니다. 순간 소비 전력이 외부 입력보다 커지면 충전이 중단되어 충전 시간뿐 아니라 배터리 수명에도 영향을 줄 수 있습니다.

Charger Manager의 `cm_suspend_again`은 `platform_suspend_ops`의 `suspend_again` callback으로 사용할 수 있습니다. platform에 다른 작업도 필요하면 자체 `suspend_again` callback 중간에서 `cm_suspend_again`을 호출할 수 있습니다. 보통 platform은 Charger Manager가 사용하는 일부 device만 resume한 뒤 다시 suspend하면 됩니다.

1. Introduction
===============

Charger Manager supports the following:

* Support for multiple chargers (e.g., a device with USB, AC, and solar panels)
        A system may have multiple chargers (or power sources) and some of
        they may be activated at the same time. Each charger may have its
        own power-supply-class and each power-supply-class can provide
        different information about the battery status. This framework
        aggregates charger-related information from multiple sources and
        shows combined information as a single power-supply-class.

* Support for in suspend-to-RAM polling (with suspend_again callback)
        While the battery is being charged and the system is in suspend-to-RAM,
        we may need to monitor the battery health by looking at the ambient or
        battery temperature. We can accomplish this by waking up the system
        periodically. However, such a method wakes up devices unnecessarily for
        monitoring the battery health and tasks, and user processes that are
        supposed to be kept suspended. That, in turn, incurs unnecessary power
        consumption and slow down charging process. Or even, such peak power
        consumption can stop chargers in the middle of charging
        (external power input < device power consumption), which not
        only affects the charging time, but the lifespan of the battery.

        Charger Manager provides a function "cm_suspend_again" that can be
        used as suspend_again callback of platform_suspend_ops. If the platform
        requires tasks other than cm_suspend_again, it may implement its own
        suspend_again callback that calls cm_suspend_again in the middle.
        Normally, the platform will need to resume and suspend some devices
        that are used by Charger Manager.

조기 full 판정과 uevent

Full-battery event가 발생하고 `fullbatt_vchkdrop_ms`가 지난 뒤 배터리 전압이 `fullbatt_vchkdrop_uV`만큼 떨어지면 framework는 충전을 다시 시작합니다. Suspend 중에도 그 시각에 맞춰 wakeup alarm을 설정하고 `suspend_again`을 이용해 같은 검사를 수행합니다.

Charger 관련 event가 발생하면 device는 UEVENT로 사용자에게 알림을 보냅니다.

* Support for premature full-battery event handling
        If the battery voltage drops by "fullbatt_vchkdrop_uV" after
        "fullbatt_vchkdrop_ms" from the full-battery event, the framework
        restarts charging. This check is also performed while suspended by
        setting wakeup time accordingly and using suspend_again.

* Support for uevent-notify
        With the charger-related events, the device sends
        notification to users with UEVENT.

suspend_again용 전역 데이터

Suspend 중 감시를 사용하는 Charger Manager는 `setup_charger_manager(struct charger_global_desc *)`에 `charger_global_desc`를 제공해야 합니다. 이름처럼 이 데이터는 전역이며, 배터리가 여러 개여도 한 번만 제공합니다. 모든 Charger Manager 인스턴스가 같은 `charger_global_desc`를 공유하여 suspend 중 감시를 함께 관리합니다.

이 기능을 활성화하려면 `struct charger_global_desc`의 세 항목을 모두 올바르게 제공해야 합니다.

`char *rtc_name;`은 Charger Manager가 suspend에서 시스템을 깨울 때 사용할 RTC 이름입니다(예: `rtc0`). 그 RTC의 alarm interrupt(AIE)는 wakeup source여야 합니다. Charger Manager는 기존 alarm 값을 저장했다 복원하며, 기존 alarm이 자체 alarm보다 먼저 울릴 예정이면 기존 값을 사용하여 먼저 설정된 alarm을 방해하지 않습니다.

`bool (*rtc_only_wakeup)(void);` callback은 resume 원인이 같은 구조체의 `rtc` alarm뿐인지 알려 줍니다. 다른 wakeup source도 작동했다면 `false`, RTC alarm만이 원인이면 `true`를 반환해야 합니다.

`bool assume_timer_stops_in_suspend;`가 `true`이면 Charger Manager는 자신이 timer로 사용하는 jiffies가 suspend 중 멈춘다고 가정합니다. 따라서 suspend 지속 시간을 alarm 길이와 같다고 계산합니다.

2. Global Charger-Manager Data related with suspend_again
=========================================================
In order to setup Charger Manager with suspend-again feature
(in-suspend monitoring), the user should provide charger_global_desc
with setup_charger_manager(`struct charger_global_desc *`).
This charger_global_desc data for in-suspend monitoring is global
as the name suggests. Thus, the user needs to provide only once even
if there are multiple batteries. If there are multiple batteries, the
multiple instances of Charger Manager share the same charger_global_desc
and it will manage in-suspend monitoring for all instances of Charger Manager.

The user needs to provide all the three entries to `struct charger_global_desc`
properly in order to activate in-suspend monitoring:

`char *rtc_name;`
        The name of rtc (e.g., "rtc0") used to wakeup the system from
        suspend for Charger Manager. The alarm interrupt (AIE) of the rtc
        should be able to wake up the system from suspend. Charger Manager
        saves and restores the alarm value and use the previously-defined
        alarm if it is going to go off earlier than Charger Manager so that
        Charger Manager does not interfere with previously-defined alarms.

`bool (*rtc_only_wakeup)(void);`
        This callback should let CM know whether
        the wakeup-from-suspend is caused only by the alarm of "rtc" in the
        same struct. If there is any other wakeup source triggered the
        wakeup, it should return false. If the "rtc" is the only wakeup
        reason, it should return true.

`bool assume_timer_stops_in_suspend;`
        if true, Charger Manager assumes that
        the timer (CM uses jiffies as timer) stops during suspend. Then, CM
        assumes that the suspend-duration is same as the alarm length.

cm_suspend_again() 연결

Charger Manager는 `extern bool cm_suspend_again(void)`을 제공합니다. 호출되면 모든 배터리를 감시하고, system의 `platform_suspend_ops`에 있는 `suspend_again` callback은 이 반환값으로 Charger Manager가 다시 suspend하기 원하는지 판단할 수 있습니다.

다른 device나 task가 `suspend_again` 기능을 사용하지 않는다면 `platform_suspend_ops.suspend_again`이 `cm_suspend_again`을 직접 가리켜도 됩니다.

시스템을 깨운 주체가 Charger Manager이고 suspend 중 polling 결과가 `normal`이면 `cm_suspend_again()`은 다시 suspend하고 싶다는 뜻으로 `true`를 반환합니다.

3. How to setup suspend_again
=============================
Charger Manager provides a function "extern bool cm_suspend_again(void)".
When cm_suspend_again is called, it monitors every battery. The suspend_ops
callback of the system's platform_suspend_ops can call cm_suspend_again
function to know whether Charger Manager wants to suspend again or not.
If there are no other devices or tasks that want to use suspend_again
feature, the platform_suspend_ops may directly refer to cm_suspend_again
for its suspend_again callback.

The cm_suspend_again() returns true (meaning "I want to suspend again")
if the system was woken up by Charger Manager and the polling
(in-suspend monitoring) results in "normal".

charger_desc: 이름과 polling mode

다른 배터리와 독립적으로 충전되는 배터리마다 Charger Manager 인스턴스 하나를 연결합니다. 여러 cell이 charger 하나에 직렬로 연결되어 함께 충전된다면 독립 배터리 하나로 셉니다.

`char *psy_name;`은 배터리의 power-supply-class 이름입니다. `NULL`이면 기본값은 `battery`이며 사용자는 `/sys/class/power_supply/[psy_name]/`에서 해당 항목에 접근할 수 있습니다.

`enum polling_modes polling_mode;`는 배터리를 언제 polling할지 결정합니다.

4. Charger-Manager Data (struct charger_desc)
=============================================
For each battery charged independently from other batteries (if a series of
batteries are charged by a single charger, they are counted as one independent
battery), an instance of Charger Manager is attached to it. The following

struct charger_desc elements:

`char *psy_name;`
        The power-supply-class name of the battery. Default is
        "battery" if psy_name is NULL. Users can access the psy entries
        at "/sys/class/power_supply/[psy_name]/".

`enum polling_modes polling_mode;`
          CM_POLL_DISABLE:
                do not poll this battery.
          CM_POLL_ALWAYS:
                always poll this battery.
          CM_POLL_EXTERNAL_POWER_ONLY:
                poll this battery if and only if an external power
                source is attached.
          CM_POLL_CHARGING_ONLY:
                poll this battery if and only if the battery is being charged.

charger_desc: 완충·주기·존재 판정

`fullbatt_vchkdrop_ms`와 `fullbatt_vchkdrop_uV`가 모두 0이 아니면 완충 후 `fullbatt_vchkdrop_ms`가 지난 시점에 전압 강하를 검사합니다. 강하량이 `fullbatt_vchkdrop_uV`보다 크면 charger를 disable했다 enable하여 재충전을 시도합니다. 지연 조건 없이 전압 강하만으로 재충전하려면 fuel gauge나 charger device/chip의 hardware interrupt를 이용해 별도로 구현해야 합니다.

`fullbatt_uV`가 0이 아니면 충전 중이 아니고 배터리 전압이 이 값 이상일 때 capacity가 100인 완충 상태로 간주합니다.

`polling_interval_ms`는 밀리초 단위의 필수 polling 간격입니다. Charger Manager는 이 간격마다 또는 더 자주 배터리를 확인합니다.

`enum data_source battery_present;`는 배터리 존재 여부의 출처를 선택합니다.

`unsigned int fullbatt_vchkdrop_ms; / unsigned int fullbatt_vchkdrop_uV;`
        If both have non-zero values, Charger Manager will check the
        battery voltage drop fullbatt_vchkdrop_ms after the battery is fully
        charged. If the voltage drop is over fullbatt_vchkdrop_uV, Charger
        Manager will try to recharge the battery by disabling and enabling
        chargers. Recharge with voltage drop condition only (without delay
        condition) is needed to be implemented with hardware interrupts from
        fuel gauges or charger devices/chips.

`unsigned int fullbatt_uV;`
        If specified with a non-zero value, Charger Manager assumes
        that the battery is full (capacity = 100) if the battery is not being
        charged and the battery voltage is equal to or greater than
        fullbatt_uV.

`unsigned int polling_interval_ms;`
        Required polling interval in ms. Charger Manager will poll
        this battery every polling_interval_ms or more frequently.

`enum data_source battery_present;`
        CM_BATTERY_PRESENT:
                assume that the battery exists.
        CM_NO_BATTERY:
                assume that the battery does not exists.
        CM_FUEL_GAUGE:
                get battery presence information from fuel gauge.
        CM_CHARGER_STAT:
                get battery presence from chargers.

charger_desc: charger·fuel gauge·온도

`char **psy_charger_stat;`은 charger의 power-supply-class 이름을 담고 `NULL`로 끝나는 배열입니다. 각 class는 `battery_present`가 `CM_CHARGER_STAT`일 때 필요한 `PRESENT`, 외부 전원 연결 여부를 나타내는 `ONLINE`, 그리고 `FULL` 여부 또는 `FULL`, `Charging`, `Discharging`, `NotCharging` 상태를 나타내는 `STATUS`를 제공해야 합니다.

`num_charger_regulators`와 `charger_regulators`는 regulator framework의 bulk function 형식으로 charger를 나타내는 regulator 개수와 `struct regulator_bulk_data` 배열입니다.

`char *psy_fuel_gauge;`는 fuel gauge의 power-supply-class 이름입니다.

`temperature_out_of_range(int *mC)` callback은 충전에 안전한 온도이면 0, 너무 뜨거우면 양수, 너무 차가우면 음수를 반환합니다. `mC`에는 섭씨 1/1000도 단위의 온도를 돌려줍니다. `measure_battery_temp` 값에 따라 배터리 온도 또는 주변 온도를 사용합니다.

`char **psy_charger_stat;`
        An array ending with NULL that has power-supply-class names of
        chargers. Each power-supply-class should provide "PRESENT" (if
        battery_present is "CM_CHARGER_STAT"), "ONLINE" (shows whether an
        external power source is attached or not), and "STATUS" (shows whether
        the battery is {"FULL" or not FULL} or {"FULL", "Charging",
        "Discharging", "NotCharging"}).

`int num_charger_regulators; / struct regulator_bulk_data *charger_regulators;`
        Regulators representing the chargers in the form for
        regulator framework's bulk functions.

`char *psy_fuel_gauge;`
        Power-supply-class name of the fuel gauge.

`int (*temperature_out_of_range)(int *mC); / bool measure_battery_temp;`
        This callback returns 0 if the temperature is safe for charging,
        a positive number if it is too hot to charge, and a negative number
        if it is too cold to charge. With the variable mC, the callback returns
        the temperature in 1/1000 of centigrade.
        The source of temperature can be battery or ambient one according to
        the value of measure_battery_temp.

cm_notify_event()와 wakeup 구성

Charger Manager에 알려야 하는 charger event가 발생하면 이를 일으킨 charger device driver가 `cm_notify_event(psy, type, msg)`를 호출합니다. `psy`는 Charger Manager와 연결된 charger driver의 `power_supply` pointer이고, `type`은 IRQ type과 같은 `enum cm_event_types`입니다. 선택 항목인 `msg`는 event type이 `UNDESCRIBED` 또는 `OTHERS`일 때만 유효합니다.

배터리 제거, charger 제거·삽입, DCIN over/under-voltage, charger 정지 등 charger에 중요한 event가 발생하면 시스템이 깨어나도록 구성해야 합니다. 최소한 charger on/off, external power in/out, 충전 중 battery in/out은 suspend에서 시스템을 깨워야 합니다.

보통 PMIC를 wakeup source로 설정해 이 동작을 구현합니다.

5. Notify Charger-Manager of charger events: cm_notify_event()
==============================================================
If there is an charger event is required to notify
Charger Manager, a charger device driver that triggers the event can call
cm_notify_event(psy, type, msg) to notify the corresponding Charger Manager.
In the function, psy is the charger driver's power_supply pointer, which is
associated with Charger-Manager. The parameter "type"
is the same as irq's type (enum cm_event_types). The event message "msg" is
optional and is effective only if the event type is "UNDESCRIBED" or "OTHERS".

6. Other Considerations
=======================

At the charger/battery-related events such as battery-pulled-out,
charger-pulled-out, charger-inserted, DCIN-over/under-voltage, charger-stopped,
and others critical to chargers, the system should be configured to wake up.
At least the following should wake up the system from a suspend:
a) charger-on/off b) external-power-in/out c) battery-in/out (while charging)

It is usually accomplished by configuring the PMIC as a wakeup source.