ARK-OS/arkos/kernel/Documentation/devicetree/bindings/regulator/maxim,max8997.yaml

# SPDX-License-Identifier: GPL-2.0-only
%YAML 1.2
---
$id: http://devicetree.org/schemas/regulator/maxim,max8997.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Maxim MAX8997 Power Management IC

maintainers:
  - Krzysztof Kozlowski <krzk@kernel.org>

description: |
  The Maxim MAX8997 is a Power Management IC which includes voltage and current
  regulators, charger controller with fuel gauge, RTC, clock outputs, haptic
  motor driver, flash LED driver and Micro-USB Interface Controller.

  The binding here is not complete and describes only regulator and charger
  controller parts.

properties:
  compatible:
    const: maxim,max8997-pmic

  charger-supply:
    description: |
      Regulator node for charging current.

  interrupts:
    items:
      - description: irq1 interrupt
      - description: alert interrupt

  max8997,pmic-buck1-dvs-voltage:
    $ref: /schemas/types.yaml#/definitions/uint32-array
    minItems: 1
    maxItems: 8
    description: |
      A set of 8 voltage values in micro-volt (uV) units for buck1 when
      changing voltage using GPIO DVS.
      If none of max8997,pmic-buck[1/2/5]-uses-gpio-dvs optional property is
      specified, the max8997,pmic-buck[1/2/5]-dvs-voltage property should
      specify at least one voltage level (which would be a safe operating
      voltage).

  max8997,pmic-buck2-dvs-voltage:
    $ref: /schemas/types.yaml#/definitions/uint32-array
    minItems: 1
    maxItems: 8
    description: |
      A set of 8 voltage values in micro-volt (uV) units for buck2 when
      changing voltage using GPIO DVS.
      If none of max8997,pmic-buck[1/2/5]-uses-gpio-dvs optional property is
      specified, the max8997,pmic-buck[1/2/5]-dvs-voltage property should
      specify at least one voltage level (which would be a safe operating
      voltage).

  max8997,pmic-buck5-dvs-voltage:
    $ref: /schemas/types.yaml#/definitions/uint32-array
    minItems: 1
    maxItems: 8
    description: |
      A set of 8 voltage values in micro-volt (uV) units for buck5 when
      changing voltage using GPIO DVS.
      If none of max8997,pmic-buck[1/2/5]-uses-gpio-dvs optional property is
      specified, the max8997,pmic-buck[1/2/5]-dvs-voltage property should
      specify at least one voltage level (which would be a safe operating
      voltage).

  max8997,pmic-buck1-uses-gpio-dvs:
    type: boolean
    description: |
      buck1 can be controlled by GPIO DVS.

  max8997,pmic-buck2-uses-gpio-dvs:
    type: boolean
    description: |
      buck2 can be controlled by GPIO DVS.

  max8997,pmic-buck5-uses-gpio-dvs:
    type: boolean
    description: |
      buck5 can be controlled by GPIO DVS.

  max8997,pmic-buck125-default-dvs-idx:
    $ref: /schemas/types.yaml#/definitions/uint32
    minimum: 0
    maximum: 7
    default: 0
    description: |
      Default voltage setting selected from the possible 8 options selectable
      by the dvs gpios. The value of this property should be between 0 and 7.
      If not specified or if out of range, the default value of this property
      is set to 0.

  max8997,pmic-buck125-dvs-gpios:
    minItems: 3
    maxItems: 3
    description: |
      GPIO specifiers for three host gpio's used for DVS.

  max8997,pmic-ignore-gpiodvs-side-effect:
    type: boolean
    description: |
      When GPIO-DVS mode is used for multiple bucks, changing the voltage value
      of one of the bucks may affect that of another buck, which is the side
      effect of the change (set_voltage).  Use this property to ignore such
      side effects and change the voltage.

  reg:
    maxItems: 1

  regulators:
    type: object
    additionalProperties: false
    description:
      List of child nodes that specify the regulators.

    patternProperties:
      # 1-18 and 21 LDOs
      "^LDO([1-9]|1[0-8]|21)$":
        type: object
        $ref: regulator.yaml#
        description:
          Properties for single LDO regulator.

        properties:
          regulator-name: true

        required:
          - regulator-name

        unevaluatedProperties: false

      # 7 bucks
      "^BUCK[1-7]$":
        type: object
        $ref: regulator.yaml#
        description:
          Properties for single BUCK regulator.

        properties:
          regulator-name: true

        required:
          - regulator-name

        unevaluatedProperties: false

      "^EN32KHZ_[AC]P$":
        type: object
        $ref: regulator.yaml#
        description:
          32768 Hz clock output (modelled as regulator)

        properties:
          regulator-name: true
          regulator-always-on: true
          regulator-boot-on: true

        required:
          - regulator-name

        additionalProperties: false

    properties:
      CHARGER:
        type: object
        $ref: regulator.yaml#
        description: main battery charger current control

        properties:
          regulator-name: true

        required:
          - regulator-name

        unevaluatedProperties: false

      CHARGER_CV:
        type: object
        $ref: regulator.yaml#
        description: main battery charger voltage control

        properties:
          regulator-name: true

        required:
          - regulator-name

        unevaluatedProperties: false

      CHARGER_TOPOFF:
        type: object
        $ref: regulator.yaml#
        description: end of charge current threshold level

        properties:
          regulator-name: true

        required:
          - regulator-name

        unevaluatedProperties: false

      ENVICHG:
        type: object
        $ref: regulator.yaml#
        description: |
          Battery Charging Current Monitor Output. This is a fixed voltage type
          regulator
        properties:
          regulator-name: true

        required:
          - regulator-name

        unevaluatedProperties: false

      ESAFEOUT1:
        type: object
        $ref: regulator.yaml#
        description: LDO19

        properties:
          regulator-name: true

        required:
          - regulator-name

        unevaluatedProperties: false

      ESAFEOUT2:
        type: object
        $ref: regulator.yaml#
        description: LDO20

        properties:
          regulator-name: true

        required:
          - regulator-name

        unevaluatedProperties: false

required:
  - compatible
  - max8997,pmic-buck1-dvs-voltage
  - max8997,pmic-buck2-dvs-voltage
  - max8997,pmic-buck5-dvs-voltage
  - reg
  - regulators

dependencies:
  max8997,pmic-buck1-uses-gpio-dvs: [ 'max8997,pmic-buck125-dvs-gpios' ]
  max8997,pmic-buck2-uses-gpio-dvs: [ 'max8997,pmic-buck125-dvs-gpios' ]
  max8997,pmic-buck5-uses-gpio-dvs: [ 'max8997,pmic-buck125-dvs-gpios' ]

additionalProperties: false

if:
  anyOf:
    - required:
        - max8997,pmic-buck1-uses-gpio-dvs
    - required:
        - max8997,pmic-buck2-uses-gpio-dvs
    - required:
        - max8997,pmic-buck5-uses-gpio-dvs
then:
  properties:
    max8997,pmic-buck1-dvs-voltage:
      minItems: 8
      maxItems: 8
    max8997,pmic-buck2-dvs-voltage:
      minItems: 8
      maxItems: 8
    max8997,pmic-buck5-dvs-voltage:
      minItems: 8
      maxItems: 8

examples:
  - |
    #include <dt-bindings/gpio/gpio.h>
    #include <dt-bindings/interrupt-controller/irq.h>

    i2c {
        #address-cells = <1>;
        #size-cells = <0>;

        pmic@66 {
            compatible = "maxim,max8997-pmic";
            reg = <0x66>;

            interrupts-extended = <&gpx0 7 IRQ_TYPE_LEVEL_LOW>,
                                  <&gpx2 3 IRQ_TYPE_EDGE_FALLING>;

            max8997,pmic-buck1-uses-gpio-dvs;
            max8997,pmic-buck2-uses-gpio-dvs;
            max8997,pmic-buck5-uses-gpio-dvs;

            max8997,pmic-ignore-gpiodvs-side-effect;
            max8997,pmic-buck125-default-dvs-idx = <0>;

            max8997,pmic-buck125-dvs-gpios = <&gpx0 5 GPIO_ACTIVE_HIGH>,
                                             <&gpx0 6 GPIO_ACTIVE_HIGH>,
                                             <&gpl0 0 GPIO_ACTIVE_HIGH>;

            max8997,pmic-buck1-dvs-voltage = <1350000>, <1300000>,
                                             <1250000>, <1200000>,
                                             <1150000>, <1100000>,
                                             <1000000>, <950000>;

            max8997,pmic-buck2-dvs-voltage = <1100000>, <1000000>,
                                             <950000>,  <900000>,
                                             <1100000>, <1000000>,
                                             <950000>,  <900000>;

            max8997,pmic-buck5-dvs-voltage = <1200000>, <1200000>,
                                             <1200000>, <1200000>,
                                             <1200000>, <1200000>,
                                             <1200000>, <1200000>;

            pinctrl-0 = <&max8997_irq>, <&otg_gp>, <&usb_sel>;
            pinctrl-names = "default";

            charger-supply = <&charger_reg>;

            regulators {
                LDO1 {
                    regulator-name = "VADC_3.3V_C210";
                    regulator-min-microvolt = <3300000>;
                    regulator-max-microvolt = <3300000>;
                    regulator-always-on;
                };

                LDO2 {
                    regulator-name = "VALIVE_1.1V_C210";
                    regulator-min-microvolt = <1100000>;
                    regulator-max-microvolt = <1100000>;
                    regulator-always-on;
                };

                BUCK1 {
                    regulator-name = "VARM_1.2V_C210";
                    regulator-min-microvolt = <65000>;
                    regulator-max-microvolt = <2225000>;
                    regulator-always-on;
                };

                // ...

                BUCK7 {
                    regulator-name = "VCC_SUB_2.0V";
                    regulator-min-microvolt = <2000000>;
                    regulator-max-microvolt = <2000000>;
                    regulator-always-on;
                };

                ESAFEOUT1 {
                    regulator-name = "SAFEOUT1";
                };

                ESAFEOUT2 {
                    regulator-name = "SAFEOUT2";
                    regulator-boot-on;
                };

                EN32KHZ_AP {
                    regulator-name = "EN32KHZ_AP";
                    regulator-always-on;
                };

                EN32KHZ_CP {
                    regulator-name = "EN32KHZ_CP";
                    regulator-always-on;
                };

                CHARGER {
                    regulator-name = "CHARGER";
                    regulator-min-microamp = <200000>;
                    regulator-max-microamp = <950000>;
                };

                CHARGER_CV {
                    regulator-name = "CHARGER_CV";
                    regulator-min-microvolt = <4200000>;
                    regulator-max-microvolt = <4200000>;
                    regulator-always-on;
                };

                CHARGER_TOPOFF {
                    regulator-name = "CHARGER_TOPOFF";
                    regulator-min-microamp = <200000>;
                    regulator-max-microamp = <200000>;
                    regulator-always-on;
                };
            };
        };
    };

  - |
    #include <dt-bindings/interrupt-controller/irq.h>

    i2c {
        #address-cells = <1>;
        #size-cells = <0>;

        pmic@66 {
            compatible = "maxim,max8997-pmic";
            reg = <0x66>;

            interrupt-parent = <&gpx0>;
            interrupts = <4 IRQ_TYPE_LEVEL_LOW>,
                         <3 IRQ_TYPE_EDGE_FALLING>;
            pinctrl-names = "default";
            pinctrl-0 = <&max8997_irq>;

            max8997,pmic-buck1-dvs-voltage = <1350000>;
            max8997,pmic-buck2-dvs-voltage = <1100000>;
            max8997,pmic-buck5-dvs-voltage = <1200000>;

            regulators {
                LDO1 {
                    regulator-name = "VDD_ABB_3.3V";
                    regulator-min-microvolt = <3300000>;
                    regulator-max-microvolt = <3300000>;
                };

                // ...

                BUCK1 {
                    regulator-name = "VDD_ARM_1.2V";
                    regulator-min-microvolt = <950000>;
                    regulator-max-microvolt = <1350000>;
                    regulator-always-on;
                    regulator-boot-on;
                };

                // ...

                EN32KHZ_AP {
                    regulator-name = "EN32KHZ_AP";
                    regulator-always-on;
                };
            };
        };
    };