android10/kernel/Documentation/devicetree/bindings/power/supply/qcom/qpnp-smbcharger.txt

QPNP SMB Battery Charger

QPNP SMB Charger is a single-cell switching mode battery charger. It can charge
the battery and power the system via the USB and AC adapter input.

The QPNP SMB Charger interfaces via the SPMI bus.

There are six different peripherals adding the following functionality.
Each of these peripherals are implemented as subnodes in the example at the
end of this file.

- qcom,chgr:		Supports charging control and status
			reporting.
- qcom,bat-if:		Battery status reporting such as presence,
			temperature reporting and voltage collapse
			protection.
- qcom,usb-chgpth:	USB charge path detection and input current
			limiting configuration.
- qcom,dc-chgpth:	DC charge path detection and input current
			limiting configuration.
- qcom,chg-misc:	Miscellaneous features such as watchdog timers
			and SYSOK pin control
- qcom,chg-otg:		OTG configuration control.

Parent node required properties:
- compatible:		Must be "qcom,qpnp-smbcharger"
- #address-cells:	Must be <1>
- #size-cells:		Must be <1>
- qcom,pmic-revid:      Should specify the phandle of PMIC
                        revid module. This is used to identify
                        the PMIC subtype.



Sub node required properties:
- reg:			The SPMI address for this peripheral
- interrupts:		Specifies the interrupt associated with the peripheral.
- interrupt-names:	Specifies the interrupt names for the peripheral. Every
			available interrupt needs to have an associated name
			with it to indentify its purpose.

			The following lists each subnode and their corresponding
			required interrupt names:

			qcom,chgr:
			 - chg-tcc-thr:		Triggers on charge completion.
			 - chg-taper-thr:	Triggers on the taper charge
						transtion.
			 - chg-inhibit:		Notifies on battery voltage
						being too high to resume
						charging.
			 - chg-p2f-thr:		Triggers on transitioning from
						precharge to fastcharge.
			 - chg-rechg-thr:	Triggers on battery voltage
						falling below the resume
						threshold.

			qcom,bat-if:
			 - batt-hot:		Triggers on battery temperature
						hitting the hot threshold.
						Charging stops.
			 - batt-warm:		Triggers on battery temperature
						hitting the warm threshold.
						Charging current is reduced.
			 - batt-cool:		Triggers on battery temperature
						hitting the cool threshold.
						Charging current is reduced
			 - batt-cold:		Triggers on battery temperature
						hitting the cold threshold.
						Charging stops.
			 - batt-missing:	Battery missing status
						interrupt.
			 - batt-low:		Triggers on battery voltage
						falling across a low threshold.

			qcom,usb-chgpth:
			 - usbin-uv:		USB input voltage falls below a
						valid threshold.
			 - usbin-src-det:	USB automatic source detection
						finishes.

			qcom,dc-chgpth:
			 - dcin-uv:		DC input voltage falls below a
						valid threshold.

			qcom,chgr-misc:
			 - wdog-timeout-mins:	Charger watchdog timer
						interrupt.
			 - temp-shutdown:	Triggers when charger goes
						overtemp and causes a shutdown.
			 - power-ok:		Triggers when the charger
						switcher turns on or off.

Regulator Subnodes:
- qcom,smbcharger-boost-otg	A subnode for a regulator device that turns on
				the charger boost for OTG operation.
- qcom,smbcharger-external-otg	A subnode for a regulator device that switches
				off charging and the USB input charge path
				in order to allow an external regulator to
				operate. This can be used in place of the
				qcom,smbcharger-boost-otg if an external boost
				is available.

Regulator Sub node required properties:
- regulator-name		A name string for the regulator in question

Optional Properties:
- qcom,battery-psy-name		The name of the main battery power supply that
				the charger will register. Failing to define
				this property will default the name to
				"battery".
- qcom,bms-psy-name		The psy name to use for reporting battery
				capacity. If left unspecified the capacity uses
				a preprogrammed default value of 50.
- qcom,float-voltage-mv		Float Voltage in mV - the maximum voltage up
				to which the battery is charged. Supported
				range 3600mV to 4500mV
- qcom,float-voltage-comp	Specifies the JEITA float voltage compensation.
				Value ranges from 0 to 63.
- qcom,fastchg-current-ma	Specifies the fast charge current in mA. Supported
				range is from 300mA to 3000mA.
- qcom,fastchg-current-comp	Specifies the fast charge current compensation in
				mA. Supported values are 250, 700, 900 and 1200mA.
- qcom,charging-timeout-mins	Maximum duration in minutes that a single
				charge cycle may last.  Supported values are:
				0, 192, 384, 768, and 1536.  A value of 0
				means that no charge cycle timeout is used and
				charging can continue indefinitely.
- qcom,precharging-timeout-mins	Maximum duration in minutes that a single
				precharge cycle may last.  Supported values
				are: 0, 24, 48, 96, 192.  A value of 0 means
				that no precharge cycle timeout is used and
				charging can continue indefinitely. Note that
				the qcom,charging-timeout-mins property must
				be specified in order for this to take effect.
- qcom,dc-psy-type		The type of charger connected to the DC path.
				Can be "Mains", "Wireless" or "Wipower"
- qcom,dc-psy-ma		The current in mA dc path can support. Must be
				specified if dc-psy-type is specified. Valid
				range 300mA to 2000mA.
- qcom,dcin-vadc		The phandle to pmi8994 voltage adc. The ADC is
				used to get notifications when the DCIN voltage
				crosses a programmed min/max threshold. This is
				used to make configurations for optimized power
				draw for Wipower.
- qcom,wipower-div2-ilim-map
- qcom,wipower-pt-ilim-map
- qcom,wipower-default-ilim-map
				Array of 5 elements to indicate the voltage ranges and their corresponding
				current limits. The 5 elements with index [0..4] are:
				[0] => voltage_low in uV
				[1] => voltage_high in uV
				[2] => current limit for pass through in mA
				[3] => current limit for div2 mode dcin low voltage in mA
				[4] => current limit for div2 mode dcin high voltage in mA
				The div2 and pt tables indicate the current limits
				to use when Wipower is operating in divide_by_2 mode
				and pass through mode respectively.
				The default table is used when the voltage ranges
				are beyond the ones specified in the mapping table.
				Note that if dcin-vadc or any of these mapping
				tables are not specified, dynamic dcin input
				is disabled.
- qcom,charging-disabled	Set this if charging should be disabled in the
				build by default.
- qcom,resume-delta-mv		Specifies the minimum voltage drop in
				millivolts below the float voltage that is
				required in order to initiate a new charging
				cycle. Supported values are: 50, 100, 200 and
				300mV.
- qcom,chg-inhibit-en		Boolean that indicates whether the charge inhibit
				feature needs to be enabled. If this is not set,
				charge inhibit feature is disabled by default.
- qcom,chg-inhibit-fg		Indicates if the recharge threshold source has
				to be Fuel gauge ADC. If this is not set, it
				will be analog sensor by default.
- qcom,bmd-algo-disabled	Indicates if the battery missing detection
				algorithm is disabled. If this node is present
				SMB uses the THERM pin for battery missing
				detection.
- qcom,charge-unknown-battery	Boolean that indicates whether an unknown
				battery without a matching profile will be
				charged. If this is not set, if the fuel gauge
				does not recognize the battery based on its
				battery ID, the charger will not start
				charging.
- qcom,bmd-pin-src		A string that indicates the source pin for the
				battery missind detection. This can be either:
				- "bpd_none"
					battery is considered always present
				- "bpd_id"
					battery id pin is used
				- "bpd_thm"
					battery therm pin is used
				- "bpd_thm_id"
					both pins are used (battery is
					considered missing if either pin is
					floating).
- qcom,iterm-ma			Specifies the termination current to indicate
				end-of-charge. Possible values in mA:
				50, 100, 150, 200, 250, 300, 500, 600.
- qcom,iterm-disabled		Disables the termination current feature. This
				is a boolean property.
- otg-parent-supply		A phandle to an external boost regulator for
				OTG if it exists.
- qcom,thermal-mitigation:	Array of input current limit values for
				different system thermal mitigation levels.
				This should be a flat array that denotates the
				maximum charge current in mA for each thermal
				level.
- qcom,rparasitics-uohm:	The parasitic resistance of the board following
				the line from the battery connectors through
				vph_power. This is used to calculate maximum
				available current of the battery.
- qcom,vled-max-uv:		The maximum input voltage of the flash leds.
				This is used to calculate maximum available
				current of the battery.
- qcom,autoadjust-vfloat	A boolean property that when set, makes the
				driver automatically readjust vfloat using the
				fuel gauge ADC readings to make charging more
				accurate.
- qcom,jeita-temp-hard-limit	property when present will enable or disable
				the jeita temperature hard limit based on the
				value 1 or 0. Specify 0 if the jeita temp hard
				limit needs to be disabled. If it is not present,
				jeita temperature hard limit will be based on what
				the bootloader had set earlier.
- qcom,low-volt-dcin:		A boolean property which upon set will enable the
				AICL deglitch configuration dynamically. This needs
				to be set if the DCIN supply is going to be less
				than or equal to 5V.
- qcom,force-aicl-rerun:	A boolean property which upon set will enable the
				AICL rerun by default along with the deglitch time
				configured to long interval (20 ms). Also, specifying
				this property will not adjust the AICL deglitch time
				dynamically for handling the battery over-voltage
				oscillations when the charger is headroom limited.
- qcom,aicl-rerun-period-s	If force-aicl-rerun is on, this property dictates
				how often aicl is reran in seconds. Possible values
				are 45, 90, 180, and 360.
- qcom,ibat-ocp-threshold-ua	Maximum current before the battery will trigger
				overcurrent protection. Use the recommended
				battery pack value minus some margin.
- qcom,soft-vfloat-comp-disabled	Set this property when the battery is
					powered via external source and could
					go above the float voltage.
- qcom,parallel-usb-min-current-ma	Minimum current drawn by the primary
					charger before enabling the parallel
					charger if one exists. Do not define
					this property if no parallel chargers
					exist.
- qcom,parallel-usb-9v-min-current-ma	Minimum current drawn by the primary
					charger before enabling the parallel
					charger if one exists. This property
					applies only for 9V chargers.
- qcom,parallel-allowed-lowering-ma	Acceptable current drop from the initial limit
					to keep parallel charger activated. If the
					charger current reduces beyond this threshold
					parallel charger is disabled. Must be specified
					if parallel charger is used.
- qcom,parallel-main-chg-fcc-percent	Percentage of the fast charge current allotted to the
					main charger when parallel charging is enabled and
					operational. If this property is not defined, the
					driver defaults to a 50%/50% split between the main
					and parallel charger.
- qcom,parallel-main-chg-icl-percent	Percentage of the input current allotted to the
					main charger when parallel charging is enabled and
					operational. If this property is not defined, the
					driver defaults to a 60%/40% split between the main
					and parallel charger.
- qcom,battery-data			Points to the phandle of node which
					contains the battery-profiles supported
					by the charger/FG.
- qcom,chg-led-support		A bool property to support the charger led feature.
- qcom,chg-led-sw-controls		A bool property to allow the software to control
					the charger led without a valid charger.
- qcom,skip-usb-notification	A boolean property to be used when usb gets present
				and type from other means. Especially true on
				liquid hardware, where usb presence is detected based on GPIO.
- qcom,skip-usb-suspend-for-fake-battery	A boolean property to skip
						suspending USB path for fake
						battery.
- qcom,vchg_sns-vadc		Phandle of the VADC node.
- qcom,vchg-adc-channel-id	The ADC channel to which the VCHG is routed.
- qcom,max-pulse-allowed	The maximum number of pulses allowed in
				HVDCP3 mode. It can be used to restrict VBUS
				to a value.

Example:
	qcom,qpnp-smbcharger {
		compatible = "qcom,qpnp-smbcharger";
		#address-cells = <1>;
		#size-cells = <1>;

		qcom,iterm-ma = <100>;
		qcom,float-voltage-mv = <4200>;
		qcom,resume-delta-mv = <100>;
		qcom,bmd-pin-src = "bpd_thm_id";
		qcom,dc-psy-type = "Mains";
		qcom,dc-psy-ma = <1500>;
		qcom,bms-psy-name = "bms";
		qcom,battery-psy-name = "battery";
		qcom,thermal-mitigation = <1500 700 600 325>;
		qcom,vchg_sns-vadc = <&pmi8950_vadc>;
		qcom,vchg-adc-channel-id = <3>;

		qcom,chgr@1000 {
			reg = <0x1000 0x100>;
			interrupts =	<0x2 0x10 0x0>,
					<0x2 0x10 0x1>,
					<0x2 0x10 0x2>,
					<0x2 0x10 0x3>,
					<0x2 0x10 0x4>,
					<0x2 0x10 0x5>,
					<0x2 0x10 0x6>,
					<0x2 0x10 0x7>;

			interrupt-names =	"chg-error",
						"chg-inhibit",
						"chg-prechg-sft",
						"chg-complete-chg-sft",
						"chg-p2f-thr",
						"chg-rechg-thr",
						"chg-taper-thr",
						"chg-tcc-thr";
		};

		qcom,otg@1100 {
			reg = <0x1100 0x100>;
		};

		qcom,bat-if@1200 {
			reg = <0x1200 0x100>;
			interrupts =	<0x2 0x12 0x0>,
					<0x2 0x12 0x1>,
					<0x2 0x12 0x2>,
					<0x2 0x12 0x3>,
					<0x2 0x12 0x4>,
					<0x2 0x12 0x5>,
					<0x2 0x12 0x6>,
					<0x2 0x12 0x7>;

			interrupt-names =	"batt-hot",
						"batt-warm",
						"batt-cold",
						"batt-cool",
						"batt-ov",
						"batt-low",
						"batt-missing",
						"batt-term-missing";
		};

		qcom,usb-chgpth@1300 {
			reg = <0x1300 0x100>;
			interrupts =	<0x2 0x13 0x0>,
					<0x2 0x13 0x1>,
					<0x2 0x13 0x2>,
					<0x2 0x13 0x3>,
					<0x2 0x13 0x4>,
					<0x2 0x13 0x5>,
					<0x2 0x13 0x6>;

			interrupt-names =	"usbin-uv",
						"usbin-ov",
						"usbin-src-det",
						"otg-fail",
						"otg-oc",
						"aicl-done",
						"usbid-change";
		};

		qcom,dc-chgpth@1400 {
			reg = <0x1400 0x100>;
			interrupts =	<0x2 0x14 0x0>,
					<0x2 0x14 0x1>;

			interrupt-names =	"dcin-uv",
						"dcin-ov";
		};

		qcom,chgr-misc@1600 {
			reg = <0x1600 0x100>;
			interrupts =	<0x2 0x16 0x0>,
					<0x2 0x16 0x1>,
					<0x2 0x16 0x2>,
					<0x2 0x16 0x3>,
					<0x2 0x16 0x4>,
					<0x2 0x16 0x5>;

			interrupt-names =	"power-ok",
						"temp-shutdown",
						"wdog-timeout",
						"flash-fail",
						"otst2",
						"otst3";
		};
	};