1Charger Manager 2 (C) 2011 MyungJoo Ham <myungjoo.ham@samsung.com>, GPL 3 4Charger Manager provides in-kernel battery charger management that 5requires temperature monitoring during suspend-to-RAM state 6and where each battery may have multiple chargers attached and the userland 7wants to look at the aggregated information of the multiple chargers. 8 9Charger Manager is a platform_driver with power-supply-class entries. 10An instance of Charger Manager (a platform-device created with Charger-Manager) 11represents an independent battery with chargers. If there are multiple 12batteries with their own chargers acting independently in a system, 13the system may need multiple instances of Charger Manager. 14 151. Introduction 16=============== 17 18Charger 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 472. Global Charger-Manager Data related with suspend_again 48======================================================== 49In order to setup Charger Manager with suspend-again feature 50(in-suspend monitoring), the user should provide charger_global_desc 51with setup_charger_manager(struct charger_global_desc *). 52This charger_global_desc data for in-suspend monitoring is global 53as the name suggests. Thus, the user needs to provide only once even 54if there are multiple batteries. If there are multiple batteries, the 55multiple instances of Charger Manager share the same charger_global_desc 56and it will manage in-suspend monitoring for all instances of Charger Manager. 57 58The user needs to provide all the two entries properly in order to activate 59in-suspend monitoring: 60 61struct charger_global_desc { 62 63char *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 71bool (*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 793. How to setup suspend_again 80============================= 81Charger Manager provides a function "extern bool cm_suspend_again(void)". 82When cm_suspend_again is called, it monitors every battery. The suspend_ops 83callback of the system's platform_suspend_ops can call cm_suspend_again 84function to know whether Charger Manager wants to suspend again or not. 85If there are no other devices or tasks that want to use suspend_again 86feature, the platform_suspend_ops may directly refer to cm_suspend_again 87for its suspend_again callback. 88 89The cm_suspend_again() returns true (meaning "I want to suspend again") 90if the system was woken up by Charger Manager and the polling 91(in-suspend monitoring) results in "normal". 92 934. Charger-Manager Data (struct charger_desc) 94============================================= 95For each battery charged independently from other batteries (if a series of 96batteries are charged by a single charger, they are counted as one independent 97battery), an instance of Charger Manager is attached to it. 98 99struct charger_desc { 100 101char *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 106enum 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 114unsigned 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 120unsigned 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 124enum 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 128char **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 136int num_charger_regulators; 137struct regulator_bulk_data *charger_regulators; 138 : Regulators representing the chargers in the form for 139 regulator framework's bulk functions. 140 141char *psy_fuel_gauge; 142 : Power-supply-class name of the fuel gauge. 143 144int (*temperature_out_of_range)(int *mC); 145bool 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 1545. Other Considerations 155======================= 156 157At the charger/battery-related events such as battery-pulled-out, 158charger-pulled-out, charger-inserted, DCIN-over/under-voltage, charger-stopped, 159and others critical to chargers, the system should be configured to wake up. 160At least the following should wake up the system from a suspend: 161a) charger-on/off b) external-power-in/out c) battery-in/out (while charging) 162 163It is usually accomplished by configuring the PMIC as a wakeup source. 164