[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@xxxxxxxxxx>
---
 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