Documentation/devicetree/bindings/mfd/gateworks-gsc.yaml

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

title: Gateworks System Controller

description: |
  The Gateworks System Controller (GSC) is a device present across various
  Gateworks product families that provides a set of system related features
  such as the following (refer to the board hardware user manuals to see what
  features are present)
   - Watchdog Timer
   - GPIO
   - Pushbutton controller
   - Hardware monitor with ADC's for temperature and voltage rails and
     fan controller

maintainers:
  - Tim Harvey <tharvey@gateworks.com>
  - Robert Jones <rjones@gateworks.com>

properties:
  $nodename:
    pattern: "gsc@[0-9a-f]{1,2}"
  compatible:
    const: gw,gsc

  reg:
    description: I2C device address
    maxItems: 1

  interrupts:
    maxItems: 1

  interrupt-controller: true

  "#interrupt-cells":
    const: 1

  "#address-cells":
    const: 1

  "#size-cells":
    const: 0

  adc:
    type: object
    description: Optional hardware monitoring module

    properties:
      compatible:
        const: gw,gsc-adc

      "#address-cells":
        const: 1

      "#size-cells":
        const: 0

    patternProperties:
      "^channel@[0-9]+$":
        type: object
        description: |
          Properties for a single ADC which can report cooked values
          (i.e. temperature sensor based on thermister), raw values
          (i.e. voltage rail with a pre-scaling resistor divider).

        properties:
          reg:
            description: Register of the ADC
            maxItems: 1

          label:
            description: Name of the ADC input

          gw,mode:
            description: |
              conversion mode:
                0 - temperature, in C*10
                1 - pre-scaled voltage value
                2 - scaled voltage based on an optional resistor divider
                    and optional offset
            $ref: /schemas/types.yaml#/definitions/uint32
            enum: [0, 1, 2]

          gw,voltage-divider-ohms:
            description: Values of resistors for divider on raw ADC input
            maxItems: 2
            items:
             minimum: 1000
             maximum: 1000000

          gw,voltage-offset-microvolt:
            description: |
              A positive voltage offset to apply to a raw ADC
              (i.e. to compensate for a diode drop).
            minimum: 0
            maximum: 1000000

        required:
          - gw,mode
          - reg
          - label

    required:
      - compatible
      - "#address-cells"
      - "#size-cells"

patternProperties:
  "^fan-controller@[0-9a-f]+$":
    type: object
    description: Optional fan controller

    properties:
      compatible:
        const: gw,gsc-fan

      "#address-cells":
        const: 1

      "#size-cells":
        const: 0

      reg:
        description: The fan controller base address
        maxItems: 1

    required:
      - compatible
      - reg
      - "#address-cells"
      - "#size-cells"

required:
  - compatible
  - reg
  - interrupts
  - interrupt-controller
  - "#interrupt-cells"
  - "#address-cells"
  - "#size-cells"

examples:
  - |
    #include <dt-bindings/gpio/gpio.h>
    i2c {
        #address-cells = <1>;
        #size-cells = <0>;

        gsc@20 {
            compatible = "gw,gsc";
            reg = <0x20>;
            interrupt-parent = <&gpio1>;
            interrupts = <4 GPIO_ACTIVE_LOW>;
            interrupt-controller;
            #interrupt-cells = <1>;
            #address-cells = <1>;
            #size-cells = <0>;

            adc {
                compatible = "gw,gsc-adc";
                #address-cells = <1>;
                #size-cells = <0>;

                channel@0 { /* A0: Board Temperature */
                    reg = <0x00>;
                    label = "temp";
                    gw,mode = <0>;
                };

                channel@2 { /* A1: Input Voltage (raw ADC) */
                    reg = <0x02>;
                    label = "vdd_vin";
                    gw,mode = <1>;
                    gw,voltage-divider-ohms = <22100 1000>;
                    gw,voltage-offset-microvolt = <800000>;
                };

                channel@b { /* A2: Battery voltage */
                    reg = <0x0b>;
                    label = "vdd_bat";
                    gw,mode = <1>;
                };
            };

            fan-controller@2c {
                #address-cells = <1>;
                #size-cells = <0>;
                compatible = "gw,gsc-fan";
                reg = <0x2c>;
            };
        };
    };