0001 ===============
0002 Charger Manager
0003 ===============
0004
0005 (C) 2011 MyungJoo Ham <myungjoo.ham@samsung.com>, GPL
0006
0007 Charger Manager provides in-kernel battery charger management that
0008 requires temperature monitoring during suspend-to-RAM state
0009 and where each battery may have multiple chargers attached and the userland
0010 wants to look at the aggregated information of the multiple chargers.
0011
0012 Charger Manager is a platform_driver with power-supply-class entries.
0013 An instance of Charger Manager (a platform-device created with Charger-Manager)
0014 represents an independent battery with chargers. If there are multiple
0015 batteries with their own chargers acting independently in a system,
0016 the system may need multiple instances of Charger Manager.
0017
0018 1. Introduction
0019 ===============
0020
0021 Charger Manager supports the following:
0022
0023 * Support for multiple chargers (e.g., a device with USB, AC, and solar panels)
0024 A system may have multiple chargers (or power sources) and some of
0025 they may be activated at the same time. Each charger may have its
0026 own power-supply-class and each power-supply-class can provide
0027 different information about the battery status. This framework
0028 aggregates charger-related information from multiple sources and
0029 shows combined information as a single power-supply-class.
0030
0031 * Support for in suspend-to-RAM polling (with suspend_again callback)
0032 While the battery is being charged and the system is in suspend-to-RAM,
0033 we may need to monitor the battery health by looking at the ambient or
0034 battery temperature. We can accomplish this by waking up the system
0035 periodically. However, such a method wakes up devices unnecessarily for
0036 monitoring the battery health and tasks, and user processes that are
0037 supposed to be kept suspended. That, in turn, incurs unnecessary power
0038 consumption and slow down charging process. Or even, such peak power
0039 consumption can stop chargers in the middle of charging
0040 (external power input < device power consumption), which not
0041 only affects the charging time, but the lifespan of the battery.
0042
0043 Charger Manager provides a function "cm_suspend_again" that can be
0044 used as suspend_again callback of platform_suspend_ops. If the platform
0045 requires tasks other than cm_suspend_again, it may implement its own
0046 suspend_again callback that calls cm_suspend_again in the middle.
0047 Normally, the platform will need to resume and suspend some devices
0048 that are used by Charger Manager.
0049
0050 * Support for premature full-battery event handling
0051 If the battery voltage drops by "fullbatt_vchkdrop_uV" after
0052 "fullbatt_vchkdrop_ms" from the full-battery event, the framework
0053 restarts charging. This check is also performed while suspended by
0054 setting wakeup time accordingly and using suspend_again.
0055
0056 * Support for uevent-notify
0057 With the charger-related events, the device sends
0058 notification to users with UEVENT.
0059
0060 2. Global Charger-Manager Data related with suspend_again
0061 =========================================================
0062 In order to setup Charger Manager with suspend-again feature
0063 (in-suspend monitoring), the user should provide charger_global_desc
0064 with setup_charger_manager(`struct charger_global_desc *`).
0065 This charger_global_desc data for in-suspend monitoring is global
0066 as the name suggests. Thus, the user needs to provide only once even
0067 if there are multiple batteries. If there are multiple batteries, the
0068 multiple instances of Charger Manager share the same charger_global_desc
0069 and it will manage in-suspend monitoring for all instances of Charger Manager.
0070
0071 The user needs to provide all the three entries to `struct charger_global_desc`
0072 properly in order to activate in-suspend monitoring:
0073
0074 `char *rtc_name;`
0075 The name of rtc (e.g., "rtc0") used to wakeup the system from
0076 suspend for Charger Manager. The alarm interrupt (AIE) of the rtc
0077 should be able to wake up the system from suspend. Charger Manager
0078 saves and restores the alarm value and use the previously-defined
0079 alarm if it is going to go off earlier than Charger Manager so that
0080 Charger Manager does not interfere with previously-defined alarms.
0081
0082 `bool (*rtc_only_wakeup)(void);`
0083 This callback should let CM know whether
0084 the wakeup-from-suspend is caused only by the alarm of "rtc" in the
0085 same struct. If there is any other wakeup source triggered the
0086 wakeup, it should return false. If the "rtc" is the only wakeup
0087 reason, it should return true.
0088
0089 `bool assume_timer_stops_in_suspend;`
0090 if true, Charger Manager assumes that
0091 the timer (CM uses jiffies as timer) stops during suspend. Then, CM
0092 assumes that the suspend-duration is same as the alarm length.
0093
0094
0095 3. How to setup suspend_again
0096 =============================
0097 Charger Manager provides a function "extern bool cm_suspend_again(void)".
0098 When cm_suspend_again is called, it monitors every battery. The suspend_ops
0099 callback of the system's platform_suspend_ops can call cm_suspend_again
0100 function to know whether Charger Manager wants to suspend again or not.
0101 If there are no other devices or tasks that want to use suspend_again
0102 feature, the platform_suspend_ops may directly refer to cm_suspend_again
0103 for its suspend_again callback.
0104
0105 The cm_suspend_again() returns true (meaning "I want to suspend again")
0106 if the system was woken up by Charger Manager and the polling
0107 (in-suspend monitoring) results in "normal".
0108
0109 4. Charger-Manager Data (struct charger_desc)
0110 =============================================
0111 For each battery charged independently from other batteries (if a series of
0112 batteries are charged by a single charger, they are counted as one independent
0113 battery), an instance of Charger Manager is attached to it. The following
0114
0115 struct charger_desc elements:
0116
0117 `char *psy_name;`
0118 The power-supply-class name of the battery. Default is
0119 "battery" if psy_name is NULL. Users can access the psy entries
0120 at "/sys/class/power_supply/[psy_name]/".
0121
0122 `enum polling_modes polling_mode;`
0123 CM_POLL_DISABLE:
0124 do not poll this battery.
0125 CM_POLL_ALWAYS:
0126 always poll this battery.
0127 CM_POLL_EXTERNAL_POWER_ONLY:
0128 poll this battery if and only if an external power
0129 source is attached.
0130 CM_POLL_CHARGING_ONLY:
0131 poll this battery if and only if the battery is being charged.
0132
0133 `unsigned int fullbatt_vchkdrop_ms; / unsigned int fullbatt_vchkdrop_uV;`
0134 If both have non-zero values, Charger Manager will check the
0135 battery voltage drop fullbatt_vchkdrop_ms after the battery is fully
0136 charged. If the voltage drop is over fullbatt_vchkdrop_uV, Charger
0137 Manager will try to recharge the battery by disabling and enabling
0138 chargers. Recharge with voltage drop condition only (without delay
0139 condition) is needed to be implemented with hardware interrupts from
0140 fuel gauges or charger devices/chips.
0141
0142 `unsigned int fullbatt_uV;`
0143 If specified with a non-zero value, Charger Manager assumes
0144 that the battery is full (capacity = 100) if the battery is not being
0145 charged and the battery voltage is equal to or greater than
0146 fullbatt_uV.
0147
0148 `unsigned int polling_interval_ms;`
0149 Required polling interval in ms. Charger Manager will poll
0150 this battery every polling_interval_ms or more frequently.
0151
0152 `enum data_source battery_present;`
0153 CM_BATTERY_PRESENT:
0154 assume that the battery exists.
0155 CM_NO_BATTERY:
0156 assume that the battery does not exists.
0157 CM_FUEL_GAUGE:
0158 get battery presence information from fuel gauge.
0159 CM_CHARGER_STAT:
0160 get battery presence from chargers.
0161
0162 `char **psy_charger_stat;`
0163 An array ending with NULL that has power-supply-class names of
0164 chargers. Each power-supply-class should provide "PRESENT" (if
0165 battery_present is "CM_CHARGER_STAT"), "ONLINE" (shows whether an
0166 external power source is attached or not), and "STATUS" (shows whether
0167 the battery is {"FULL" or not FULL} or {"FULL", "Charging",
0168 "Discharging", "NotCharging"}).
0169
0170 `int num_charger_regulators; / struct regulator_bulk_data *charger_regulators;`
0171 Regulators representing the chargers in the form for
0172 regulator framework's bulk functions.
0173
0174 `char *psy_fuel_gauge;`
0175 Power-supply-class name of the fuel gauge.
0176
0177 `int (*temperature_out_of_range)(int *mC); / bool measure_battery_temp;`
0178 This callback returns 0 if the temperature is safe for charging,
0179 a positive number if it is too hot to charge, and a negative number
0180 if it is too cold to charge. With the variable mC, the callback returns
0181 the temperature in 1/1000 of centigrade.
0182 The source of temperature can be battery or ambient one according to
0183 the value of measure_battery_temp.
0184
0185
0186 5. Notify Charger-Manager of charger events: cm_notify_event()
0187 ==============================================================
0188 If there is an charger event is required to notify
0189 Charger Manager, a charger device driver that triggers the event can call
0190 cm_notify_event(psy, type, msg) to notify the corresponding Charger Manager.
0191 In the function, psy is the charger driver's power_supply pointer, which is
0192 associated with Charger-Manager. The parameter "type"
0193 is the same as irq's type (enum cm_event_types). The event message "msg" is
0194 optional and is effective only if the event type is "UNDESCRIBED" or "OTHERS".
0195
0196 6. Other Considerations
0197 =======================
0198
0199 At the charger/battery-related events such as battery-pulled-out,
0200 charger-pulled-out, charger-inserted, DCIN-over/under-voltage, charger-stopped,
0201 and others critical to chargers, the system should be configured to wake up.
0202 At least the following should wake up the system from a suspend:
0203 a) charger-on/off b) external-power-in/out c) battery-in/out (while charging)
0204
0205 It is usually accomplished by configuring the PMIC as a wakeup source.
