diff options
author | Donggeun Kim <dg77.kim@samsung.com> | 2011-12-27 04:47:48 -0500 |
---|---|---|
committer | Anton Vorontsov <cbouatmailru@gmail.com> | 2012-01-03 23:08:27 -0500 |
commit | 3bb3dbbd56ea39e5537db8f8041ea95d28f16a7f (patch) | |
tree | b660ceed66ef404530109f9670b63640bd2be4b6 /Documentation/power | |
parent | 00a159a5567232fbe1dd85bc611c55f53943b0fc (diff) |
power_supply: Add initial Charger-Manager driver
Because battery health monitoring should be done even when suspended,
it needs to wake up and suspend periodically. Thus, userspace battery
monitoring may incur too much overhead; every device and task is woken
up periodically. Charger Manager uses suspend-again to provide
in-suspend monitoring.
This patch allows to monitor battery health in-suspend state.
Signed-off-by: Donggeun Kim <dg77.kim@samsung.com>
Signed-off-by: MyungJoo Ham <myungjoo.ham@samsung.com>
Signed-off-by: Kyungmin Park <kyungmin.park@samsung.com>
Signed-off-by: Anton Vorontsov <cbouatmailru@gmail.com>
Diffstat (limited to 'Documentation/power')
-rw-r--r-- | Documentation/power/charger-manager.txt | 149 |
1 files changed, 149 insertions, 0 deletions
diff --git a/Documentation/power/charger-manager.txt b/Documentation/power/charger-manager.txt new file mode 100644 index 000000000000..081489f3db25 --- /dev/null +++ b/Documentation/power/charger-manager.txt | |||
@@ -0,0 +1,149 @@ | |||
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. | ||