bindings: Documentation: Add documentation for qpnp-adc-tm nodes

Add snapshot of qpnp-adc-tm driver from msm-4.9
'commit 7e65e03259909 (Merge "msm: kgsl: Deregister gpu
address on memdesc_sg_virt failure")'.

Adc-tm driver provides interface to thermal clients to
set temperature thresholds.

Change-Id: Ifb4d8f4e21fdbf9bdf02e30aafb7b39617c6ca5f

1 files changed, 216 insertions, 0 deletions

diff --git a/bindings/thermal/qpnp-adc-tm.txt b/bindings/thermal/qpnp-adc-tm.txt
new file mode 100644
index 00000000..d3f765ca
--- /dev/null
+++ b/bindings/thermal/qpnp-adc-tm.txt
@@ -0,0 +1,216 @@
+Qualcomm Technologies, Inc. QPNP PMIC thermal monitor ADC driver (VADC_TM)
+
+QPNP PMIC thermal monitoring (TM) provides interface to thermal clients
+to set temperature thresholds and receive notification when the thresholds
+are crossed. A 15 bit ADC is used for measurements. The driver is part
+of the sysfs thermal framework that provides support to read the trip
+points, set threshold for the trip points and enable the trip points.
+Separat kernel api's are provided to usb_id and batt_therm
+to set thresholds and receive threshold notifications.
+
+VADC_TM node
+
+Required properties:
+- compatible : should be "qcom,qpnp-adc-tm-hc" for thermal ADC driver using
+	       refreshed BTM peripheral.
+	       should include "qcom,qpnp-adc-tm-hc-pm5" for PMIC5.
+- reg : offset and length of the PMIC Aribter register map.
+- address-cells : Must be one.
+- size-cells : Must be zero.
+- interrupts : The thermal ADC bank peripheral interrupts for eoc, high and low interrupts.
+- interrupt-names : Should be "eoc-int-en-set", "high-thr-en-set" and "low-thr-en-set"
+		    for qcom,qpnp-adc-tm type.
+		  : Should be "eoc-int-en-set" for qcom,qpnp-adc-tm-hc type.
+- qcom,adc-bit-resolution : Bit resolution of the ADC.
+- qcom,adc-vdd-reference : Voltage reference used by the ADC.
+
+The following properties are required in the main node for qcom,qpnp-adc-tm-hc peripheral.
+- qcom,decimation : Should be present for qcom,qpnp-adc-tm-hc peripheral as its common setting
+		    across all the channels. Sampling rate to use for all the channel measurements.
+		    Select from the following unsigned int.
+		    0 : 512
+		    1 : 1K
+		    2 : 2K
+		    3 : 4K
+- qcom,fast-avg-setup : Should be present for qcom,qpnp-adc-tm-hc peripheral as its common setting
+		    across all the channels. Average number of samples to be used for measurement.
+		    Fast averaging provides the option to obtain a single measurement from the ADC
+		    that is an average of multiple samples. The value selected is 2^(value)
+		    Select from the following unsigned int.
+			0 : 1
+			1 : 2
+			2 : 4
+			3 : 8
+			4 : 16
+			5 : 32
+			6 : 64
+			7 : 128
+			8 : 256
+
+Optional properties:
+- qcom,thermal-node : If present a thermal node is created and the channel is registered as
+		part of the thermal sysfs which allows clients to use the thermal framework
+		to set temperature thresholds and receive notification when the temperature
+		crosses a set threshold, read temperature and enable/set trip types supported
+		by the thermal framework.
+- qcom,meas-interval-timer-idx: If present select from the following timer index to choose
+		a preset configurable measurement interval timer value. The driver defaults
+		to timer 2 with a measurement interval of 1 second if the property is not present.
+		0 : Select Timer 1 for a measurement polling interval of 3.9 milliseconds.
+		1 : Select Timer 2 for a measurement polling interval of 1 second.
+		2 : Select Timer 3 for a measurement polling interval of 4 seconds.
+- qcom,adc-tm-recalib-check: Add this property to check if recalibration required due to inaccuracy.
+- hkadc_ldo-supply : Add this property if VADC needs to perform a Software Vote for the HKADC.
+- hkadc_ok-supply : Add this property if the VADC needs to perform a Software vote for the HKADC VREG_OK.
+- #thermal-sensor-cells : To register ADC sensors with of_thermal. Should be 1.
+  See ./thermal.txt for a description.
+
+Client required property:
+- qcom,<consumer name>-adc_tm : The phandle to the corresponding adc_tm device.
+			The consumer name passed to the driver when calling
+			qpnp_get_adc_tm() is used to associate the client
+			with the corresponding device.
+
+Channel nodes
+NOTE: Atleast one Channel node is required.
+
+Required properties:
+- label : Channel name used for sysfs entry.
+- reg : AMUX channel number.
+- qcom,decimation : Sampling rate to use for the individual channel measurement.
+		    Select from the following unsigned int.
+		    0 : 512
+		    1 : 1K
+		    2 : 2K
+		    3 : 4K
+		    Note: This property is not required in the channel node in qcom,qpnp-adc-tm-hc
+		    peripheral.
+- qcom,pre-div-channel-scaling : Pre-div used for the channel before the signal is being measured.
+				 Select from the following unsigned int for the corresponding
+				 numerator/denominator pre-div ratio.
+				 0 : pre-div ratio of {1, 1}
+				 1 : pre-div ratio of {1, 3}
+				 2 : pre-div ratio of {1, 4}
+				 3 : pre-div ratio of {1, 6}
+				 4 : pre-div ratio of {1, 20}
+				 5 : pre-div ratio of {1, 8}
+				 6 : pre-div ratio of {10, 81}
+				 7 : pre-div ratio of {1, 10}
+- qcom,calibration-type : Reference voltage to use for channel calibration.
+			  Channel calibration is dependendent on the channel.
+			  Certain channels like XO_THERM, BATT_THERM use ratiometric
+			  calibration. Most other channels fall under absolute calibration.
+			  Select from the following strings.
+			  "absolute" : Uses the 625mv and 1.25V reference channels.
+			  "ratiometric" : Uses the reference Voltage/GND for calibration.
+- qcom,scale-function : Reverse scaling function used to convert raw ADC code to units specific to
+			a given channel.
+			Select from the following unsigned int.
+			0 : Scaling to convert voltage in uV to raw adc code.
+			1 : Scaling to convert decidegC to raw adc code.
+			2 : Scaling for converting USB_ID reverse scaling.
+			3 : Scaling to convert milldegC to raw ADC code.
+			4 : Scaling to convert smb_batt_therm values to raw ADC code.
+			5 : Scaling to perform reverse calibration for absolute voltage from uV
+			    to raw ADC code.
+			6 : Scaling to convert qrd skuh battery decidegC to raw ADC code.
+- qcom,hw-settle-time : Settling period for the channel before ADC read.
+			Select from the following unsigned int.
+			0 : 0us
+			1 : 100us
+			2 : 200us
+			3 : 300us
+			4 : 400us
+			5 : 500us
+			6 : 600us
+			7 : 700us
+			8 : 800us
+			9 : 900us
+			0xa : 1ms
+			0xb : 2ms
+			0xc : 4ms
+			0xd : 6ms
+			0xe : 8ms
+			0xf : 10ms
+- qcom,fast-avg-setup : Average number of samples to be used for measurement. Fast averaging
+			provides the option to obtain a single measurement from the ADC that
+			is an average of multiple samples. The value selected is 2^(value)
+			Select from
+			0 : 1
+			1 : 2
+			2 : 4
+			3 : 8
+			4 : 16
+			5 : 32
+			6 : 64
+			7 : 128
+			8 : 256
+			Note: This property is not required in the channel node in
+			qcom,qpnp-adc-tm-hc peripheral.
+- qcom,btm-channel-number : Depending on the PMIC version, a max of upto 8 BTM channels.
+			    The BTM channel numbers are statically allocated to the
+			    corresponding channel node.
+- qcom,adc_tm-vadc : phandle to the corresponding VADC device to read the ADC channels.
+
+Client device example:
+/* Add to the clients node that needs the ADC_TM channel A/D */
+client_node {
+	qcom,client-adc_tm = <&pm8941_adc_tm>;
+};
+
+Example for "qcom,qpnp-adc-tm-hc" device:
+	/* Main Node */
+	pm8998_adc_tm: vadc@3400 {
+			compatible = "qcom,qpnp-adc-tm-hc";
+			reg = <0x3400 0x100>;
+			#address-cells = <1>;
+			#size-cells = <0>;
+			interrupts = <0x0 0x34 0x0 IRQ_TYPE_EDGE_RISING>;
+			interrupt-names = "eoc-int-en-set";
+			qcom,adc-bit-resolution = <15>;
+			qcom,adc-vdd-reference = <1875>;
+			qcom,adc_tm-vadc = <&pm8998_vadc>;
+			qcom,decimation = <0>;
+			qcom,fast-avg-setup = <0>;
+
+			/* Channel Node to be registered as part of thermal sysfs */
+                        chan@b5 {
+                                label = "msm_therm";
+				reg = <0xb5>;
+                                qcom,pre-div-channel-scaling = <0>;
+                                qcom,calibration-type = "absolute";
+                                qcom,scale-function = <2>;
+                                qcom,hw-settle-time = <0>;
+				qcom,btm-channel-number = <0x70>;
+				qcom,thermal-node;
+                        };
+
+			/* Channel Node */
+			chan@6 {
+				label = "vbat_sns";
+				reg = <6>;
+				qcom,pre-div-channel-scaling = <1>;
+				qcom,calibration-type = "absolute";
+				qcom,scale-function = <3>;
+				qcom,hw-settle-time = <0>;
+				qcom,btm-channel-number = <0x78>;
+			};
+	};
+
+/* Example to register thermal sensor using of_thermal */
+&thermal_zones {
+	msm-therm-adc {
+		polling-delay-passive = <0>;
+		polling-delay = <0>;
+		thermal-sensors = <&pm8998_adc_tm 0xb5>;
+		thermal-governor = "user_space";
+
+		trips {
+			active-config0 {
+				temperature = <65000>;
+				hysteresis = <1000>;
+				type = "passive";
+			};
+		};
+	};
+};