diff --git a/bindings/regulator/rpm-smd-regulator.yaml b/bindings/regulator/rpm-smd-regulator.yaml new file mode 100644 index 00000000..9672de58 --- /dev/null +++ b/bindings/regulator/rpm-smd-regulator.yaml @@ -0,0 +1,548 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/rpm-smd-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies, Inc. RPM Regulators + +maintainers: + - David Collins + - Kamal Wadhwa + - Jishnu Prakash + +description: | + rpm-regulator-smd is a regulator driver which supports regulators inside of + PMICs which are controlled by the RPM processor. Communication with the RPM + processor takes place over SMD. + + Required Node Structure: + + RPM regulators must be described in two levels of devices nodes. The first + level describes the interface with the RPM. The second level describes + properties of one regulator framework interface (of potentially many) to + the regulator. + +properties: + compatible: + const: qcom,rpm-smd-regulator-resource + + qcom,resource-name: + description: | + Resource name string for this regulator to be used in RPM + transactions. Length is 4 characters max. + $ref: /schemas/types.yaml#/definitions/string + + qcom,resource-id: + description: | + Resource instance ID for this regulator to be used in RPM + transactions. + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,regulator-type: + description: | + Type of this regulator. Supported values are 0 = LDO, 1 = SMPS + 2 = VS, 3 = NCP, 4 = Buck or Boost (BoB) + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 4 + + qcom,allow-atomic: + description: | + Boolean flag specifying if atomic access is allowed for this + regulator. + $ref: /schemas/types.yaml#/definitions/flag + + qcom,enable-time: + description: + Time in us to delay after enabling the regulator + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,hpm-min-load: + description: | + Load current in uA which corresponds to the minimum load + which requires the regulator to be in high power mode. + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,apps-only: + description: | + Boolean flag which indicates that the regulator only has + consumers on the application processor. If this flag + is specified, then voltage and current updates are + only sent to the RPM if the regulator is enabled. + $ref: /schemas/types.yaml#/definitions/flag + + qcom,always-wait-for-ack: + description: | + Boolean flag which indicates that the application processor + must wait for an ACK or a NACK from RPMh for every request + sent for this regulator including those which are for a + strictly lower power state. + $ref: /schemas/types.yaml#/definitions/flag + + qcom,regulator-hw-type: + description: | + Specifies the regulator LDO hardware type. This + property must be specified if "qcom,regulator-type" + has been specified with a value of 0 (LDO). + + enum: + - pmic4-ldo + - pmic5-ldo + + qcom,supported-modes: + description: | + A list of integers specifying the PMIC regulator modes + supported by this regulator. Supported values are + RPMH_REGULATOR_MODE_* (i.e. 0 to 4). Elements must be + specified in order from lowest to highest. + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 5 + items: + minimum: 0 + maximum: 4 + + qcom,mode-threshold-currents: + description: | + A list of integers specifying minimum allowed current in + microamps for each of the modes listed in qcom,supported-modes. + The first element should always be 0. Elements must be specified + in order from lowest to highest. + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 5 + +additionalProperties: false + +required: + - compatible + - qcom,resource-name + - qcom,resource-id + - qcom,regulator-type + +patternProperties: + "^regulator.*$": + type: object + $ref: regulator.yaml# + description: regulator client voting interface node(s). + + properties: + compatible: + const: qcom,rpm-smd-regulator + + regulator-name: + description: A string used as a descriptive name for regulator output + + regulator-min-microvolt: + description: | + For VRM resources, this is the minimum supported voltage in + microvolts. For ARC resources, this is the minimum + supported voltage level from RPMH_REGULATOR_LEVEL_*. + + regulator-max-microvolt: + description: | + For VRM resources, this is the maximum supported voltage in + microvolts. For ARC resources, this is the maximum + supported voltage level from RPMH_REGULATOR_LEVEL_*. + + parent-supply: + description: | + phandle to the parent supply/regulator node. + + qcom,set: + description: | + Specifies which sets that requests made with this + regulator interface should be sent to. Regulator + requests sent in the active set take effect immediately. + Requests sent in the sleep set take effect when the Apps + processor transitions into RPM assisted power collapse. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + maximum: 3 + + qcom,system-load: + description: | + Load in uA present on regulator that is not + captured by any consumer request. + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,use-voltage-corner: + description: | + Flag that signifies if regulator_set_voltage + calls should modify the corner parameter instead + of the voltage parameter. When used, voltages + specified inside of the regulator framework + represent corners that have been incremented by + 1. This value shift is necessary to work around + limitations in the regulator framework which + treat 0 uV as an error. + $ref: /schemas/types.yaml#/definitions/flag + + qcom,use-voltage-floor-corner: + description: | + Flag that signifies if regulator_set_voltage + calls should modify the floor corner parameter + instead of the voltage parameter. When used, + voltages specified inside of the regulator + framework represent corners that have been + incremented by 1. The properties + qcom,use-voltage-corner and + qcom,use-voltage-floor-corner are mutually + exclusive. Only one may be specified for a + given regulator. + $ref: /schemas/types.yaml#/definitions/flag + + qcom,use-voltage-level: + description: | + Flag that signifies if regulator_set_voltage + calls should modify the level parameter instead + of the voltage parameter. + $ref: /schemas/types.yaml#/definitions/flag + + qcom,use-voltage-floor-level: + description: | + Flag that signifies if regulator_set_voltage + calls should modify the floor level parameter + instead of the voltage parameter. + The properties qcom,use-voltage-level and + qcom,use-voltage-floor-level are mutually + exclusive. Only one may be specified for a + given regulator. + $ref: /schemas/types.yaml#/definitions/flag + + qcom,use-pin-ctrl-voltage1: + description: | + Flag which indicates that updates to voltage + should be sent to the pin control voltage 1 + parameter. Only one pin may be specified per + regulator. This property only applies to BoB + type regulators. + $ref: /schemas/types.yaml#/definitions/flag + + qcom,use-pin-ctrl-voltage2: + description: | + Flag which indicates that updates to voltage + should be sent to the pin control voltage 2 + parameter. Only one pin may be specified per + regulator. This property only applies to BoB + type regulators. + $ref: /schemas/types.yaml#/definitions/flag + + qcom,use-pin-ctrl-voltage3: + description: | + Flag which indicates that updates to voltage + should be sent to the pin control voltage 3 + parameter. Only one pin may be specified per + regulator. This property only applies to BoB + type regulators. + $ref: /schemas/types.yaml#/definitions/flag + + qcom,always-send-voltage: + description: | + Flag which indicates that updates to the + voltage, voltage corner or voltage level set + point should always be sent immediately to the + RPM. If this flag is not specified, then + voltage set point updates are only sent if the + given regulator has also been enabled by a + Linux consumer. + $ref: /schemas/types.yaml#/definitions/flag + + qcom,always-send-current: + description: | + Flag which indicates that updates to the load + current should always be sent immediately to the + RPM. If this flag is not specified, then load + current updates are only sent if the given + regulator has also been enabled by a Linux + consumer. + $ref: /schemas/types.yaml#/definitions/flag + + qcom,send-defaults: + description: | + Boolean flag which indicates that the initial + parameter values should be sent to the RPM + before consumers make their own requests. If + this flag is not specified, then initial + parameters values will only be sent after some + consumer makes a request. + $ref: /schemas/types.yaml#/definitions/flag + + qcom,enable-with-pin-ctrl: + description: | + Double in which the first element corresponds to + the pin control enable parameter value to send + when all consumers have requested the regulator + to be disabled. The second element corresponds + to the pin control enable parameter value to + send when any consumer has requested the + regulator to be enabled. Each element supports + the same set of values as the + qcom,init-pin-ctrl-enable property listed below. + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,init-enable: + description: | + Specifies the initial enable state to request for a VRM + regulator: 0 = disabled and 1 = enabled. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 1 + + qcom,init-voltage: + description: Voltage in uV. + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,init-current: + description: Current in mA. + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,init-ldo-mode: + description: | + Operating mode to be used with LDO regulators + Supported values are 0 = mode determined by current requests + 1 = force HPM (NPM) + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,init-smps-mode: + description: | + Operating mode to be used with SMPS regulators + Supported values are: + 0 = auto; hardware determines mode + 1 = mode determined by current requests + 2 = force HPM (PWM) + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,init-bob-mode: + description: | + Operating mode to be used with BoB regulators + Supported values are: + 0 = pass; use priority order + 1 = force PFM + 2 = auto; hardware determines mode + 3 = force PWM + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,init-pin-ctrl-enable: + description: | + Bit mask specifying which hardware pins should be + used to enable the regulator, if any; supported + bits are: + 0 = ignore all hardware enable signals + BIT(0) = follow HW0_EN signal + BIT(1) = follow HW1_EN signal + BIT(2) = follow HW2_EN signal + BIT(3) = follow HW3_EN signal + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,init-pin-ctrl-mode: + description: | + Bit mask specifying which hardware pins should be + used to force the regulator into high power + mode, if any. Supported bits are: + 0 = ignore all hardware enable signals + BIT(0) = follow HW0_EN signal + BIT(1) = follow HW1_EN signal + BIT(2) = follow HW2_EN signal + BIT(3) = follow HW3_EN signal + BIT(4) = follow PMIC awake state + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,init-pin-ctrl-voltage1: + description: | + Minimum voltage in micro-volts to use while pin + control 1 is enabled. This property only + applies to BoB type regulators. + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,init-pin-ctrl-voltage2: + description: | + Minimum voltage in micro-volts to use while pin + control 2 is enabled. This property only + applies to BoB type regulators. + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,init-pin-ctrl-voltage3: + description: | + Minimum voltage in micro-volts to use while pin + control 3 is enabled. This property only + applies to BoB type regulators. + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,init-frequency: + description: | + Switching frequency divisor for SMPS regulators. + Supported values are n = 0 to 31 where + freq = 19.2 MHz / (n + 1). + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,init-head-room: + description: | + Voltage head room in mV required for the + regulator. This head room value should be used + in situations where the device connected to the + output of the regulator has low noise tolerance. + Note that the RPM independently enforces a + safety head room value for subregulated LDOs + which is sufficient to account for LDO drop-out + voltage. + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,init-quiet-mode: + description: | + Specify that quiet mode is needed for an SMPS + regulator in order to have lower output noise. + Supported values are: + 0 = No quiet mode + 1 = Quiet mode + 2 = Super quiet mode + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,init-freq-reason: + description: | + Consumer requiring specified frequency for an + SMPS regulator. Supported values are: + 0 = None + 1 = Bluetooth + 2 = GPS + 4 = WLAN + 8 = WAN + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,init-voltage-corner: + description: | + Performance corner to use in order to determine + voltage set point. This value corresponds to + the actual value that will be sent and is not + incremented by 1 like the values used inside of + the regulator framework. The meaning of corner + values is set by the RPM. It is possible that + different regulators on a given platform or + similar regulators on different platforms will + utilize different corner values. These are + corner values supported on MSM8974 for PMIC + PM8841 SMPS 2 (VDD_Dig); nominal voltages for + these corners are also shown: + 0 = None (don't care) + 1 = Retention (0.5000 V) + 2 = SVS Krait (0.7250 V) + 3 = SVS SOC (0.8125 V) + 4 = Normal (0.9000 V) + 5 = Turbo (0.9875 V) + 6 = Super Turbo (1.0500 V) + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,init-disallow-bypass: + description: | + Specify that bypass mode should not be used for a + given LDO regulator. When in bypass mode, an + LDO performs no regulation and acts as a simple + switch. The RPM can utilize this mode for an + LDO that is subregulated from an SMPS when it is + possible to reduce the SMPS voltage to the + desired LDO output level. Bypass mode may be + disallowed if lower LDO output noise is + required. Supported values are: + 0 = Allow RPM to utilize LDO bypass mode + if possible + 1 = Disallow LDO bypass mode + $ref: /schemas/types.yaml#/definitions/flag + + qcom,init-voltage-floor-corner: + description: | + Minimum performance corner to use if any + processor in the system is awake.This property + supports the same values as + qcom,init-voltage-corner. + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,init-voltage-level: + description: | + Performance level to use in order to determine + voltage set point. The meaning of level + values is set by the RPM. It is possible that + different regulators on a given platform or + similar regulators on different platforms will + utilize different level values. These are + level values supported on MSM8952 for PMIC + PM8952 SMPS 2 (VDD_Dig); nominal voltages for + these level are also shown: + 16 = Retention (0.5000 V) + 128 = SVS (1.0500 V) + 192 = SVS+ (1.1550 V) + 256 = Normal (1.2250 V) + 320 = Normal+ (1.2875 V) + 384 = Turbo (1.3500 V) + $ref: /schemas/types.yaml#/definitions/uint32 + + qcom,init-voltage-floor-level: + description: | + Minimum performance level to use if any + processor in the system is awake. This property + supports the same values as + qcom,init-voltage-level + $ref: /schemas/types.yaml#/definitions/uint32 + + additionalProperties: false + + required: + - compatible + - regulator-name + - qcom,set + +examples: + - | + + rpm-regulator-smpb1 { + compatible = "qcom,rpm-smd-regulator-resource"; + qcom,resource-name = "smpb"; + qcom,resource-id = <1>; + qcom,regulator-type = <1>; + qcom,hpm-min-load = <100000>; + + pm8841_s1: regulator-s1 { + compatible = "qcom,rpm-smd-regulator"; + regulator-name = "8841_s1"; + qcom,set = <3>; + regulator-min-microvolt = <900000>; + regulator-max-microvolt = <1150000>; + qcom,init-voltage = <1150000>; + }; + + pm8841_s1_ao: regulator-s1-ao { + compatible = "qcom,rpm-smd-regulator"; + regulator-name = "8841_s1_ao"; + qcom,set = <1>; + regulator-min-microvolt = <900000>; + regulator-max-microvolt = <1150000>; + }; + + pm8841_s1_corner: regulator-s1-corner { + compatible = "qcom,rpm-smd-regulator"; + regulator-name = "8841_s1_corner"; + qcom,set = <3>; + regulator-min-microvolt = <1>; + regulator-max-microvolt = <6>; + qcom,init-voltage-corner = <3>; + qcom,use-voltage-corner; + }; + }; + + rpm-regulator-ldoa2 { + compatible = "qcom,rpm-smd-regulator-resource"; + qcom,resource-name = "ldoa"; + qcom,resource-id = <2>; + qcom,regulator-type = <0>; + qcom,hpm-min-load = <10000>; + + regulator-l2 { + compatible = "qcom,rpm-smd-regulator"; + regulator-name = "8941_l2"; + qcom,set = <3>; + regulator-min-microvolt = <1225000>; + regulator-max-microvolt = <1225000>; + qcom,init-voltage = <1225000>; + }; + }; +...