The core gains placeholders for recently added functions when CONFIG_I2C

is not defined as well documentation fixes to start using inclusive
 terminology. The drivers get paths in DT bindings fixed as well as
 proper interrupt handling for the ocores driver.
 -----BEGIN PGP SIGNATURE-----
 
 iQIzBAABCgAdFiEEOZGx6rniZ1Gk92RdFA3kzBSgKbYFAmZ31U4ACgkQFA3kzBSg
 KbYgMg/9Ew5g86A9u1BBiCytjzNXIrNNbL1rm7GsHH4elq5h+Pa2jS1AZjHB1ZtC
 8KwogPvUeqJyzmO6SEzJVoDq8B4QIUGS7QFadqhKSNScO60MNfRmHXiOPoIXMNkS
 pws3oquqM3BDdfvqtod1KFkVKsfok+UlDcOXmGJLKNzoBaBfZWHwGVBEW1E1xdLt
 PrimxsIzMWNySmWimTf1nQl5Ah3gzcB79SdQFvqU50dGmscF4fAd7BirjNktrgJB
 E45jD5341U2xb1pCEtsfgwyvJiul//Cx/iHneCiu/EvVelZjl/WG1lNu5DYpOzmU
 oqhqkZJw3o0G3W8dK/CjyGlp8MsbQJoa2qSGA2V+1ZtQyj09wM727qhRMkFvqsRH
 moTTNx2+KcSWrvjjXMvC2oht/rfKYbLzFSqzDiRzmphfgFjPQKDCL6EVoyQwvOYD
 LpFRKyhSMTR/OpHfpdES+VQwvcvfmk5wHHQu5kl956bec63buIj0cFLiaAxiJR3v
 HhsCeX+BCp5+3z15+/x2vnKPzNAmS8oc0ZOGiN3W8qYUBpv1GjwLXuEDNLKCXf+W
 6xlTCb+lNTSR2m3R2me1fI0iuFQW5nLT6t3T/mGbNLu4xJ79Wq0rLRXpMxJQDnf7
 XB+251eg2BOTe0Qbi015NUNF2LbVblsxz8n9pqYaRsF+bVyaiO0=
 =T67e
 -----END PGP SIGNATURE-----

Merge tag 'i2c-for-6.10-rc5' of git://git.kernel.org/pub/scm/linux/kernel/git/wsa/linux

Pull i2c fixes from Wolfram Sang:
 "The core gains placeholders for recently added functions when
  CONFIG_I2C is not defined as well documentation fixes to start using
  inclusive terminology.

  The drivers get paths in DT bindings fixed as well as proper interrupt
  handling for the ocores driver"

* tag 'i2c-for-6.10-rc5' of git://git.kernel.org/pub/scm/linux/kernel/git/wsa/linux:
  docs: i2c: summary: be clearer with 'controller/target' and 'adapter/client' pairs
  docs: i2c: summary: document 'local' and 'remote' targets
  docs: i2c: summary: document use of inclusive language
  docs: i2c: summary: update speed mode description
  docs: i2c: summary: update I2C specification link
  docs: i2c: summary: start sentences consistently.
  i2c: Add nop fwnode operations
  i2c: ocores: set IACK bit after core is enabled
  dt-bindings: i2c: google,cros-ec-i2c-tunnel: correct path to i2c-controller schema
  dt-bindings: i2c: atmel,at91sam: correct path to i2c-controller schema

Documentation/devicetree/bindings/i2c/atmel,at91sam-i2c.yaml

@@ -77,7 +77,7 @@ required:
   - clocks
 
 allOf:
-  - $ref: i2c-controller.yaml
+  - $ref: /schemas/i2c/i2c-controller.yaml#
   - if:
       properties:
         compatible:

Documentation/devicetree/bindings/i2c/google,cros-ec-i2c-tunnel.yaml

@@ -21,7 +21,7 @@ description: |
   google,cros-ec-spi or google,cros-ec-i2c.
 
 allOf:
-  - $ref: i2c-controller.yaml#
+  - $ref: /schemas/i2c/i2c-controller.yaml#
 
 properties:
   compatible:

Documentation/i2c/i2c_bus.svg

@@ -1,5 +1,6 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <!-- Created with Inkscape (http://www.inkscape.org/) -->
+<!-- Updated to inclusive terminology by Wolfram Sang -->
 
 <svg
    xmlns:dc="http://purl.org/dc/elements/1.1/"
@@ -1120,7 +1121,7 @@
     <rect
        style="opacity:1;fill:#ffb9b9;fill-opacity:1;stroke:#f00000;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
        id="rect4424-3-2-9-7"
-       width="112.5"
+       width="134.5"
        height="113.75008"
        x="112.5"
        y="471.11221"
@@ -1133,15 +1134,15 @@
        y="521.46259"
        id="text4349"><tspan
          sodipodi:role="line"
-         x="167.5354"
+         x="178.5354"
          y="521.46259"
          style="font-size:25px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle"
          id="tspan1273">I2C</tspan><tspan
          sodipodi:role="line"
-         x="167.5354"
+         x="178.5354"
          y="552.71259"
          style="font-size:25px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle"
-         id="tspan1285">Master</tspan></text>
+         id="tspan1285">Controller</tspan></text>
     <rect
        style="color:#000000;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;fill:#b9ffb9;fill-opacity:1;fill-rule:nonzero;stroke:#006400;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate"
        id="rect4424-3-2-9-7-3-3-5-3"
@@ -1171,7 +1172,7 @@
          x="318.59131"
          y="552.08752"
          style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px"
-         id="tspan1287">Slave</tspan></text>
+         id="tspan1287">Target</tspan></text>
     <path
        style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968767;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
        d="m 112.49995,677.36223 c 712.50005,0 712.50005,0 712.50005,0"
@@ -1233,7 +1234,7 @@
          x="468.59131"
          y="552.08746"
          style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px"
-         id="tspan1287-6">Slave</tspan></text>
+         id="tspan1287-6">Target</tspan></text>
     <rect
        style="color:#000000;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;vector-effect:none;fill:#b9ffb9;fill-opacity:1;fill-rule:nonzero;stroke:#006400;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate"
        id="rect4424-3-2-9-7-3-3-5-3-1"
@@ -1258,7 +1259,7 @@
          x="618.59131"
          y="552.08746"
          style="font-size:25.00000191px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:1px"
-         id="tspan1287-9">Slave</tspan></text>
+         id="tspan1287-9">Target</tspan></text>
     <path
        style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.99968743;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#DotM)"
        d="m 150,583.61221 v 93.75"

Documentation/i2c/summary.rst

@@ -3,19 +3,17 @@ Introduction to I2C and SMBus
 =============================
 
 I²C (pronounce: I squared C and written I2C in the kernel documentation) is
-a protocol developed by Philips. It is a slow two-wire protocol (variable
+a protocol developed by Philips. It is a two-wire protocol with variable
-speed, up to 400 kHz), with a high speed extension (3.4 MHz).  It provides
+speed (typically up to 400 kHz, high speed modes up to 5 MHz). It provides
 an inexpensive bus for connecting many types of devices with infrequent or
 low bandwidth communications needs. I2C is widely used with embedded
 systems. Some systems use variants that don't meet branding requirements,
 and so are not advertised as being I2C but come under different names,
 e.g. TWI (Two Wire Interface), IIC.
 
-The latest official I2C specification is the `"I2C-bus specification and user
+The latest official I2C specification is the `"I²C-bus specification and user
-manual" (UM10204) <https://www.nxp.com/webapp/Download?colCode=UM10204>`_
+manual" (UM10204) <https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_
-published by NXP Semiconductors. However, you need to log-in to the site to
+published by NXP Semiconductors, version 7 as of this writing.
-access the PDF. An older version of the specification (revision 6) is archived
-`here <https://web.archive.org/web/20210813122132/https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_.
 
 SMBus (System Management Bus) is based on the I2C protocol, and is mostly
 a subset of I2C protocols and signaling. Many I2C devices will work on an
@@ -33,29 +31,52 @@ implement all the common SMBus protocol semantics or messages.
 Terminology
 ===========
 
-Using the terminology from the official documentation, the I2C bus connects
+The I2C bus connects one or more controller chips and one or more target chips.
-one or more *master* chips and one or more *slave* chips.
 
 .. kernel-figure::  i2c_bus.svg
-   :alt:    Simple I2C bus with one master and 3 slaves
+   :alt:    Simple I2C bus with one controller and 3 targets
 
    Simple I2C bus
 
-A **master** chip is a node that starts communications with slaves. In the
+A **controller** chip is a node that starts communications with targets. In the
-Linux kernel implementation it is called an **adapter** or bus. Adapter
+Linux kernel implementation it is also called an "adapter" or "bus". Controller
-drivers are in the ``drivers/i2c/busses/`` subdirectory.
+drivers are usually in the ``drivers/i2c/busses/`` subdirectory.
 
-An **algorithm** contains general code that can be used to implement a
+An **algorithm** contains general code that can be used to implement a whole
-whole class of I2C adapters. Each specific adapter driver either depends on
+class of I2C controllers. Each specific controller driver either depends on an
-an algorithm driver in the ``drivers/i2c/algos/`` subdirectory, or includes
+algorithm driver in the ``drivers/i2c/algos/`` subdirectory, or includes its
-its own implementation.
+own implementation.
 
-A **slave** chip is a node that responds to communications when addressed
+A **target** chip is a node that responds to communications when addressed by a
-by the master. In Linux it is called a **client**. Client drivers are kept
+controller. In the Linux kernel implementation it is also called a "client".
-in a directory specific to the feature they provide, for example
+While targets are usually separate external chips, Linux can also act as a
-``drivers/media/gpio/`` for GPIO expanders and ``drivers/media/i2c/`` for
+target (needs hardware support) and respond to another controller on the bus.
+This is then called a **local target**. In contrast, an external chip is called
+a **remote target**.
+
+Target drivers are kept in a directory specific to the feature they provide,
+for example ``drivers/gpio/`` for GPIO expanders and ``drivers/media/i2c/`` for
 video-related chips.
 
-For the example configuration in figure, you will need a driver for your
+For the example configuration in the figure above, you will need one driver for
-I2C adapter, and drivers for your I2C devices (usually one driver for each
+the I2C controller, and drivers for your I2C targets. Usually one driver for
-device).
+each target.
+
+Synonyms
+--------
+
+As mentioned above, the Linux I2C implementation historically uses the terms
+"adapter" for controller and "client" for target. A number of data structures
+have these synonyms in their name. So, when discussing implementation details,
+you should be aware of these terms as well. The official wording is preferred,
+though.
+
+Outdated terminology
+--------------------
+
+In earlier I2C specifications, controller was named "master" and target was
+named "slave". These terms have been obsoleted with v7 of the specification and
+their use is also discouraged by the Linux Kernel Code of Conduct. You may
+still find them in references to documentation which has not been updated. The
+general attitude, however, is to use the inclusive terms: controller and
+target. Work to replace the old terminology in the Linux Kernel is on-going.

drivers/i2c/busses/i2c-ocores.c

@@ -431,8 +431,8 @@ static int ocores_init(struct device *dev, struct ocores_i2c *i2c)
 	oc_setreg(i2c, OCI2C_PREHIGH, prescale >> 8);
 
 	/* Init the device */
-	oc_setreg(i2c, OCI2C_CMD, OCI2C_CMD_IACK);
 	oc_setreg(i2c, OCI2C_CONTROL, ctrl | OCI2C_CTRL_EN);
+	oc_setreg(i2c, OCI2C_CMD, OCI2C_CMD_IACK);
 
 	return 0;
 }

include/linux/i2c.h

@@ -960,8 +960,6 @@ int i2c_handle_smbus_host_notify(struct i2c_adapter *adap, unsigned short addr);
 #define builtin_i2c_driver(__i2c_driver) \
 	builtin_driver(__i2c_driver, i2c_add_driver)
 
-#endif /* I2C */
-
 /* must call put_device() when done with returned i2c_client device */
 struct i2c_client *i2c_find_device_by_fwnode(struct fwnode_handle *fwnode);
 
@@ -971,6 +969,28 @@ struct i2c_adapter *i2c_find_adapter_by_fwnode(struct fwnode_handle *fwnode);
 /* must call i2c_put_adapter() when done with returned i2c_adapter device */
 struct i2c_adapter *i2c_get_adapter_by_fwnode(struct fwnode_handle *fwnode);
 
+#else /* I2C */
+
+static inline struct i2c_client *
+i2c_find_device_by_fwnode(struct fwnode_handle *fwnode)
+{
+	return NULL;
+}
+
+static inline struct i2c_adapter *
+i2c_find_adapter_by_fwnode(struct fwnode_handle *fwnode)
+{
+	return NULL;
+}
+
+static inline struct i2c_adapter *
+i2c_get_adapter_by_fwnode(struct fwnode_handle *fwnode)
+{
+	return NULL;
+}
+
+#endif /* !I2C */
+
 #if IS_ENABLED(CONFIG_OF)
 /* must call put_device() when done with returned i2c_client device */
 static inline struct i2c_client *of_find_i2c_device_by_node(struct device_node *node)