Commit | Line | Data |
---|---|---|
151f4e2b | 1 | =============== |
3bb3dbbd | 2 | Charger Manager |
151f4e2b MCC |
3 | =============== |
4 | ||
3bb3dbbd DK |
5 | (C) 2011 MyungJoo Ham <myungjoo.ham@samsung.com>, GPL |
6 | ||
7 | Charger Manager provides in-kernel battery charger management that | |
8 | requires temperature monitoring during suspend-to-RAM state | |
9 | and where each battery may have multiple chargers attached and the userland | |
10 | wants to look at the aggregated information of the multiple chargers. | |
11 | ||
12 | Charger Manager is a platform_driver with power-supply-class entries. | |
13 | An instance of Charger Manager (a platform-device created with Charger-Manager) | |
14 | represents an independent battery with chargers. If there are multiple | |
15 | batteries with their own chargers acting independently in a system, | |
16 | the system may need multiple instances of Charger Manager. | |
17 | ||
18 | 1. Introduction | |
19 | =============== | |
20 | ||
21 | Charger 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 | |
d8755dcf | 35 | periodically. However, such a method wakes up devices unnecessarily for |
3bb3dbbd DK |
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 | ||
d829dc75 CC |
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 | ||
dfeccb12 CC |
56 | * Support for uevent-notify |
57 | With the charger-related events, the device sends | |
58 | notification to users with UEVENT. | |
59 | ||
3bb3dbbd | 60 | 2. Global Charger-Manager Data related with suspend_again |
151f4e2b | 61 | ========================================================= |
3bb3dbbd DK |
62 | In order to setup Charger Manager with suspend-again feature |
63 | (in-suspend monitoring), the user should provide charger_global_desc | |
151f4e2b | 64 | with setup_charger_manager(`struct charger_global_desc *`). |
3bb3dbbd DK |
65 | This charger_global_desc data for in-suspend monitoring is global |
66 | as the name suggests. Thus, the user needs to provide only once even | |
67 | if there are multiple batteries. If there are multiple batteries, the | |
68 | multiple instances of Charger Manager share the same charger_global_desc | |
69 | and it will manage in-suspend monitoring for all instances of Charger Manager. | |
70 | ||
151f4e2b MCC |
71 | The user needs to provide all the three entries to `struct charger_global_desc` |
72 | properly in order to activate in-suspend monitoring: | |
3bb3dbbd | 73 | |
151f4e2b MCC |
74 | `char *rtc_name;` |
75 | The name of rtc (e.g., "rtc0") used to wakeup the system from | |
3bb3dbbd DK |
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 | ||
151f4e2b MCC |
82 | `bool (*rtc_only_wakeup)(void);` |
83 | This callback should let CM know whether | |
3bb3dbbd DK |
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. | |
d829dc75 | 88 | |
151f4e2b MCC |
89 | `bool assume_timer_stops_in_suspend;` |
90 | if true, Charger Manager assumes that | |
d829dc75 CC |
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. | |
151f4e2b | 93 | |
3bb3dbbd DK |
94 | |
95 | 3. How to setup suspend_again | |
96 | ============================= | |
97 | Charger Manager provides a function "extern bool cm_suspend_again(void)". | |
98 | When cm_suspend_again is called, it monitors every battery. The suspend_ops | |
99 | callback of the system's platform_suspend_ops can call cm_suspend_again | |
100 | function to know whether Charger Manager wants to suspend again or not. | |
101 | If there are no other devices or tasks that want to use suspend_again | |
102 | feature, the platform_suspend_ops may directly refer to cm_suspend_again | |
103 | for its suspend_again callback. | |
104 | ||
105 | The cm_suspend_again() returns true (meaning "I want to suspend again") | |
106 | if the system was woken up by Charger Manager and the polling | |
107 | (in-suspend monitoring) results in "normal". | |
108 | ||
109 | 4. Charger-Manager Data (struct charger_desc) | |
110 | ============================================= | |
111 | For each battery charged independently from other batteries (if a series of | |
112 | batteries are charged by a single charger, they are counted as one independent | |
151f4e2b | 113 | battery), an instance of Charger Manager is attached to it. The following |
3bb3dbbd | 114 | |
151f4e2b | 115 | struct charger_desc elements: |
3bb3dbbd | 116 | |
151f4e2b MCC |
117 | `char *psy_name;` |
118 | The power-supply-class name of the battery. Default is | |
ad3d13ee DK |
119 | "battery" if psy_name is NULL. Users can access the psy entries |
120 | at "/sys/class/power_supply/[psy_name]/". | |
121 | ||
151f4e2b MCC |
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 | |
d829dc75 CC |
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 | ||
151f4e2b MCC |
142 | `unsigned int fullbatt_uV;` |
143 | If specified with a non-zero value, Charger Manager assumes | |
ad3d13ee DK |
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 | ||
151f4e2b MCC |
148 | `unsigned int polling_interval_ms;` |
149 | Required polling interval in ms. Charger Manager will poll | |
3bb3dbbd DK |
150 | this battery every polling_interval_ms or more frequently. |
151 | ||
151f4e2b MCC |
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 | |
3bb3dbbd DK |
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 | ||
151f4e2b MCC |
170 | `int num_charger_regulators; / struct regulator_bulk_data *charger_regulators;` |
171 | Regulators representing the chargers in the form for | |
3bb3dbbd DK |
172 | regulator framework's bulk functions. |
173 | ||
151f4e2b MCC |
174 | `char *psy_fuel_gauge;` |
175 | Power-supply-class name of the fuel gauge. | |
3bb3dbbd | 176 | |
151f4e2b MCC |
177 | `int (*temperature_out_of_range)(int *mC); / bool measure_battery_temp;` |
178 | This callback returns 0 if the temperature is safe for charging, | |
3bb3dbbd DK |
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. | |
ad3d13ee DK |
182 | The source of temperature can be battery or ambient one according to |
183 | the value of measure_battery_temp. | |
151f4e2b | 184 | |
3bb3dbbd | 185 | |
dfeccb12 | 186 | 5. Notify Charger-Manager of charger events: cm_notify_event() |
151f4e2b | 187 | ============================================================== |
dfeccb12 CC |
188 | If there is an charger event is required to notify |
189 | Charger Manager, a charger device driver that triggers the event can call | |
190 | cm_notify_event(psy, type, msg) to notify the corresponding Charger Manager. | |
191 | In the function, psy is the charger driver's power_supply pointer, which is | |
192 | associated with Charger-Manager. The parameter "type" | |
193 | is the same as irq's type (enum cm_event_types). The event message "msg" is | |
194 | optional and is effective only if the event type is "UNDESCRIBED" or "OTHERS". | |
195 | ||
196 | 6. Other Considerations | |
3bb3dbbd DK |
197 | ======================= |
198 | ||
199 | At the charger/battery-related events such as battery-pulled-out, | |
200 | charger-pulled-out, charger-inserted, DCIN-over/under-voltage, charger-stopped, | |
201 | and others critical to chargers, the system should be configured to wake up. | |
202 | At least the following should wake up the system from a suspend: | |
203 | a) charger-on/off b) external-power-in/out c) battery-in/out (while charging) | |
204 | ||
205 | It is usually accomplished by configuring the PMIC as a wakeup source. |