diff mbox series

dt-bindings: i2c: Remove obsolete i2c.txt

Message ID 20240222174343.3482354-2-robh@kernel.org
State New
Headers show
Series dt-bindings: i2c: Remove obsolete i2c.txt | expand

Commit Message

Rob Herring (Arm) Feb. 22, 2024, 5:43 p.m. UTC 
Everything in i2c.txt is covered by schemas/i2c/i2c-controller.yaml in
dtschema project, so remove i2c.txt and update links to it in the tree.

Signed-off-by: Rob Herring <robh@kernel.org>
---
Wolfram, you can take it or I can.

 .../bindings/gpio/gateworks,pld-gpio.txt      |   3 +-
 Documentation/devicetree/bindings/i2c/i2c.txt | 151 ------------------
 .../i2c/nvidia,tegra186-bpmp-i2c.yaml         |   3 +-
 .../devicetree/bindings/i3c/i3c.yaml          |   2 +-
 .../devicetree/bindings/sound/cs4341.txt      |   2 +-
 MAINTAINERS                                   |   1 -
 6 files changed, 4 insertions(+), 158 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/i2c/i2c.txt

Comments

Mark Brown Feb. 22, 2024, 5:48 p.m. UTC | #1 
On Thu, Feb 22, 2024 at 10:43:42AM -0700, Rob Herring wrote:
> Everything in i2c.txt is covered by schemas/i2c/i2c-controller.yaml in
> dtschema project, so remove i2c.txt and update links to it in the tree.

Acked-by: Mark Brown <broonie@kernel.org>
Wolfram Sang Feb. 22, 2024, 7:55 p.m. UTC | #2 
On Thu, Feb 22, 2024 at 10:43:42AM -0700, Rob Herring wrote:
> Everything in i2c.txt is covered by schemas/i2c/i2c-controller.yaml in
> dtschema project, so remove i2c.txt and update links to it in the tree.
> 
> Signed-off-by: Rob Herring <robh@kernel.org>

Differences to i2c.txt:

* In the schema, "clock-frequency" has a minimum of 1kHz and a maximum
  of 3MHz. Why? The specs do not say anything about a minimum freq and
  fastest speed mentioned in the docs is 5Mhz (Ultra fast mode).

* new binding "i2c-scl-clk-low-timeout-us" has a description which I do
  not understand. What is a waiting state?

* new binding "no-detect" is broken. At the least, it should be named
  something like "bus-fully-described" and then the OS can decide to
  leave out auto-detection mechanisms. If you are interested in the
  latter, you can simply disable class based instantiation on the host
  controller. No need to describe this in DT.

> Wolfram, you can take it or I can.

Once we are done, I guess it is better if you take it.

Thanks for the work,

   Wolfram
Rob Herring (Arm) Feb. 23, 2024, 4:55 p.m. UTC | #3 
On Thu, Feb 22, 2024 at 12:55 PM Wolfram Sang
<wsa+renesas@sang-engineering.com> wrote:
>
> On Thu, Feb 22, 2024 at 10:43:42AM -0700, Rob Herring wrote:
> > Everything in i2c.txt is covered by schemas/i2c/i2c-controller.yaml in
> > dtschema project, so remove i2c.txt and update links to it in the tree.
> >
> > Signed-off-by: Rob Herring <robh@kernel.org>
>
> Differences to i2c.txt:

Thanks

> * In the schema, "clock-frequency" has a minimum of 1kHz and a maximum
>   of 3MHz. Why? The specs do not say anything about a minimum freq and
>   fastest speed mentioned in the docs is 5Mhz (Ultra fast mode).

IIRC, the high speed mode originally topped out at 3MHz. I guess
that's been revised.

We can drop the minimum.

> * new binding "i2c-scl-clk-low-timeout-us" has a description which I do
>   not understand. What is a waiting state?

Shrug. May have to look at the MPC h/w that uses the property.

>
> * new binding "no-detect" is broken. At the least, it should be named
>   something like "bus-fully-described" and then the OS can decide to
>   leave out auto-detection mechanisms. If you are interested in the
>   latter, you can simply disable class based instantiation on the host
>   controller. No need to describe this in DT.

I've reverted the property now.

Rob
Wolfram Sang Feb. 23, 2024, 10:34 p.m. UTC | #4 
Hi Rob,

> > * In the schema, "clock-frequency" has a minimum of 1kHz and a maximum
> >   of 3MHz. Why? The specs do not say anything about a minimum freq and
> >   fastest speed mentioned in the docs is 5Mhz (Ultra fast mode).
> 
> IIRC, the high speed mode originally topped out at 3MHz. I guess
> that's been revised.

Hs-mode has a max of 3.4MHz...

> 
> We can drop the minimum.

... but I see you changed min/max now to 1/5000000. That's what I would
have suggested as well.


> > * new binding "i2c-scl-clk-low-timeout-us" has a description which I do
> >   not understand. What is a waiting state?
> 
> Shrug. May have to look at the MPC h/w that uses the property.

I will also have another look. My gut feeling is that the binding is
okay, only the description might need an update.

> >
> > * new binding "no-detect" is broken. At the least, it should be named
> >   something like "bus-fully-described" and then the OS can decide to
> >   leave out auto-detection mechanisms. If you are interested in the
> >   latter, you can simply disable class based instantiation on the host
> >   controller. No need to describe this in DT.
> 
> I've reverted the property now.

Cool, thanks!

Kind regards,

   Wolfram
Rob Herring (Arm) Feb. 27, 2024, 1:26 p.m. UTC | #5 
On Fri, Feb 23, 2024 at 4:34 PM Wolfram Sang
<wsa+renesas@sang-engineering.com> wrote:
>
> Hi Rob,
>
> > > * In the schema, "clock-frequency" has a minimum of 1kHz and a maximum
> > >   of 3MHz. Why? The specs do not say anything about a minimum freq and
> > >   fastest speed mentioned in the docs is 5Mhz (Ultra fast mode).
> >
> > IIRC, the high speed mode originally topped out at 3MHz. I guess
> > that's been revised.
>
> Hs-mode has a max of 3.4MHz...
>
> >
> > We can drop the minimum.
>
> ... but I see you changed min/max now to 1/5000000. That's what I would
> have suggested as well.
>
>
> > > * new binding "i2c-scl-clk-low-timeout-us" has a description which I do
> > >   not understand. What is a waiting state?
> >
> > Shrug. May have to look at the MPC h/w that uses the property.
>
> I will also have another look. My gut feeling is that the binding is
> okay, only the description might need an update.
>
> > >
> > > * new binding "no-detect" is broken. At the least, it should be named
> > >   something like "bus-fully-described" and then the OS can decide to
> > >   leave out auto-detection mechanisms. If you are interested in the
> > >   latter, you can simply disable class based instantiation on the host
> > >   controller. No need to describe this in DT.
> >
> > I've reverted the property now.
>
> Cool, thanks!

I don't think there's anything else to discuss on this patch, can I
get your ack?

Rob
Wolfram Sang Feb. 27, 2024, 5:04 p.m. UTC | #6 
On Thu, Feb 22, 2024 at 10:43:42AM -0700, Rob Herring wrote:
> Everything in i2c.txt is covered by schemas/i2c/i2c-controller.yaml in
> dtschema project, so remove i2c.txt and update links to it in the tree.
> 
> Signed-off-by: Rob Herring <robh@kernel.org>

Reviewed-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/gpio/gateworks,pld-gpio.txt b/Documentation/devicetree/bindings/gpio/gateworks,pld-gpio.txt
index 6e81f8b755c5..d543fd1b8b23 100644
--- a/Documentation/devicetree/bindings/gpio/gateworks,pld-gpio.txt
+++ b/Documentation/devicetree/bindings/gpio/gateworks,pld-gpio.txt
@@ -1,7 +1,6 @@ 
 Gateworks PLD GPIO controller bindings
 
-The GPIO controller should be a child node on an I2C bus,
-see: i2c/i2c.txt for details.
+The GPIO controller should be a child node on an I2C bus.
 
 Required properties:
 - compatible: Should be "gateworks,pld-gpio"
diff --git a/Documentation/devicetree/bindings/i2c/i2c.txt b/Documentation/devicetree/bindings/i2c/i2c.txt
deleted file mode 100644
index fc3dd7ec0445..000000000000
--- a/Documentation/devicetree/bindings/i2c/i2c.txt
+++ /dev/null
@@ -1,151 +0,0 @@ 
-Generic device tree bindings for I2C busses
-===========================================
-
-This document describes generic bindings which can be used to describe I2C
-busses and their child devices in a device tree.
-
-Required properties (per bus)
------------------------------
-
-- #address-cells  - should be <1>. Read more about addresses below.
-- #size-cells     - should be <0>.
-- compatible      - name of I2C bus controller
-
-For other required properties e.g. to describe register sets,
-clocks, etc. check the binding documentation of the specific driver.
-
-The cells properties above define that an address of children of an I2C bus
-are described by a single value.
-
-Optional properties (per bus)
------------------------------
-
-These properties may not be supported by all drivers. However, if a driver
-wants to support one of the below features, it should adapt these bindings.
-
-- clock-frequency
-	frequency of bus clock in Hz.
-
-- i2c-bus
-	For I2C adapters that have child nodes that are a mixture of both I2C
-	devices and non-I2C devices, the 'i2c-bus' subnode can be used for
-	populating I2C devices. If the 'i2c-bus' subnode is present, only
-	subnodes of this will be considered as I2C slaves. The properties,
-	'#address-cells' and '#size-cells' must be defined under this subnode
-	if present.
-
-- i2c-scl-falling-time-ns
-	Number of nanoseconds the SCL signal takes to fall; t(f) in the I2C
-	specification.
-
-- i2c-scl-internal-delay-ns
-	Number of nanoseconds the IP core additionally needs to setup SCL.
-
-- i2c-scl-rising-time-ns
-	Number of nanoseconds the SCL signal takes to rise; t(r) in the I2C
-	specification.
-
-- i2c-sda-falling-time-ns
-	Number of nanoseconds the SDA signal takes to fall; t(f) in the I2C
-	specification.
-
-- i2c-analog-filter
-	Enable analog filter for i2c lines.
-
-- i2c-digital-filter
-	Enable digital filter for i2c lines.
-
-- i2c-digital-filter-width-ns
-	Width of spikes which can be filtered by digital filter
-	(i2c-digital-filter). This width is specified in nanoseconds.
-
-- i2c-analog-filter-cutoff-frequency
-	Frequency that the analog filter (i2c-analog-filter) uses to distinguish
-	which signal to filter. Signal with higher frequency than specified will
-	be filtered out. Only lower frequency will pass (this is applicable to
-	a low-pass analog filter). Typical value should be above the normal
-	i2c bus clock frequency (clock-frequency).
-	Specified in Hz.
-
-- multi-master
-	states that there is another master 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'.
-
-- pinctrl
-	add extra pinctrl to configure SCL/SDA pins to GPIO function for bus
-	recovery, call it "gpio" or "recovery" (deprecated) state
-
-- scl-gpios
-	specify the gpio related to SCL pin. Used for GPIO bus recovery.
-
-- sda-gpios
-	specify the gpio related to SDA pin. Optional for GPIO bus recovery.
-
-- single-master
-	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'.
-
-- smbus
-	states that additional SMBus restrictions and features apply to this bus.
-	An example of feature is SMBusHostNotify. Examples of restrictions are
-	more reserved addresses and timeout definitions.
-
-- smbus-alert
-	states that the optional SMBus-Alert feature apply to this bus.
-
-- mctp-controller
-	indicates that the system is accessible via this bus as an endpoint for
-	MCTP over I2C transport.
-
-Required properties (per child device)
---------------------------------------
-
-- compatible
-	name of I2C slave device
-
-- reg
-	One or many I2C slave addresses. These are usually a 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
-	which, in theory, can be on the same bus.
-	Another flag is I2C_OWN_SLAVE_ADDRESS to mark addresses on which we
-	listen to be devices ourselves.
-
-Optional properties (per child device)
---------------------------------------
-
-These properties may not be supported by all drivers. However, if a driver
-wants to support one of the below features, it should adapt these bindings.
-
-- host-notify
-	device uses SMBus host notify protocol instead of interrupt line.
-
-- interrupts
-	interrupts used by the device.
-
-- interrupt-names
-	"irq", "wakeup" and "smbus_alert" names are recognized by I2C core,
-	other names are	left to individual drivers.
-
-- reg-names
-	Names of map programmable addresses.
-	It can contain any map needing another address than default one.
-
-- wakeup-source
-	device can be used as a wakeup source.
-
-Binding may contain optional "interrupts" property, describing interrupts
-used by the device. I2C core will assign "irq" interrupt (or the very first
-interrupt if not using interrupt names) as primary interrupt for the slave.
-
-Alternatively, devices supporting SMBus Host Notify, and connected to
-adapters that support this feature, may use "host-notify" property. I2C
-core will create a virtual interrupt for Host Notify and assign it as
-primary interrupt for the slave.
-
-Also, if device is marked as a wakeup source, I2C core will set up "wakeup"
-interrupt for the device. If "wakeup" interrupt name is not present in the
-binding, then primary interrupt will be used as wakeup interrupt.
diff --git a/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.yaml b/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.yaml
index b8319dcf3d8a..8676335e9e94 100644
--- a/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.yaml
+++ b/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.yaml
@@ -21,8 +21,7 @@  description: |
   See ../firmware/nvidia,tegra186-bpmp.yaml for details of the BPMP
   binding.
 
-  This node represents an I2C controller. See ../i2c/i2c.txt for details
-  of the core I2C binding.
+  This node represents an I2C controller.
 
 properties:
   compatible:
diff --git a/Documentation/devicetree/bindings/i3c/i3c.yaml b/Documentation/devicetree/bindings/i3c/i3c.yaml
index c816e295d565..87cadbcdc61c 100644
--- a/Documentation/devicetree/bindings/i3c/i3c.yaml
+++ b/Documentation/devicetree/bindings/i3c/i3c.yaml
@@ -71,7 +71,7 @@  patternProperties:
     description: |
       I2C child, should be named: <device-type>@<i2c-address>
 
-      All properties described in Documentation/devicetree/bindings/i2c/i2c.txt
+      All properties described in dtschema schemas/i2c/i2c-controller.yaml
       are valid here, except the reg property whose content is changed.
 
     properties:
diff --git a/Documentation/devicetree/bindings/sound/cs4341.txt b/Documentation/devicetree/bindings/sound/cs4341.txt
index 12b4aa8ef0db..c1d5c8ad1a36 100644
--- a/Documentation/devicetree/bindings/sound/cs4341.txt
+++ b/Documentation/devicetree/bindings/sound/cs4341.txt
@@ -9,7 +9,7 @@  Required properties:
           number for SPI.
 
 For required properties on I2C-bus, please consult
-Documentation/devicetree/bindings/i2c/i2c.txt
+dtschema schemas/i2c/i2c-controller.yaml
 For required properties on SPI-bus, please consult
 Documentation/devicetree/bindings/spi/spi-bus.txt
 
diff --git a/MAINTAINERS b/MAINTAINERS
index 45c6c13b4edf..50a906eb8dfd 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -10074,7 +10074,6 @@  S:	Maintained
 W:	https://i2c.wiki.kernel.org/
 Q:	https://patchwork.ozlabs.org/project/linux-i2c/list/
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/wsa/linux.git
-F:	Documentation/devicetree/bindings/i2c/i2c.txt
 F:	Documentation/i2c/
 F:	drivers/i2c/*
 F:	include/dt-bindings/i2c/i2c.h