[1/2] dt-bindings: i2c: nxp,pca9541: convert to DT schema

Convert the bindings for NXP PCA9541 I2C bus master selector to DT
schema.

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

---

Changes in v2:
1. New patch (Doug)
---
 .../devicetree/bindings/i2c/nxp,pca9541.txt   | 29 ----------
 .../devicetree/bindings/i2c/nxp,pca9541.yaml  | 56 +++++++++++++++++++
 2 files changed, 56 insertions(+), 29 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/i2c/nxp,pca9541.txt
 create mode 100644 Documentation/devicetree/bindings/i2c/nxp,pca9541.yaml

Hi!

2023-07-22 at 11:57, Krzysztof Kozlowski wrote:
> Convert the bindings for NXP PCA9541 I2C bus master selector to DT
> schema.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

Thanks for doing this conversion!

Acked-by: Peter Rosin <peda@axentia.se>

> 
> ---
> 
> Changes in v2:
> 1. New patch (Doug)
> ---
>  .../devicetree/bindings/i2c/nxp,pca9541.txt   | 29 ----------
>  .../devicetree/bindings/i2c/nxp,pca9541.yaml  | 56 +++++++++++++++++++
>  2 files changed, 56 insertions(+), 29 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/i2c/nxp,pca9541.txt
>  create mode 100644 Documentation/devicetree/bindings/i2c/nxp,pca9541.yaml
> 
> diff --git a/Documentation/devicetree/bindings/i2c/nxp,pca9541.txt b/Documentation/devicetree/bindings/i2c/nxp,pca9541.txt
> deleted file mode 100644
> index 42bfc09c8918..000000000000
> --- a/Documentation/devicetree/bindings/i2c/nxp,pca9541.txt
> +++ /dev/null
> @@ -1,29 +0,0 @@
> -* NXP PCA9541 I2C bus master selector
> -
> -Required Properties:
> -
> -  - compatible: Must be "nxp,pca9541"
> -
> -  - reg: The I2C address of the device.
> -
> -  The following required properties are defined externally:
> -
> -  - I2C arbitration bus node. See i2c-arb.txt in this directory.
> -
> -
> -Example:
> -
> -	i2c-arbitrator@74 {
> -		compatible = "nxp,pca9541";
> -		reg = <0x74>;
> -
> -		i2c-arb {
> -			#address-cells = <1>;
> -			#size-cells = <0>;
> -
> -			eeprom@54 {
> -				compatible = "atmel,24c08";
> -				reg = <0x54>;
> -			};
> -		};
> -	};
> diff --git a/Documentation/devicetree/bindings/i2c/nxp,pca9541.yaml b/Documentation/devicetree/bindings/i2c/nxp,pca9541.yaml
> new file mode 100644
> index 000000000000..b65c25c1a435
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/i2c/nxp,pca9541.yaml
> @@ -0,0 +1,56 @@
> +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/i2c/nxp,pca9541.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: NXP PCA9541 I2C bus master selector
> +
> +maintainers:
> +  - Peter Rosin <peda@axentia.se>
> +
> +properties:
> +  compatible:
> +    const: nxp,pca9541
> +
> +  reg:
> +    maxItems: 1
> +
> +  i2c-arb:
> +    type: object
> +    $ref: /schemas/i2c/i2c-controller.yaml
> +    unevaluatedProperties: false
> +    description:
> +      I2C arbitration bus node.
> +
> +required:
> +  - compatible
> +  - reg
> +  - i2c-arb
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/gpio/gpio.h>
> +    #include <dt-bindings/interrupt-controller/irq.h>
> +
> +    i2c {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        i2c-arbitrator@74 {
> +            compatible = "nxp,pca9541";
> +            reg = <0x74>;
> +
> +            i2c-arb {
> +                #address-cells = <1>;
> +                #size-cells = <0>;
> +
> +                eeprom@54 {
> +                    compatible = "atmel,24c08";
> +                    reg = <0x54>;
> +                };
> +            };
> +        };
> +    };

On Sat, Jul 22, 2023 at 11:57:09AM +0200, Krzysztof Kozlowski wrote:
> Convert the bindings for NXP PCA9541 I2C bus master selector to DT
> schema.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

Reviewed-by: Conor Dooley <conor.dooley@microchip.com>

Thanks,
Conor.

On Sat, Jul 22, 2023 at 11:57:10AM +0200, Krzysztof Kozlowski wrote:

> +description: |
> +  This uses GPIO lines and a challenge & response mechanism to arbitrate who is
> +  the master of an I2C bus in a multimaster situation.
> +
> +  In many cases using GPIOs to arbitrate is not needed and a design can use the
> +  standard I2C multi-master rules.  Using GPIOs is generally useful in the case
> +  where there is a device on the bus that has errata and/or bugs that makes
> +  standard multimaster mode not feasible.
> +
> +  Note that this scheme works well enough but has some downsides:
> +   * It is nonstandard (not using standard I2C multimaster)
> +   * Having two masters on a bus in general makes it relatively hard to debug
> +     problems (hard to tell if i2c issues were caused by one master, another,
> +     or some device on the bus).
> +
> +  Algorithm:
> +  All masters on the bus have a 'bus claim' line which is an output that the
> +  others can see. These are all active low with pull-ups enabled.  We'll
> +  describe these lines as:
> +   * OUR_CLAIM: output from us signaling to other hosts that we want the bus
> +   * THEIR_CLAIMS: output from others signaling that they want the bus
> +
> +  The basic algorithm is to assert your line when you want the bus, then make
> +  sure that the other side doesn't want it also.  A detailed explanation is
> +  best done with an example.
> +
> +  Let's say we want to claim the bus.  We:
> +  1. Assert OUR_CLAIM.
> +  2. Waits a little bit for the other sides to notice (slew time, say 10
> +     microseconds).
> +  3. Check THEIR_CLAIMS.  If none are asserted then the we have the bus and we
> +     are done.
> +  4. Otherwise, wait for a few milliseconds and see if THEIR_CLAIMS are released.
> +  5. If not, back off, release the claim and wait for a few more milliseconds.
> +  6. Go back to 1 (until retry time has expired).

> +  their-claim-gpios:
> +    minItems: 1
> +    maxItems: 2
> +    description:
> +      The GPIOs that the other sides use to claim the bus.  Note that some
> +      implementations may only support a single other master.

Where does the maxItems: 2 come from?

On 22/07/2023 12:50, Peter Rosin wrote:
>> +  their-claim-gpios:
>> +    minItems: 1
>> +    maxItems: 2
> 
> I don't think there should be a max here? There is no reason for not
> supporting more than 2 other masters. True, the current Linux driver
> happens to only support 1 other master. So if there should be a max,
> I guess it should be 1? But that feels like an implementation
> detail of the driver. The Linux driver bails out with an error if
> there are more than one other master, it's the only thing it does
> with that 2nd 'their-claim-goios' ref.

I will make it some higher number.

Best regards,
Krzysztof

Hi Krzysztof,

On Sat, Jul 22, 2023 at 11:57:09AM +0200, Krzysztof Kozlowski wrote:
> Convert the bindings for NXP PCA9541 I2C bus master selector to DT
> schema.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>

Acked-by: Andi Shyti <andi.shyti@kernel.org> 

Andi