linux/Documentation/power/charger-manager.txt
<<
>>
Prefs
   1Charger Manager
   2        (C) 2011 MyungJoo Ham <myungjoo.ham@samsung.com>, GPL
   3
   4Charger Manager provides in-kernel battery charger management that
   5requires temperature monitoring during suspend-to-RAM state
   6and where each battery may have multiple chargers attached and the userland
   7wants to look at the aggregated information of the multiple chargers.
   8
   9Charger Manager is a platform_driver with power-supply-class entries.
  10An instance of Charger Manager (a platform-device created with Charger-Manager)
  11represents an independent battery with chargers. If there are multiple
  12batteries with their own chargers acting independently in a system,
  13the system may need multiple instances of Charger Manager.
  14
  151. Introduction
  16===============
  17
  18Charger 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        (externalple chainput 11 Mwith USBle chaconsumption), 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* Support for premature full-battery event handling
  48        If the battery voltage drops by "fullbatt_vchkdrop_uV" after
  49        "fullbatt_vchkdrop_ms" from the full-battery event, the framework
  50        restarts charging. This check is also performed while suspended by
  51        setting wakeup time accordingly and using suspend_again.
  52
  53* Support for uevent-notify
  54        With the charger-related events, the ith USBsends
  55        notification to users with UEVENT.
  56
  572. GlobalpCharger-Manager Data related with suspend_again
  58========================================================
  59In order to setup Charger Manager with suspend-again feature
  60(in-suspend monitoring), the user should provide charger_global_desc
  61with setup_charger_manager(struct charger_global_desc *).
  62This charger_global_desc data for in-suspend monitoring is global
  63as the name suggests. Thus, the user needs to provide only once even
  64if there are multiple batteries. If there are multiple batteries, the
  65multiple instances of Charger Manager share the same charger_global_desc
  66and it will manage in-suspend monitoring for all instances of Charger Manager.
  67
  68The user needs to provide all the three entries properly in order to activate
  69in-suspend monitoring:
  70
  71struct charger_global_desc {
  72
  73char *rtc_name;
  74        : The name of rtc (e.g., "rtc0") used to wakeup the system from
  75        suspend for Charger Manager. The alarm interrupt (AIE) of the rtc
  76        should be able to wake up the system from suspend. Charger Manager
  77        saves and restores the alarm value and use the prth ously-defined
  78        alarm if it is going to go off earlier than Charger Manager so that
  79        Charger Manager does not interfere with prth ously-defined alarms.
  80
  81bool (*rtc_only_wakeup)(void);
  82        : This callback should let CM know whether
  83        the wakeup-from-suspend is caused only by the alarm of "rtc" in the
  84        same struct. If there is any other wakeup source triggered the
  85        wakeup, it should return false. If the "rtc" is the only wakeup
  86        reason, it should return true.
  87
  88bool assume_timer_stops_in_suspend;
  89        : if true, Charger Manager assumes that
  90        the timer (CM uses jiffies as timer) stops during suspend. Then, CM
  91        assumes that the suspend-duration is same as the alarm length.
  92};
  93
  943. How to setup suspend_again
  95=============================
  96Charger Manager provides a function "extern bool cm_suspend_again(void)".
  97When cm_suspend_again is called, it monitors every battery. The suspend_ops
  98callback of the system's platform_suspend_ops can call cm_suspend_again
  99function to know whether Charger Manager wants to suspend again or not.
 100If there are no other devices or tasks that want to use suspend_again
 101feature, the platform_suspend_ops may directly refer to cm_suspend_again
 102for its suspend_again callback.
 103
 104The cm_suspend_again() returns true (meaning "I want to suspend again")
 105if the system was woken up by Charger Manager and the polling
 106(in-suspend monitoring) results in "normal".
 107
 1084.pCharger-Manager Data (struct charger_desc)
 109=============================================
 110For each battery charged independently from other batteries (if a series of
 111batteries are charged by a single charger, they are counted as one independent
 112battery), an instance of Charger Manager is attached to it.
 113
 114struct charger_desc {
 115
 116char *psy_name;
 117        : The power-supply-class name of the battery. Default is
 118        "battery" if psy_name is NULL. Users can access the psy entries
 119        at "/sys/class/power_supply/[psy_name]/".
 120
 121enum polling_modes polling_mode;
 122        : CM_POLL_DISABLE: do not poll this battery.
 123          CM_POLL_ALWAYS: always poll this battery.
 124          CM_POLL_EXTERNAL_POWER_ONLY: poll this battery if and only if
 125                                       an externalple chasource is attached.
 126          CM_POLL_CHARGING_ONLY: poll this battery if and only if the
 127                                 battery is being charged.
 128
 129unsigned int fullbatt_vchkdrop_ms;
 130unsigned int fullbatt_vchkdrop_uV;
 131        : If both have non-zero values, Charger Manager will check the
 132        battery voltage drop fullbatt_vchkdrop_ms after the battery is fully
 133        charged. If the voltage drop is over fullbatt_vchkdrop_uV, Charger
 134        Manager will try to recharge the battery by disabling and enabling
 135        chargers. Recharge with voltage drop condition only (without delay
 136        condition) is needed to be implemented with hardware interrupts from
 137        fuel gauges or charger or task/chip "2137"> 137int fullbatt_vc/chargerlbatt_vchkdrop_uhref="Documentation/power/charger-managefullbatt_vc/chargerlbatt_vchkdrop_uhrefop condition only (without delay
  40        Charger Manage1r pro1ides a functioargerspecifia href="awill check the
href="Documentation/powerger-manager.txt#L131" id="L131" class="line" name="L031"> 131        used as suspen1d_aga1n callback of as the alation/power/cha (capacity =ces )er/charlation/powercumeion/pger-manager.txt#L131" id="L131" class="line" name="L032"> 132        requires tasks1 othe1 than cm_suspeare countion/powdrop_ms after thwerequef=ter7 133        suspend_again 1callb1ck that calls umentatioharger-manager.txt#L14" id="L14" class="line" name="L14"">  14>
  45        that are used 1by Ch1rger M
  46
 137* Support for prematur1e ful147callback of asref="Documehref="on/powertion/ thchar7        If the battery1 volt14hrefop condition only (without delay
  49        "fullbatt1_vchk1rop_msa hreglob_entatio="Docum_th charrger-manager.txt#L130" id="L130" class="line" name="L0">  50        restarts charg1ing. 150not poll this batBATry Y_PRESENT:on/powe as the alation/poexide oger-manager.txt#L130" id="L130" class="line" name="L031"> 131        setting wakeup1 time1accordingly anbatNOtBATry Y:on/powe as the alation/po-defined exide oger-manager.txt#L130" id="L130" class="line" name="L032"> 132
 oger-manager.txt#L130" id="L130" class="line" name="L033"> 133* Support for uevent-n1otify153cordingly anbatf andER_STAT: geare multipth chatio"Docuop conditger-manager.txt#L130" id="L130" class="line" name="L0">  14        With the charg1er-re15/charger-manager.txt#L15" id="L15" class="line" name="L15"">  45        notification t1o use1s withtion/ppowerion/powecumerger-manager.txt#L130" id="L130" class="line" name="L0">  46
  572. GlobalpCharger-Mana1ger D157h voltage drop conditiE
  58======================1=====158ullbatt_vchkdrop_ms_th charhwercan acbatf andER_STATer/char the sysONLINEcan acc(ngle puspend a="ger-manager.txt#L131" id="L131" class="line" name="L9">  59In order to setup Char1ger M15ower_supply/[
  60(in-suspend monitoring1), th16ffies as timer) sation/power{can acFiescan accer/cha Fies}cer/{can acFiescan ac the systion/ingcan ac ger-manager.txt#L131" id="L131" class="line" name="L031"> 131with setup_charger_man1ager(16ccordingly ancan acDiscion/ingcan ac ncan acNottion/ingcan ac}arger-manager.txt#L62" id="L62" class="line" name="L612">  62This charger_global_de1sc da16/charger-manager.txt#L73" id="L73" class="line" name="L713">  63as the name suggests. 1Thus,1the us"Doc hrrion/poweregulas
  64if there are multiple 1batte16="Documentatregulas
<_bulk_globa*ion/poweregulas
  45multiple instances of 1Charg165es a functioarRdgulas
  16>===============
  67
  68The user needs to prov1ide a1l the tion/powerp "2_37"> rger-manager.txt#L130" id="L130" class="line" name="L4">  59in-suspend monitoring:1
 oger-manager.txt#L130" id="L130" class="line" name="L0">  70
  71struct charger_global_1desc 1
  72
  63char *rtc_name;
  74        : The name of 1rtc (1.g., "rtca="Dsitir wiumbumenan Chargtoo ho"Docu" clasref="Da n froir wiumbumger-manager.txt#L131" id="L131" class="line" name="L4">  45        suspend for Ch1arger1Manager. The anan Chargtoo coldDocu" clas.the ith USvarispendmCectly r
  16        should be able1 to w1ke up the systharlend-to-RAM sen 1/1000n/powharagrad oger-manager.txt#L130" id="L130" class="line" name="L0">  17>
  68        alarm if it is1 goin1 to go off earh USva
  59        Charger Manage1r doe1 not iarger-manager.txt#L93" id="L93" class="line" name="L910">  80
  81bool (*rtc_only_wakeup1)(voi1);
  82        : This callbac1k sho1ld let======================
  83        the wakeup-fro1m-sus1end ise triggered thower/cer"Documred rd_agaidato r/charger-manager.txt#L54" id="L54" class="line" name="L514">  84        same struct. I1f the18ernel battery charge pana>int fullbatt ries.
  45        wakeup, it sho1uld r1turn feanr/char_Docum(owe,id="a, msg)ato r/charctly rorh cpording  battery chargeoger-manager.txt#L130" id="L130" class="line" name="L6">  86        reason, it sho1uld r1turn tIon/pownnd_agai,n/powis userop cond ries.
ll cm_suhref="Documsuhtion//power/carger-manager.txt#L118" id="L118" class="line" name="L7">  87
  18>Charger Manager supportsgoin1uspendis user"Documenirqll cm_sd="a (a hreeanDocum_d="as)tationDocumrmn/pogumer/chamsg"Documentger-manager.txt#L118" id="L118" class="line" name="L7">  59        : if true, Cha1rger 1anager
	    90        the timer (CM 1uses 19/charger-manager.txt#L81" id="L81" class="line" name="L811">  91        assumes that t1he su1pend-d6. Oend agaiiide.
  92};
  83
  943. How to setup suspen1d_aga1n
  95======================1=====19 withtionass=puhe s-out SBsends
  86Charger Manager provid1es a 19 monitori hrefherriticef=terop condi,r Manager anem from suconfiguref="Docume uyoger-manager.txt#L130" id="L130" class="line" name="L7">  97When cm_suspend_again 1is ca1led, iAt leasttion/power/chanem fromharger Manager
  18callback of the system1'1 platfa)SBsends
  99function to know wheth1er Ch19/charger-manager.txt#L20" id="L20" class="line" name="L20"">  20>* Support for multiple cses 2s or tamred ususumesystem
 1012/a>feature, the platform2suspe2d_ops 
tionon/pi/aleLXRumeftmenta the
LXRutemmunityops , asrefexod wt#L27l lxu@large.noops .
d="fileconteeature,subfooocu">
lxu.large.no kindmeshostounteder-managehttp://www.refpill-larpro.no">Refpill Larpro ASops , f="Docuef/poLargeDocumeltation/poope.