# 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 <quic_collinsd@quicinc.com>
  - Kamal Wadhwa <quic_kamalw@quicinc.com>
  - Jishnu Prakash <quic_jprakash@quicinc.com>

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>;
      };
    };
...
