Documentation/power/charger-manager.txt

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