max77620.yaml

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

title: Maxim Semiconductor MAX77620 Power Management IC

maintainers:
  - Rob Herring <robh+dt@kernel.org>

description:
  The Maxim MAX77620 is a system power management IC that can be used to
  drive the power sequences need to boot an SoC as well as provide runtime
  configurable power supplies for various aspects of that SoC.

  In addition, the MAX77620 has 8 GPIO pins which can be configured as GPIO
  as well as a set of special I/O functions.

  The MAX77620 also supports alarm interrupts when its die temperature crosses
  120° C and 140° C. These threshold temperatures are not configurable. The
  device does not provide the real temperature of die, but merely indicates
  whether the temperature is above or below the threshold levels.

properties:
  compatible:
    enum:
      - maxim,max77620
      - maxim,max20024
      - maxim,max77663

  reg:
    maxItems: 1

  interrupts:
    description: The interrupt on the parent the controller is connected to.
    $ref: /schemas/types.yaml#/definitions/uint32-array

  interrupt-controller:
    description: Marks the device node as an interrupt controller.

  "#interrupt-cells":
    description: Must be 2 and their usage is compliant to the 2 cells
      variant of <../interrupt-controller/interrupts.txt>. IRQ numbers for
      different interrupt source of MAX77620 are defined at
      dt-bindings/mfd/max77620.h.
    $ref: /schemas/types.yaml#/definitions/uint32
    const: 2

  system-power-controller:
    $ref: /schemas/types.yaml#/definitions/flag
    description:
      Indicates that this PMIC is controlling the system power, see
      ../power/power-controller.txt for more details.

  "#gpio-cells":
    description: The first cell is the pin number and the second cell is used
      to specify the GPIO polarity (0 = active high, 1 = active low).
    $ref: /schemas/types.yaml#/definitions/uint32
    const: 2

  gpio-controller:
    description: Marks the device node as a GPIO controller.
    type: boolean

  "#thermal-sensor-cells":
    description: Please refer to ../thermal/thermal-sensor.yaml for more details.
    const: 0

  fps:
    description: |
      The Flexible Power Sequencer (FPS) allows each regulator to power up
      under hardware or software control. Additionally, each regulator can
      power on independently or among a group of other regulators with an
      adjustable power-up and power-down delays (sequencing). GPIO1, GPIO2,
      and GPIO3 can be programmed to be part of a sequence allowing external
      regulators to be sequenced along with internal regulators. 32KHz clock
      can be programmed to be part of a sequence.

      The flexible sequencing structure consists of two hardware enable
      inputs (EN0, EN1), and 3 master sequencing timers called FPS0, FPS1
      and FPS2. Each master sequencing timer is programmable through its
      configuration register to have a hardware enable source (EN1 or EN2)
      or a software enable source (SW). When enabled/disabled, the master
      sequencing timer generates eight sequencing events on different time
      periods called slots. The time period between each event is
      programmable within the configuration register. Each regulator,
      GPIO1, GPIO2, GPIO3, and 32KHz clock has a flexible power sequence
      slave register which allows its enable source to be specified as a
      flexible power sequencer timer or a software bit. When a FPS source
      of regulators, GPIOs and clocks specifies the enable source to be a
      flexible power sequencer, the power up and power down delays can be
      specified in the regulators, GPIOs and clocks flexible power
      sequencer configuration registers.

      When FPS event cleared (set to LOW), regulators, GPIOs and 32KHz
      clock are set into following state at the sequencing event that
      corresponds to its flexible sequencer configuration register.

      Sleep state: In this state, regulators, GPIOs and 32KHz clock get
        disabled at the sequencing event.

      Global Low Power Mode (GLPM): In this state, regulators are set in
        low power mode at the sequencing event.

      The configuration parameters of FPS is provided through sub-node
      "fps" and their child for FPS specific. The child node name for FPS
      are "fps0", "fps1", and "fps2" for FPS0, FPS1 and FPS2 respectively.

      The FPS configurations like FPS source, power up and power down slots
      for regulators, GPIOs and 32kHz clocks are provided in their respective
      configuration nodes which is explained in respective sub-system DT
      binding document.

      There is need for different FPS configuration parameters based on
      system state like when system state changed from active to suspend or
      active to power off (shutdown).
    type: object
    properties:
      maxim,fps-event-source:
        description: |
          FPS event source like external hardware input to PMIC i.e. EN0, EN1
          or software (SW).

          The macros are defined on dt-bindings/mfd/max77620.h for different
          control source.

          - MAX77620_FPS_EVENT_SRC_EN0: for hardware input pin EN0
          - MAX77620_FPS_EVENT_SRC_EN1: for hardware input pin EN1
          - MAX77620_FPS_EVENT_SRC_SW: for software control
        $ref: /schemas/types.yaml#/definitions/uint32

      maxim,shutdown-fps-time-period-us:
        description: FPS time period in microseconds when system enters into
          shutdown state.

      maxim,suspend-fps-time-period-us:
        description: FPS time period in microseconds when system enters into
          suspend state.

      maxim,device-state-on-disabled-event:
        description: |
          Describe the PMIC state when FPS event cleared (set to LOW) whether
          it should go to sleep state or low-power state. Following are valid
          values:

            - MAX77620_FPS_INACTIVE_STATE_SLEEP: to set the PMIC state to
                sleep
            - MAX77620_FPS_INACTIVE_STATE_LOW_POWER: to set the PMIC state to
                low power

          Absence of this property or other value will not change device state
          when FPS event get cleared.
        $ref: /schemas/types.yaml#/definitions/uint32

      maxim,power-ok-control:
        description: |
          Used to configure the map power OK bit.

            - 1: Enables POK(Power OK) to control nRST_IO and GPIO1 POK
                function.
            - 0: Disables POK control.

          If this property is missing, do not configure MPOK bit. If POK
          mapping is enabled for GPIO1/nRST_IO then, GPIO1/nRST_IO pins are
          HIGH only if all rails that have POK control enabled are HIGH.

          If any of the rails goes down(which are enabled for POK control)
          then, GPIO1/nRST_IO goes LOW. this property is valid for max20024
          only.
        $ref: /schemas/types.yaml#/definitions/uint32

  regulators:
    description: |
      The MAX77620 has multiple DCDCs (sd[0-3]) and LDOs (ldo[0-8]). Details
      about each of these regulators are defined using child nodes named after
      the regulator under a top-level "regulators" node. Input supplies for
      each of the regulators are defined in the "regulators" node.

      Each subnode should contain the constraints and initialization details
      for the corresponding regulator. The definition for each of these nodes
      is defined using the standard bindings for regulators found in:

        ../regulator/regulator.txt

      Additional properties required to configure FPS parameters for SDs and
      LDOs are defined below.
    type: object
    properties:
      in-sd0-supply:
        description: input supply for SD0, INA-SD0 or INB-SD0 pins

      in-sd1-supply:
        description: input supply for SD1

      in-sd2-supply:
        description: input supply for SD2

      in-sd3-supply:
        description: input supply for SD3

      in-ld0-1-supply:
        description: input supply for LDO0 and LDO1

      in-ld2-supply:
        description: input supply for LDO2

      in-ld3-5-supply:
        description: input supply for LDO3 and LDO5

      in-ld4-6-supply:
        description: input supply for LDO4 and LDO6

      in-ld7-8-supply:
        description: input supply for LDO7 and LDO8

    patternProperties:
      "^(sd[0-3]|ldo[0-8])$":
        type: object
        $ref: /schemas/regulator/regulator.yaml
        properties:
          maxim,active-fps-source:
            description: |
              FPS source for the regulators to get enabled/disabled when the
              system is in active state. Valid values are:

                - MAX77620_FPS_SRC_0: FPS source is FPS0.
                - MAX77620_FPS_SRC_1: FPS source is FPS1.
                - MAX77620_FPS_SRC_2: FPS source is FPS2.
                - MAX77620_FPS_SRC_NONE: Regulator is not controlled by FPS
                    events and it gets enabled/disabled by register access.

              Absence of this property will leave the FPS configuration
              register for that regulator at the default value.
            $ref: /schemas/types.yaml#/definitions/uint32
            enum: [0, 1, 2, 3]

          maxim,active-fps-power-up-slot:
            description: Sequencing event slot number on which the regulator
              gets enabled when master FPS input event set to HIGH. Valid
              values are 0 to 7. This is applicable if FPS source is selected
              as FPS0, FPS1 or FPS2.
            $ref: /schemas/types.yaml#/definitions/uint32
            enum: [0, 1, 2, 3, 4, 5, 6, 7]

          maxim,active-fps-power-down-slot:
            description: Sequencing event slot number on which the regulator
              gets disabled when master FPS input event set to LOW. Valid
              values are 0 to 7. This is applicable if FPS source is selected
              as FPS0, FPS1 or FPS2.
            $ref: /schemas/types.yaml#/definitions/uint32
            enum: [0, 1, 2, 3, 4, 5, 6, 7]

          maxim,suspend-fps-source:
            description: This is same as "maxim,active-fps-source" but the
              value gets configured when the system enters suspend.
            $ref: /schemas/types.yaml#/definitions/uint32
            enum: [0, 1, 2, 3]

          maxim,suspend-fps-power-up-slot:
            description: This is same as "maxim,active-fps-power-up-slot" but
              the value gets configured when the system enters suspend. This
              is applicable if the suspend state FPS source is selected as
              FPS0, FPS1 or FPS2.
            $ref: /schemas/types.yaml#/definitions/uint32
            enum: [0, 1, 2, 3, 4, 5, 6, 7]

          maxim,suspend-fps-power-down-slot:
            description: This is same as "maxim,active-fps-power-down-slot"
              but this value gets configured when the system enters suspend.
              This is applicable if the suspend state FPS source is selected
              as FPS0, FPS1 or FPS2.
            $ref: /schemas/types.yaml#/definitions/uint32
            enum: [0, 1, 2, 3, 4, 5, 6, 7]

          maxim,ramp-rate-setting:
            description: |
              Ramp rate (uV/us) setting to be configured for the device. The
              platform may have a ramp rate different from that advertised if
              it has design variation from Maxim's recommended rate. In this
              case, the platform specific ramp rate is used for ramp time
              calculation and this property is used for device register
              configurations. The measured ramp rate of platform is provided
              by the "regulator-ramp-delay" property as described in
              <../regulator/regulator.txt>.

              The Maxim Max77620 PMIC supports the following ramp delays:

                - SD: 13.75 mV/us, 27.5 mV/us, 55 mV/us
                - LDOs: 5 mV/us, 100 mV/us

              Note: If the measured ramp delay is same as advertised ramp
              delay then it is not required to provide the ramp delay with
              property "maxim,ramp-rate-setting". The ramp rate can be
              provided by the regulator-ramp-delay which will be used for
              ramp time calculation for voltage change as well as for
              device configuration.
            $ref: /schemas/types.yaml#/definitions/uint32
            enum: [5000, 13750, 27500, 55000, 100000]

patternProperties:
  "^gpio(@[0-9]+)?$":
    type: object
    properties:
      gpio-hog:
        $ref: /schemas/types.yaml#/definitions/flag

      output-high:
        $ref: /schemas/types.yaml#/definitions/flag

      gpios:
        $ref: /schemas/types.yaml#/definitions/uint32-matrix

  "^(.+-hog(-[0-9]+)?)$":
    type: object

  "^pinmux(@[0-9]+)?$":
    type: object
    patternProperties:
      "^gpio[0-7_]+$":
        type: object
        properties:
          pins:
            items:
              pattern: "^gpio[0-7]$"
            minItems: 1
            maxItems: 8

          function:
            $ref: /schemas/types.yaml#/definitions/string
            enum:
              - gpio
              - lpm-control-in
              - fps-out
              - 32k-out1
              - sd0-dvs-in
              - sd1-dvs-in
              - reference-out

          drive-push-pull:
            $ref: /schemas/types.yaml#/definitions/uint32
            enum: [0, 1]

          drive-open-drain:
            $ref: /schemas/types.yaml#/definitions/uint32
            enum: [0, 1]

          bias-pull-up:
            $ref: /schemas/types.yaml#/definitions/uint32
            enum: [0, 1]

          bias-pull-down:
            $ref: /schemas/types.yaml#/definitions/uint32
            enum: [0, 1]

          maxim,active-fps-source:
            description: |
              FPS source for the GPIOs to get enabled/disabled when the system
              is in active state. Valid values are:

                - MAX77620_FPS_SRC_0: FPS source is FPS0.
                - MAX77620_FPS_SRC_1: FPS source is FPS1.
                - MAX77620_FPS_SRC_2: FPS source is FPS2.
                - MAX77620_FPS_SRC_NONE: GPIO is not controlled by FPS events
                    and it gets enabled/disabled by register access.

              Absence of this property will leave the FPS configuration
              register for that GPIO at the default value.
            $ref: /schemas/types.yaml#/definitions/uint32
            enum: [0, 1, 2, 3, 4]

          maxim,active-fps-power-up-slot:
            description: Sequencing event slot number on which the GPIO gets
              enabled when master FPS input event set to HIGH. Valid values
              are 0 to 7. This is applicable if FPS source is selected as
              FPS0, FPS1 or FPS2.
            $ref: /schemas/types.yaml#/definitions/uint32
            enum: [0, 1, 2, 3, 4, 5, 6, 7]

          maxim,active-fps-power-down-slot:
            description: Sequencing event slot number on which the GPIO gets
              disabled when master FPS input event set to LOW. Valid values
              are 0 to 7. This is applicable if FPS source is selected as
              FPS0, FPS1 or FPS2.
            $ref: /schemas/types.yaml#/definitions/uint32
            enum: [0, 1, 2, 3, 4, 5, 6, 7]

          maxim,suspend-fps-source:
            description: This is same as "maxim,active-fps-source" but the
              value gets configured when the system enters suspend.
            $ref: /schemas/types.yaml#/definitions/uint32
            enum: [0, 1, 2, 3, 4]

          maxim,suspend-fps-power-up-slot:
            description: This is same as "maxim,active-fps-power-up-slot" but
              the value gets configured when the system enters suspend. This
              is applicable if the suspend state FPS source is selected as
              FPS0, FPS1 or FPS2.
            $ref: /schemas/types.yaml#/definitions/uint32
            enum: [0, 1, 2, 3, 4, 5, 6, 7]

          maxim,suspend-fps-power-down-slot:
            description: This is same as "maxim,active-fps-power-down-slot"
              but this value gets configured when the system enters suspend.
              This is applicable if the suspend state FPS source is selected
              as FPS0, FPS1 or FPS2.
            $ref: /schemas/types.yaml#/definitions/uint32
            enum: [0, 1, 2, 3, 4, 5, 6, 7]

        required:
          - pins

    unevaluatedProperties: false

required:
  - compatible
  - reg

unevaluatedProperties: false

allOf:
  - if:
      properties:
        compatible:
          contains:
            const: maxim,max77620
    then:
      properties:
        fps:
          properties:
            maxim,shutdown-fps-time-period-us:
              enum: [40, 80, 160, 320, 640, 1280, 2560, 5120]

            maxim,suspend-fps-time-period-us:
              enum: [40, 80, 160, 320, 640, 1280, 2560, 5120]

  - if:
      properties:
        compatible:
          contains:
            const: maxim,max20024
    then:
      properties:
        fps:
          properties:
            maxim,shutdown-fps-time-period-us:
              enum: [20, 40, 80, 160, 320, 640, 1280, 2540]

            maxim,suspend-fps-time-period-us:
              enum: [20, 40, 80, 160, 320, 640, 1280, 2540]

  - if:
      properties:
        compatible:
          contains:
            const: maxim,max77663
    then:
      properties:
        fps:
          properties:
            maxim,shutdown-fps-time-period-us:
              enum: [20, 40, 80, 160, 320, 640, 1280, 2540]

            maxim,suspend-fps-time-period-us:
              enum: [20, 40, 80, 160, 320, 640, 1280, 2540]

additionalProperties: false

examples:
  - |
    #include <dt-bindings/interrupt-controller/arm-gic.h>
    #include <dt-bindings/interrupt-controller/irq.h>
    #include <dt-bindings/mfd/max77620.h>
    #include <dt-bindings/thermal/thermal.h>

    i2c@7000d000 {
        reg = <0x7000d000 0x100>;
        #address-cells = <1>;
        #size-cells = <0>;

        pmic: pmic@3c {
            compatible = "maxim,max77620";
            reg = <0x3c>;

            interrupt-parent = <&intc>;
            interrupts = <GIC_SPI 86 IRQ_TYPE_NONE>;

            #interrupt-cells = <2>;
            interrupt-controller;

            #gpio-cells = <2>;
            gpio-controller;

            #thermal-sensor-cells = <0>;

            pinctrl-names = "default";
            pinctrl-0 = <&default>;

            fps {
                fps0 {
                    maxim,shutdown-fps-time-period-us = <1280>;
                    maxim,fps-event-source = <MAX77620_FPS_EVENT_SRC_EN1>;
                };

                fps1 {
                    maxim,shutdown-fps-time-period-us = <1280>;
                    maxim,fps-event-source = <MAX77620_FPS_EVENT_SRC_EN0>;
                };

                fps2 {
                    maxim,shutdown-fps-time-period-us = <1280>;
                    maxim,fps-event-source = <MAX77620_FPS_EVENT_SRC_SW>;
                };
            };

            default: pinmux {
                gpio0 {
                    pins = "gpio0";
                    function = "gpio";
                };

                gpio1 {
                    pins = "gpio1";
                    function = "fps-out";
                    maxim,active-fps-source = <MAX77620_FPS_SRC_0>;
                };

                gpio2 {
                    pins = "gpio2";
                    function = "fps-out";
                    maxim,active-fps-source = <MAX77620_FPS_SRC_1>;
                };
            };

            regulators {
                in-ldo0-1-supply = <&sd2>;
                in-ldo7-8-supply = <&sd2>;

                sd0 {
                    regulator-name = "vdd-core";
                    regulator-min-microvolt = <600000>;
                    regulator-max-microvolt = <1400000>;
                    regulator-boot-on;
                    regulator-always-on;
                    maxim,active-fps-source = <MAX77620_FPS_SRC_1>;
                };

                sd1 {
                   regulator-name = "vddio-ddr";
                   regulator-min-microvolt = <1200000>;
                   regulator-max-microvolt = <1200000>;
                   regulator-always-on;
                   regulator-boot-on;
                   maxim,active-fps-source = <MAX77620_FPS_SRC_0>;
                };

                sd2 {
                    regulator-name = "vdd-pre-reg";
                    regulator-min-microvolt = <1350000>;
                    regulator-max-microvolt = <1350000>;
                };

                sd3 {
                    regulator-name = "vdd-1v8";
                    regulator-min-microvolt = <1800000>;
                    regulator-max-microvolt = <1800000>;
                    regulator-always-on;
                    regulator-boot-on;
                };

                ldo0 {
                    regulator-name = "avdd-sys";
                    regulator-min-microvolt = <1200000>;
                    regulator-max-microvolt = <1200000>;
                    regulator-always-on;
                    regulator-boot-on;
                };

                ldo1 {
                    regulator-name = "vdd-pex";
                    regulator-min-microvolt = <1050000>;
                    regulator-max-microvolt = <1050000>;
                };

                ldo2 {
                    regulator-name = "vddio-sdmmc3";
                    regulator-min-microvolt = <1800000>;
                    regulator-max-microvolt = <3300000>;
                };

                ldo3 {
                    regulator-name = "vdd-cam-hv";
                    regulator-min-microvolt = <2800000>;
                    regulator-max-microvolt = <2800000>;
                };

                ldo4 {
                    regulator-name = "vdd-rtc";
                    regulator-min-microvolt = <1250000>;
                    regulator-max-microvolt = <1250000>;
                    regulator-always-on;
                    regulator-boot-on;
                };

                ldo5 {
                    regulator-name = "avdd-ts-hv";
                    regulator-min-microvolt = <3000000>;
                    regulator-max-microvolt = <3000000>;
                };

                ldo6 {
                    regulator-name = "vdd-ts";
                    regulator-min-microvolt = <1800000>;
                    regulator-max-microvolt = <1800000>;
                    regulator-always-on;
                    regulator-boot-on;
                };

                ldo7 {
                    regulator-name = "vdd-gen-pll-edp";
                    regulator-min-microvolt = <1050000>;
                    regulator-max-microvolt = <1050000>;
                    regulator-always-on;
                    regulator-boot-on;
                };

                ldo8 {
                    regulator-name = "vdd-hdmi-dp";
                    regulator-min-microvolt = <1050000>;
                    regulator-max-microvolt = <1050000>;
                };
            };
        };
    };

    thermal-zones {
        pmic-thermal {
            polling-delay = <0>;
            polling-delay-passive = <0>;
            thermal-sensors = <&pmic>;

            trips {
                pmic_die_warn_temp_thresh: hot-die {
                    temperature = <120000>;
                    type = "hot";
                    hysteresis = <0>;
                };

                pmic_die_crit_temp_thresh: critical-die {
                    temperature = <140000>;
                    type = "critical";
                    hysteresis = <0>;
                };
            };

            cooling-maps {
                map0 {
                    trip = <&pmic_die_warn_temp_thresh>;
                    cooling-device = <&cool_dev THERMAL_NO_LIMIT
                                                THERMAL_NO_LIMIT>;
                    contribution = <100>;
                };
            };
        };
    };