diff --git a/bindings/power/supply/qcom/qpnp-qg.txt b/bindings/power/supply/qcom/qpnp-qg.txt new file mode 100644 index 000000000000..f095303c1e2f --- /dev/null +++ b/bindings/power/supply/qcom/qpnp-qg.txt @@ -0,0 +1,506 @@ +Qualcomm Technologies, Inc. QPNP PMIC QGAUGE (QG) Device + +QPNP PMIC QGAUGE device provides the ability to gauge the State-of-Charge +of the battery. It provides an interface to the clients to read various +battery related parameters. + +======================= +Required Node Structure +======================= + +Qgauge device must be described in two level of nodes. The first level +describes the properties of the Qgauge device and the second level +describes the peripherals managed/used of the module. + +==================================== +First Level Node - QGAUGE device +==================================== + +- compatible + Usage: required + Value type: + Definition: Should be "qcom,qpnp-qg" or "qcom,qpnp-qg-lite". + +- qcom,pmic-revid + Usage: required + Value type: + Definition: Should specify the phandle of PMIC revid module. This is + used to identify the PMIC subtype. + +- qcom,qg-vadc + Usage: required + Value type: + Definition: Phandle for the VADC node, it is used for BATT_ID and + BATT_THERM readings. + +- qcom,vbatt-empty-mv + Usage: optional + Value type: + Definition: The battery voltage threshold (in mV) at which the + vbatt-empty interrupt fires. The SOC is forced to 0 + when this interrupt fires. If not specified, the + default value is 3200 mV. + +- qcom,vbatt-empty-cold-mv + Usage: optional + Value type: + Definition: The battery voltage threshold (in mV) at which the + vbatt-empty interrupt fires. This threshold is only + applied at cold temperature specified by + 'qcom,cold-temp-threshold'. The SOC is forced to 0 + when this interrupt fires. If not specified, the + default value is 3000 mV. + +- qcom,vbatt-cutoff-mv + Usage: optional + Value type: + Definition: The battery voltage threshold (in mV) at which the + the Qgauge algorithm converges to 0 SOC. If not specified + the default value is 3400 mV. + +- qcom,vbatt-low-mv + Usage: optional + Value type: + Definition: The battery voltage threshold (in mV) at which the + the VBAT_LOW interrupt fires. Software can take necessary + the action when this interrupt fires. If not specified + the default value is 3500 mV. + +- qcom,vbatt-low-cold-mv + Usage: optional + Value type: + Definition: The battery voltage threshold (in mV) at which the + the VBAT_LOW interrupt fires. The threshold is only + applied at cold temperature specified by + 'qcom,cold-temp-threshold'. Software can take necessary + the action when this interrupt fires. If not specified + the default value is 3800 mV. + +- qcom,qg-iterm-ma + Usage: optional + Value type: + Definition: The battery current (in mA) at which the the QG algorithm + converges the SOC to 100% during charging and can be used to + terminate charging. If not specified, the default value is + 100mA. + +- qcom,delta-soc + Usage: optional + Value type: + Definition: The SOC percentage increase at which the SOC is + periodically reported to the userspace. If not specified, + the value defaults to 1%. + +- qcom,s2-fifo-length + Usage: optional + Value type: + Definition: The total number if FIFO samples which need to be filled up + in S2 state of QG to fire the FIFO DONE interrupt. + Minimum value = 1 Maximum Value = 8. If not specified, + the default value is 5. + +- qcom,s2-acc-length + Usage: optional + Value type: + Definition: The number of distinct V & I samples to be accumulated + in each FIFO in the S2 state of QG. + Minimum Value = 0 Maximum Value = 256. If not specified, + the default value is 128. + +- qcom,s2-acc-interval-ms + Usage: optional + Value type: + Definition: The time (in ms) between each of the V & I samples being + accumulated in FIFO. + Minimum Value = 0 ms Maximum Value = 2550 ms. If not + specified the default value is 100 ms. + +- qcom,ocv-timer-expiry-min + Usage: optional + Value type: + Definition: The maximum time (in minutes) for the QG to transition from + S3 to S2 state. + Minimum Value = 2 min Maximum Value = 30 min. If not + specified the hardware default is set to 14 min. + +- qcom,ocv-tol-threshold-uv + Usage: optional + Value type: + Definition: The OCV detection error tolerance (in uV). The maximum + voltage allowed between 2 VBATT readings in the S3 state + to qualify for a valid OCV. + Minimum Value = 0 uV Maximum Value = 12262 uV Step = 195 uV + +- qcom,s3-entry-fifo-length + Usage: optional + Value type: + Definition: The minimum number if FIFO samples which have to qualify the + S3 IBAT entry threshold (qcom,s3-entry-ibat-ua) for QG + to enter into S3 state. + Minimum Value = 1 Maximum Value = 8. The hardware default + is configured to 3. + +- qcom,s3-entry-ibat-ua + Usage: optional + Value type: + Definition: The battery current (in uA) for the QG to enter into the S3 + state. The QG algorithm enters into S3 if the battery + current is lower than this threshold consecutive for + the FIFO length specified in 'qcom,s3-entry-fifo-length'. + Minimum Value = 0 uA Maximum Value = 155550 uA + Step = 610 uA. + +- qcom,s3-exit-ibat-ua + Usage: optional + Value type: + Definition: The battery current (in uA) for the QG to exit S3 state. + If the battery current is higher than this threshold QG + exists S3 state. + Minimum Value = 0 uA Maximum Value = 155550 uA + Step = 610 uA. + +- qcom,rbat-conn-mohm + Usage: optional + Value type: + Definition: Resistance of the battery connectors in mOhms. + +- qcom,ignore-shutdown-soc-secs + Usage: optional + Value type: + Definition: Time in seconds beyond which shutdown SOC is ignored. + If not specified the default value is 360 secs. + +- qcom,hold-soc-while-full + Usage: optional + Value type: + Definition: A boolean property that when defined holds SOC at 100% when + the battery is full until recharge starts. + +- qcom,linearize-soc + Usage: optional + Value type: + Definition: A boolean property that when defined linearizes SOC when + the SOC drops after charge termination monotonically to + improve the user experience. This is applicable only if + "qcom,hold-soc-while-full" is specified. + +- qcom,cold-temp-threshold + Usage: optional + Value type: + Definition: Temperature threshold in decidegree at which the low + temperature specific configuration as applied. If not + specified, the default value is 0 degree centigrade. + +- qcom,cl-disable + Usage: optional + Value type: + Definition: A boolean property to disable the battery capacity + learning when charging. + +- qcom,cl-feedback-on + Usage: optional + Value type: + Definition: A boolean property to feedback the learned capacity into + the capacity lerning algorithm. This has to be used only if the + property "qcom,cl-disable" is not specified. + +- qcom,cl-max-start-soc + Usage: optional + Value type: + Definition: Battery SOC has to be below or equal to this value at the + start of a charge cycle to start the capacity learning. + If this is not specified, then the default value used + will be 15. Unit is in percentage. + +- qcom,cl-min-start-soc + Usage: optional + Value type: + Definition: Battery SOC has to be above or equal to this value at the + start of a charge cycle to start the capacity learning. + If this is not specified, then the default value used + will be 10. Unit is in percentage. + +- qcom,cl-min-temp + Usage: optional + Value type: + Definition: Lower limit of battery temperature to start the capacity + learning. If this is not specified, then the default value + used will be 150 (15 C). Unit is in decidegC. + +- qcom,cl-max-temp + Usage: optional + Value type: + Definition: Upper limit of battery temperature to start the capacity + learning. If this is not specified, then the default value + used will be 500 (50 C). Unit is in decidegC. + +- qcom,cl-max-increment + Usage: optional + Value type: + Definition: Maximum capacity increment allowed per capacity learning + cycle. If this is not specified, then the default value + used will be 5 (0.5%). Unit is in decipercentage. + +- qcom,cl-max-decrement + Usage: optional + Value type: + Definition: Maximum capacity decrement allowed per capacity learning + cycle. If this is not specified, then the default value + used will be 100 (10%). Unit is in decipercentage. + +- qcom,cl-min-limit + Usage: optional + Value type: + Definition: Minimum limit that the capacity cannot go below in a + capacity learning cycle. If this is not specified, then + the default value is 0. Unit is in decipercentage. + +- qcom,cl-max-limit + Usage: optional + Value type: + Definition: Maximum limit that the capacity cannot go above in a + capacity learning cycle. If this is not specified, then + the default value is 0. Unit is in decipercentage. + +- qcom,cl-min-delta-batt-soc + Usage: optional + Value type: + Definition: Minimum change in battery SOC to qualify for capacity + learning. If this is not specified, then the default + value is 10. Unit is in percentage. + +- qcom,cl-wt-enable + Usage: optional + Value type: + Definition: A boolean property to enable weighted capacity learning + based on change in battery SOC during a charging cycle. + If this is specified, then "qcom,cl-min-start-soc" and + "qcom,cl-max-start-soc" is not used. + +- qcom,esr-disable + Usage: optional + Value type: + Definition: Boolean property to disable ESR estimation. If not defined + ESR estimation stays enabled for charge-cycles. + +- qcom,esr-discharge-enable + Usage: optional + Value type: + Definition: Boolean property to enable ESR estimation during discharge. + Only valid if 'qcom,esr-disable' is not defined. + +- qcom,esr-qual-current-ua + Usage: optional + Value type: + Definition: Minimum current differential in uA to qualify an ESR + reading as valid. If not defined the value defaults + to 130mA. + +- qcom,esr-qual-vbatt-uv + Usage: optional + Value type: + Definition: Minimum vbatt differential in uV to qualify an ESR + reading as valid. If not defined the value defaults + to 7mV. + +- qcom,esr-disable-soc + Usage: optional + Value type: + Definition: Minimum battery SOC below which ESR will not be + attempted by QG. If not defined the value defaults + to 10%. + +- qcom,esr-chg-min-ibat-ua + Usage: optional + Value type: + Definition: Minimun charge current (IBAT) in uA at which ESR will + be attempted. If not specified the default value is + in -450mA. + +- qcom,qg-ext-sns + Usage: optional + Value type: + Definition: Boolean property to support external-rsense based + configuration. + +- qcom,shutdown-temp-diff + Usage: optional + Value type: + Definition: The allowed battery temperature in deci-degree difference + between shutdown and power-on to continue with the shutdown + SOC. If not specified the default value is 6 degrees C (60). + +- qcom,shutdown-soc-threshold + Usage: optional + Value type: + Definition: The SOC difference allowed between PON and SHUTDOWN SOC + for the shutdown SOC to be used. If the difference is + beyond this value the PON SOC is used. + +- qcom,qg-use-s7-ocv + Usage: optional + Value type: + Definition: Boolean property to use S7 for PON OCV. + +- qcom,min-sleep-time-secs + Usage: optional + Value type: + Definition: The minimum sleep time in secs to allow a SOC + jump if there has been a GOOD_OCV. + +- qcom,qg-sys-min-voltage + Usage: optional + Value type: + Definition: The voltage threshold (in mV) which describes the system + minimum voltage as per the hardware recommendation. This + is not used for any configuration but only for calculating + the available power. If this property is not specified, + then the default value used is 2800 mV. + +- qcom,qg-sleep-config + Usage: optional + Value type: bool + Definition: Enables sleep-state configurtion for QG. This + allows configuring the FIFO length, accumulator + interval and the accumulator length when system + enters sleep. + +- qcom,sleep-s2-fifo-length + Usage: optional + Value type: + Definition: The FIFO length to be applied when system enters sleep + while discharging. Takes effect only if + 'qcom,qg-sleep-config' is enabled. the default value + if not specified is 8. + +- qcom,sleep-s2-acc-length + Usage: optional + Value type: + Definition: The accululator length to be applied when system + enters sleep while discharging. Takes effect only if + 'qcom,qg-sleep-config' is enabled. the default value + if not specified is 256. + +- qcom,sleep-s2-acc-intvl-ms + Usage: optional + Value type: + Definition: The accululator count to be applied when system + enters sleep while discharging. Takes effect only if + 'qcom,qg-sleep-config' is enabled. the default value + if not specified is 200ms. + +- qcom,qg-fast-chg-config + Usage: optional + Value type: bool + Definition: Enables fast-charge configurtion for QG. This + allows configuring the FIFO length during + fast charge. + +- qcom,fast-chg-s2-fifo-length + Usage: optional + Value type: + Definition: The FIFO length to be applied when system enters + fast-chargging. Takes effect only if + 'qcom,qg-fast-chg-config' is enabled. The + default value if not specified is 1. + +- qcom,fvss-enable + Usage: optional + Value type: bool + Definition: Enable Filtered Voltage based SOC scaling. + This logic enables SOC scaling to report + 0 at the cutoff voltage. + +- qcom,fvss-vbatt-mv + Usage: optional + Value type: + Definition: Battery voltage threshold at which FVSS is + enabled. Applicable only if 'qcom,fvss-enable' + is set. + +- qcom,multi-profile-load + Usage: optional + Value type: + Definition: A boolean property that when specified indicates that + multiple profile loading needs to be enabled. This requires + multiple battery profiles to be specified for a battery for + proper functionality. + +- qcom,tcss-enable + Usage: optional + Value type: bool + Definition: Enable Termination current based SOC scaling. + This logic enables SOC scaling to report + 100% at the QG termination current defined by + qcom,qg-iterm-ma. + +- qcom,tcss-entry-soc + Usage: optional + Value type: + Definition: SOC threshold at which TCSS starts. The default + value is 90%. This property is valid only if + qcom,tcss-enable is defined. + +- qcom,bass-enable + Usage: optional + Value type: bool + Definition: Enable Battery SOC based SOC scaling. This logic + allows monotonic-SOC scaling at low-temperatures + when there is variation in system-SOC due to + changes in the load. + +========================================================== +Second Level Nodes - Peripherals managed by QGAUGE driver +========================================================== +- reg + Usage: required + Value type: + Definition: Addresses and sizes for the specified peripheral + +- interrupts + Usage: optional + Value type: + Definition: Interrupt mapping as per the interrupt encoding + +- interrupt-names + Usage: optional + Value type: + Definition: Interrupt names. This list must match up 1-to-1 with the + interrupts specified in the 'interrupts' property. + +======== +Example +======== + +pmi632_qg: qpnp,qg { + compatible = "qcom,qpnp-qg"; + qcom,pmic-revid = <&pmi632_revid>; + qcom,qg-vadc = <&pmi632_vadc>; + qcom,vbatt-empty-mv = <3200>; + qcom,vbatt-low-mv = <3500>; + qcom,vbatt-cutoff-mv = <3400>; + qcom,qg-iterm-ma = <100>; + + qcom,qgauge@4800 { + status = "okay"; + reg = <0x4800 0x100>; + interrupts = <0x2 0x48 0x0 IRQ_TYPE_EDGE_BOTH>, + <0x2 0x48 0x1 IRQ_TYPE_EDGE_BOTH>, + <0x2 0x48 0x2 IRQ_TYPE_EDGE_BOTH>, + <0x2 0x48 0x4 IRQ_TYPE_EDGE_BOTH>, + <0x2 0x48 0x5 IRQ_TYPE_EDGE_BOTH>, + <0x2 0x48 0x6 IRQ_TYPE_EDGE_BOTH>; + interrupt-names = "qg-batt-missing", + "qg-vbat-low", + "qg-vbat-empty", + "qg-fifo-done", + "qg-good-ocv", + "qg-fsm-state-chg", + "qg-event"; + }; + + qcom,qg-sdam@b000 { + status = "okay"; + reg = <0xb000 0x100>; + }; +};