[V5,1/2] dt-bindings: iio: aw9610x: Add bindings for aw9610x sensor

From: shuaijie wang <wangshuaijie@awinic.com>

Add device tree bindings for aw9610x proximity sensor.

Signed-off-by: shuaijie wang <wangshuaijie@awinic.com>
---
 .../iio/proximity/awinic,aw9610x.yaml         | 61 +++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/iio/proximity/awinic,aw9610x.yaml

On 26/07/2024 08:13, wangshuaijie@awinic.com wrote:
> From: shuaijie wang <wangshuaijie@awinic.com>
> 
> Add device tree bindings for aw9610x proximity sensor.
> 
> Signed-off-by: shuaijie wang <wangshuaijie@awinic.com>
> ---

Reviewed-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>


---

<form letter>
This is an automated instruction, just in case, because many review tags
are being ignored. If you know the process, you can skip it (please do
not feel offended by me posting it here - no bad intentions intended).
If you do not know the process, here is a short explanation:

Please add Acked-by/Reviewed-by/Tested-by tags when posting new
versions, under or above your Signed-off-by tag. Tag is "received", when
provided in a message replied to you on the mailing list. Tools like b4
can help here. However, there's no need to repost patches *only* to add
the tags. The upstream maintainer will do that for tags received on the
version they apply.

https://elixir.bootlin.com/linux/v6.5-rc3/source/Documentation/process/submitting-patches.rst#L577
</form letter>

Best regards,
Krzysztof

On Fri, 26 Jul 2024 06:13:11 +0000
wangshuaijie@awinic.com wrote:

> From: shuaijie wang <wangshuaijie@awinic.com>
> 
> Add device tree bindings for aw9610x proximity sensor.
> 
> Signed-off-by: shuaijie wang <wangshuaijie@awinic.com>
> ---
>  .../iio/proximity/awinic,aw9610x.yaml         | 61 +++++++++++++++++++
>  1 file changed, 61 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/proximity/awinic,aw9610x.yaml

No wild cards in naming of dt-bindings or within the driver.
It goes wrong far too often because manufacturers love to release
new devices that have similar part names but are completely unrelated.

So we just name everything after the first part supported.

One other thing inline.

Jonathan

> 
> diff --git a/Documentation/devicetree/bindings/iio/proximity/awinic,aw9610x.yaml b/Documentation/devicetree/bindings/iio/proximity/awinic,aw9610x.yaml
> new file mode 100644
> index 000000000000..631b1fe5a900
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/proximity/awinic,aw9610x.yaml
> @@ -0,0 +1,61 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/iio/proximity/awinic,aw9610x.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Awinic's AW9610X capacitive proximity sensor

Title is less important for wild cards but even here I'd just name it
after one part + add "and similar" to the end of the title.

title: Awinic's AW96101 capacity proximity sensor and similar

> +
> +maintainers:
> +  - Wang Shuaijie <wangshuaijie@awinic.com>
> +
> +description: |
> +  Awinic's AW9610X proximity sensor.
> +  The specific absorption rate (SAR) is a metric that measures
> +  the degree of absorption of electromagnetic radiation emitted by
> +  wireless devices, such as mobile phones and tablets, by human tissue.
> +  In mobile phone applications, the proximity sensor is primarily
> +  used to detect the proximity of the human body to the phone. When the
> +  phone approaches the human body, it will actively reduce the transmit
> +  power of the antenna to keep the SAR within a safe range. Therefore,
> +  we also refer to the proximity sensor as a SAR sensor.
> +
> +properties:
> +  compatible:
> +    enum:
> +      - awinic,aw96103
> +      - awinic,aw96105
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    description:
> +      Generated by the device to announce that a close/far
> +      proximity event has happened.
> +    maxItems: 1
> +
> +  vcc-supply:
> +    description:
> +      Optional regulator for chip, 1.7V-3.6V.
> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts

vcc-supply should be required.
Note this is about the binding documenting the need for power vs
an optional powersupply which some devices have.  It is not
related to whether the dts files actually provide that supply
(though good if they do) because the regulator core will happily
provide you with a fake regulator on the assumption that any regulators
we don't know about must be turned on already.

A well written dts will use a fixed regulator to provide more
description to the drivers etc.

Jonathan

> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/irq.h>
> +    i2c {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +        proximity@12 {
> +            compatible = "awinic,aw96103";
> +            reg = <0x12>;
> +            interrupt-parent = <&gpio>;
> +            interrupts = <23 IRQ_TYPE_EDGE_FALLING>;
> +        };
> +    };