Documentation/power/charger-manager.rst

   1 ===============
   2 Charger Manager
   3 ===============
   4
   5         (C) 2011 MyungJoo Ham <myungjoo.ham@samsung.com>, GPL
   6
   7 Charger Manager provides in-kernel battery charger management that
   8 requires temperature monitoring during suspend-to-RAM state
   9 and where each battery may have multiple chargers attached and the userland
  10 wants to look at the aggregated information of the multiple chargers.
  11
  12 Charger Manager is a platform_driver with power-supply-class entries.
  13 An instance of Charger Manager (a platform-device created with Charger-Manager)
  14 represents an independent battery with chargers. If there are multiple
  15 batteries with their own chargers acting independently in a system,
  16 the system may need multiple instances of Charger Manager.
  17
  18 1. Introduction
  19 ===============
  20
  21 Charger Manager supports the following:
  22
  23 * Support for multiple chargers (e.g., a device with USB, AC, and solar panels)
  24         A system may have multiple chargers (or power sources) and some of
  25         they may be activated at the same time. Each charger may have its
  26         own power-supply-class and each power-supply-class can provide
  27         different information about the battery status. This framework
  28         aggregates charger-related information from multiple sources and
  29         shows combined information as a single power-supply-class.
  30
  31 * Support for in suspend-to-RAM polling (with suspend_again callback)
  32         While the battery is being charged and the system is in suspend-to-RAM,
  33         we may need to monitor the battery health by looking at the ambient or
  34         battery temperature. We can accomplish this by waking up the system
  35         periodically. However, such a method wakes up devices unnecessarily for
  36         monitoring the battery health and tasks, and user processes that are
  37         supposed to be kept suspended. That, in turn, incurs unnecessary power
  38         consumption and slow down charging process. Or even, such peak power
  39         consumption can stop chargers in the middle of charging
  40         (external power input < device power consumption), which not
  41         only affects the charging time, but the lifespan of the battery.
  42
  43         Charger Manager provides a function "cm_suspend_again" that can be
  44         used as suspend_again callback of platform_suspend_ops. If the platform
  45         requires tasks other than cm_suspend_again, it may implement its own
  46         suspend_again callback that calls cm_suspend_again in the middle.
  47         Normally, the platform will need to resume and suspend some devices
  48         that are used by Charger Manager.
  49
  50 * Support for premature full-battery event handling
  51         If the battery voltage drops by "fullbatt_vchkdrop_uV" after
  52         "fullbatt_vchkdrop_ms" from the full-battery event, the framework
  53         restarts charging. This check is also performed while suspended by
  54         setting wakeup time accordingly and using suspend_again.
  55
  56 * Support for uevent-notify
  57         With the charger-related events, the device sends
  58         notification to users with UEVENT.
  59
  60 2. Global Charger-Manager Data related with suspend_again
  61 =========================================================
  62 In order to setup Charger Manager with suspend-again feature
  63 (in-suspend monitoring), the user should provide charger_global_desc
  64 with setup_charger_manager(`struct charger_global_desc *`).
  65 This charger_global_desc data for in-suspend monitoring is global
  66 as the name suggests. Thus, the user needs to provide only once even
  67 if there are multiple batteries. If there are multiple batteries, the
  68 multiple instances of Charger Manager share the same charger_global_desc
  69 and it will manage in-suspend monitoring for all instances of Charger Manager.
  70
  71 The user needs to provide all the three entries to `struct charger_global_desc`
  72 properly in order to activate in-suspend monitoring:
  73
  74 `char *rtc_name;`
  75         The name of rtc (e.g., "rtc0") used to wakeup the system from
  76         suspend for Charger Manager. The alarm interrupt (AIE) of the rtc
  77         should be able to wake up the system from suspend. Charger Manager
  78         saves and restores the alarm value and use the previously-defined
  79         alarm if it is going to go off earlier than Charger Manager so that
  80         Charger Manager does not interfere with previously-defined alarms.
  81
  82 `bool (*rtc_only_wakeup)(void);`
  83         This callback should let CM know whether
  84         the wakeup-from-suspend is caused only by the alarm of "rtc" in the
  85         same struct. If there is any other wakeup source triggered the
  86         wakeup, it should return false. If the "rtc" is the only wakeup
  87         reason, it should return true.
  88
  89 `bool assume_timer_stops_in_suspend;`
  90         if true, Charger Manager assumes that
  91         the timer (CM uses jiffies as timer) stops during suspend. Then, CM
  92         assumes that the suspend-duration is same as the alarm length.
  93
  94
  95 3. How to setup suspend_again
  96 =============================
  97 Charger Manager provides a function "extern bool cm_suspend_again(void)".
  98 When cm_suspend_again is called, it monitors every battery. The suspend_ops
  99 callback of the system's platform_suspend_ops can call cm_suspend_again
 100 function to know whether Charger Manager wants to suspend again or not.
 101 If there are no other devices or tasks that want to use suspend_again
 102 feature, the platform_suspend_ops may directly refer to cm_suspend_again
 103 for its suspend_again callback.
 104
 105 The cm_suspend_again() returns true (meaning "I want to suspend again")
 106 if the system was woken up by Charger Manager and the polling
 107 (in-suspend monitoring) results in "normal".
 108
 109 4. Charger-Manager Data (struct charger_desc)
 110 =============================================
 111 For each battery charged independently from other batteries (if a series of
 112 batteries are charged by a single charger, they are counted as one independent
 113 battery), an instance of Charger Manager is attached to it. The following
 114
 115 struct charger_desc elements:
 116
 117 `char *psy_name;`
 118         The power-supply-class name of the battery. Default is
 119         "battery" if psy_name is NULL. Users can access the psy entries
 120         at "/sys/class/power_supply/[psy_name]/".
 121
 122 `enum polling_modes polling_mode;`
 123           CM_POLL_DISABLE:
 124                 do not poll this battery.
 125           CM_POLL_ALWAYS:
 126                 always poll this battery.
 127           CM_POLL_EXTERNAL_POWER_ONLY:
 128                 poll this battery if and only if an external power
 129                 source is attached.
 130           CM_POLL_CHARGING_ONLY:
 131                 poll this battery if and only if the battery is being charged.
 132
 133 `unsigned int fullbatt_vchkdrop_ms; / unsigned int fullbatt_vchkdrop_uV;`
 134         If both have non-zero values, Charger Manager will check the
 135         battery voltage drop fullbatt_vchkdrop_ms after the battery is fully
 136         charged. If the voltage drop is over fullbatt_vchkdrop_uV, Charger
 137         Manager will try to recharge the battery by disabling and enabling
 138         chargers. Recharge with voltage drop condition only (without delay
 139         condition) is needed to be implemented with hardware interrupts from
 140         fuel gauges or charger devices/chips.
 141
 142 `unsigned int fullbatt_uV;`
 143         If specified with a non-zero value, Charger Manager assumes
 144         that the battery is full (capacity = 100) if the battery is not being
 145         charged and the battery voltage is equal to or greater than
 146         fullbatt_uV.
 147
 148 `unsigned int polling_interval_ms;`
 149         Required polling interval in ms. Charger Manager will poll
 150         this battery every polling_interval_ms or more frequently.
 151
 152 `enum data_source battery_present;`
 153         CM_BATTERY_PRESENT:
 154                 assume that the battery exists.
 155         CM_NO_BATTERY:
 156                 assume that the battery does not exists.
 157         CM_FUEL_GAUGE:
 158                 get battery presence information from fuel gauge.
 159         CM_CHARGER_STAT:
 160                 get battery presence from chargers.
 161
 162 `char **psy_charger_stat;`
 163         An array ending with NULL that has power-supply-class names of
 164         chargers. Each power-supply-class should provide "PRESENT" (if
 165         battery_present is "CM_CHARGER_STAT"), "ONLINE" (shows whether an
 166         external power source is attached or not), and "STATUS" (shows whether
 167         the battery is {"FULL" or not FULL} or {"FULL", "Charging",
 168         "Discharging", "NotCharging"}).
 169
 170 `int num_charger_regulators; / struct regulator_bulk_data *charger_regulators;`
 171         Regulators representing the chargers in the form for
 172         regulator framework's bulk functions.
 173
 174 `char *psy_fuel_gauge;`
 175         Power-supply-class name of the fuel gauge.
 176
 177 `int (*temperature_out_of_range)(int *mC); / bool measure_battery_temp;`
 178         This callback returns 0 if the temperature is safe for charging,
 179         a positive number if it is too hot to charge, and a negative number
 180         if it is too cold to charge. With the variable mC, the callback returns
 181         the temperature in 1/1000 of centigrade.
 182         The source of temperature can be battery or ambient one according to
 183         the value of measure_battery_temp.
 184
 185
 186 5. Notify Charger-Manager of charger events: cm_notify_event()
 187 ==============================================================
 188 If there is an charger event is required to notify
 189 Charger Manager, a charger device driver that triggers the event can call
 190 cm_notify_event(psy, type, msg) to notify the corresponding Charger Manager.
 191 In the function, psy is the charger driver's power_supply pointer, which is
 192 associated with Charger-Manager. The parameter "type"
 193 is the same as irq's type (enum cm_event_types). The event message "msg" is
 194 optional and is effective only if the event type is "UNDESCRIBED" or "OTHERS".
 195
 196 6. Other Considerations
 197 =======================
 198
 199 At the charger/battery-related events such as battery-pulled-out,
 200 charger-pulled-out, charger-inserted, DCIN-over/under-voltage, charger-stopped,
 201 and others critical to chargers, the system should be configured to wake up.
 202 At least the following should wake up the system from a suspend:
 203 a) charger-on/off b) external-power-in/out c) battery-in/out (while charging)
 204
 205 It is usually accomplished by configuring the PMIC as a wakeup source.