# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/regulator/rpmh-regulator.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Qualcomm Technologies, Inc. RPMh Regulators

maintainers:
  - David Collins <quic_collinsd@quicinc.com>

description: |
  rpmh-regulator devices support PMIC regulator management via the Voltage
  Regulator Manager (VRM), Aggregated Resource Controller (ARC) and
  Oscillator Buffer (XOB) RPMh accelerators.  The APPS processor communicates
  with these hardware blocks via a Resource State Coordinator (RSC) using command
  packets.  The VRM allows changing four parameters for a given regulator: enable state,
  output voltage, operating mode and minimum headroom voltage.  The ARC allows changing
  only a single parameter for a given regulator: its operating level.  This
  operating level is fed into CPR which then decides upon a final explicit voltage
  for the regulator.  The XOB allows changing only a single parameter for a given
  regulator: its enable state.  Despite its name, the XOB is capable of controlling
  the enable state of any PMIC peripheral.  It is used for clock buffers, low-voltage
  switches, and LDO/SMPS regulators which have a fixed voltage and mode.

  Required Node Structure:

  RPMh regulators must be described in two levels of device nodes.  The first
  level describes the interface with RPMh (resource) and must reside within an
  RPMh device node.  The second level describes properties of one regulator
  framework interface (of potentially many) for the regulator resource.

properties:
  compatible:
    enum:
      - qcom,rpmh-vrm-regulator
      - qcom,rpmh-arc-regulator
      - qcom,rpmh-xob-regulator

  qcom,resource-name:
    description: |
      RPMh resource name which encodes the specific instance
      of a given type of regulator (LDO, SMPS, VS, etc) within
      a particular PMIC found in the system.  This name must match
      to one that is defined by the bootloader.
    $ref: /schemas/types.yaml#/definitions/string

  qcom,regulator-type:
    description: |
      The physical type of the regulator including the PMIC family.
      This is used for mode control.
    enum:
      - pmic4-ldo
      - pmic4-hfsmps
      - pmic4-ftsmps
      - pmic4-bob
      - pmic5-ldo
      - pmic5-hfsmps
      - pmic5-ftsmps
      - pmic5-bob

  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,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

  qcom,send-defaults:
    description: |
      Boolean flag which indicates that the initial parameter
      values should be sent to RPMh 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,disable-mode:
    description: |
      Specifies the mode to set for a VRM regulator when it gets disabled.
      The actual previously voted mode will be restored when the regulator
      is enabled.
      Supported values are RPMH_REGULATOR_MODE_* (i.e. 0 to 4).
    $ref: /schemas/types.yaml#/definitions/uint32
    minimum: 0
    maximum: 4

additionalProperties: false

required:
  - compatible
  - qcom,resource-name

patternProperties:
  "^regulator.*$":
    type: object
    $ref: "regulator.yaml#"
    description: regulator client voting interface node(s).

    properties:
      regulator-name:
        description: Specifies the name for this RPMh regulator.

      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_*.

      regulator-enable-ramp-delay:
        description: |
          For VRM and XOB resources, the time in microseconds to delay
          after enabling a regulator.

      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 RPMh assisted power collapse.
        $ref: /schemas/types.yaml#/definitions/uint32
        minimum: 1
        maximum: 3

      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: |
          Specifies the initial voltage in microvolts to request for a
          VRM regulator.
        $ref: /schemas/types.yaml#/definitions/uint32
        minimum: 0
        maximum: 8191000

      qcom,init-mode:
        description: |
          Specifies the initial mode to request for a VRM regulator.
        $ref: /schemas/types.yaml#/definitions/uint32
        minimum: 0
        maximum: 4

      qcom,init-headroom-voltage:
        description: |
          Specifies the initial headroom voltage in microvolts to
          request for a VRM regulator.  RPMh ensures that the parent
          of this regulator outputs a voltage high enough to satisfy
          the requested headroom.
        $ref: /schemas/types.yaml#/definitions/uint32
        minimum: 0
        maximum: 511000

      qcom,init-voltage-level:
        description: |
          Specifies the initial voltage level to request for an ARC
          regulator.
        $ref: /schemas/types.yaml#/definitions/uint32
        minimum: 0
        maximum: 65535

      qcom,min-dropout-voltage:
        description: |
          Specifies the minimum voltage in microvolts that the parent
          supply regulator must output above the output of this
          regulator.  It is only meaningful if the property
          <regulator-name>-parent-supply has been specified in the
          first level node.
        $ref: /schemas/types.yaml#/definitions/uint32

      qcom,min-dropout-voltage-level:
        description: |
          Specifies the minimum voltage level difference that the
          parent supply regulator must output above the output of this
          regulator.  It is only meaningful if the property
          <regulator-name>-parent-supply has been specified in the
          first level node.
        $ref: /schemas/types.yaml#/definitions/uint32

    patternProperties:
      "^.*-parent-supply$":
        description: |
          phandle of the parent supply regulator of one of the
          regulators for this RPMh resource.  The property name is defined by
          the value specified for the regulator-name property.

    additionalProperties: false

    required:
      - regulator-name
      - qcom,set

examples:
  - |
    #include <dt-bindings/regulator/qcom,rpmh-regulator-levels.h>

    rpmh-regulator-cxlvl {
      compatible = "qcom,rpmh-arc-regulator";
      qcom,resource-name = "cx.lvl";
      qcom,send-defaults;
      pm8998_s9_level: regulator-s9-level {
        regulator-name = "pm8998_s9_level";
        qcom,set = <RPMH_REGULATOR_SET_ALL>;
        regulator-min-microvolt =
            <RPMH_REGULATOR_LEVEL_RETENTION>;
        regulator-max-microvolt = <RPMH_REGULATOR_LEVEL_MAX>;
        qcom,init-voltage-level = <RPMH_REGULATOR_LEVEL_TURBO>;
      };

      pm8998_s9_level_ao: regulator-s9-level-ao {
        regulator-name = "pm8998_s9_level_ao";
        qcom,set = <RPMH_REGULATOR_SET_ACTIVE>;
        regulator-min-microvolt =
            <RPMH_REGULATOR_LEVEL_RETENTION>;
        regulator-max-microvolt = <RPMH_REGULATOR_LEVEL_MAX>;
      };
    };

    rpmh-regulator-smpa2 {
      compatible = "qcom,rpmh-vrm-regulator";
      qcom,resource-name = "smpa2";
      qcom,regulator-type = "pmic4-hfsmps";
      qcom,supported-modes =
        <RPMH_REGULATOR_MODE_AUTO
         RPMH_REGULATOR_MODE_HPM>;
      qcom,mode-threshold-currents = <0 2000000>;

      pm8998_s2: regulator-s2 {
        regulator-name = "pm8998_s2";
        qcom,set = <RPMH_REGULATOR_SET_ALL>;
        regulator-min-microvolt = <1100000>;
        regulator-max-microvolt = <1200000>;
        regulator-enable-ramp-delay = <200>;
        qcom,init-mode = <RPMH_REGULATOR_MODE_AUTO>;
        qcom,init-voltage = <1150000>;
      };
    };

    rpmh-regulator-ldoa4 {
      compatible = "qcom,rpmh-vrm-regulator";
      qcom,resource-name = "ldoa4";
      qcom,regulator-type = "pmic4-ldo";
      pm8998_l4: regulator-l4 {
        regulator-name = "pm8998_l4";
        qcom,set = <RPMH_REGULATOR_SET_ALL>;
        regulator-min-microvolt = <1000000>;
        regulator-max-microvolt = <1000000>;
        qcom,init-voltage = <1000000>;
      };
    };

    rpmh-regulator-ldoc1 {
      compatible = "qcom,rpmh-xob-regulator";
      qcom,resource-name = "ldoc1";
      pm8150l_l1: regulator-pm8150l-l1 {
        regulator-name = "pm8150l_l1";
        qcom,set = <RPMH_REGULATOR_SET_ALL>;
        regulator-min-microvolt = <1800000>;
        regulator-max-microvolt = <1800000>;
      };
    };

  - |
    #include <dt-bindings/regulator/qcom,rpmh-regulator-levels.h>

    rpmh-regulator-ldoa3-disp {
      compatible = "qcom,rpmh-vrm-regulator";
      qcom,resource-name = "ldoa3";
      qcom,regulator-type = "pmic4-ldo";
      qcom,supported-modes =
        <RPMH_REGULATOR_MODE_LPM
         RPMH_REGULATOR_MODE_HPM>;
      qcom,mode-threshold-currents = <0 10000>;
      qcom,always-wait-for-ack;

      pm8998_l3_disp_ao: regulator-l3-ao {
        regulator-name = "pm8998_l3_disp_ao";
        qcom,set = <RPMH_REGULATOR_SET_ACTIVE>;
        regulator-min-microvolt = <1000000>;
        regulator-max-microvolt = <1200000>;
        qcom,init-voltage = <1000000>;
        qcom,init-headroom-voltage = <60000>;
      };

      pm8998_l3_disp_so: regulator-l3-so {
        regulator-name = "pm8998_l3_disp_so";
        qcom,set = <RPMH_REGULATOR_SET_SLEEP>;
        regulator-min-microvolt = <1000000>;
        regulator-max-microvolt = <1200000>;
        qcom,init-mode = <RPMH_REGULATOR_MODE_LPM>;
        qcom,init-voltage = <1000000>;
        qcom,init-enable = <0>;
      };
    };
