[PATCH 0/2] Add the clock stretching i2c property

[PATCH 0/2] Add the clock stretching i2c property

[Andi Shyti]

Hello,

fter a discussion between Krzysztof and Ryan[*], it has become
apparent that the i2c binding is lacking the definition of a
property that needs to be added at a more generic level. This
property is also used by the mpc i2c controller, which has been
updated in the second patch.

As it has been several years since I worked with DTSs, I hope
that I have done everything correctly.

Thank you,
Andi

[*] https://lore.kernel.org/all/c41ee6b5-ddb4-1253-de54-a295b3bab2cc@linaro.org/

Andi Shyti (2):
  dt-bindings: i2c: Add the clock stretching property
  i2c: mpc: Use the i2c-scl-clk-low-timeout-ms property

 Documentation/devicetree/bindings/i2c/i2c-mpc.yaml | 12 ++++++------
 Documentation/devicetree/bindings/i2c/i2c.txt      |  9 +++++++++
 drivers/i2c/busses/i2c-mpc.c                       |  3 ++-
 3 files changed, 17 insertions(+), 7 deletions(-)

-- 
2.39.2

[PATCH 1/2] dt-bindings: i2c: Add the clock stretching property

[Andi Shyti]

The I2C specification allows for the clock line to be held low
for a specified timeout to force the slave device into a 'wait'
mode. This feature is known as 'Clock stretching' and is
optional.

In the NXP I2C specification, clock stretching is described as
the process of pausing a transaction by holding the SCL line LOW.
The transaction can only continue when the line is released HIGH
again.[*] However, most target devices do not include an SCL
driver and are therefore unable to stretch the clock.

Add the following properties:

 - i2c-scl-clk-low-timeout-ms: This property specifies the
   duration, in milliseconds, for which the clock is kept low and
   a client needs to detect a forced waiting state.

 - i2c-scl-has-clk-low-timeout: This property specifies whether
    the I2C controller implements the clock stretching property.

It's important to note that this feature should not be confused
with the SMBUS clock timeout, which serves a similar function but
specifies a timeout of 25-35ms. The I2C specification does not
recommend any specific timeout.

[*] NXP, UM10204 - I2C-bus specification and user manual
    Rev. 7.0, 1 October 2021, chapter 3.1.9.

Signed-off-by: Andi Shyti <andi.shyti@kernel.org>
---
 Documentation/devicetree/bindings/i2c/i2c.txt | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/devicetree/bindings/i2c/i2c.txt b/Documentation/devicetree/bindings/i2c/i2c.txt
index fc3dd7ec0445..12c311f0e831 100644
--- a/Documentation/devicetree/bindings/i2c/i2c.txt
+++ b/Documentation/devicetree/bindings/i2c/i2c.txt
@@ -45,6 +45,15 @@ wants to support one of the below features, it should adapt these bindings.
 	Number of nanoseconds the SCL signal takes to rise; t(r) in the I2C
 	specification.
 
+- i2c-scl-clk-low-timeout-ms
+	Number of miliseconds the clock line needs to be pulled down in order
+	to force a waiting state.
+
+- i2c-scl-has-clk-low-timeout
+	Boolean value that indicates whether the controller implements the
+	feature of wait induction through SCL low, with the timeout being
+	implemented internally by the controller.
+
 - i2c-sda-falling-time-ns
 	Number of nanoseconds the SDA signal takes to fall; t(f) in the I2C
 	specification.
-- 
2.39.2

[PATCH 2/2] i2c: mpc: Use the i2c-scl-clk-low-timeout-ms property

[Andi Shyti]

Now we have the i2c-scl-clk-low-timeout-ms property defined in
the binding. Use it and remove the previous "fsl,timeout".

Signed-off-by: Andi Shyti <andi.shyti@kernel.org>
Cc: Chris Packham <chris.packham@alliedtelesis.co.nz>
---
 Documentation/devicetree/bindings/i2c/i2c-mpc.yaml | 12 ++++++------
 drivers/i2c/busses/i2c-mpc.c                       |  3 ++-
 2 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/Documentation/devicetree/bindings/i2c/i2c-mpc.yaml b/Documentation/devicetree/bindings/i2c/i2c-mpc.yaml
index 018e1b944424..c01547585456 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-mpc.yaml
+++ b/Documentation/devicetree/bindings/i2c/i2c-mpc.yaml
@@ -41,11 +41,6 @@ properties:
       if defined, the clock settings from the bootloader are
       preserved (not touched)
 
-  fsl,timeout:
-    $ref: /schemas/types.yaml#/definitions/uint32
-    description: |
-      I2C bus timeout in microseconds
-
   fsl,i2c-erratum-a004447:
     $ref: /schemas/types.yaml#/definitions/flag
     description: |
@@ -53,6 +48,11 @@ properties:
       says that the standard i2c recovery scheme mechanism does
       not work and an alternate implementation is needed.
 
+  i2c-scl-clk-low-timeout-ms:
+    description:
+      Indicates the SCL timeouts which used to force the client
+      into a waiting state
+
 required:
   - compatible
   - reg
@@ -95,6 +95,6 @@ examples:
         interrupts = <43 2>;
         interrupt-parent = <&mpic>;
         clock-frequency = <400000>;
-        fsl,timeout = <10000>;
+        i2c-scl-clk-low-timeout-ms = <10000>;
     };
 ...
diff --git a/drivers/i2c/busses/i2c-mpc.c b/drivers/i2c/busses/i2c-mpc.c
index 81ac92bb4f6f..93c484efc3f3 100644
--- a/drivers/i2c/busses/i2c-mpc.c
+++ b/drivers/i2c/busses/i2c-mpc.c
@@ -846,7 +846,8 @@ static int fsl_i2c_probe(struct platform_device *op)
 			mpc_i2c_setup_8xxx(op->dev.of_node, i2c, clock);
 	}
 
-	prop = of_get_property(op->dev.of_node, "fsl,timeout", &plen);
+	prop = of_get_property(op->dev.of_node,
+			       "i2c-scl-clk-low-timeout-ms", &plen);
 	if (prop && plen == sizeof(u32)) {
 		mpc_ops.timeout = *prop * HZ / 1000000;
 		if (mpc_ops.timeout < 5)
-- 
2.39.2

Re: [PATCH 1/2] dt-bindings: i2c: Add the clock stretching property

[Krzysztof Kozlowski]

On 12/03/2023 14:19, Andi Shyti wrote:
> The I2C specification allows for the clock line to be held low
> for a specified timeout to force the slave device into a 'wait'
> mode. This feature is known as 'Clock stretching' and is
> optional.
> 
> In the NXP I2C specification, clock stretching is described as
> the process of pausing a transaction by holding the SCL line LOW.
> The transaction can only continue when the line is released HIGH
> again.[*] However, most target devices do not include an SCL
> driver and are therefore unable to stretch the clock.
> 
> Add the following properties:
> 
>  - i2c-scl-clk-low-timeout-ms: This property specifies the
>    duration, in milliseconds, for which the clock is kept low and
>    a client needs to detect a forced waiting state.
> 
>  - i2c-scl-has-clk-low-timeout: This property specifies whether
>     the I2C controller implements the clock stretching property.
> 
> It's important to note that this feature should not be confused
> with the SMBUS clock timeout, which serves a similar function but
> specifies a timeout of 25-35ms. The I2C specification does not
> recommend any specific timeout.
> 
> [*] NXP, UM10204 - I2C-bus specification and user manual
>     Rev. 7.0, 1 October 2021, chapter 3.1.9.
> 
> Signed-off-by: Andi Shyti <andi.shyti@kernel.org>
> ---
>  Documentation/devicetree/bindings/i2c/i2c.txt | 9 +++++++++
>  1 file changed, 9 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/i2c/i2c.txt b/Documentation/devicetree/bindings/i2c/i2c.txt
> index fc3dd7ec0445..12c311f0e831 100644
> --- a/Documentation/devicetree/bindings/i2c/i2c.txt
> +++ b/Documentation/devicetree/bindings/i2c/i2c.txt

Although the properties are still sometimes added here, but the bindings
are now in dtschema, so rather this should be updated:

https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/i2c/i2c-controller.yaml

> @@ -45,6 +45,15 @@ wants to support one of the below features, it should adapt these bindings.
>  	Number of nanoseconds the SCL signal takes to rise; t(r) in the I2C
>  	specification.
>  
> +- i2c-scl-clk-low-timeout-ms
> +	Number of miliseconds the clock line needs to be pulled down in order
> +	to force a waiting state.
> +
> +- i2c-scl-has-clk-low-timeout
> +	Boolean value that indicates whether the controller implements the
> +	feature of wait induction through SCL low, with the timeout being
> +	implemented internally by the controller.
> +
>  - i2c-sda-falling-time-ns
>  	Number of nanoseconds the SDA signal takes to fall; t(f) in the I2C
>  	specification.

Best regards,
Krzysztof

Re: [PATCH 2/2] i2c: mpc: Use the i2c-scl-clk-low-timeout-ms property

[Krzysztof Kozlowski]

On 12/03/2023 14:19, Andi Shyti wrote:
> Now we have the i2c-scl-clk-low-timeout-ms property defined in
> the binding. Use it and remove the previous "fsl,timeout".
> 
> Signed-off-by: Andi Shyti <andi.shyti@kernel.org>
> Cc: Chris Packham <chris.packham@alliedtelesis.co.nz>
> ---
>  Documentation/devicetree/bindings/i2c/i2c-mpc.yaml | 12 ++++++------
>  drivers/i2c/busses/i2c-mpc.c                       |  3 ++-
>  2 files changed, 8 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/i2c/i2c-mpc.yaml b/Documentation/devicetree/bindings/i2c/i2c-mpc.yaml
> index 018e1b944424..c01547585456 100644
> --- a/Documentation/devicetree/bindings/i2c/i2c-mpc.yaml
> +++ b/Documentation/devicetree/bindings/i2c/i2c-mpc.yaml
> @@ -41,11 +41,6 @@ properties:
>        if defined, the clock settings from the bootloader are
>        preserved (not touched)
>  
> -  fsl,timeout:
> -    $ref: /schemas/types.yaml#/definitions/uint32
> -    description: |
> -      I2C bus timeout in microseconds

Instead:
  deprecated: true

> -
>    fsl,i2c-erratum-a004447:
>      $ref: /schemas/types.yaml#/definitions/flag
>      description: |
> @@ -53,6 +48,11 @@ properties:
>        says that the standard i2c recovery scheme mechanism does
>        not work and an alternate implementation is needed.
>  
> +  i2c-scl-clk-low-timeout-ms:
> +    description:
> +      Indicates the SCL timeouts which used to force the client
> +      into a waiting state

No need for this - will be coming from dtschema.

> +
>  required:
>    - compatible
>    - reg
> @@ -95,6 +95,6 @@ examples:
>          interrupts = <43 2>;
>          interrupt-parent = <&mpic>;
>          clock-frequency = <400000>;
> -        fsl,timeout = <10000>;
> +        i2c-scl-clk-low-timeout-ms = <10000>;
>      };
>  ...
> diff --git a/drivers/i2c/busses/i2c-mpc.c b/drivers/i2c/busses/i2c-mpc.c
> index 81ac92bb4f6f..93c484efc3f3 100644
> --- a/drivers/i2c/busses/i2c-mpc.c
> +++ b/drivers/i2c/busses/i2c-mpc.c
> @@ -846,7 +846,8 @@ static int fsl_i2c_probe(struct platform_device *op)
>  			mpc_i2c_setup_8xxx(op->dev.of_node, i2c, clock);
>  	}
>  
> -	prop = of_get_property(op->dev.of_node, "fsl,timeout", &plen);
> +	prop = of_get_property(op->dev.of_node,
> +			       "i2c-scl-clk-low-timeout-ms", &plen);

That's an ABI break. You need to keep old code as fallback.


Best regards,
Krzysztof

Re: [PATCH 2/2] i2c: mpc: Use the i2c-scl-clk-low-timeout-ms property

[Krzysztof Kozlowski]

On 12/03/2023 14:19, Andi Shyti wrote:
> Now we have the i2c-scl-clk-low-timeout-ms property defined in
> the binding. Use it and remove the previous "fsl,timeout".
> 
> Signed-off-by: Andi Shyti <andi.shyti@kernel.org>
> Cc: Chris Packham <chris.packham@alliedtelesis.co.nz>
> ---
>  Documentation/devicetree/bindings/i2c/i2c-mpc.yaml | 12 ++++++------

Ah, and I forgot: bindings are always separate patches from driver
changes. Cannot be mixed.

Best regards,
Krzysztof

Re: [PATCH 2/2] i2c: mpc: Use the i2c-scl-clk-low-timeout-ms property

[Andi Shyti]

Hi Krzysztof,

On Sun, Mar 12, 2023 at 02:44:47PM +0100, Krzysztof Kozlowski wrote:
> On 12/03/2023 14:19, Andi Shyti wrote:
> > Now we have the i2c-scl-clk-low-timeout-ms property defined in
> > the binding. Use it and remove the previous "fsl,timeout".
> > 
> > Signed-off-by: Andi Shyti <andi.shyti@kernel.org>
> > Cc: Chris Packham <chris.packham@alliedtelesis.co.nz>
> > ---
> >  Documentation/devicetree/bindings/i2c/i2c-mpc.yaml | 12 ++++++------
> 
> Ah, and I forgot: bindings are always separate patches from driver
> changes. Cannot be mixed.

Thanks for all your comments, will send a v2.

Andi