drivers: i2c: document "slave" API

doc/guides/coding_guidelines/index.rst

@@ -824,6 +824,8 @@ their documentation from being generated. Their absence also prevents use of
 ``if (IS_ENABLED(CONFIG_FOO)) {}`` as an alternative to preprocessor
 conditionals when the code path should change based on the selected options.
 
+.. _coding_guideline_inclusive_language:
+
 Rule A.2: Inclusive Language
 ============================
 
@@ -916,6 +918,8 @@ Related GitHub Issues and Pull Requests are tagged with the `Inclusive Language
  terminology is confirmed by a public announcement or updated
  specification.
 
+ See `Zephyr issue 27033`_.
+
  * - :ref:`i2s_api`
  - * ``master / slave`` => TBD
  -
@@ -939,3 +943,4 @@ Related GitHub Issues and Pull Requests are tagged with the `Inclusive Language
 .. _I2C Specification: https://www.nxp.com/docs/en/user-guide/UM10204.pdf
 .. _Bluetooth Appropriate Language Mapping Tables: https://btprodspecificationrefs.blob.core.windows.net/language-mapping/Appropriate_Language_Mapping_Table.pdf
 .. _OSHWA Resolution to Redefine SPI Signal Names: https://www.oshwa.org/a-resolution-to-redefine-spi-signal-names/
+.. _Zephyr issue 27033: https:/zephyrproject-rtos/zephyr/issues/27033

doc/reference/overview.rst

@@ -157,6 +157,11 @@ current :ref:`stability level <api_lifecycle>`.
  - 1.0
  - 2.4
 
+ * - :ref:`i2c-slave-api`
+ - Experimental
+ - 1.12
+ - 1.12
+
  * - :ref:`i2s_api`
  - Stable
  - 1.9

doc/reference/peripherals/i2c.rst

@@ -1,12 +1,57 @@
 .. _i2c_api:
 
-
 I2C
 ####
 
 Overview
 ********
 
+.. note::
+
+ Zephyr recognizes the need to change the terms "master" and "slave"
+ used in the current `I2C Specification <i2c-specification>`_. This
+ will be done when the conditions identified in
+ :ref:`coding_guideline_inclusive_language` have been met. Existing
+ documentation, data structures, functions, and value symbols in code
+ are likely to change at that point.
+
+`I2C <i2c-specification>`_ (Inter-Integrated Circuit, pronounced "eye
+squared see") is a commonly-used two-signal shared peripheral interface
+bus. Many system-on-chip solutions provide controllers that communicate
+on an I2C bus. Devices on the bus can operate in two roles: as a
+"master" that initiates transactions and controls the clock, or as a
+"slave" that responds to transaction commands. A I2C controller on a
+given SoC will generally support the master role, and some will also
+support the slave mode. Zephyr has API for both roles.
+
+.. _i2c-master-api:
+
+I2C Master API
+==============
+
+Zephyr's I2C master API is used when an I2C peripheral controls the bus,
+in particularly the start and stop conditions and the clock. This is
+the most common mode, used to interact with I2C devices like sensors and
+serial memory.
+
+This API is supported in all in-tree I2C peripheral drivers and is
+considered stable.
+
+.. _i2c-slave-api:
+
+I2C Slave API
+================
+
+Zephyr's I2C slave API is used when an I2C peripheral responds to
+transactions initiated by a different controller on the bus. It might
+be used for a Zephyr application with transducer roles that are
+controlled by another device such as a host processor.
+
+This API is supported in very few in-tree I2C peripheral drivers. The
+API is considered experimental, as it is not compatible with the
+capabilities of all I2C peripherals supported in master mode.
+
+
 Configuration Options
 *********************
 
@@ -19,3 +64,6 @@ API Reference
 
 .. doxygengroup:: i2c_interface
  :project: Zephyr
+
+.. _i2c-specification:
+ https://www.nxp.com/docs/en/user-guide/UM10204.pdf

drivers/i2c/i2c_litex.c

@@ -110,8 +110,6 @@ static int i2c_litex_transfer(const struct device *dev, struct i2c_msg *msgs,
 static const struct i2c_driver_api i2c_litex_driver_api = {
  .configure = i2c_litex_configure,
  .transfer = i2c_litex_transfer,
- .slave_register = NULL,
- .slave_unregister = NULL,
 };
 
 /* Device Instantiation */