[v1,1/2] dt-bindings: mfd: Document QTI I2C PMIC controller

The Qualcomm Technologies, Inc. I2C PMIC Controller is used by
multi-function PMIC devices which communicate over the I2C bus.  The
controller enumerates all child nodes as platform devices, and
instantiates a regmap interface for them to communicate over the I2C
bus.

The controller also controls interrupts for all of the children platform
devices.  The controller handles the summary interrupt by deciphering
which peripheral triggered the interrupt, and which of the peripheral
interrupts were triggered.  Finally, it calls the interrupt handlers for
each of the virtual interrupts that were registered.

Signed-off-by: Guru Das Srinagesh <gurus@codeaurora.org>
---
Changes from v0:
- Fixed "FATAL ERROR: Unable to parse input tree" error thrown by `make
  dt_binding_check`.

 .../devicetree/bindings/mfd/qcom,i2c-pmic.yaml     | 86 ++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/mfd/qcom,i2c-pmic.yaml

On Tue, 28 Apr 2020, Guru Das Srinagesh wrote:

> The Qualcomm Technologies, Inc. I2C PMIC Controller is used by
> multi-function PMIC devices which communicate over the I2C bus.  The
> controller enumerates all child nodes as platform devices, and
> instantiates a regmap interface for them to communicate over the I2C
> bus.
> 
> The controller also controls interrupts for all of the children platform
> devices.  The controller handles the summary interrupt by deciphering
> which peripheral triggered the interrupt, and which of the peripheral
> interrupts were triggered.  Finally, it calls the interrupt handlers for
> each of the virtual interrupts that were registered.
> 
> Signed-off-by: Guru Das Srinagesh <gurus@codeaurora.org>
> ---
> Changes from v0:
> - Fixed "FATAL ERROR: Unable to parse input tree" error thrown by `make
>   dt_binding_check`.
> 
>  .../devicetree/bindings/mfd/qcom,i2c-pmic.yaml     | 86 ++++++++++++++++++++++
>  1 file changed, 86 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/mfd/qcom,i2c-pmic.yaml
> 
> diff --git a/Documentation/devicetree/bindings/mfd/qcom,i2c-pmic.yaml b/Documentation/devicetree/bindings/mfd/qcom,i2c-pmic.yaml
> new file mode 100644
> index 0000000..42482af
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mfd/qcom,i2c-pmic.yaml
> @@ -0,0 +1,86 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/mfd/qcom,i2c-pmic.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Qualcomm Technologies, Inc. I2C PMIC Interrupt Controller Platform Independent Bindings
> +
> +description: |
> +  The I2C PMIC Controller is used by multi-function PMIC devices which
> +  communicate over the I2C bus. An I2C PMIC controller node typically contains
> +  one or more child nodes representing the device's peripherals. Each of the
> +  peripherals typically has its own driver on the platform bus and will be
> +  enumerated by this controller. The controller exposes a regmap to the
> +  peripherals to communicate over the I2C bus.
> +
> +  The controller also controls interrupts for all of the peripherals on the
> +  bus. The controller takes a summary interrupt, deciphers which peripheral
> +  triggered the interrupt, and which of the peripheral's interrupts were
> +  triggered. Finally, it calls the handlers for each of the virtual interrupts
> +  that were registered.
> +
> +  This document describes the common platform independent bindings that apply
> +  to all I2C PMIC interrupt controllers.
> +
> +maintainers:
> +  - Guru Das Srinagesh <gurus@codeaurora.org>
> +
> +properties:
> +  compatible:
> +    const: qcom,i2c-pmic
> +
> +  reg:
> +    description: 7-bit I2C address of the device.
> +    maxItems: 1
> +
> +  interrupts:
> +    description: Summary interrupt specifier.
> +
> +  interrupt-controller:
> +    description: Flag indicating that this device is an interrupt controller.
> +
> +  "#interrupt-cells":
> +    description: Number of cells to encode an interrupt source.
> +
> +  qcom,periph-map:
> +    description: |
> +      A contiguous list of u32 arrays where each element specifies the base
> +      address of a single peripheral within the chip. This provides a mapping
> +      between the summary status register bits and peripheral addresses as each
> +      bit in the summary status register represents a peripheral.
> +
> +      The number of arrays should match the number of summary registers with up
> +      to 8 elements each. Within each array, One element per bit of the summary
> +      status register in order from the least sigificant bit to the most
> +      significant bit.
> +    $ref: /schemas/types.yaml#/definitions/uint32-array
> +
> +  pinctrl-names:
> +    const: default
> +
> +  pinctrl-0:
> +    description: phandle of the pin configuration.
> +    $ref: /schemas/types.yaml#/definitions/phandle
> +
> +required:
> +  - compatible
> +  - reg
> +
> +examples:
> +  - |
> +    qcom,smb138x@8 {
> +      compatible = "qcom,i2c-pmic";
> +      reg = <0x8>;
> +      interrupt-parent = <&tlmm_pinmux>;
> +      interrupts = <83 0>;
> +      interrupt-controller;
> +      #interrupt-cells = <3>;
> +      pinctrl-names = "default";
> +      pinctrl-0 = <&smb_stat_active>;
> +      #address-cells = <1>;
> +      #size-cells = <0>;
> +      qcom,periph-map = <0x10 0x11 0x12 0x13 0x14 0x16 0x36>;

Please provide examples of this device's children.

> +    };
> +
> +...

On Tue, 28 Apr 2020 17:30:11 -0700, Guru Das Srinagesh wrote:
> The Qualcomm Technologies, Inc. I2C PMIC Controller is used by
> multi-function PMIC devices which communicate over the I2C bus.  The
> controller enumerates all child nodes as platform devices, and
> instantiates a regmap interface for them to communicate over the I2C
> bus.
> 
> The controller also controls interrupts for all of the children platform
> devices.  The controller handles the summary interrupt by deciphering
> which peripheral triggered the interrupt, and which of the peripheral
> interrupts were triggered.  Finally, it calls the interrupt handlers for
> each of the virtual interrupts that were registered.
> 
> Signed-off-by: Guru Das Srinagesh <gurus@codeaurora.org>
> ---
> Changes from v0:
> - Fixed "FATAL ERROR: Unable to parse input tree" error thrown by `make
>   dt_binding_check`.
> 
>  .../devicetree/bindings/mfd/qcom,i2c-pmic.yaml     | 86 ++++++++++++++++++++++
>  1 file changed, 86 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/mfd/qcom,i2c-pmic.yaml
> 

My bot found errors running 'make dt_binding_check' on your patch:

Documentation/devicetree/bindings/mfd/qcom,i2c-pmic.example.dts:19.11-23: Warning (reg_format): /example-0/qcom,smb138x@8:reg: property has invalid length (4 bytes) (#address-cells == 1, #size-cells == 1)
Documentation/devicetree/bindings/mfd/qcom,i2c-pmic.example.dt.yaml: Warning (pci_device_reg): Failed prerequisite 'reg_format'
Documentation/devicetree/bindings/mfd/qcom,i2c-pmic.example.dt.yaml: Warning (pci_device_bus_num): Failed prerequisite 'reg_format'
Documentation/devicetree/bindings/mfd/qcom,i2c-pmic.example.dt.yaml: Warning (simple_bus_reg): Failed prerequisite 'reg_format'
Documentation/devicetree/bindings/mfd/qcom,i2c-pmic.example.dt.yaml: Warning (i2c_bus_reg): Failed prerequisite 'reg_format'
Documentation/devicetree/bindings/mfd/qcom,i2c-pmic.example.dt.yaml: Warning (spi_bus_reg): Failed prerequisite 'reg_format'

See https://patchwork.ozlabs.org/patch/1278818

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure dt-schema is up to date:

pip3 install git+https://github.com/devicetree-org/dt-schema.git@master --upgrade

Please check and re-submit.