Qualcomm Technologies, Inc. LPG driver specific bindings

This binding document describes the properties of LPG (Light Pulse Generator)
device module in Qualcomm Technologies, Inc. PMIC chips.

- compatible:
	Usage: required
	Value type: <string>
	Definition: Must be "qcom,pwm-lpg".

- reg:
	Usage: required
	Value type: <u32>
	Definition: Register base for LPG and LUT modules.

- reg-names:
	Usage: required
	Value type: <string>
	Definition: The name of the register defined in the reg property.
		      It must have "lpg-base", "lut-base" is optional but
		      it's required if any LPG channels support LUT mode
		      with a LUT module.

- #pwm-cells:
	Usage: required
	Value type: <u32>
	Definition: The number of cells in "pwms" property specified in
		      PWM user nodes. It should be 2. The first cell is
		      the PWM channel ID indexed from 0, and the second
		      cell is the PWM default period in nanoseconds.

- qcom,num-lpg-channels:
	Usage: required
	Value type: <u32>
	Definition: The number of the consecutive LPG/PWM channels in the chip.

- qcom,pfm-chan-ids:
	Usage: optional
	Value type: <u32 array>
	Definition: 1-indexed channel numbers that support Pulse Frequency
		      Modulation (PFM) in which duty cycle is fixed at 50% and
		      only the period/frequency can be changed. PFM mode will
		      be enabled only if the HW supports it.

- nvmem-names:
	Usage: optional
	Value type: <stringlist>
	Definition: The nvmem device name(s) for the SDAM module(s) where the
		      LUT pattern data is stored. This property is required
		      only when LUT mode is supported with a SDAM module
		      instead of a LUT module. It can take the following
		      mutually exclusive sets of values:
		      (a) "ppg_sdam":
			  LUT pattern data and per-channel data are stored in a
			  single SDAM module.
		      (b) "lut_sdam", "lpg_chan_sdam":
			  LUT pattern data and per-channel data are stored in
			  two different SDAM modules.

- nvmem:
	Usage: optional
	Value type: <phandle-list>
	Definition: Phandle(s) of the nvmem device(s) to access the LUT stored
		      in the SDAM module(s). This property is required only when
		      LUT mode is supported and the LUT pattern is stored in
		      SDAM modules instead of a LUT module.

- qcom,pbs-client
	Usage: optional
	Value type: <phandle>
	Definition: Phandle of the PBS client used for sending the PBS
		      trigger. This property is required when LUT mode is
		      supported and the LUT pattern is stored in a single SDAM
		      module (not two) instead of a LUT module.

- qcom,lut-sdam-base:
	Usage: optional
	Value type: <u32>
	Definition: The register base of the LUT entries stored in SDAM. This
		      property is required only when LUT mode is supported and
		      the LUT pattern is stored in a SDAM module instead of a
		      LUT module.

- qcom,lut-patterns:
	Usage: optional
	Value type: <prop-encoded-array>
	Definition: Duty ratios in percentages for LPG working at LUT mode.
		      These duty ratios will be translated into PWM values
		      and stored in LUT or SDAM module shared for all LPG
		      channels. The LUT module has resource to store 47 PWM
		      values at max while SDAM module can store upto 64 PWM
		      values. This property is required if any LPG channels
		      support LUT mode.

- qcom,sync-channel-ids:
	Usage: optional
	Value type: <prop-encoded-array>
	Definition: The hardware IDs of the LPG channel that required be
		      grouped together. These channels will share the same LUT
		      ramping configuration so that they will be enabled with a
		      synchronized pattern. If the LUT ramping configuration
		      differs for the channels grouped for synchronization,
		      configuration of the first channel will be applied for
		      all others.

Subnode is optional if LUT mode is not required, it's required if any LPG
channels expected to be supported in LUT mode.

Subnode properties:
Subnodes for each LPG channel (lpg@X) can be defined if any of the following
parameters needs to be configured for that channel. These properties cannot be
specified for a channel that is configured as PFM enabled using the
`qcom,pfm-chan-ids` property.

- qcom,lpg-chan-id:
	Usage: required
	Value type: <u32>
	Definition: The LPG channel's hardware ID indexed from 1. Allowed
		      range is 1 - 8. Maximum value depends on the number of
		      channels supported on PMIC. Cannot specify this property
		      for a channel that is PFM enabled.

- qcom,lpg-sdam-base:
	Usage: optional
	Value type: <u32>
	Definition: Register base address for LPG configuration in SDAM for
		      the LPG channel specified under "qcom,lpg-chan-id".
		      This property is required if LUT mode is supported with
		      a SDAM module.

- qcom,ramp-step-ms:
	Usage: required
	Value type: <u32>
	Definition: The step duration in milliseconds for LPG staying at each
		      duty specified in the LUT pattern. Allowed range:
		      1 - 511 when LUT module is used, and 8 - 2000 when SDAM
		      is used.

- qcom,tick-duration-us:
	Usage: optional
	Value type: <u32>
	Definition: The tick duration in microseconds for PPG. If this property
		      is not specified, a default value of 7800 will be used.

- qcom,ramp-high-index:
	Usage: required
	Value type: <u32>
	Definition: The high index of the LUT pattern where LPG ends up
		      ramping to. Allowed range: 1 - 47 when LUT module
		      is used, and 1 - 64 when SDAM module is used.

- qcom,ramp-low-index:
	Usage: required
	Value type: <u32>
	Definition: The low index of the LUT pattern from where LPG begins
		      ramping from. The ramp-low-index should be always less
		      than ramp-high-index when SDAM module is used. Allowed
		      range: 0 - 46 when LUT module is used, and 0 - 63 when
		      SDAM module is used.

- qcom,ramp-pattern-repeat:
	Usage: optional
	Value type: <empty>
	Definition: The flag to specify if LPG would be ramping with the LUT
		      pattern repeatedly.

- qcom,ramp-pause-hi-count:
	Usage: optional
	Value type: <u32>
	Definition: The number of step counts for which the LPG will continue
		      to hold the output after it has ramped up to the high
		      index of the LUT. Allowed range: 0 - 254 if SDAM is used.

- qcom,ramp-pause-lo-count:
	Usage: optional
	Value type: <u32>
	Definition: The number of step counts for which the LPG will continue
		      to hold the output after it has ramped down to the low
		      index of the LUT. Allowed range: 0 - 254 if SDAM is used.

- qcom,ramp-from-low-to-high:
	Usage: optional
	Value type: <empty>
	Definition: The flag to specify the LPG ramping direction. The ramping
		      direction is from low index to high index of the LUT
		      pattern if it's specified. This property is not required
		      when SDAM module is used.

- qcom,ramp-toggle:
	Usage: optional
	Value type: <empty>
	Definition: The flag to specify if LPG would toggle the LUT pattern
		      in ramping. If toggling enabled, LPG would return to the
		      low index when high index is reached, or return to the high
		      index when low index is reached. This property is not
		      required when SDAM module is used.

Example when LUT pattern is stored in a LUT module:

	pm8150l_lpg: lpg@b100 {
		compatible = "qcom,pwm-lpg";
		reg = <0xb100>, <0xb000>;
		reg-names = "lpg-base", "lut-base";
		qcom,num-lpg-channels = <6>;
		#pwm-cells = <2>;
		qcom,lut-patterns = <0 14 28 42 56 70 84 100
					100 84 70 56 42 28 14 0>;
		lpg@1 {
			qcom,lpg-chan-id = <1>;
			qcom,ramp-step-ms = <200>;
			qcom,ramp-pause-hi-count = <10>;
			qcom,ramp-pause-lo-count = <10>;
			qcom,ramp-low-index = <0>;
			qcom,ramp-high-index = <15>;
			qcom,ramp-from-low-to-high;
			qcom,ramp-pattern-repeat;
		};
		lpg@2 {
			qcom,lpg-chan-id = <2>;
			qcom,ramp-step-ms = <200>;
			qcom,ramp-pause-hi-count = <10>;
			qcom,ramp-pause-lo-count = <10>;
			qcom,ramp-low-index = <0>;
			qcom,ramp-high-index = <15>;
			qcom,ramp-from-low-to-high;
			qcom,ramp-pattern-repeat;
		};
		lpg@3 {
			qcom,lpg-chan-id = <3>;
			qcom,ramp-step-ms = <200>;
			qcom,ramp-pause-hi-count = <10>;
			qcom,ramp-pause-lo-count = <10>;
			qcom,ramp-low-index = <0>;
			qcom,ramp-high-index = <15>;
			qcom,ramp-from-low-to-high;
			qcom,ramp-pattern-repeat;
		};
	};

Example when LUT pattern is stored in a SDAM module:

	pmi632_lpg: lpg@b100 {
		compatible = "qcom,pwm-lpg";
		reg = <0xb100>;
		reg-names = "lpg-base";
		qcom,num-lpg-channels = <3>;
		#pwm-cells = <2>;
		nvmem-names = "ppg_sdam";
		nvmem = <&sdam7>;
		qcom,pbs-client = <&pbs_client_3>;
		qcom,lut-sdam-base = <0x80>;
		qcom,lut-patterns = <0 14 28 42 56 70 84 100
					100 84 70 56 42 28 14 0>;
		lpg@1 {
			qcom,lpg-sdam-base = <0x48>:
			qcom,lpg-chan-id = <1>;
			qcom,ramp-step-ms = <200>;
			qcom,ramp-low-index = <0>;
			qcom,ramp-high-index = <15>;
			qcom,ramp-pause-hi-count = <10>;
			qcom,ramp-pause-lo-count = <10>;
			qcom,ramp-pattern-repeat;
		};
		lpg@2 {
			qcom,lpg-sdam-base = <0x56>;
			qcom,lpg-chan-id = <2>;
			qcom,ramp-step-ms = <200>;
			qcom,ramp-low-index = <0>;
			qcom,ramp-high-index = <15>;
			qcom,ramp-pause-hi-count = <10>;
			qcom,ramp-pause-lo-count = <10>;
			qcom,ramp-pattern-repeat;
		};
		lpg@3 {
			qcom,lpg-sdam-base = <0x64>;
			qcom,lpg-chan-id = <3>;
			qcom,ramp-step-ms = <200>;
			qcom,ramp-low-index = <0>;
			qcom,ramp-high-index = <15>;
			qcom,ramp-pause-hi-count = <10>;
			qcom,ramp-pause-lo-count = <10>;
			qcom,ramp-pattern-repeat;
		};
	};

Example when LUT pattern is stored in two SDAM modules:

	pm8350c_pwm_1: pwms@e800 {
		compatible = "qcom,pwm-lpg";
		reg = <0xe800>;
		reg-names = "lpg-base";
		#pwm-cells = <2>;
		qcom,num-lpg-channels = <3>;
		nvmem = <&pmk8350_sdam_21 &pmk8350_sdam_22>;
		nvmem-names = "lpg_chan_sdam", "lut_sdam";
		qcom,lut-sdam-base = <0x45>;
		qcom,lut-patterns = <0 10 20 30 40 50 60 70 80 90 100
		                     90 80 70 60 50 40 30 20 10 0>;
		lpg@1 {
			qcom,lpg-sdam-base = <0x48>;
			qcom,lpg-chan-id = <1>;
			qcom,ramp-step-ms = <200>;
			qcom,ramp-low-index = <0>;
			qcom,ramp-high-index = <19>;
			qcom,ramp-pause-hi-count = <10>;
			qcom,ramp-pause-lo-count = <10>;
			qcom,ramp-pattern-repeat;
		};

		lpg@2 {
			qcom,lpg-sdam-base = <0x56>;
			qcom,lpg-chan-id = <2>;
			qcom,ramp-step-ms = <200>;
			qcom,ramp-low-index = <0>;
			qcom,ramp-high-index = <19>;
			qcom,ramp-pause-hi-count = <10>;
			qcom,ramp-pause-lo-count = <10>;
			qcom,ramp-pattern-repeat;
		};

		lpg@3 {
			qcom,lpg-sdam-base = <0x64>;
			qcom,lpg-chan-id = <3>;
			qcom,ramp-step-ms = <200>;
			qcom,ramp-low-index = <0>;
			qcom,ramp-high-index = <19>;
			qcom,ramp-pause-hi-count = <10>;
			qcom,ramp-pause-lo-count = <10>;
			qcom,ramp-pattern-repeat;
		};
	};
