dt-bindings: i2c: Remove obsolete i2c.txt
Commit Message
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
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
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
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
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
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>
@@ -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"
deleted file mode 100644
@@ -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.
@@ -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:
@@ -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:
@@ -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
@@ -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