|
| 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 | +enum polling_modes polling_mode; |
| 102 | + : CM_POLL_DISABLE: do not poll this battery. |
| 103 | + CM_POLL_ALWAYS: always poll this battery. |
| 104 | + CM_POLL_EXTERNAL_POWER_ONLY: poll this battery if and only if |
| 105 | + an external power source is attached. |
| 106 | + CM_POLL_CHARGING_ONLY: poll this battery if and only if the |
| 107 | + battery is being charged. |
| 108 | + |
| 109 | +unsigned int polling_interval_ms; |
| 110 | + : Required polling interval in ms. Charger Manager will poll |
| 111 | + this battery every polling_interval_ms or more frequently. |
| 112 | + |
| 113 | +enum data_source battery_present; |
| 114 | + CM_FUEL_GAUGE: get battery presence information from fuel gauge. |
| 115 | + CM_CHARGER_STAT: get battery presence from chargers. |
| 116 | + |
| 117 | +char **psy_charger_stat; |
| 118 | + : An array ending with NULL that has power-supply-class names of |
| 119 | + chargers. Each power-supply-class should provide "PRESENT" (if |
| 120 | + battery_present is "CM_CHARGER_STAT"), "ONLINE" (shows whether an |
| 121 | + external power source is attached or not), and "STATUS" (shows whether |
| 122 | + the battery is {"FULL" or not FULL} or {"FULL", "Charging", |
| 123 | + "Discharging", "NotCharging"}). |
| 124 | + |
| 125 | +int num_charger_regulators; |
| 126 | +struct regulator_bulk_data *charger_regulators; |
| 127 | + : Regulators representing the chargers in the form for |
| 128 | + regulator framework's bulk functions. |
| 129 | + |
| 130 | +char *psy_fuel_gauge; |
| 131 | + : Power-supply-class name of the fuel gauge. |
| 132 | + |
| 133 | +int (*temperature_out_of_range)(int *mC); |
| 134 | + : This callback returns 0 if the temperature is safe for charging, |
| 135 | + a positive number if it is too hot to charge, and a negative number |
| 136 | + if it is too cold to charge. With the variable mC, the callback returns |
| 137 | + the temperature in 1/1000 of centigrade. |
| 138 | +}; |
| 139 | + |
| 140 | +5. Other Considerations |
| 141 | +======================= |
| 142 | + |
| 143 | +At the charger/battery-related events such as battery-pulled-out, |
| 144 | +charger-pulled-out, charger-inserted, DCIN-over/under-voltage, charger-stopped, |
| 145 | +and others critical to chargers, the system should be configured to wake up. |
| 146 | +At least the following should wake up the system from a suspend: |
| 147 | +a) charger-on/off b) external-power-in/out c) battery-in/out (while charging) |
| 148 | + |
| 149 | +It is usually accomplished by configuring the PMIC as a wakeup source. |
0 commit comments