[PATCH v2 dt-schema 0/3] schemas: i2c: fix "smbus_alert" handling

[PATCH v2 dt-schema 0/3] schemas: i2c: fix "smbus_alert" handling

[Wolfram Sang]

"smbus_alert" is currently listed as an interrupt for targets. This is
wrong, it is an interrupt for the controller. The mistake (mea culpa!)
was already in the originating "i2c.txt" file in the Linux Kernel. Time
to fix it. Make small changes to descriptions to use inclusive language
while we are here.

Changes since v1:
* use "contains" instead of "items" in patch 2+3
* drop "irq" binding from patch 3
* checked with dt-doc-validate now

Thanks, Rob, for the support!


Wolfram Sang (3):
  schemas: i2c: reword descriptions for inclusive language
  schemas: i2c: clean up interrupt descriptions for I2C targets
  schemas: i2c: add generic interrupt name for I2C controllers

 dtschema/schemas/i2c/i2c-controller.yaml | 37 +++++++++++++++++-------
 1 file changed, 26 insertions(+), 11 deletions(-)

-- 
2.43.0

[PATCH v2 dt-schema 1/3] schemas: i2c: reword descriptions for inclusive language

[Wolfram Sang]

Changing bindings is hard, changing descriptions is easy. Let's start
with the low-hanging fruits and use the official I2C terminology (as of
specs v7) in the descriptions. Drop a superfluous 'a' from the
description of 'reg' for targets.

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
---
 dtschema/schemas/i2c/i2c-controller.yaml | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/dtschema/schemas/i2c/i2c-controller.yaml b/dtschema/schemas/i2c/i2c-controller.yaml
index 9670082..e475ead 100644
--- a/dtschema/schemas/i2c/i2c-controller.yaml
+++ b/dtschema/schemas/i2c/i2c-controller.yaml
@@ -99,7 +99,7 @@ properties:
   multi-master:
     type: boolean
     description:
-      States that there is another master active on this bus. The OS can use
+      States that there is another controller active on this bus. The OS can use
       this information to adapt power management to keep the arbitration awake
       all the time, for example. Can not be combined with 'single-master'.
 
@@ -116,9 +116,9 @@ properties:
   single-master:
     type: boolean
     description:
-      States that there is no other master active on this bus. The OS can use
-      this information to detect a stalled bus more reliably, for example. Can
-      not be combined with 'multi-master'.
+      States that there is no other controller active on this bus. The OS can
+      use this information to detect a stalled bus more reliably, for example.
+      Can not be combined with 'multi-master'.
 
   smbus:
     type: boolean
@@ -155,7 +155,7 @@ patternProperties:
                 - minimum: 0xc0000000
                   maximum: 0xc00003ff
         description: |
-          One or many I2C slave addresses. These are usually a 7 bit addresses.
+          One or many I2C target addresses. These are usually 7 bit addresses.
           However, flags can be attached to an address. I2C_TEN_BIT_ADDRESS is
           used to mark a 10 bit address. It is needed to avoid the ambiguity
           between e.g. a 7 bit address of 0x50 and a 10 bit address of 0x050
@@ -172,7 +172,7 @@ patternProperties:
       interrupts:
         description:
           I2C core will treat "irq" interrupt (or the very first interrupt if
-          not using interrupt names) as primary interrupt for the slave.
+          not using interrupt names) as primary interrupt for the target.
 
       interrupt-names:
         anyOf:
-- 
2.43.0

[PATCH v2 dt-schema 2/3] schemas: i2c: clean up interrupt descriptions for I2C targets

[Wolfram Sang]

Schemas should be OS agnostic, so don't mention what the "I2C core" will
do because this only applies to Linux. Also, drop the generic
"smbus_alert" naming because this belongs to controllers not targets, so
we don't want to describe it here. Finally, use "contains" instead of
"items" because the enum is not exhaustive.

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
---
 dtschema/schemas/i2c/i2c-controller.yaml | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/dtschema/schemas/i2c/i2c-controller.yaml b/dtschema/schemas/i2c/i2c-controller.yaml
index e475ead..6dc73f8 100644
--- a/dtschema/schemas/i2c/i2c-controller.yaml
+++ b/dtschema/schemas/i2c/i2c-controller.yaml
@@ -171,20 +171,20 @@ patternProperties:
 
       interrupts:
         description:
-          I2C core will treat "irq" interrupt (or the very first interrupt if
-          not using interrupt names) as primary interrupt for the target.
+          If not using interrupt-names, the first interrupt will be treated as
+          the primary interrupt for the target.
 
       interrupt-names:
         anyOf:
           - {} # Any name is allowed.
-          - items:
+          - contains:
               enum:
                 - irq
                 - wakeup
-                - smbus_alert
             description:
-              Names which are recognized by I2C core, other names are left to
-              individual bindings.
+              Generic names are "irq" for the primary interrupt and "wakeup"
+              for the wakeup interrupt. Other names are left to individual
+              bindings.
 
       wakeup-source:
         description:
-- 
2.43.0

[PATCH v2 dt-schema 3/3] schemas: i2c: add generic interrupt name for I2C controllers

[Wolfram Sang]

"smbus_alert" is a generic interrupt name for controllers, so document
it.

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
---
 dtschema/schemas/i2c/i2c-controller.yaml | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/dtschema/schemas/i2c/i2c-controller.yaml b/dtschema/schemas/i2c/i2c-controller.yaml
index 6dc73f8..97d0aaa 100644
--- a/dtschema/schemas/i2c/i2c-controller.yaml
+++ b/dtschema/schemas/i2c/i2c-controller.yaml
@@ -90,6 +90,21 @@ properties:
       low-pass analog filter). Typical value should be above the normal i2c bus
       clock frequency (clock-frequency). Specified in Hz.
 
+  interrupts:
+    description:
+      If not using interrupt-names, the first interrupt will be treated as the
+      primary interrupt for the controller.
+
+  interrupt-names:
+    anyOf:
+      - {} # Any name is allowed.
+      - contains:
+          enum:
+            - smbus_alert
+        description:
+          Generic name is "smbus_alert" for the SMBusAlert signal. Other names
+          are left to individual bindings.
+
   mctp-controller:
     type: boolean
     description:
-- 
2.43.0

Re: [PATCH v2 dt-schema 0/3] schemas: i2c: fix "smbus_alert" handling

[Rob Herring]

On Thu, Aug 15, 2024 at 11:40:10PM +0200, Wolfram Sang wrote:
> "smbus_alert" is currently listed as an interrupt for targets. This is
> wrong, it is an interrupt for the controller. The mistake (mea culpa!)
> was already in the originating "i2c.txt" file in the Linux Kernel. Time
> to fix it. Make small changes to descriptions to use inclusive language
> while we are here.
> 
> Changes since v1:
> * use "contains" instead of "items" in patch 2+3
> * drop "irq" binding from patch 3
> * checked with dt-doc-validate now
> 
> Thanks, Rob, for the support!
> 
> 
> Wolfram Sang (3):
>   schemas: i2c: reword descriptions for inclusive language
>   schemas: i2c: clean up interrupt descriptions for I2C targets
>   schemas: i2c: add generic interrupt name for I2C controllers

Applied, thanks!

Rob