1=============== 2Charger Manager 3=============== 4 5 (C) 2011 MyungJoo Ham <myungjoo.ham@samsung.com>, GPL 6 7Charger Manager provides in-kernel battery charger management that 8requires temperature monitoring during suspend-to-RAM state 9and where each battery may have multiple chargers attached and the userland 10wants to look at the aggregated information of the multiple chargers. 11 12Charger Manager is a platform_driver with power-supply-class entries. 13An instance of Charger Manager (a platform-device created with Charger-Manager) 14represents an independent battery with chargers. If there are multiple 15batteries with their own chargers acting independently in a system, 16the system may need multiple instances of Charger Manager. 17 181. Introduction 19=============== 20 21Charger 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 602. Global Charger-Manager Data related with suspend_again 61========================================================= 62In order to setup Charger Manager with suspend-again feature 63(in-suspend monitoring), the user should provide charger_global_desc 64with setup_charger_manager(`struct charger_global_desc *`). 65This charger_global_desc data for in-suspend monitoring is global 66as the name suggests. Thus, the user needs to provide only once even 67if there are multiple batteries. If there are multiple batteries, the 68multiple instances of Charger Manager share the same charger_global_desc 69and it will manage in-suspend monitoring for all instances of Charger Manager. 70 71The user needs to provide all the three entries to `struct charger_global_desc` 72properly 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 953. How to setup suspend_again 96============================= 97Charger Manager provides a function "extern bool cm_suspend_again(void)". 98When cm_suspend_again is called, it monitors every battery. The suspend_ops 99callback of the system's platform_suspend_ops can call cm_suspend_again 100function to know whether Charger Manager wants to suspend again or not. 101If there are no other devices or tasks that want to use suspend_again 102feature, the platform_suspend_ops may directly refer to cm_suspend_again 103for its suspend_again callback. 104 105The cm_suspend_again() returns true (meaning "I want to suspend again") 106if the system was woken up by Charger Manager and the polling 107(in-suspend monitoring) results in "normal". 108 1094. Charger-Manager Data (struct charger_desc) 110============================================= 111For each battery charged independently from other batteries (if a series of 112batteries are charged by a single charger, they are counted as one independent 113battery), an instance of Charger Manager is attached to it. The following 114 115struct 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 1865. Notify Charger-Manager of charger events: cm_notify_event() 187============================================================== 188If there is an charger event is required to notify 189Charger Manager, a charger device driver that triggers the event can call 190cm_notify_event(psy, type, msg) to notify the corresponding Charger Manager. 191In the function, psy is the charger driver's power_supply pointer, which is 192associated with Charger-Manager. The parameter "type" 193is the same as irq's type (enum cm_event_types). The event message "msg" is 194optional and is effective only if the event type is "UNDESCRIBED" or "OTHERS". 195 1966. Other Considerations 197======================= 198 199At the charger/battery-related events such as battery-pulled-out, 200charger-pulled-out, charger-inserted, DCIN-over/under-voltage, charger-stopped, 201and others critical to chargers, the system should be configured to wake up. 202At least the following should wake up the system from a suspend: 203a) charger-on/off b) external-power-in/out c) battery-in/out (while charging) 204 205It is usually accomplished by configuring the PMIC as a wakeup source. 206