Commit | Line | Data |
---|---|---|
3bb3dbbd DK |
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 | ||
ad3d13ee DK |
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 | ||
3bb3dbbd DK |
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 | ||
ad3d13ee DK |
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 | ||
3bb3dbbd DK |
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); | |
ad3d13ee | 145 | bool measure_battery_temp; |
3bb3dbbd DK |
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. | |
ad3d13ee DK |
150 | The source of temperature can be battery or ambient one according to |
151 | the value of measure_battery_temp. | |
3bb3dbbd DK |
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. |