^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) Charger Manager
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) (C) 2011 MyungJoo Ham <myungjoo.ham@samsung.com>, GPL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) Charger Manager provides in-kernel battery charger management that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) requires temperature monitoring during suspend-to-RAM state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) and where each battery may have multiple chargers attached and the userland
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) wants to look at the aggregated information of the multiple chargers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) Charger Manager is a platform_driver with power-supply-class entries.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) An instance of Charger Manager (a platform-device created with Charger-Manager)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) represents an independent battery with chargers. If there are multiple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) batteries with their own chargers acting independently in a system,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) the system may need multiple instances of Charger Manager.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) 1. Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) Charger Manager supports the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) * Support for multiple chargers (e.g., a device with USB, AC, and solar panels)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) A system may have multiple chargers (or power sources) and some of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) they may be activated at the same time. Each charger may have its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) own power-supply-class and each power-supply-class can provide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) different information about the battery status. This framework
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) aggregates charger-related information from multiple sources and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) shows combined information as a single power-supply-class.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) * Support for in suspend-to-RAM polling (with suspend_again callback)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) While the battery is being charged and the system is in suspend-to-RAM,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) we may need to monitor the battery health by looking at the ambient or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) battery temperature. We can accomplish this by waking up the system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) periodically. However, such a method wakes up devices unnecessarily for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) monitoring the battery health and tasks, and user processes that are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) supposed to be kept suspended. That, in turn, incurs unnecessary power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) consumption and slow down charging process. Or even, such peak power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) consumption can stop chargers in the middle of charging
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) (external power input < device power consumption), which not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) only affects the charging time, but the lifespan of the battery.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) Charger Manager provides a function "cm_suspend_again" that can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) used as suspend_again callback of platform_suspend_ops. If the platform
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) requires tasks other than cm_suspend_again, it may implement its own
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) suspend_again callback that calls cm_suspend_again in the middle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) Normally, the platform will need to resume and suspend some devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) that are used by Charger Manager.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) * Support for premature full-battery event handling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) If the battery voltage drops by "fullbatt_vchkdrop_uV" after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) "fullbatt_vchkdrop_ms" from the full-battery event, the framework
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) restarts charging. This check is also performed while suspended by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) setting wakeup time accordingly and using suspend_again.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) * Support for uevent-notify
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) With the charger-related events, the device sends
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) notification to users with UEVENT.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) 2. Global Charger-Manager Data related with suspend_again
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) =========================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) In order to setup Charger Manager with suspend-again feature
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) (in-suspend monitoring), the user should provide charger_global_desc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) with setup_charger_manager(`struct charger_global_desc *`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) This charger_global_desc data for in-suspend monitoring is global
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) as the name suggests. Thus, the user needs to provide only once even
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) if there are multiple batteries. If there are multiple batteries, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) multiple instances of Charger Manager share the same charger_global_desc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) and it will manage in-suspend monitoring for all instances of Charger Manager.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) The user needs to provide all the three entries to `struct charger_global_desc`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) properly in order to activate in-suspend monitoring:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) `char *rtc_name;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) The name of rtc (e.g., "rtc0") used to wakeup the system from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) suspend for Charger Manager. The alarm interrupt (AIE) of the rtc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) should be able to wake up the system from suspend. Charger Manager
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) saves and restores the alarm value and use the previously-defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) alarm if it is going to go off earlier than Charger Manager so that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) Charger Manager does not interfere with previously-defined alarms.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) `bool (*rtc_only_wakeup)(void);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) This callback should let CM know whether
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) the wakeup-from-suspend is caused only by the alarm of "rtc" in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) same struct. If there is any other wakeup source triggered the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) wakeup, it should return false. If the "rtc" is the only wakeup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) reason, it should return true.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) `bool assume_timer_stops_in_suspend;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) if true, Charger Manager assumes that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) the timer (CM uses jiffies as timer) stops during suspend. Then, CM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) assumes that the suspend-duration is same as the alarm length.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) 3. How to setup suspend_again
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) =============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) Charger Manager provides a function "extern bool cm_suspend_again(void)".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) When cm_suspend_again is called, it monitors every battery. The suspend_ops
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) callback of the system's platform_suspend_ops can call cm_suspend_again
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) function to know whether Charger Manager wants to suspend again or not.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) If there are no other devices or tasks that want to use suspend_again
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) feature, the platform_suspend_ops may directly refer to cm_suspend_again
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) for its suspend_again callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) The cm_suspend_again() returns true (meaning "I want to suspend again")
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) if the system was woken up by Charger Manager and the polling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) (in-suspend monitoring) results in "normal".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) 4. Charger-Manager Data (struct charger_desc)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) =============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) For each battery charged independently from other batteries (if a series of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) batteries are charged by a single charger, they are counted as one independent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) battery), an instance of Charger Manager is attached to it. The following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) struct charger_desc elements:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) `char *psy_name;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) The power-supply-class name of the battery. Default is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) "battery" if psy_name is NULL. Users can access the psy entries
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) at "/sys/class/power_supply/[psy_name]/".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) `enum polling_modes polling_mode;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) CM_POLL_DISABLE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) do not poll this battery.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) CM_POLL_ALWAYS:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) always poll this battery.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) CM_POLL_EXTERNAL_POWER_ONLY:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) poll this battery if and only if an external power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) source is attached.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) CM_POLL_CHARGING_ONLY:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) poll this battery if and only if the battery is being charged.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) `unsigned int fullbatt_vchkdrop_ms; / unsigned int fullbatt_vchkdrop_uV;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) If both have non-zero values, Charger Manager will check the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) battery voltage drop fullbatt_vchkdrop_ms after the battery is fully
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) charged. If the voltage drop is over fullbatt_vchkdrop_uV, Charger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) Manager will try to recharge the battery by disabling and enabling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) chargers. Recharge with voltage drop condition only (without delay
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) condition) is needed to be implemented with hardware interrupts from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) fuel gauges or charger devices/chips.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) `unsigned int fullbatt_uV;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) If specified with a non-zero value, Charger Manager assumes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) that the battery is full (capacity = 100) if the battery is not being
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) charged and the battery voltage is equal to or greater than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) fullbatt_uV.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) `unsigned int polling_interval_ms;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) Required polling interval in ms. Charger Manager will poll
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) this battery every polling_interval_ms or more frequently.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) `enum data_source battery_present;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) CM_BATTERY_PRESENT:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) assume that the battery exists.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) CM_NO_BATTERY:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) assume that the battery does not exists.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) CM_FUEL_GAUGE:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) get battery presence information from fuel gauge.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) CM_CHARGER_STAT:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) get battery presence from chargers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) `char **psy_charger_stat;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) An array ending with NULL that has power-supply-class names of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) chargers. Each power-supply-class should provide "PRESENT" (if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) battery_present is "CM_CHARGER_STAT"), "ONLINE" (shows whether an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) external power source is attached or not), and "STATUS" (shows whether
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) the battery is {"FULL" or not FULL} or {"FULL", "Charging",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) "Discharging", "NotCharging"}).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) `int num_charger_regulators; / struct regulator_bulk_data *charger_regulators;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) Regulators representing the chargers in the form for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) regulator framework's bulk functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) `char *psy_fuel_gauge;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) Power-supply-class name of the fuel gauge.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) `int (*temperature_out_of_range)(int *mC); / bool measure_battery_temp;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) This callback returns 0 if the temperature is safe for charging,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) a positive number if it is too hot to charge, and a negative number
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) if it is too cold to charge. With the variable mC, the callback returns
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) the temperature in 1/1000 of centigrade.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) The source of temperature can be battery or ambient one according to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) the value of measure_battery_temp.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) 5. Notify Charger-Manager of charger events: cm_notify_event()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) ==============================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) If there is an charger event is required to notify
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) Charger Manager, a charger device driver that triggers the event can call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) cm_notify_event(psy, type, msg) to notify the corresponding Charger Manager.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) In the function, psy is the charger driver's power_supply pointer, which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) associated with Charger-Manager. The parameter "type"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) is the same as irq's type (enum cm_event_types). The event message "msg" is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) optional and is effective only if the event type is "UNDESCRIBED" or "OTHERS".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) 6. Other Considerations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) =======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) At the charger/battery-related events such as battery-pulled-out,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) charger-pulled-out, charger-inserted, DCIN-over/under-voltage, charger-stopped,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) and others critical to chargers, the system should be configured to wake up.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) At least the following should wake up the system from a suspend:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) a) charger-on/off b) external-power-in/out c) battery-in/out (while charging)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) It is usually accomplished by configuring the PMIC as a wakeup source.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags